How to add human approvals to Claude Managed Agents

Use the integration skill

Copy this skill link into your code agent to add Claude Managed Agents and Contro1 to your system.

Copy skill link

Key takeaways

• Start with one approval request for each blocking event referenced by session.status_idle stop_reason.event_ids.
• Use session_id as correlation_id and session_id:event_id in external_request_id.
• Verify signed Contro1 callbacks before sending user.tool_confirmation or user.custom_tool_result back to Claude.
• Log autonomous allowed actions, Claude response-event delivery, and dead letters when they need evidence.

Connect your Claude Managed Agent agent to Contro1

A Claude Managed Agent agent runs in your own code, so it connects with an Agent Credential: a key bound to one agent, so every call is attributed to it and nothing in a request can change which agent it is.

• 1. Create the agent: Agents, New agent, "An agent you are building for production" (or contro1 init --name "<name>" --framework claude-managed-agents). You are its accountable owner.
• 2. Connect the application account under Apps, if it is not connected yet.
• 3. Give the agent the Actions it needs under Access. It starts with none.
• 4. Create an Agent Credential for it (Settings, Agent keys) and store it as CONTRO1_API_KEY in your secret manager.
• 5. Call Actions from your tools as below. The same credential creates approval requests for work your own code does.

Connect an agent: every step, in full

Run an application Action from a Claude Managed Agent tool

Contro1 holds the account and makes the call, so the record is what Contro1 observed. The tool returns what the Action produced; when a person has to approve first, it waits and then returns the result. It never re-submits: a retry could send a second email.

Before writing the input, read the exact input_schema with get_action_contract, or from the Action on the Access page.

import os, uuid
from centcom import CentcomClient, needs_human_resolution

contro1 = CentcomClient(api_key=os.environ["CONTRO1_API_KEY"])  # an Agent Credential

def run_action(action_id: str, input: dict, *, account_mode: str = "shared", **kw):
    """Run a Contro1 Action and return what it produced. Never retries a send."""
    out = contro1.actions.invoke(
        action_id, input,
        authority_mode=kw.pop("authority_mode", "agent_principal"),
        account_mode=account_mode,
        idempotency_key=kw.pop("idempotency_key", str(uuid.uuid4())),
        **kw,
    )
    inv = out["invocation"]
    if inv["state"] == "executed":
        return out["result"]
    if inv["state"] == "awaiting_approval":
        settled = contro1.actions.wait_for_invocation(inv["invocation_id"])
        if needs_human_resolution(settled):
            raise RuntimeError("Outcome unknown; a person must check. Do not retry.")
        return contro1.actions.get_result(settled["invocation_id"])
    raise RuntimeError(f"Not run: {inv['state']} {out.get('not_run', '')}")

# Declare a custom tool "list_recent_emails" on the agent, and answer its
# tool_use events from your service - where the Agent Credential lives, never
# inside the agent's environment.
def handle_tool_use(name: str, tool_input: dict):
    if name == "list_recent_emails":
        return run_action("gmail.message.list", {"max_results": tool_input.get("max_results", 5)})
    raise ValueError(f"unknown tool {name}")

What this integration does

Claude Managed Agents can run long-lived sessions where the action that matters appears after several model and tool turns. Contro1 should sit at the session action boundary: when the stream emits session.status_idle with stop_reason.type = requires_action, your bridge reads the blocking stop_reason.event_ids, creates one routed approval request per risky event, and lets the session continue only after a verified decision.

This is different from Claude Code. Claude Code blocks local tool calls through PreToolUse hooks; Claude Managed Agents need a server-side session bridge that tracks session_id, action IDs, callback delivery, and continuation retries.

Building with the Claude Agent SDK (claude-agent-sdk) instead, where the agent runs in your own process? That is a different product with its own page: Connect a Claude Agent SDK agent to Contro1.

Setup

Install the Contro1 Python SDK in the bridge process that listens to Claude Managed Agents session events and receives Contro1 callbacks.

CENTCOM_API_KEY=cc_live_your_key
CENTCOM_BASE_URL=https://api.contro1.com/api/centcom/v1
CENTCOM_WEBHOOK_SECRET=whsec_your_secret
PUBLIC_BASE_URL=https://your-bridge.example.com

Short example: ask for approval

