Multi-Agent Governance#

Multi-agent governance in Claude Code is the set of mechanisms that control what subagents can do, when they can stop, and how their activity is tracked. These mechanisms operate at three layers: spawning restrictions (which agents can run and with what tools), lifecycle hooks (blocking/redirecting agents at key transitions), and observability (tracing agent identity through API requests and telemetry).

Spawning Restrictions#

Tool allowlists / denylists on subagent definitions#

Every subagent markdown file can declare a tools allowlist or disallowedTools denylist in YAML frontmatter. Omitting tools grants full access; setting it to a list restricts the agent to exactly those tools 1. If both fields are set, disallowedTools is applied first.

Certain tools are always unavailable to subagents regardless of configuration 1:

• Agent, AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers

Restricting which subagents an orchestrator can spawn#

Use Agent(agent_type) syntax in a coordinator agent's tools field to create an allowlist of spawnable types 2:

tools: Agent(worker, researcher), Read, Bash

If Agent is omitted entirely, the agent cannot spawn any subagents. To block specific agents while allowing all others, use permissions.deny with Agent(subagent-name) format, or pass --disallowedTools "Agent(name)" on the CLI 2.

Note: Agent() syntax was originally called Task() and was renamed in v2.1.63. Task(...) references still work as aliases 2.

This restriction only applies when agents run as the main thread (claude --agent). Subagents cannot spawn other subagents 2.

Permission modes#

Subagents inherit the parent's permission mode. Parents running bypassPermissions or acceptEdits take precedence and cannot be overridden by the subagent 1. Available modes: default, acceptEdits, auto, dontAsk, bypassPermissions, plan.

Lifecycle Hooks#

Hooks are event-driven scripts (shell commands, prompt-based, HTTP, or MCP tool) that intercept key agent transitions. All governance-relevant hooks support blocking via exit code 2 or {"decision": "block", "reason": "..."} output 3.

Agent-team hooks (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)#

TeammateIdle and TaskCompleted were introduced in v2.1.33 4. TaskCreated was introduced in v2.1.84 4.

Subagent-level hooks#

Hook definitions can live in 5 6:

• ~/.claude/settings.json or .claude/settings.json — run in the main session when agents start/stop
• Subagent frontmatter hooks: block — run only while that specific subagent is active

PreToolUse for conditional tool blocking#

PreToolUse hooks run before any tool executes and can deny specific operations. This is the primary mechanism for fine-grained policy enforcement beyond static tool lists — e.g., blocking SQL writes for a db-reader agent that otherwise has Bash access 1. See hooks reference for full input schema.

Observability#

Sub-agents are currently black boxes from the parent's perspective — the parent has no real-time event stream into what tools a subagent is using 7. Observability is telemetry-only:

• OTEL spans: agent_id and parent_agent_id attributes on claude_code.tool and claude_code.llm_request spans; background subagent spans nest under the dispatching Agent tool span — added in v2.1.145 4
• HTTP headers: x-claude-code-agent-id / x-claude-code-parent-agent-id on all sub-agent API requests — added in v2.1.139 4

Known gap: real-time parent-child communication#

The core open request (issue #1770) is to expose streaming tool-call events from subagents to the parent, enabling the parent to detect strategy deviations (e.g., a subagent creating simulation scripts instead of running real searches) and send mid-execution control messages (pause/redirect/halt). As of v2.1.145+, this remains unimplemented. The parent_tool_use_id infrastructure in -p mode demonstrates the plumbing exists; it is not yet exposed programmatically to the parent instance 7.

Community workarounds include file-based coordination state + Stop/SubagentStop hooks that notify a coordinator session via tmux or shared files 8, and third-party tools like Orchestra that add observability via MCP.

Key References#