This repository has been archived on 2026-08-16. You can view files and clone it, but cannot push or open issues or pull requests.

2.5 KiB

Raw Blame History

Subagent Tools

Spawn independent subagent sessions with JIT-generated identities.

Trigger condition: a task decomposes into independent subtasks needing multi-step reasoning; you are processing N items with the same operation; or the current agent's identity would work against subtask quality.

subagent_generate

Generate a JIT agent config. No args prints the template. With JSON input, creates the config and prints the agent name.

Calling convention:

pipe: stages=[
  {tool: "subagent_generate", args: ["JSON_CONFIG"]},
  {tool: "subagent_spawn", args: ["-name", "NAME", "TASK"]}
]

JSON_CONFIG fields:

Field	Required	Description
`role`	yes*	Who this agent is and what it does
`roster`	no	Name → task mapping of all peers, `(you)` marking this agent
`shared_task`	no	Tracking entry or issue ID
`protocol`	no	Coordination mechanics
`constraints`	no	Array of constraint strings
`name`	no	Config name (default: `jit-<hex>`)
`prompt`	yes*	Legacy: complete identity as a single string

*One of role or prompt required. Prefer role.

subagent_spawn

Spawn a session, submit a prompt, return immediately.

Calling convention:

call_tool: calls=[{tool: "subagent_spawn", args: ["-name", "NAME", "TASK"]}]
call_tool: calls=[{tool: "subagent_spawn", args: ["-name", "NAME", "-agent", "AGENT", "-backend", "B", "-model", "M", "TASK"]}]

Flags: -name NAME, -agent A, -backend B, -model M, -cwd DIR.

Returns: session, path, backend, model as KV lines.

Auto-injects into the prompt: [parent_session_id=...], [session_id=...], and parent plan contents.

Returning results to the parent

Subagents write to s/{parent_session_id}/prompt when done:

[from={session_id}]
STATUS: done|blocked|partial
SUMMARY: <what was accomplished>
ARTIFACTS: <paths written, omit if none>
OPEN: <unresolved items, omit if none>

Critical: the parent must NEVER actively wait for results. No statewait, no polling. After spawning, continue work or end your turn. Results queue automatically.

Constraints

Identity carries coordination, prompt carries task. Roster/protocol go in the identity. The spawn prompt is purely the task.
Subagents do not share memory. Pass context explicitly in the seed prompt.
Names must be globally unique under s/. Prefix with parent session ID is automatic.
For simple delegation with no identity requirements, subagent_spawn alone with -agent or defaults is fine.

2.5 KiB Raw Blame History