Skip to content

Reference

Subagent policies and recovery

Use the subagent guide to choose a lifetime. This reference describes Subagent.make, Subagent.layer, the background action tools, and Subagent.reporting.

Option Default Caller contract
target Required Definition Child owns instructions, input/output schemas, and toolkit
parameters Child input Schema Model-facing delegation input
prepareInput Validate input as child input Receives bounded parent metadata, never its transcript
success { output, budgetExhausted } Schema for the parent’s result
projectResult Wrap child output Validate and bound what crosses back to the parent
failure Schema.Never Declared application failure data
failureMode "error" "return" exposes expected delegation failures as data
needsApproval Absent Approves establishment only

Subagent.layer captures the child model and services at construction. An explicit model or Binding can override the surrounding model. Custom projections must retain exhaustion information when partial output matters to the parent.

Return mode contains expected failures; defects and interruption retain their Effect meaning. Durable waiting remains suspension. Durable child failures use bounded SubagentExecutionFailure data; mapChildFailure maps expected failures on the ephemeral path only. Decode contained failures with the declaration’s containedFailure Schema.

Setting Default or behavior
Child policy fields Omitted fields inherit the parent’s resolved policy; declaration ceilings then clamp them
Delegation policy Omission derives a shared child pool from parent limits
Explicit SubagentPolicy Sets per-child ceilings; aggregate caps multiply by maxChildren
parentCaps on the handler Layer Optional shared aggregate pool; declarations in one parent Run must agree
descendantInvocations Zero when omitted
parentReserveDuration Zero; accepts a finite, nonnegative Effect Duration input
Token and cost caps Optional; missing usage never creates budget credit

Each parent Run has its own delegation pool, separate from its execution counters. In-process pools are released after the Run and its attached children finish cleanup. Durable accounting conservatively charges reservations when usage is unavailable. The child’s resolved policy sets its tool allowance; a larger budget requires a fresh delegation. See budgets.

In-process attached children are also capped by the parent’s remaining deadline. Set parentReserveDuration: "30 seconds" on SubagentPolicy and failureMode: "return" on the declaration to leave time to handle a SubagentBudgetExhausted result and finish. Calls that reach their execution slot without remaining time fail before spawning a child. The default reserves no final-answer time; durable attached children and background workers do not use this reserve.

Grant field Default Effect
allowedToolNames Target’s declared tool names Intersection narrows visible and executable tools
maxDepth 1 Root-relative ceiling; a direct child is depth one
childLifetimes Both when omitted Restricts attached/background descendants

Parent tools do not become child tools. Resource access still needs handler authorization.

Nested work needs permitted tool names, depth, lifetime, invocation slots, and remaining allocation. Descendants share the reserved subtree allowance after the child’s own execution ceiling is accounted for. More depth alone does not fund a grandchild. Handoff is unsupported.

source-subtree funding uses the selected source Run’s allowance. Root programmatic starts without selected input default to worker-run funding, which requires WorkerBudgetAuthorizer; its default denies. Models cannot select funding scope. Joined input shares the active Run’s budget. A host concurrency ceiling limits active workers separately from per-Run tool concurrency.

startTool, followUpTool, inspectTool, summaryTool, listTool, and cancelTool each return { tool, layer }. Pass a delegation and install the operations the parent needs.

Operation or option Caller limit
start / followUp Retained delivery status, then destination receipt; reuse keys after uncertainty
inspect Supply exactly one message reference or receipt
await Programmatic only; interruption detaches the waiter
cancel One exact receipt
stop Permanently seals the worker; does not undo external actions
Assignment lifecycle Typed completion seals only after latest accepted input is applied

Worker summaries report unknown when unresolved operations park a Run. This state is not active progress; reconcile the original operations before retrying external effects.

Pass Subagent.reporting(delegation) in the parent registration’s reporting array to send standard completion messages. Its optional pure reportCompletion and reportUpdate predicates filter notifications. Registration captures projection services independently of attempt Layers; each projection receives a fresh Scope. Child settlement, delivery acceptance, and parent processing are distinct. Programmatic reporting requires the exact sourceSubmissionId supplying parent context. Reports cannot target an attached child’s nonexistent continuing inbox.

An Agent’s updates Schema defines emit_update findings independently of final output. AgentUpdates.emit uses a stable Run-scoped key; changed payloads conflict. AgentUpdates.observe decodes accepted updates. Acceptance retains the finding; it does not prove parent delivery. Native update recovery reuses that acceptance under the original call identity. A recovery sweep can also close an accepted update previously marked unknown without replaying it.