Agent lifecycle

A subagent is a separate conversation carrying out a delegated task. It can inspect files, use tools, and return findings while the coordinating agent continues working. A separate conversation is not automatically a separate checkout, a separate security boundary, or an independent background service.

Choose the kind of work

Need | Use | Important boundary | 

Independent research in the same checkout | A shared-workspace subagent | All agents see the same files; ask for no edits when appropriate. | 

Independent implementation changes | A subagent in a dedicated Git worktree | Changes require explicit review and integration. | 

A conversation you will direct yourself | /fork, optionally with --worktree | This creates a peer session, rather than delegating a bounded child task. | 

A reusable procedure | A skill | Instructions are not themselves a running agent. | 

Tell the coordinating agent your intended outcome and isolation requirement. Tool names below explain what you may see in the transcript; they are not slash commands to enter into the terminal. The available collaboration interface depends on the active model's dialect.

Define a bounded assignment

Specify the deliverable, allowed changes, files owned, verification, and when to stop. For example:

Create a subagent named parser_review in the current checkout.
It must inspect parser code and tests without editing files or running shell commands.
Report the three most important missing test cases with file references.
Do not implement fixes. Continue reviewing the public API yourself.

In the collaboration interface, spawning returns a canonical name such as /root/parser_review. Nested children extend their parent's path. Keep this name when requesting follow-up work so the coordinator can target the existing conversation instead of spawning a replacement.

A read-only assignment is an instruction, not a filesystem lock. Approval and sandbox controls still matter.

Workspace and shared state

State | Behavior | Practical consequence | 

Conversation | Each child retains its own transcript after initialization. | The parent's later conversation is not continuously copied into the child; send relevant updates explicitly. | 

Shared-workspace files | Normal spawning uses the caller's working directory. | Two edits to the same file can conflict even though their conversations are separate. | 

Worktree files | Worktree spawning creates a dedicated checkout owned by that child. | The child does not see arbitrary uncommitted changes in the parent checkout. Confirm its base before depending on recent work. | 

Approval and plan controls | The CLI child runtime uses the session's shared approval policy, allowed-root state, and plan-mode hooks. | Delegation is not a way around a denied operation or plan-mode editing restriction. | 

MCP | The child runtime receives the session's MCP tools. | A worktree does not provide a separate external service account or database. External mutations can still affect the same resources. | 

Host resources | Children use the same host and configured services. | Separate checkouts do not isolate TCP ports, installed dependencies, or provider rate limits. | 

For shared-checkout editing, assign non-overlapping file ownership and one integration owner. For separate checkouts, specify how the changes will be transferred before starting. See worktree base selection and retention.

Context and model selection

The collaboration spawn tools accept a task message and optional history, model, and reasoning settings:

Setting | Meaning | Constraint | 

fork_turns omitted or "all" | Fork the available parent conversation history. | Inherits the parent model and reasoning effort; explicit overrides are rejected. | 

fork_turns: "none" | Do not copy the parent transcript. | The task message must provide the necessary background, paths, and constraints. | 

fork_turns: "3" | Copy a bounded recent history using a positive integer string. | Older decisions may be missing; summarize those in the assignment. | 

model | Select a different allowed child model. | Requires no-history or bounded-history spawning and must satisfy the host's model policy. | 

reasoning_effort | Request a child reasoning setting. | Requires no-history or bounded-history spawning; supported values depend on the selected model. | 

Ask for a self-contained assignment when switching models. “Use another model” alone does not establish which files, acceptance criteria, or previous decisions it should know. If an organization rejects a child model, select an allowed model rather than retrying with an invented alias.

Monitor and limit concurrency

/agents
/agents limit
/agents limit 3

The first command opens agent browsing; the others inspect or change the concurrent subagent cap. You can also set it at startup with agent-cli --max-concurrent-agents 3. Lowering the cap does not interrupt existing work: active agents retain their slots, and the new limit applies to subsequent spawn or follow-up admission.

The collaboration listing distinguishes these states:

State | Interpretation | 

pending_init | Accepted work has not yet entered its running phase. | 

running | The current task is active; it may be generating, using a tool, or waiting. | 

completed | The turn finished; inspect its final report and evidence. | 

errored | The turn failed; inspect the error before retrying. | 

interrupted | The turn was stopped, not necessarily rolled back. | 

shutdown | The agent has been closed. | 

Completion notifications reach the coordinator. It can wait for an update instead of repeatedly listing agents. A timeout while waiting is not itself proof that the child failed.

wait_agent accepts optional timeout_ms (default 30,000). list_agents accepts optional path_prefix, without a trailing slash, to restrict the tree. Use returned canonical task paths when names are ambiguous. Neither operation starts a fresh child turn.

{"path_prefix":"/root/parser_review"}

These short-lived children are not independent durable conversations. For explicit cross-session creation, reading, messaging and waiting, see persisted sessions. Grok's typed task interface is documented under scheduled work.

Messages versus follow-up tasks

send_message delivers information without starting a new turn when the target is idle. followup_task sends an assignment and starts a turn for an idle child; for a running child, it is delivered at message boundaries. These are different from creating another agent.

Send parser_review this clarification: focus on malformed nested input.
When its review is complete, give that same agent a follow-up task:
rank the proposed tests by regression risk, without editing files.

If a completed agent does not answer an informational message, ask the coordinator to give it a follow-up task. Do not assume every message causes fresh model execution.

Interrupt, resume, and close

Ask the coordinator to interrupt a named child when its current work must stop. interrupt_agent requests cancellation and returns the previous status; that response is not a new completion report. The agent remains available for messages and follow-up tasks.

Interrupt parser_review. Check its resulting status and any files it changed.
Do not restart it until you have reported what completed and what remains uncertain.

Cancellation does not undo edits or an external action that already completed. Inspect the diff, process state, and external service before retrying a mutation. Aborting a root turn also interrupts pending or running child work owned by that turn and discards its queued work; do not treat children as independent services that will necessarily survive cancellation.

Closing is stronger than interrupting: registry shutdown closes the agent and its descendants and releases owned resources. A child-owned worktree is scheduled for cleanup when its owner closes. Preserve and integrate required changes before closure rather than using that worktree as permanent storage. Exact close controls depend on the available dialect and host.

Verify completion and integrate results


- Read the final report and distinguish completed work from suggestions.
- For research, verify important claims against cited files or tool output.
- For implementation, inspect the exact checkout, changed files, and diff.
- Request the precise test commands, exit results, and untested boundaries.
- For a separate worktree, explicitly transfer the reviewed change into the intended branch. Completion does not automatically merge it.
- Run integration checks against the combined result, not only each child's isolated change.

The parallel-changes tutorial demonstrates an explicit review and integration workflow. Keep the coordinating agent responsible for the final result rather than treating several successful reports as proof that the combined application works.

Troubleshooting

Symptom | Next action | 

Spawn rejected by concurrency policy | Inspect active agents and wait for completion or interrupt unnecessary work. Increase the cap only when the host and provider can support it. | 

Child cannot find the parent's new file | Check whether it has a separate worktree and which base it uses. Supply or integrate the required change explicitly. | 

Conflicting edits | Stop overlapping writers, inspect the shared diff, and assign a single integration owner. | 

Model override rejected | Check allowed model IDs and use "none" or a positive integer for fork_turns, not "all". | 

Message sent but no answer | An idle target needs a follow-up task, not only an informational message. | 

Completed report but no changes in the parent | Inspect the child worktree and integration plan. A report is not a merge. | 

Interrupted operation has an uncertain outcome | Inspect local or remote state before retrying. Do not equate cancellation with rollback. |