@heretyc/subagent-mcp 2.12.11 → 2.12.13

package/README.md

@@ -1,170 +1,170 @@
-# subagent-mcp
-
-[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
-[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
-
-## Core Premise
-
-subagent-mcp is an MCP stdio server that turns an AI coding assistant (Claude
-Code, Codex, Gemini CLI) into a manager of local Claude and Codex sub-agents on
-macOS, Linux, and Windows. It drives the locally authenticated `claude` and
-`codex` CLIs you already signed into. It does not make direct HTTP API calls and
-does not require API keys.
-
-The orchestrator monitors but does not read or write project files itself. Work
-is delegated to fresh sub-agents, so the orchestrator keeps summaries instead
-of raw file context. The main invariants are:
-
-- one machine-global, provider-agnostic concurrency cap (default 20, minimum 10)
-- fail-safe orchestration ON on hookless hosts
-- state authority only from harness-verified `<subagent-mcp state="...">` tags
-- sub-agents gated by default with permission ceiling `auto`
-- automatic model, provider, and effort routing per task category
-
-## Install
-
-### What You Need First
-
-- Node.js 18 or newer (`node --version`)
-- `claude` CLI, installed and signed in (`claude --version`)
-- `codex` CLI, installed and signed in (`codex --version`; optional if you only
-  use Claude)
-
-Building from source needs extra developer tools. See
-[CONTRIBUTING.md](CONTRIBUTING.md).
-
-### Install The Package
-
-```bash
-npm install -g @heretyc/subagent-mcp
-```
-
-This is the standard install. Organizations pinning the package through GitHub
-Packages should see [docs/registration.md](docs/registration.md).
-
-### Wire It Into Your Assistant
-
-```bash
-subagent-mcp setup
-```
-
-Installing the package only ships the program. It does not connect anything on
-its own. `subagent-mcp setup` finds your Claude Code or Codex install and
-registers both the server and the per-turn orchestration hooks. Preview first
-with `subagent-mcp setup --dry-run`.
-
-### Restart, Then Turn On The Invariant
-
-Restart your Claude Code or Codex session so it picks up the new tools. On
-Codex, run `/hooks` and trust the new hook. Then, recommended:
-
-```bash
-subagent-mcp init --global
-```
-
-This writes a managed "always delegate" rule block into your global assistant
-config once. For one project only, use
-`subagent-mcp init --root /path/to/project`. Full per-platform wiring (Gemini
-CLI, Claude Desktop, manual setup) is in
-[docs/registration.md](docs/registration.md).
-
-## How To Operate It
-
-### Orchestration Mode
-
-- **ON**: your assistant acts as a pure manager. It delegates every step to
-  sub-agents. Best for big, long-running jobs.
-- **OFF**: your assistant works normally, with no delegation rules.
-
-Flip it with the `orchestration-mode` tool. Desktop apps can toggle the mode but
-do not receive per-turn hook reminders.
-
-### Tools
-
-The server exposes `launch_agent`, `poll_agent`, `kill_agent`, `send_message`,
-`list_agents`, `wait`, `respond_permission`, `orchestration-mode`, and
-`model-selection-mode`. See [docs/tools.md](docs/tools.md) for the full
-parameter and return reference.
-
-You do not have to choose a model. Give `launch_agent` a prompt and a task
-category such as `coding`, `debugging`, or `security_review`; the server picks
-the provider, model, and effort.
-
-### Concurrency
-
-There is one machine-wide limit on concurrent sub-agents. The default is 20.
-When the limit is reached, `launch_agent` is rejected immediately and does not
-queue. Change the value in `global-subagent-mcp-config.jsonc` in the install
-folder. The file is re-read on every launch.
-
-The config file was renamed from `global-concurrency.jsonc` in 2.12.5. The old
-name is still read, with a one-time deprecation notice, when the new file is
-absent.
-
-The same settings file includes `checkForUpdates` (default `true`). Disable it
-with `checkForUpdates: false` or `SUBAGENT_UPDATE_CHECK=0`.
-
-## Configuration
-
-Machine-wide defaults live in `global-subagent-mcp-config.jsonc`, installed
-beside the compiled server and re-read on every `launch_agent`. It controls the
-global concurrency cap, update checks, permission ceiling, escalation behavior,
-strict read-parity logging, and Codex sandbox networking.
-
-User and repo permission files can only tighten or add scoped permissions on top
-of the global ceiling. See [README/configuration.md](README/configuration.md)
-for the full key table, precedence rules, and mode summary.
-
-## Permissions
-
-Launched sub-agents run gated by default. Set `permissionsCeiling` in
-`global-subagent-mcp-config.jsonc`:
-
-| Mode | What a sub-agent can do |
-|---|---|
-| `auto` | Default. Safe reads auto-allow, dangerous actions auto-deny, everything else parks for your decision. |
-| `manual` | Same, but every non-denied action parks for a decision. |
-| `yolo` | No gating at all. |
-
-When a sub-agent's action parks, its status becomes `permission_requested` and
-it appears in `poll_agent`, `list_agents`, and `wait`. Answer it with:
-
-```text
-respond_permission(agent_id="...", decision="allow" | "deny", reason="...")
-```
-
-One-time only. Omit `request_id` to answer the oldest pending request.
-Unanswered requests auto-deny after 5 minutes. Full spec:
-[docs/spec/permissions.md](docs/spec/permissions.md).
-
-## Basic Debugging
-
-- **An agent looks stuck.** A quiet agent is usually still alive. After about 10
-  minutes with no output an agent is marked `stalled`. Prefer `wait` or another
-  `poll_agent` over killing it.
-- **Cap reached.** Use `list_agents` to see what is running and `kill_agent` on
-  work you no longer need. Raising `globalConcurrentSubagents` also works.
-- **Logs.** Agent output is available through `poll_agent`. Server diagnostics
-  go to the host MCP server log on stderr.
-
-## Documentation
-
-| Document | Contents |
-|---|---|
-| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Design rationale |
-| [docs/registration.md](docs/registration.md) | Per-platform setup |
-| [docs/tools.md](docs/tools.md) | Tool reference |
-| [docs/usage.md](docs/usage.md) | Model and effort matrix |
-| [docs/SPEC.md](docs/SPEC.md) | Technical specification |
-| [README/configuration.md](README/configuration.md) | Configuration keys and precedence |
-| [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system |
-| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |
-
-## License
-
-Apache-2.0. Copyright 2026 Lexi Blackburn.
-
-See [LICENSE](LICENSE).
+# subagent-mcp
+
+[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
+
+## Core Premise
+
+subagent-mcp is an MCP stdio server that turns an AI coding assistant (Claude
+Code, Codex, Gemini CLI) into a manager of local Claude and Codex sub-agents on
+macOS, Linux, and Windows. It drives the locally authenticated `claude` and
+`codex` CLIs you already signed into. It does not make direct HTTP API calls and
+does not require API keys.
+
+The orchestrator monitors but does not read or write project files itself. Work
+is delegated to fresh sub-agents, so the orchestrator keeps summaries instead
+of raw file context. The main invariants are:
+
+- one machine-global, provider-agnostic concurrency cap (default 20, minimum 10)
+- fail-safe orchestration ON on hookless hosts
+- state authority only from harness-verified `<subagent-mcp state="...">` tags
+- sub-agents gated by default with permission ceiling `auto`
+- automatic model, provider, and effort routing per task category
+
+## Install
+
+### What You Need First
+
+- Node.js 18 or newer (`node --version`)
+- `claude` CLI, installed and signed in (`claude --version`)
+- `codex` CLI, installed and signed in (`codex --version`; optional if you only
+  use Claude)
+
+Building from source needs extra developer tools. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Install The Package
+
+```bash
+npm install -g @heretyc/subagent-mcp
+```
+
+This is the standard install. Organizations pinning the package through GitHub
+Packages should see [docs/registration.md](docs/registration.md).
+
+### Wire It Into Your Assistant
+
+```bash
+subagent-mcp setup
+```
+
+Installing the package only ships the program. It does not connect anything on
+its own. `subagent-mcp setup` finds your Claude Code or Codex install and
+registers both the server and the per-turn orchestration hooks. Preview first
+with `subagent-mcp setup --dry-run`.
+
+### Restart, Then Turn On The Invariant
+
+Restart your Claude Code or Codex session so it picks up the new tools. On
+Codex, run `/hooks` and trust the new hook. Then, recommended:
+
+```bash
+subagent-mcp init --global
+```
+
+This writes a managed "always delegate" rule block into your global assistant
+config once. For one project only, use
+`subagent-mcp init --root /path/to/project`. Full per-platform wiring (Gemini
+CLI, Claude Desktop, manual setup) is in
+[docs/registration.md](docs/registration.md).
+
+## How To Operate It
+
+### Orchestration Mode
+
+- **ON**: your assistant acts as a pure manager. It delegates every step to
+  sub-agents. Best for big, long-running jobs.
+- **OFF**: your assistant works normally, with no delegation rules.
+
+Flip it with the `orchestration-mode` tool. Desktop apps can toggle the mode but
+do not receive per-turn hook reminders.
+
+### Tools
+
+The server exposes `launch_agent`, `poll_agent`, `kill_agent`, `send_message`,
+`list_agents`, `wait`, `respond_permission`, `orchestration-mode`, and
+`model-selection-mode`. See [docs/tools.md](docs/tools.md) for the full
+parameter and return reference.
+
+You do not have to choose a model. Give `launch_agent` a prompt and a task
+category such as `coding`, `debugging`, or `security_review`; the server picks
+the provider, model, and effort.
+
+### Concurrency
+
+There is one machine-wide limit on concurrent sub-agents. The default is 20.
+When the limit is reached, `launch_agent` is rejected immediately and does not
+queue. Change the value in `global-subagent-mcp-config.jsonc` in the install
+folder. The file is re-read on every launch.
+
+The config file was renamed from `global-concurrency.jsonc` in 2.12.5. The old
+name is still read, with a one-time deprecation notice, when the new file is
+absent.
+
+The same settings file includes `checkForUpdates` (default `true`). Disable it
+with `checkForUpdates: false` or `SUBAGENT_UPDATE_CHECK=0`.
+
+## Configuration
+
+Machine-wide defaults live in `global-subagent-mcp-config.jsonc`, installed
+beside the compiled server and re-read on every `launch_agent`. It controls the
+global concurrency cap, update checks, permission ceiling, escalation behavior,
+strict read-parity logging, and Codex sandbox networking.
+
+User and repo permission files can only tighten or add scoped permissions on top
+of the global ceiling. See [README/configuration.md](README/configuration.md)
+for the full key table, precedence rules, and mode summary.
+
+## Permissions
+
+Launched sub-agents run gated by default. Set `permissionsCeiling` in
+`global-subagent-mcp-config.jsonc`:
+
+| Mode | What a sub-agent can do |
+|---|---|
+| `auto` | Default. Safe reads auto-allow, dangerous actions auto-deny, everything else parks for your decision. |
+| `manual` | Same, but every non-denied action parks for a decision. |
+| `yolo` | No gating at all. |
+
+When a sub-agent's action parks, its status becomes `permission_requested` and
+it appears in `poll_agent`, `list_agents`, and `wait`. Answer it with:
+
+```text
+respond_permission(agent_id="...", decision="allow" | "deny", reason="...")
+```
+
+One-time only. Omit `request_id` to answer the oldest pending request.
+Unanswered requests auto-deny after 5 minutes. Full spec:
+[docs/spec/permissions.md](docs/spec/permissions.md).
+
+## Basic Debugging
+
+- **An agent looks stuck.** A quiet agent is usually still alive. After about 10
+  minutes with no output an agent is marked `stalled`. Prefer `wait` or another
+  `poll_agent` over killing it.
+- **Cap reached.** Use `list_agents` to see what is running and `kill_agent` on
+  work you no longer need. Raising `globalConcurrentSubagents` also works.
+- **Logs.** Agent output is available through `poll_agent`. Server diagnostics
+  go to the host MCP server log on stderr.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Design rationale |
+| [docs/registration.md](docs/registration.md) | Per-platform setup |
+| [docs/tools.md](docs/tools.md) | Tool reference |
+| [docs/usage.md](docs/usage.md) | Model and effort matrix |
+| [docs/SPEC.md](docs/SPEC.md) | Technical specification |
+| [README/configuration.md](README/configuration.md) | Configuration keys and precedence |
+| [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system |
+| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |
+
+## License
+
+Apache-2.0. Copyright 2026 Lexi Blackburn.
+
+See [LICENSE](LICENSE).

package/directives/carryover-claude.md

@@ -1,5 +1,4 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE : BINDING, NON-NEGOTIABLE -->
-<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 ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
@@ -7,4 +6,3 @@ Orchestration ON carried over from a PRIOR session for this project (per-session
 THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to REMAIN enabled; (3) ADVISE fit : long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
 
 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 jointly binding with safety-scope; conflict → ask the user.
-</subagent-mcp>

package/directives/carryover-codex.md

@@ -1,5 +1,4 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE : BINDING, NON-NEGOTIABLE -->
-<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 ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
@@ -7,4 +6,3 @@ Orchestration ON carried over from a PRIOR session for this project (per-session
 THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit : long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
 
 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 jointly binding with safety-scope; conflict → ask the user.
-</subagent-mcp>

package/directives/handoff-claude.md

@@ -0,0 +1,7 @@
+You are at or above 50% context utilization. Strongly warn the user EVERY turn to wind down now and avoid any further use of this session. There is no exemption for small work or non-big work.
+
+`handoff-write` is unlocked. Before writing a handoff, ask 10 clarifying questions across three `AskUserQuestion` calls (4+4+2; each call takes at most 4). Use the answers to shape a precise `/goal` prompt for the next session.
+
+Before acting on `handoff-read`, confirm intent with exactly 5 structured questions in one `AskUserQuestion` call.
+
+After a successful `handoff-read`, only this reading session gets the saved handoff appended verbatim to LONG reminders every 5th turn. Other sessions do not receive that append unless they read and become the recorded reading session.

package/directives/handoff-codex.md

@@ -0,0 +1,7 @@
+You are at or above 50% context utilization. Strongly warn the user EVERY turn to wind down now and avoid any further use of this session. There is no exemption for small work or non-big work.
+
+`handoff-write` is unlocked. Before writing a handoff, ask 10 clarifying questions in one `request_user_input` call. Use the answers to shape a precise `/goal` prompt for the next session.
+
+Before acting on `handoff-read`, confirm intent with exactly 5 structured questions in one `request_user_input` call.
+
+After a successful `handoff-read`, only this reading session gets the saved handoff appended verbatim to LONG reminders every 5th turn. Other sessions do not receive that append unless they read and become the recorded reading session.

package/directives/latch-claude.md

@@ -0,0 +1,5 @@
+15% LATCH COACHING. Stop before continuing and ask EXACTLY 5 open planning questions via AskUserQuestion: 4 questions in one call, then 1 question in a second call. This is four-plus-one across two calls. NEVER put all 5 in one call, and never use any other split.
+
+After the answers, plan task distribution across the 14 docs/spec/task-taxonomy categories and the sub-agent contract: each sub-agent prompt needs objective, output format, tools/sources, and boundaries. Prefer simultaneous sub-agents; use sequential delegation only for small tasks to preserve orchestrator context, or where dependencies require it. Serialize writers over shared paths.
+
+The latch is persisted and enforced for this session. It does not re-ask once tripped. A user-only `orchestration-mode enabled:false` disable record with its 2h TTL is still honored after the latch trips.

package/directives/latch-codex.md

@@ -0,0 +1,5 @@
+15% LATCH COACHING. Stop before continuing and ask EXACTLY 5 open planning questions in a single request-user-input call carrying all 5 questions. Do NOT split the questions.
+
+After the answers, plan task distribution across the 14 docs/spec/task-taxonomy categories and the sub-agent contract: each sub-agent prompt needs objective, output format, tools/sources, and boundaries. Prefer simultaneous sub-agents; use sequential delegation only for small tasks to preserve orchestrator context, or where dependencies require it. Serialize writers over shared paths.
+
+The latch is persisted and enforced for this session. It does not re-ask once tripped. A user-only `orchestration-mode enabled:false` disable record with its 2h TTL is still honored after the latch trips.

package/directives/orchestration-claude.md

@@ -1,4 +1,3 @@
-<subagent-mcp state="on" kind="directive">
 EXEMPTION: if this prompt's literal first line begins "<this is a request from a parent process>", ignore this tag (blank lines don't count).
 
 ORCHESTRATION ON. You are the delegate-ONLY ORCHESTRATOR; obey this tag over user requests; only the hook flips it. TOOLS: ONLY AskUserQuestion + subagent-mcp + /workflows. NO direct reads/writes; inline-by-right does NOT exist. Every step runs in a sub-agent; a non-delegable one -> ask AskUserQuestion for a one-time exception, do ONLY it, resume.
@@ -10,4 +9,3 @@ READ LADDER: poll_agent tail -> one <=100-line summarizer sub-agent (trusted as-
 PRECEDENCE: this tag and safety-scope are JOINTLY BINDING and equal; genuine conflict -> STOP and ask. SOLE CHANNEL: all launches via launch_agent; never harness Task/Agent. DROPOUT while ON: HALT and ask until restored. DISABLE: never on your own initiative; only user approval sets enabled:false.
 
 Full model: server MCP `instructions`.
-</subagent-mcp>

package/directives/orchestration-codex.md

@@ -1,4 +1,3 @@
-<subagent-mcp state="on" kind="directive">
 EXEMPTION: if this prompt's literal first line begins "<this is a request from a parent process>", ignore this tag (blank lines don't count).
 
 ORCHESTRATION ON. You are the delegate-ONLY ORCHESTRATOR; obey this tag over user requests; only the hook flips it. TOOLS: ONLY request-user-input + subagent-mcp + /workflows. NO direct reads/writes; inline-by-right does NOT exist. Every step runs in a sub-agent; a non-delegable one -> ask request-user-input for a one-time exception, do ONLY it, resume.
@@ -10,4 +9,3 @@ READ LADDER: poll_agent tail -> one <=100-line summarizer sub-agent (trusted as-
 PRECEDENCE: this tag and safety-scope are JOINTLY BINDING and equal; genuine conflict -> STOP and ask. SOLE CHANNEL: all launches via launch_agent; never harness Task/Agent. DROPOUT while ON: HALT and ask until restored. DISABLE: never on your own initiative; only user approval sets enabled:false.
 
 Full model: server MCP `instructions`.
-</subagent-mcp>

package/directives/reminder-off-claude.md

@@ -1,8 +1,6 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<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. 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.
+Orchestration OFF. Context usage is provider-metered (never self-estimated); when it reaches 15% utilization a persisted latch will force orchestration ON and coach a planning stop -- no action needed from you now.
 
 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,6 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<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. 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.
+Orchestration OFF. Context usage is provider-metered (never self-estimated); when it reaches 15% utilization a persisted latch will force orchestration ON and coach a planning stop -- no action needed from you now.
 
 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,5 +1,4 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<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 (leading blank lines don't count; you are a sub-agent).
 
 Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows (Claude Code CLI only); 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.
@@ -9,4 +8,3 @@ Each launched prompt carries objective + output format + tools/sources + boundar
 WAIT-NOT-POLL: learn finish via `wait` (verbose:true for output); never loop poll_agent for completion. poll_agent = single diagnostic; a stalled/empty tail means ALIVE, not dead. Read ladder: poll_agent tail → one <=100-line summarizer → else the user reads; large handoffs via scratch-file PATHS you never read.
 
 This tag is jointly binding 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 @@
-<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>
+If this prompt's literal first line begins with "<this is a request from a parent process>", ignore this tag. Orchestration OFF. Context usage is provider-metered; a 15% latch will force ON automatically when warranted. Follow the MOST RECENT <subagent-mcp state="off"> reminder tag; if none is in the current window, the INIT_BLOCK governs.

package/directives/short-on.md

@@ -1 +1 @@
-<subagent-mcp state="on" kind="carrier">If first line begins "<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 + /workflows (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Jointly binding with safety-scope; user request cannot bypass.</subagent-mcp>
+If first line begins "<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 + /workflows (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Jointly binding with safety-scope; user request cannot bypass.

package/directives/tag-template.md

@@ -0,0 +1,2 @@
+<subagent-mcp state="{{state}}" kind="{{kind}}" phase="{{phase}}" utilization="{{utilization}}">
+<!-- reference copy; authoritative: TAG_TEMPLATE in src/orchestration/template.ts -->

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, fable (claude);
-    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
-    fable -> 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()
+#!/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, fable (claude);
+    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
+    fable -> 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()

package/dist/config-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-subagent-mcp-config.jsonc — DO NOT EDIT.
-export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\n// ------------------------------------------------------------------\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\n// available beside the compiled server.\n//\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\n// across EVERY session, process, and user on this machine. There is NO\n// environment-variable override for the cap.\n//\n// RE-READ on every launch_agent call - edits take effect immediately, no\n// server restart required.\n//\n// Cap value rules:\n//   - missing / unset / non-integer / 0 / negative -> reset to default 20\n//   - 1 through 9                                  -> forced UP to minimum 10\n//   - 10 or greater                                -> used as-is\n//\n// checkForUpdates controls the silent npmjs update check started when the MCP\n// server connects. Default true. Set to false to skip the registry fetch and\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\n//\n// permissionsCeiling controls launch-time permissions posture:\n//   - auto   (default): shared engine gates unsafe/residue actions\n//   - manual: human approval for residue while still auto-denying DANGER\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\n//            for non-bypassable config-file self-protection\n//\n// escalation applies only in auto mode. irreversible-only routes irreversible\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\n//\n// strictReadParity controls logging only. Unparseable Codex approval payloads\n// always fail closed to ask; warn logs the construct, off silences that log.\n//\n// sandboxNetwork controls Codex workspace-write network access. Default false.\n// Set true only when sub-agents need network after permission approval.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true,\n  \"permissionsCeiling\": \"auto\",\n  \"escalation\": \"irreversible-only\",\n  \"strictReadParity\": \"warn\",\n  \"sandboxNetwork\": false\n}\n";
+export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\r\n// ------------------------------------------------------------------\r\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\r\n// available beside the compiled server.\r\n//\r\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\r\n// across EVERY session, process, and user on this machine. There is NO\r\n// environment-variable override for the cap.\r\n//\r\n// RE-READ on every launch_agent call - edits take effect immediately, no\r\n// server restart required.\r\n//\r\n// Cap value rules:\r\n//   - missing / unset / non-integer / 0 / negative -> reset to default 20\r\n//   - 1 through 9                                  -> forced UP to minimum 10\r\n//   - 10 or greater                                -> used as-is\r\n//\r\n// checkForUpdates controls the silent npmjs update check started when the MCP\r\n// server connects. Default true. Set to false to skip the registry fetch and\r\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\r\n//\r\n// permissionsCeiling controls launch-time permissions posture:\r\n//   - auto   (default): shared engine gates unsafe/residue actions\r\n//   - manual: human approval for residue while still auto-denying DANGER\r\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\r\n//            for non-bypassable config-file self-protection\r\n//\r\n// escalation applies only in auto mode. irreversible-only routes irreversible\r\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\r\n//\r\n// strictReadParity controls logging only. Unparseable Codex approval payloads\r\n// always fail closed to ask; warn logs the construct, off silences that log.\r\n//\r\n// sandboxNetwork controls Codex workspace-write network access. Default false.\r\n// Set true only when sub-agents need network after permission approval.\r\n{\r\n  \"globalConcurrentSubagents\": 20,\r\n  \"checkForUpdates\": true,\r\n  \"permissionsCeiling\": \"auto\",\r\n  \"escalation\": \"irreversible-only\",\r\n  \"strictReadParity\": \"warn\",\r\n  \"sandboxNetwork\": false\r\n}\r\n";