Subagent invocation, context passing, and spawning

These settings are mechanical, but each one controls a different part of delegation.

The Agent tool, availability, and approval

Current Agent SDK releases spawn subagents with the Agent tool. Older materials and compatibility surfaces may call it Task, so recognize both names; current tool_use blocks emit Agent.

Two configuration questions must stay separate:

• The top-level tools option determines which tools are available. If a restricted list omits Agent, the coordinator cannot delegate.
• Top-level allowedTools pre-approves calls. Include Agent there when delegation must proceed without a permission prompt, such as in unattended execution. Omitting it does not by itself remove the tool.

Two different things stand between you and the practice room: whether your ID opens the door at all, and whether the desk asks you to sign in. Taking your name off the sign-in sheet doesn't lock the door.

AgentDefinition.tools restricts what that subagent can use. The definition also carries its description and system prompt.

Only the field this section turns on is shown; a real definition carries more.

const researcher: AgentDefinition = {
  // This subagent's ceiling. Nothing the coordinator holds is inherited.
  tools: ['Read', 'Grep', 'Glob'],
};

researcher = AgentDefinition(
    # This subagent's ceiling. Nothing the coordinator holds is inherited.
    tools=["Read", "Grep", "Glob"],
)

A subagent spawned from this cannot write a file whatever its prompt says, because there is no write tool present to call.

Permissions don't flow downward either. A subagent doesn't receive the coordinator's tool list or its approvals; each agent's are configured for that agent. Nor does prose restrict anything — a subagent told in its prompt not to write files can still call a write tool it holds. Withhold the tool, or the restriction is only a request.

Three settings that are easy to conflate, and the different question each one answers:

tools                  is Agent available to the coordinator at all?
allowedTools           does calling it skip the permission prompt?
AgentDefinition.tools  what may the spawned subagent use?

Only the first can stop delegation from happening. Removing Agent from the second changes who is asked, not what is possible.

Pass complete findings

Because each subagent has isolated context, a synthesis subagent needs the relevant search results and document analysis in its prompt. A reference to a different subagent's work isn't enough because the synthesis subagent can't open that subagent's conversation.

Use a structured format that keeps content separate from source metadata. Store source URLs, document names, and page numbers beside each finding. The synthesis subagent can then cite the source for each claim.

Parallel means one response

To run subagents concurrently, emit multiple Agent calls in a single coordinator response. Spreading them across separate turns is sequential execution with extra steps, and the latency shows.

Subagents spawned in the same response cannot wait on one another. Every result returns to the coordinator, so a subagent that needs another's output has to be spawned in a later response, once the coordinator holds it. Group everything independent into one response, and let a real dependency cost exactly one turn.

Give subagents goals instead of step-by-step procedures

A coordinator prompt that specifies research goals and quality criteria lets subagents adapt to what they find. One that specifies steps gets you compliance with the steps, including when the steps are wrong for the situation.

Forking

fork_session branches from a shared baseline so two approaches can be explored independently without redoing the analysis they share. It isolates conversation history, not the working directory: use checkpointing, a worktree, or another isolated workspace when a branch may modify files.