Subagents

The parent explicitly lists immediate children in agent.md:

subagents:
  - researcher
  - coder

Each child is a complete nested MD-first surface at subagents/<name>/agent.md, with optional skills/, plugins/, sandbox/, and nested subagents/. An unlisted directory is inert. The child compiles recursively and receives an isolated durable run and conversation-scoped control state.

Durable learned skills and reusable memory are isolated by the same recursive surface path. Learning created during a researcher run is available to future researcher runs and is not exposed to the parent or sibling subagents. The child declares its own mutability ceiling in agent.md, and runtime skill writes automatically stay in the child's scope.

Child runs automatically inherit the parent's canonical principal, initiator, project, and metadata. Its declarative composition rules and plugin tool contexts can therefore apply the same role policy, and user-subject connections resolve for the same person. Credentials are never copied into the child run.

---
id: researcher
description: Use this subagent for scoped research tasks.
model: openrouter/openai/gpt-5.4-mini
reasoning: low
maxReasoning: low
mutability: static
---

# Researcher

Research only the delegated question and return cited findings.

The description is parent-facing when-to-use guidance. Every child selects its own model in its agent.md; model selection does not implicitly inherit from the parent.

Child capabilities come from its own plugins and skills. The execution host, durable adapter, and blob adapter remain owned by the deployed root service; state, memory, workspaces, and credentials are isolated by the child's stable surface path. A child can select its own sandbox profile, output schema, mutability ceiling, model, reasoning, and iteration limits.

A child may declare schedules and event automations in its own agent.md. They appear in resolved inspection under names such as researcher/morning-brief, use namespaced idempotency and lifecycle references, and execute on the child surface. A scheduled child therefore receives the child's instructions, tools, hooks, context, memory scope, and saved default outbound route rather than the parent's.

It does not inherit executable plugins or agent-specific skills from its parent. Select a shared published plugin in both agent.md files when both surfaces need the same capability.

Exposing And Invoking A Subagent

One or more immediate child folders automatically expose one framework-owned delegate tool on their parent surface. Its agent field is restricted to the enabled immediate-child names in the current capability snapshot, and its description includes each child's parent-facing description. Nested children appear only in the delegate tool on their immediate parent. The runtime checks the selected name against the snapshot and relative surface again at execution, so delegate cannot address an arbitrary path or a sibling agent.

The model-facing call is:

{
  "agent": "researcher",
  "task": "Summarize the three most recent issues and create a review workbook.",
  "expectedOutput": "A concise summary plus the staged workbook.",
  "deliverables": [
    { "kind": "file", "description": "Issue review workbook" }
  ],
  "constraints": ["Read-only: do not comment on issues."]
}

Use deliverables whenever the child must return a file or a hosted page/link. Each entry is { kind: "file" | "link", description: string }. The declaration turns artifact return into a runtime-checked contract instead of relying on a path or URL in the child's prose.

For every file, the child must call handoff_artifact with the exact /workspace/... path. The tool reads the exact bytes, stores them privately, and records their size and SHA-256 without selecting user delivery. A hosted page or UI must come from a verified publication tool that records its canonical HTTPS delivery link. The runtime then returns a compact handoff object to the parent, without private blob coordinates. Each handed-off file is also indexed for that parent run at a read-only /files/handoffs/<child-run-id>/... path. The parent can use normal file reads, listing, or grep against that path when a root-owned follow-up action needs the contents; copy it into /workspace only when it must be edited. The exact path remains readable to later root turns in the same conversation, including after a fresh sandbox is created: the runtime authorizes the source child again and rehydrates its byte-verified private blob from the durable handoff receipt. To attach the unchanged child file, the root calls deliver_artifact with the exact /files/handoffs/... path. Other conversations and child surfaces cannot resolve that resource. The child-local /workspace path is never exposed as though it belonged to the parent. Unselected workspace files are never swept into the handoff or final response.

If a declared deliverable is missing, unreadable, corrupt, or not published, the runtime rejects the handoff and resumes the same child once with the exact failure and retry instructions. A second failure ends the child run with subagent.handoff_failed; the parent sees that failure instead of receiving a successful result with a dropped artifact. The normal Pi continuation makes the retry durable across the child boundary.

Root agents can add "background": true to return from delegate immediately. The child run is durable and executes outside the root turn. While it is active, later root turns receive a compact activeWork prompt-context summary. When it finishes, the runtime queues a new turn in the original conversation; the root agent reads the result and owns the user-facing response. Any verified handoff receipt is adopted into that new root turn before it runs, so it can inspect, transform, or explicitly deliver the child files before its final reply. Final channel delivery uses only files the root selected without reopening the child sandbox. The completion message names the parent-readable /files/handoffs path when the root needs to inspect or consume the file before replying. Child agents never deliver that response directly.

Recovering A Child Run

A child that fails keeps its sandbox session, workspace files, and durable continuation. delegate accepts resumeRunId to continue that run instead of starting a new one:

{ "agent": "analyst", "resumeRunId": "...", "task": "Hand off the workbook you already built." }

The agent must match the original child, the run must belong to the current conversation, and the resumed turn runs inline even when the original ran in the background. A failed delegate result and a background failure turn both carry a recovery instruction naming the run id, because re-sending the original task instead creates a new child on an empty workspace and pays for finished work twice. The resume rides the child's continuation checkpoint; if none was persisted the runtime says so and a fresh delegation is the only option.

Root surfaces with subagents also receive manage_work:

{ "operation": "list" }
{ "operation": "status", "runId": "..." }
{ "operation": "cancel", "runId": "..." }

These operations are scoped to background work from the current conversation, so a run ID cannot be used to inspect or cancel another conversation's work. Nested subagent delegation remains synchronous; only the root can start background work.

delegate is reserved for this framework-owned dispatcher and cannot be replaced by a plugin contribution. Plugin-authored tools may call ctx.spawnSubagent(...) directly:

await ctx.spawnSubagent({
  name: "researcher",
  task: "Summarize the three most recent issues and create a review workbook.",
  expectedOutput: "A concise summary plus the staged workbook.",
  deliverables: [{ kind: "file", description: "Issue review workbook" }],
  constraints: ["Read-only: do not comment on issues."]
});

A child that creates files must select a sandbox profile in its own agent.md; sandbox selection does not inherit from the parent surface.

Realtime services remain connections and typed tools, not child-agent engines. The runtime enforces connection authorization and tool approvals independently for the child.

Filesystem scope is recursive and non-inheriting:

agent/plugins/                                      # root only
agent/subagents/researcher/plugins/                 # researcher only
agent/subagents/researcher/subagents/verifier/plugins/ # verifier only

Put reusable execution code in a published plugin. Each surface's plugin selection or checked-in local plugin is the auditable declaration that it exposes that authority.

Related Docs

• MD-First Agents
• Connections
• Tools
• Runtime And Deployment