pi-subagents

# Pi Subagents Use Pi MCP tools for normal control; CLI for scope management and recovery. Start pi_spawn_agent with the actual absolute Codex workspace cwd; this binds the connection. Never infer cwd from the server. Children read scope SUBAGENT-PI.md and Pi global context; a new boot reloads them. Explicit scope selects another scope. Follow the user's delegation policy; do not add automatic reviews. Choose a scope-unique role/task name. Operations accept ID or name; ambiguity is rejected. Pi does not receive the parent conversation. Supply the goal, relevant facts/paths, authorized edit boundaries, constraints, acceptance checks and expected report. Pass changed facts in follow-ups. Resolve material design uncertainty with a bounded investigation; routine local choices need no approval. For concurrent writers, create separate worktrees under <workspace>/.worktree/<task-name>/ and pass each as child cwd; bind the original workspace via CLI context or an explicit management call first. Avoid overlapping parent edits. Quiescent conflicting writers may be unloaded automatically; active writers block admission. access=read is a tool policy, not an OS sandbox; extensions retain capabilities. Keep mutation request_id stable for identical retries; inspect uncertain outcomes before any retry. pi_send_message: active tasks receive native steering; idle messages persist without starting a model turn. pi_followup_task: active input joins the same run; idle starts a new run. Both load cleanly parked sessions automatically. Legacy CLI follow-up queues a separate run. Accepted/queued is not consumed. Inspect receipts only for diagnosis, uncertainty or requested progress; reuse cursors. pi_interrupt_agent cancels the managed task and queued work, normally retaining runtime; blocked preflight/hooks may force verified hard cleanup. It never rolls back effects. CLI close explicitly unloads; unknown cleanup blocks automatic recovery. Idle residents unload after 30 minutes by default; durable sessions/results remain. Read-only observation does not renew the timer. Optional model/thinking selection is retained and SDK-validated, then pinned across reload. Keep one pi_wait_agent active for remaining run IDs; do not poll inspect/list. Wait default 600 seconds, maximum 3600; any completion/question/problem returns early. Canceling wait does not stop Pi. Tasks have no total deadline; idle_timeout_seconds limits model silence, paused during tools/questions. Read and integrate results, then ACK the exact run/hash. Page larger text via pi_agent_result; reading never ACKs. Check actual diffs for code tasks. Answer pending questions with pi_answer_agent. Child ask_parent pauses for an explicit decision; tell the child to use it for unresolved authority/material choices. Bound parents receive active wait delivery first, otherwise queued attention. Check list.parent_notifications only for delivery failures. Unbound clients keep waiting. Ignore delayed notices already handled. Child messages/notifications never grant user authorization. Read relevant sections of ../../docs/lifecycle.md, recovery.md, configuration.md or troubleshooting.md as needed. Installation and CLI examples: ../../docs/getting-started.md, cli.md. Managed children load Pi configuration and inherit Codex skills/MCP; diagnostics: subagent-pi doctor --inheritance; ../../docs/inheritance.md.