@heretyc/subagent-mcp 2.8.6 → 2.8.7

package/README.md

@@ -1,136 +1,136 @@
-# subagent-mcp
-
-MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions. Runs on **macOS, Linux, and Windows**.
-
-**No direct API calls.** subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. Claude sessions use the Claude Agent SDK against your local Claude Code executable; Codex sessions use your local `codex app-server`. No API keys.
-
-**License:** Apache-2.0 | **Author:** Lexi Blackburn | **Repo:** https://github.com/Heretyc/subagent-mcp
-
----
-
-## Features
-
-- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
-- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
-- Concurrency caps: 5 concurrent Claude agents + 5 concurrent Codex agents (counts only actively-streaming `processing` agents, to limit API rate-limit pressure; quiet `stalled` agents don't reserve a slot)
-- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet -- thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
-- Ultracode mode for Opus 4.8 -- headless activation via `--settings {"ultracode":true}` (see [docs/usage.md](docs/usage.md))
-- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
-- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
-- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)
-
----
-
-## Quick Start
-
-**Prerequisites:** Node.js >= 18, plus the `claude` and/or `codex` CLIs installed globally and authenticated.
-
-Installed via [GitHub Packages](https://github.com/Heretyc/subagent-mcp/pkgs/npm/subagent-mcp). One-time `.npmrc` setup required (GitHub Packages requires auth even for public packages):
-
-```bash
-# 1. Configure registry for @heretyc scope (once per machine)
-echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
-
-# 2. Authenticate — use a classic PAT with read:packages scope
-echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
-
-# 3. Install and wire
-npm install -g @heretyc/subagent-mcp
-subagent-mcp setup
-```
-
-`setup` detects which vendors are present, registers the MCP server, and writes orchestration-mode hooks. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.
-
-For consumer projects, run `subagent-mcp init --root /path/to/project` to upsert
-the managed invariant block into `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.
-Use `--dry-run` to preview, `--remove` to uninstall the block, and `--force`
-only if you intentionally run inside this source repo.
-
-After setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.
-
-**Updating:** `subagent-mcp update && subagent-mcp setup`
-
-For manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see [docs/registration.md](docs/registration.md).
-
----
-
-## Auto Mode
-
-`launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
-
-`provider`, `model`, and `effort` are optional overrides — omit them to get auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
-
-**task_category** (required) — pick one:
-
-| Category | What it is |
-|---|---|
-| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
-| `security_review` | security verdict, threat assessment, or demonstrated exploit |
-| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
-| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
-| `architecture` | cross-module design/plan, no code, no execution loop |
-| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
-| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
-| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
-| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
-| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
-| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
-| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
-| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
-| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
-| `fallback_default` | no category matches with confidence; prefer splitting work instead |
-
-The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
-
-**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
-
----
-
-## Tools
-
-Six tools are exposed over the stdio MCP transport:
-
-| Tool | Purpose |
-|------|---------|
-| `launch_agent` | Start a new `claude`/`codex` sub-agent session |
-| `poll_agent` | Get status + output tail of one agent |
-| `kill_agent` | Immediately force-kill any live agent |
-| `send_message` | Enqueue a user message on a live session |
-| `list_agents` | List all agents with token-efficient core metrics |
-| `wait` | Block until one or more agents finish, or 15-minute timeout |
-
-Full parameters, return shapes, the `alive` / `idle_seconds` / `hint` / `recent_stream` fields, and `poll_agent`'s last-3 visible-stream items are in [docs/tools.md](docs/tools.md).
-
----
-
-## Agent Lifecycle
-
-Each agent transitions through these states:
-
-| Status | Meaning |
-|--------|---------|
-| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat |
-| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes -- working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
-| `finished` | Current turn completed, or driver exited with code 0 |
-| `errored` | Process exited with non-zero code |
-| `stopped` | Terminated by `kill_agent` |
-
-`processing` and `stalled` are live. `finished` is reportable for `wait`; if `alive` is still true, `send_message` can start the next turn on the same session. A health monitor runs every 10 seconds, and `poll_agent`/`list_agents` additionally reconcile driver exit synchronously. `wait` does not return just because an agent is `stalled`. `stalled` agents recover to `processing` if the visible stream resumes and are never auto-killed -- prefer `wait`/re-poll over `kill_agent`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
-
----
-
-## Documentation
-
-- [docs/registration.md](docs/registration.md) -- per-platform registration (Claude Code, Codex, Gemini), prerequisites, install, config paths.
-- [docs/tools.md](docs/tools.md) -- full Tool Reference for all six tools, including `alive` / `idle_seconds` / `hint` fields.
-- [docs/usage.md](docs/usage.md) -- model & effort matrix, ultracode mechanism, underlying CLI invocations, usage examples.
-- [docs/SPEC.md](docs/SPEC.md) -- full technical specification (architecture, schemas, status lifecycle, error catalogue).
-- [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) -- always-interactive Claude/Codex driver model.
-
----
-
-## License
-
-Apache-2.0 -- Copyright 2026 Lexi Blackburn
-
-See [docs/SPEC.md](docs/SPEC.md) for the full technical specification.
+# subagent-mcp
+
+MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions. Runs on **macOS, Linux, and Windows**.
+
+**No direct API calls.** subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. Claude sessions use the Claude Agent SDK against your local Claude Code executable; Codex sessions use your local `codex app-server`. No API keys.
+
+**License:** Apache-2.0 | **Author:** Lexi Blackburn | **Repo:** https://github.com/Heretyc/subagent-mcp
+
+---
+
+## Features
+
+- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
+- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
+- Concurrency caps: 5 concurrent Claude agents + 5 concurrent Codex agents (counts only actively-streaming `processing` agents, to limit API rate-limit pressure; quiet `stalled` agents don't reserve a slot)
+- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet -- thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
+- Ultracode mode for Opus 4.8 -- headless activation via `--settings {"ultracode":true}` (see [docs/usage.md](docs/usage.md))
+- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
+- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
+- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)
+
+---
+
+## Quick Start
+
+**Prerequisites:** Node.js >= 18, plus the `claude` and/or `codex` CLIs installed globally and authenticated.
+
+Installed via [GitHub Packages](https://github.com/Heretyc/subagent-mcp/pkgs/npm/subagent-mcp). One-time `.npmrc` setup required (GitHub Packages requires auth even for public packages):
+
+```bash
+# 1. Configure registry for @heretyc scope (once per machine)
+echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
+
+# 2. Authenticate — use a classic PAT with read:packages scope
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
+
+# 3. Install and wire
+npm install -g @heretyc/subagent-mcp
+subagent-mcp setup
+```
+
+`setup` detects which vendors are present, registers the MCP server, and writes orchestration-mode hooks. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.
+
+For consumer projects, run `subagent-mcp init --root /path/to/project` to upsert
+the managed invariant block into `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.
+Use `--dry-run` to preview, `--remove` to uninstall the block, and `--force`
+only if you intentionally run inside this source repo.
+
+After setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.
+
+**Updating:** `subagent-mcp update && subagent-mcp setup`
+
+For manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see [docs/registration.md](docs/registration.md).
+
+---
+
+## Auto Mode
+
+`launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
+
+`provider`, `model`, and `effort` are optional overrides — omit them to get auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
+
+**task_category** (required) — pick one:
+
+| Category | What it is |
+|---|---|
+| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
+| `security_review` | security verdict, threat assessment, or demonstrated exploit |
+| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
+| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
+| `architecture` | cross-module design/plan, no code, no execution loop |
+| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
+| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
+| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
+| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
+| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
+| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
+| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
+| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
+| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
+| `fallback_default` | no category matches with confidence; prefer splitting work instead |
+
+The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
+
+**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
+
+---
+
+## Tools
+
+Six tools are exposed over the stdio MCP transport:
+
+| Tool | Purpose |
+|------|---------|
+| `launch_agent` | Start a new `claude`/`codex` sub-agent session |
+| `poll_agent` | Get status + output tail of one agent |
+| `kill_agent` | Immediately force-kill any live agent |
+| `send_message` | Enqueue a user message on a live session |
+| `list_agents` | List all agents with token-efficient core metrics |
+| `wait` | Block until one or more agents finish, or 15-minute timeout |
+
+Full parameters, return shapes, the `alive` / `idle_seconds` / `hint` / `recent_stream` fields, and `poll_agent`'s last-3 visible-stream items are in [docs/tools.md](docs/tools.md).
+
+---
+
+## Agent Lifecycle
+
+Each agent transitions through these states:
+
+| Status | Meaning |
+|--------|---------|
+| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat |
+| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes -- working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
+| `finished` | Current turn completed, or driver exited with code 0 |
+| `errored` | Process exited with non-zero code |
+| `stopped` | Terminated by `kill_agent` |
+
+`processing` and `stalled` are live. `finished` is reportable for `wait`; if `alive` is still true, `send_message` can start the next turn on the same session. A health monitor runs every 10 seconds, and `poll_agent`/`list_agents` additionally reconcile driver exit synchronously. `wait` does not return just because an agent is `stalled`. `stalled` agents recover to `processing` if the visible stream resumes and are never auto-killed -- prefer `wait`/re-poll over `kill_agent`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
+
+---
+
+## Documentation
+
+- [docs/registration.md](docs/registration.md) -- per-platform registration (Claude Code, Codex, Gemini), prerequisites, install, config paths.
+- [docs/tools.md](docs/tools.md) -- full Tool Reference for all six tools, including `alive` / `idle_seconds` / `hint` fields.
+- [docs/usage.md](docs/usage.md) -- model & effort matrix, ultracode mechanism, underlying CLI invocations, usage examples.
+- [docs/SPEC.md](docs/SPEC.md) -- full technical specification (architecture, schemas, status lifecycle, error catalogue).
+- [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) -- always-interactive Claude/Codex driver model.
+
+---
+
+## License
+
+Apache-2.0 -- Copyright 2026 Lexi Blackburn
+
+See [docs/SPEC.md](docs/SPEC.md) for the full technical specification.

package/directives/carryover-claude.md

@@ -1,13 +1,10 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-CARRYOVER>
+<subagent-mcp state="on" kind="carryover">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
-Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with permission). Not enabled THIS session.
+Orchestration ON carried over from a PRIOR session for this project (persists until disabled with user permission). Not enabled THIS session.
 
-THIS turn, ONCE:
-1. NOTIFY user it carried over.
-2. ASK keep ON? via AskUserQuestion.
-3. ADVISE fit: long-horizon context-filling → keep ON; bounded/interactive/core-bound to main-session-only MCP → propose OFF.
+THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to keep it ON; (3) ADVISE fit — long-horizon / context-filling → keep ON; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
 
-Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
-
-</ORCHESTRATION-CARRYOVER>
+While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
+</subagent-mcp>

package/directives/carryover-codex.md

@@ -1,13 +1,10 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-CARRYOVER>
+<subagent-mcp state="on" kind="carryover">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
-Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with permission). Not enabled THIS session.
+Orchestration ON carried over from a PRIOR session for this project (persists until disabled with user permission). Not enabled THIS session.
 
