ollie/prompts/tools-subagent.md

subagent_generate & subagent_spawn

Spawn independent subagent sessions with JIT-generated identities via echo JSON | subagent_generate | xargs subagent_spawn.

Trigger condition: a task decomposes into independent subtasks each requiring multi-step reasoning or multiple tool calls; you are processing N items with the same operation; or the current agent's identity would work against the quality of a subtask — delegate to an agent whose identity is aligned with it.

Calling convention:

execute_code: steps=[{code: "echo '{\"prompt\": \"IDENTITY\"}' | subagent_generate | xargs -I {} subagent_spawn -name 'NAME' -agent {} 'TASK'"}]

Parallel — use {parallel: [...]}, each entry an independent pipeline:

execute_code: steps=[{parallel: [
  {code: "echo '{\"prompt\": \"IDENTITY_A\"}' | subagent_generate | xargs -I {} subagent_spawn -name 'a' -agent {} 'TASK_A'"},
  {code: "echo '{\"prompt\": \"IDENTITY_B\"}' | subagent_generate | xargs -I {} subagent_spawn -name 'b' -agent {} 'TASK_B'"}
]}]

Returns: subagent_generate returns the agent config name. subagent_spawn returns the session path (e.g. s/my-session).

subagent_generate

No stdin prints the template. With JSON on stdin, creates a JIT agent config inheriting hooks and tooling from default.json with a clean prompt (SYSTEM_PROMPT + identity only).

Field	Required	Description
name	no	Config name (default: jit-<hex>)
prompt	yes	Complete identity: role, roster, shared task, coordination protocol

The prompt must include:

• Role: who this agent is and what it does
• Roster: complete name → task mapping of all peers, (you) marking this agent
• Shared task: beads issue ID or tracking entry
  • Coordination protocol: clear mechanics for interaction. Must define a lead or a decision path (e.g., "Reviewer A proposes, Reviewer B approves; if B objects, A has final say") to prevent consultative deadlocks. Include specific triggers and prompt file targets.

subagent_spawn

Flag	Default	Description
-name NAME	auto	Session name
-agent A	server default	Agent config name (from subagent_generate)
-backend B	server default	Backend override
-model M	server default	Model override
-cwd DIR	pwd	Working directory

Remaining args: the task prompt (immediate task only — coordination lives in the identity).

Constraints:

• Always use the pipeline. Never call subagent_spawn without subagent_generate.
• Identity carries coordination, prompt carries task. Roster, shared task, and protocol go in the identity. The seed prompt is purely the task.
• Subagents do not share memory. Pass context explicitly in the seed prompt.
• subagent_spawn auto-injects [parent_session_id=...] and [session_id=...] headers — the child knows its own ID and the parent's address.
• Peers are known at spawn time. Assign -name to each and include the full roster in each identity.
• Write to s/{sid}/prompt to communicate with any session. Subagents signal completion by writing results to s/{parent-sid}/prompt.
• Names must be globally unique under s/. Duplicate names fail silently.
• Clean up when done: rm $OLLIE/a/<name>.json