request = centcom.create_request(
    type="approval",
    question=f"Allow Claude managed-agent event {event_id}?",
    context={"event": blocking_event},
    callback_url=f"{PUBLIC_BASE_URL}/webhooks/contro1",
    required_role="developer",
    external_request_id=f"claude:{session_id}:{event_id}",
    correlation_id=session_id,
    metadata={
        "integration": "claude-managed-agents",
        "session_id": session_id,
        "blocking_event_id": event_id,
        "blocking_event_type": blocking_event["type"],
        "tool_name": blocking_event.get("name"),
    },
)

Send context the reviewer can trust

The blocking event you copy into context is machine-observed fact: it comes from the session stream, not from the model, so the reviewer can trust it as the exact action Claude is trying to take. Enrich it with the trigger - the user message or task that started the session - which the bridge can read from earlier session events.

If you also forward text the model wrote about itself (a summary or justification), keep it in a separate agent_reported block. It helps the reviewer decide, but it must never change routing, risk_level, or approval policy, because a prompt-injected agent writes very persuasive reasons.

Reviewer context and trust rules

Full example: bridge action to approval

A production bridge should stream events, detect session.status_idle with stop_reason.type = requires_action, create one request for each blocking event ID, persist the mapping, wait for a signed callback, and then send the matching Claude event.

with anthropic_client.beta.sessions.events.stream(session_id) as stream:
    for event in stream:
        events_by_id[event.id] = event

        if event.type != "session.status_idle" or not event.stop_reason:
            continue
        if event.stop_reason.type != "requires_action":
            continue

        for event_id in event.stop_reason.event_ids:
            blocking_event = events_by_id[event_id]
            dedupe_key = f"claude:{session_id}:{event_id}"
            request = centcom.create_request(
                type="approval",
                question=f"Allow Claude event {event_id}?",
                context={"event": blocking_event},
                callback_url="https://bridge.example.com/webhooks/contro1",
                required_role="developer",
                external_request_id=dedupe_key,
                correlation_id=session_id,
                metadata={
                    "integration": "claude-managed-agents",
                    "session_id": session_id,
                    "blocking_event_id": event_id,
                    "blocking_event_type": blocking_event["type"],
                },
            )
            store_mapping(request["id"], session_id, event_id, blocking_event["type"])

Send the right Claude response event

Tool confirmations and custom tools resume differently. After Contro1 approves a tool-use confirmation, send user.tool_confirmation with the blocking event ID in tool_use_id and result = allow. If Contro1 denies it, send result = deny and include a deny_message.

For agent.custom_tool_use, do not send user.tool_confirmation. Execute the custom tool only after approval, then return user.custom_tool_result with custom_tool_use_id set to the blocking event ID.

anthropic_client.beta.sessions.events.send(
    session_id,
    events=[{
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow" if approved else "deny",
        **({} if approved else {"deny_message": "Denied in Contro1"}),
    }],
)

result = execute_custom_tool(blocking_event["name"], blocking_event["input"])

anthropic_client.beta.sessions.events.send(
    session_id,
    events=[{
        "type": "user.custom_tool_result",
        "custom_tool_use_id": event_id,
        "content": [{"type": "text", "text": result}],
    }],
)

If routing fails, check who is available

Most integrations do not need Control Map in the normal approval path. If a request cannot be routed, times out unexpectedly, or your bridge wants to show a clear operational error, call Control Map to see who is currently available.

It helps answer which required roles are mapped, who is on shift now, whether fallback reviewers exist, and which warning explains the routing problem.

preview = centcom.post("/requests/control-map", {
    "approval_requirements": {
        "required_roles": ["developer"],
        "required_approvals": 1,
    },
    "metadata": {
        "integration": "claude-managed-agents",
        "session_id": session_id,
        "blocking_event_type": blocking_event_type,
    },
})

print(preview["satisfiable"])            # can this request be routed?
print(preview.get("on_shift_capacity"))  # who is currently available?
print(preview.get("fallback_reviewers")) # who can receive fallback routing?
print(preview.get("warnings"))           # why routing may fail

Callback and continuation rules