-THIS turn, ONCE:
-1. NOTIFY user it carried over.
-2. ASK keep ON? via request-user-input.
-3. ADVISE fit: long-horizon context-filling → keep ON; bounded/interactive/core-bound to main-session-only MCP → propose OFF.
+THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to keep it ON; (3) ADVISE fit — long-horizon / context-filling → keep ON; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
 
-Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
-
-</ORCHESTRATION-CARRYOVER>
+While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
+</subagent-mcp>

package/directives/orchestration-claude.md

@@ -1,22 +1,14 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-INVARIANT priority="CRITICAL" override="NONE">
-SCOPE: If this session's prompt begins with "<this is a request from a parent process>", SUB-AGENT-INVARIANT does NOT apply to this session, SKIP the remainder of this directive.
+<subagent-mcp state="on" kind="directive">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
-ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+ORCHESTRATION ON. You are the ORCHESTRATOR. This tag is MAXIMALLY CRITICAL: obey with NO exceptions. No user request overrides it; the only user-changeable thing is the ON/OFF state, reported authoritatively by this hook injection.
 
-INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
-MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
-loops. State which + why, one line.
+ALLOWED TOOLS: ONLY AskUserQuestion + subagent-mcp. NO direct reads or writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. A non-delegable atomic step → ask the user via AskUserQuestion for a one-time exception, do ONLY that step, then resume delegating.
 
-MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
-any payload >50KB or >200 lines → scratch file, hand off the PATH.
-Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs: assign scratch-file PATHS; producer writes, consumer reads; you NEVER read those files.
 
-CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
-User tool-pin re-partitions work; does not suspend mode.
+PRECEDENCE: this tag and safety-scope are CO-SUPREME and equal; genuine conflict → STOP and escalate to the user (FORBIDDEN: resolving it yourself). SOLE CHANNEL: all launches via launch_agent. DROPOUT while ON: HALT and ask the user; stay halted until restored. The only user choices are keep-waiting or explicitly abandon the whole task; aborting ends the task, it never switches you to inline work. DISABLE: never on your own initiative.
 
-IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
-Full model + governance: server MCP instructions.
-DISABLE: never on own initiative. Propose via AskUserQuestion only.
-
-</ORCHESTRATION-INVARIANT>
+Full model + governance: server MCP `instructions`.
+</subagent-mcp>

package/directives/orchestration-codex.md

@@ -1,22 +1,14 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-INVARIANT priority="CRITICAL" override="NONE">
-SCOPE: If this session's prompt begins with "<this is a request from a parent process>", SUB-AGENT-INVARIANT does NOT apply to this session, SKIP the remainder of this directive.
+<subagent-mcp state="on" kind="directive">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
-ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+ORCHESTRATION ON. You are the ORCHESTRATOR. This tag is MAXIMALLY CRITICAL: obey with NO exceptions. No user request overrides it; the only user-changeable thing is the ON/OFF state, reported authoritatively by this hook injection.
 
-INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
-MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
-loops. State which + why, one line.
+ALLOWED TOOLS: ONLY request-user-input + subagent-mcp. NO direct reads or writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. A non-delegable atomic step → ask the user via request-user-input for a one-time exception, do ONLY that step, then resume delegating.
 
-MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
-any payload >50KB or >200 lines → scratch file, hand off the PATH.
-Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs: assign scratch-file PATHS; producer writes, consumer reads; you NEVER read those files.
 
-CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
-User tool-pin re-partitions work; does not suspend mode.
+PRECEDENCE: this tag and safety-scope are CO-SUPREME and equal; genuine conflict → STOP and escalate to the user (FORBIDDEN: resolving it yourself). SOLE CHANNEL: all launches via launch_agent. DROPOUT while ON: HALT and ask the user; stay halted until restored. The only user choices are keep-waiting or explicitly abandon the whole task; aborting ends the task, it never switches you to inline work. DISABLE: never on your own initiative.
 
-IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
-Full model + governance: server MCP instructions.
-DISABLE: never on own initiative. Propose via request-user-input only.
-
-</ORCHESTRATION-INVARIANT>
+Full model + governance: server MCP `instructions`.
+</subagent-mcp>

package/directives/reminder-off-claude.md

@@ -1,8 +1,8 @@
 <!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-INVARIANT>
+<subagent-mcp state="off" kind="reminder">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration OFF. 5-CALL RULE: request likely needs >5 tool calls, OR 5th call done with work remaining — STOP, ask via AskUserQuestion whether to switch Orchestration ON. Even OFF, delegating via subagent-mcp auto routing advisable for durable results — calling model not always best fit. Sub-agent sessions: ignore.
+Orchestration OFF. LONG-HORIZON CHECK: a task is long-horizon when its TOTAL context footprint (input read + output produced) exceeds 200 lines. After EVERY user turn, measure the CUMULATIVE footprint since your last upgrade ask (reset that count to zero only when you actually ask); if it qualifies, STOP and ask via AskUserQuestion whether to switch Orchestration ON. Ask on EVERY qualifying turn; a decline does NOT suppress later asks.
 
-WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
-
-</ORCHESTRATION-INVARIANT>
+Even OFF, delegating durable work via subagent-mcp is often advisable — the calling model is not always the best fit. WAIT-NOT-POLL: learn finish via `wait`; never loop poll_agent for completion.
+</subagent-mcp>

package/directives/reminder-off-codex.md

@@ -1,8 +1,8 @@
 <!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-INVARIANT>
+<subagent-mcp state="off" kind="reminder">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration OFF. 5-CALL RULE: request likely needs >5 tool calls, OR 5th call done with work remaining — STOP, ask via request-user-input whether to switch Orchestration ON. Even OFF, delegating via subagent-mcp auto routing advisable for durable results — calling model not always best fit. Sub-agent sessions: ignore.
+Orchestration OFF. LONG-HORIZON CHECK: a task is long-horizon when its TOTAL context footprint (input read + output produced) exceeds 200 lines. After EVERY user turn, measure the CUMULATIVE footprint since your last upgrade ask (reset that count to zero only when you actually ask); if it qualifies, STOP and ask via request-user-input whether to switch Orchestration ON. Ask on EVERY qualifying turn; a decline does NOT suppress later asks.
 
-WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
-
-</ORCHESTRATION-INVARIANT>
+Even OFF, delegating durable work via subagent-mcp is often advisable — the calling model is not always the best fit. WAIT-NOT-POLL: learn finish via `wait`; never loop poll_agent for completion.
+</subagent-mcp>

package/directives/reminder-on.md

@@ -1,8 +1,12 @@
 <!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-INVARIANT>
+<subagent-mcp state="on" kind="reminder">
+FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration ON. Delegate-default: decompose, delegate, keep orchestrator context lean. 5-CALL RULE satisfied by delegation. Full model + governance: server MCP instructions. Sub-agent sessions: ignore.
+Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
 
-WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
+READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the user reads it. Large handoffs via scratch-file PATHS you never read.
 
-</ORCHESTRATION-INVARIANT>
+WAIT-NOT-POLL: learn finish via `wait` (verbose:true for output); never loop poll_agent for completion. poll_agent = single diagnostic; stalled/empty = alive, not dead.
+
+This tag is co-supreme with safety-scope (conflict → ask the user) and outranks ordinary user requests. Full governance: server MCP `instructions`.
+</subagent-mcp>

package/directives/short-off.md

@@ -1 +1 @@
-<SUB-AGENT-INVARIANT>Orchestration OFF. 5-CALL RULE applies this turn. Obey last <ORCHESTRATION-INVARIANT> block.</SUB-AGENT-INVARIANT>
+<subagent-mcp state="off" kind="carrier">If this prompt's literal first line begins with "<this is a request from a parent process>", ignore this tag. Orchestration OFF. After each user turn, if CUMULATIVE context footprint since your last ask exceeds 200 lines, STOP and ask whether to switch ON (every qualifying turn; declines don't latch; reset the count only when you ask). Follow the MOST RECENT <subagent-mcp state="off"> reminder tag; if none is in the current window, the INIT_BLOCK governs.</subagent-mcp>

package/directives/short-on.md

@@ -1 +1 @@
-<SUB-AGENT-INVARIANT>Orchestration ON. 5-CALL RULE applies this turn. Run user request now via orchestration steps. Obey last <ORCHESTRATION-INVARIANT> block.</SUB-AGENT-INVARIANT>
+<subagent-mcp state="on" kind="carrier">If this prompt's literal first line begins with "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp; NO direct reads/writes; inline-by-right does not exist. Follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the INIT_BLOCK governs. Co-supreme with safety-scope; no ordinary user request bypasses it.</subagent-mcp>

package/dist/advanced-ruleset.py