• Verify X-CentCom-Signature and X-CentCom-Timestamp before reading the decision.
• For agent.tool_use, answer with user.tool_confirmation.
• For agent.custom_tool_use, run the custom tool only after approval, then answer with user.custom_tool_result.
• Treat rejected, cancelled, timed_out, invalid signatures, and unknown request IDs as fail-closed.
• Retry event delivery with bounded backoff, then write a dead-letter record if delivery is exhausted.

Webhooks · Audit records and cases · Claude Code approval hooks

Log autonomous and delivery actions

Every approval request already stores the human decision in Contro1. Use audit records for autonomous allowed actions, Claude response delivery, and dead-letter records.

centcom.log_action(
    action="claude_managed_agent.read_only_action_allowed",
    summary="Allowed read-only managed-agent event without human approval",
    source={"integration": "claude-managed-agents", "run_id": event_id},
    outcome="success",
    severity="info",
    correlation_id=session_id,
)

centcom.log_action(
    action="claude_managed_agent.response_event_delivered",
    summary=f"Sent Claude response event for {event_id}",
    source={"integration": "claude-managed-agents", "workflow_id": blocking_event_type, "run_id": event_id},
    outcome="success",
    correlation_id=session_id,
    in_reply_to={"type": "request", "id": request_id},
)

Get evidence for compliance or incident review

Use request evidence for one reviewed managed-agent event. Use the case timeline when you need the full session: approvals, logs, denied events, response delivery, and dead letters sharing the same correlation_id.

evidence = centcom.get(f"/requests/{request_id}/evidence")

timeline = centcom.get(f"/cases/{session_id}")

Send full agent traceability

Beyond the approval call, attach a run trace, the tools you invoked, and the context you retrieved. Each field is optional; add what you have. Identity always comes from your credential. When a named part of a multi-agent system made the call, say which with the Contro1-Sub-Agent header (as_sub_agent in the SDKs): Contro1 registers it under this agent, and it never has more authority than this agent.

• trace_id / parent_trace_id - link one run (and sub-agent runs) into a single trace.
• tool_calls[] - what the agent tried to do, so reviewers see the actions. A hook can report every tool call for you.
• retrieved_context[] - the data the decision was based on (RAG provenance).
• Then export a signed evidence packet from GET /requests/:id/evidence.

# Same approval call you already make - now with full traceability.
billing = client.as_sub_agent("billing")   # optional: a named part of this agent
billing.create_protocol_request({
    "request_type": "approval",
    "title": "Refund $4,200 to customer 8831",
    "source": {"integration": "claude"},
    "trace_id": f"trc_{run_id}",          # link every step of this run
    "tool_calls": [{"name": "lookup_order", "outcome": "success"}],
    "retrieved_context": [{"source": "policy:refunds", "uri": "kb://policy/refunds"}],
    "continuation": {"mode": "decision"},
})

Agent identity, traceability & signed evidence

Make the approval the gate, not a suggestion

The signed webhook is cryptographic proof of a human decision. Verify it inside the system that executes the action - not inside the agent. Any tool that must never run without human sign-off (payments, deploys, data deletion) should refuse to act without a verified approval; that way no agent, including shadow agents nobody registered, can trigger it by skipping Contro1.

• Verify the signature and reject timestamps older than 5 minutes (replay protection; the timestamp marks callback delivery, not request creation, so long SLAs are unaffected).
• Bind the approval to the exact action parameters via metadata / correlation_id - never treat "an approval arrived" as permission for a different action.
• Execute each request_id exactly once (idempotency on your side).
• When in doubt, confirm state directly with GET /v1/requests/:id using a read-only API key.

Full guardrail pattern with code: Webhooks

Put this integration in the enterprise control model

The connector creates the runtime gate. The operating model around it defines which actions pause, which owner receives the decision, how a timeout escalates, and where the outcome is recorded across agent frameworks.

runtime human approval for AI agents · enterprise AI agent control plane

Frequently asked questions

What should correlation_id be?

Use the Claude Managed Agents session_id. This groups every approval, callback, Claude response event log, and dead-letter record from the session into one Contro1 case timeline.

What should external_request_id be?

Use a deterministic key that includes session_id and the blocking event_id from stop_reason.event_ids. That makes retries and replayed status_idle events idempotent.

Do I send tool_confirmation for every approval?

No. Send user.tool_confirmation for agent.tool_use confirmations. For agent.custom_tool_use, execute the custom tool only after approval and send user.custom_tool_result.

Related resources