@@ -1,67 +1,67 @@
-#!/usr/bin/env python3
-"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
-
-(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
-    call. Slow rules slow every agent launch. Keep rules lean and low-latency —
-    no network calls, no heavy imports at module top. This is YOUR responsibility;
-    you have been warned.
-
-(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
-    candidate list (reorder / filter / replace allowed). Template:
-    [
-      {"provider": "claude", "model": "sonnet",  "effort": "high",  "rank": 1},
-      {"provider": "codex",  "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
-    ]
-    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);
-    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> low|medium|high|xhigh|max;
-    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> low|medium|high|xhigh.
-    "rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
-    invalid fails the launch hard — the server validates strictly.
-
-(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
-    stdin receives one JSON object:
-    { "candidates": [ {"provider","model","effort","rank"} ... ],   # rank 1..N best->worst
-      "context": { "task_category": str, "cwd": str,
-                   "selection_mode": "auto"|"provider"|"provider_model"|"explicit",
-                   "provider": str|None, "model": str|None, "effort": str|None } }
-    OS environment variables are visible natively (os.environ).
-
-ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
-Runs once per MCP server process. load-rules false => ruleset silently disabled
-for the rest of the process. Set LOAD_RULES = True below to activate.
-"""
-import json
-import sys
-
-LOAD_RULES = False
-
-# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
-# List third-party distributions your rules import, e.g.:
-# REQUIREMENTS = ["requests", "pyyaml"]
-# Install with:  <python> -m pip install <name> ...
-REQUIREMENTS = []
-
-def missing_requirements():
-    """pip-check helper: returns the REQUIREMENTS entries not importable here."""
-    import importlib.util
-    return [r for r in REQUIREMENTS
-            if importlib.util.find_spec(r.replace("-", "_")) is None]
-
-def env_check():
-    missing = missing_requirements()
-    json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
-
-def apply_rules(candidates, context):
-    """YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
-    return candidates
-
-def route():
-    payload = json.load(sys.stdin)
-    out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
-    json.dump(out, sys.stdout)
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1 and sys.argv[1] == "route":
-        route()
-    else:
-        env_check()
+#!/usr/bin/env python3
+"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
+
+(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
+    call. Slow rules slow every agent launch. Keep rules lean and low-latency —
+    no network calls, no heavy imports at module top. This is YOUR responsibility;
+    you have been warned.
+
+(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
+    candidate list (reorder / filter / replace allowed). Template:
+    [
+      {"provider": "claude", "model": "sonnet",  "effort": "high",  "rank": 1},
+      {"provider": "codex",  "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
+    ]
+    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);
+    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
+    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
+    "rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
+    invalid fails the launch hard — the server validates strictly.
+
+(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
+    stdin receives one JSON object:
+    { "candidates": [ {"provider","model","effort","rank"} ... ],   # rank 1..N best->worst
+      "context": { "task_category": str, "cwd": str,
+                   "selection_mode": "auto"|"provider"|"provider_model"|"explicit",
+                   "provider": str|None, "model": str|None, "effort": str|None } }
+    OS environment variables are visible natively (os.environ).
+
+ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
+Runs once per MCP server process. load-rules false => ruleset silently disabled
+for the rest of the process. Set LOAD_RULES = True below to activate.
+"""
+import json
+import sys
+
+LOAD_RULES = False
+
+# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
+# List third-party distributions your rules import, e.g.:
+# REQUIREMENTS = ["requests", "pyyaml"]
+# Install with:  <python> -m pip install <name> ...
+REQUIREMENTS = []
+
+def missing_requirements():
+    """pip-check helper: returns the REQUIREMENTS entries not importable here."""
+    import importlib.util
+    return [r for r in REQUIREMENTS
+            if importlib.util.find_spec(r.replace("-", "_")) is None]
+
+def env_check():
+    missing = missing_requirements()
+    json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
+
+def apply_rules(candidates, context):
+    """YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
+    return candidates
+
+def route():
+    payload = json.load(sys.stdin)
+    out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
+    json.dump(out, sys.stdout)
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "route":
+        route()
+    else:
+        env_check()