@heretyc/subagent-mcp 2.8.1 → 2.8.3

package/README.md

@@ -17,7 +17,7 @@ MCP server that launches and manages locally installed `claude` and `codex` CLI
 - 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 an orchestrator-only directive that the bundled Claude Code / Codex plugin injects every turn via its `UserPromptSubmit` hook (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)
+- `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)
 
 ---
 
@@ -39,11 +39,16 @@ npm install -g @heretyc/subagent-mcp
 subagent-mcp setup
 ```
 
-`setup` detects which vendors are present, registers the MCP server, and writes the `UserPromptSubmit` hook for orchestration-mode injection. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.
+`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:** `npm install -g @heretyc/subagent-mcp && subagent-mcp setup`
+**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).
 

package/directives/carryover-claude.md

@@ -1,17 +1,13 @@
-<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-CARRYOVER priority="CRITICAL" override="NONE">
-
-ORCHESTRATION MODE was ON at session start — carried over from a PRIOR session
-for this project (persists until disabled with permission). Not enabled in 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, or
-   core-bound to main-session-only MCP → propose OFF.
-
-Declines → orchestration-mode enabled:false. NEVER disable on own initiative.
-After answer: handshake done — do not re-raise.
-
-</ORCHESTRATION-CARRYOVER>
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER>
+
+Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with 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.
+
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
+
+</ORCHESTRATION-CARRYOVER>

package/directives/carryover-codex.md

@@ -1,17 +1,13 @@
-<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<ORCHESTRATION-CARRYOVER priority="CRITICAL" override="NONE">
-
-ORCHESTRATION MODE was ON at session start — carried over from a PRIOR session
-for this project (persists until disabled with permission). Not enabled in 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, or
-   core-bound to main-session-only MCP → propose OFF.
-
-Declines → orchestration-mode enabled:false. NEVER disable on own initiative.
-After answer: handshake done — do not re-raise.
-
-</ORCHESTRATION-CARRYOVER>
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER>
+
+Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with 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.
+
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
+
+</ORCHESTRATION-CARRYOVER>

package/directives/orchestration-claude.md

@@ -1,14 +1,22 @@
-<!-- INJECTED PRE-PROMPT DIRECTIVE - BINDING, NON-NEGOTIABLE -->
-<SUB-AGENT-INVARIANT priority="CRITICAL" override="NONE">
-ORCHESTRATION MODE ON: ORCHESTRATOR; default=DELEGATE.
-
-INLINE BY RIGHT only for main-session-only capability: user interaction/consent, agent control, tiny audits, final git/PR, irreducible verify loops. State which+why. Direct tool calls spend main context; keep to that set.
-
-Clarification/consent: subagents surface questions to orchestrator. Orchestrator asks with AskUserQuestion, sends answer back. Question/gate/audit duty does not justify adjacent discovery or edits inline.
-
-MUST DELEGATE/OFFLOAD: pure compute; implementation/integration edits; mixed tasks split. One MCP-bound step never makes all inline. Payload >50KB or >200 lines -> scratch path (%TEMP% or /tmp), hand off PATH. Orchestrator audits diffs/results before commit.
-
-CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default. Tool-pin repartitions work, does not suspend mode. IPC=temp scratch files only. Full model/governance: server MCP instructions.
-
-DISABLE: never on own initiative. Propose via AskUserQuestion only; disable only after explicit user permission.
-</SUB-AGENT-INVARIANT>
+<!-- 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.
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+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.
+
+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.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+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>

package/directives/orchestration-codex.md

@@ -1,15 +1,22 @@
-<SUB-AGENT-INVARIANT priority="CRITICAL" override="NONE">
-SCOPE: if prompt begins "<this is a request from a parent process>", skip rest.
-
-ORCHESTRATION MODE ON: ORCHESTRATOR; default=DELEGATE.
-
-INLINE BY RIGHT only for main-session-only capability: user interaction/consent, agent control, tiny audits, final git/PR, irreducible verify loops. State which+why. Direct calls spend main context; keep to that set.
-
-Clarification/consent: subagents surface questions to orchestrator. Orchestrator asks with request-user-input, sends answer back. Question/gate/audit duty does not justify adjacent discovery or edits inline.
-
-MUST DELEGATE/OFFLOAD: pure compute; implementation/integration edits; mixed tasks split. One MCP-bound step never makes all inline. Payload >50KB or >200 lines -> scratch path (%TEMP% or /tmp), hand off PATH. Orchestrator audits diffs/results before commit.
-
-CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default. Tool-pin repartitions work, does not suspend mode. IPC=temp scratch files only. Full governance: server MCP instructions.
-
-DISABLE: never on own initiative. Propose via request-user-input only; disable only after explicit permission.
-</SUB-AGENT-INVARIANT>
+<!-- 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.
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+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.
+
+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.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+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>

package/directives/reminder-off-claude.md

@@ -1,12 +1,8 @@
-<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-REMINDER-INVARIANT>
-
-ORCHESTRATION OFF. 5-CALL RULE: if the request likely needs >5 tool calls, OR
-your 5th call completes with work remaining — STOP, ask via AskUserQuestion
-whether to switch orchestration mode ON. Even while OFF, delegating via
-subagent-mcp full-auto routing (per-category, latest benchmark data) is
-advisable for well-rounded, durable results — do not assume the calling model
-is always the best fit. Why this exists: agents grind through large work
-without ever considering orchestration. Sub-agent sessions: ignore this block.
-
-</ORCHESTRATION-REMINDER-INVARIANT>
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
+<ORCHESTRATION-INVARIANT>
+
+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.
+
+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>

package/directives/reminder-off-codex.md

@@ -1,12 +1,8 @@
-<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-REMINDER-INVARIANT>
-
-ORCHESTRATION OFF. 5-CALL RULE: if the request likely needs >5 tool calls, OR
-your 5th call completes with work remaining — STOP, ask via request-user-input
-whether to switch orchestration mode ON. Even while OFF, delegating via
-subagent-mcp full-auto routing (per-category, latest benchmark data) is
-advisable for well-rounded, durable results — do not assume the calling model
-is always the best fit. Why this exists: agents grind through large work
-without ever considering orchestration. Sub-agent sessions: ignore this block.
-
-</ORCHESTRATION-REMINDER-INVARIANT>
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
+<ORCHESTRATION-INVARIANT>
+
+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.
+
+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>

package/directives/reminder-on.md

@@ -1,15 +1,8 @@
-<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
-<ORCHESTRATION-REMINDER-INVARIANT>
-
-ORCHESTRATION ON. Delegate-default: decompose; delegate; keep orchestrator
-context lean. The 5-CALL RULE is satisfied by delegation.
-Subagents may ask for clarification/consent through the orchestrator; answers
-return to subagents. Questions, gates, and audits do not justify adjacent
-inline discovery/edits. Orchestrator tool use is limited to user interaction,
-agent control, tiny audits, final git/PR actions, and irreducible verify loops.
-Implementation/integration edits remain delegated by default; audit before
-commit.
-<SUB-AGENT-INVARIANT> governance applies — full model: server MCP instructions.
-Sub-agent sessions: ignore this block.
-
-</ORCHESTRATION-REMINDER-INVARIANT>
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
+<ORCHESTRATION-INVARIANT>
+
+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.
+
+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>

package/directives/short-off.md

@@ -0,0 +1 @@
+<SUB-AGENT-INVARIANT>Orchestration OFF. 5-CALL RULE applies this turn. Obey last <ORCHESTRATION-INVARIANT> block.</SUB-AGENT-INVARIANT>

package/directives/short-on.md

@@ -0,0 +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>

package/dist/hooks/orchestration-claude-pretool.js

@@ -0,0 +1,41 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { runClaudePreTool, } from "../orchestration/pretool.js";
+/**
+ * Claude Code PreToolUse hook entry. Enforces deterministic subagent-mcp
+ * routing only while the server heartbeat is fresh; stale/missing heartbeat is
+ * fail-open so a broken MCP server never traps the user.
+ */
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+async function main() {
+    let payload = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim()) {
+            payload = JSON.parse(raw);
+        }
+    }
+    catch {
+        payload = {};
+    }
+    const result = runClaudePreTool(payload, process.env);
+    if (result) {
+        process.stdout.write(JSON.stringify(result));
+    }
+    process.exit(0);
+}
+const isMain = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+if (isMain) {
+    void main();
+}

package/dist/hooks/orchestration-claude.js

@@ -1,6 +1,7 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { countJsonlType, runHook, } from "../orchestration/hook-core.js";
+import { resetToolCount } from "../orchestration/pretool.js";
 /**
  * Claude Code UserPromptSubmit hook entry. Reads the JSON payload from stdin,
  * runs the provider-agnostic core with the Claude adapter, and writes the
@@ -42,11 +43,23 @@ export const claudeAdapter = {
         return countJsonlType(transcriptPath, "user");
     },
     fullDirectiveFile: "orchestration-claude.md",
-    offTurnFile: "off-turn-reminder.md",
+    shortOnFile: "short-on.md",
+    shortOffFile: "short-off.md",
     carryoverDirectiveFile: "carryover-claude.md",
     reminderOnFile: "reminder-on.md",
     reminderOffFile: "reminder-off-claude.md",
 };
+export function runClaudeHook(payload, env, adapter = claudeAdapter) {
+    try {
+        if (!adapter.isSubagent(payload, env)) {
+            resetToolCount(payload);
+        }
+        return runHook(payload, env, adapter);
+    }
+    catch {
+        return "";
+    }
+}
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -71,7 +84,7 @@ async function main() {
     }
     let out = "";
     try {
-        out = runHook(payload, process.env, claudeAdapter);
+        out = runClaudeHook(payload, process.env, claudeAdapter);
     }
     catch {
         out = "";

package/dist/hooks/orchestration-codex.js

@@ -58,7 +58,8 @@ export const codexAdapter = {
         return countJsonlType(transcriptPath, "turn_context");
     },
     fullDirectiveFile: "orchestration-codex.md",
-    offTurnFile: "off-turn-reminder.md",
+    shortOnFile: "short-on.md",
+    shortOffFile: "short-off.md",
     carryoverDirectiveFile: "carryover-codex.md",
     reminderOnFile: "reminder-on.md",
     reminderOffFile: "reminder-off-codex.md",

package/dist/index.js

@@ -3,9 +3,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { spawn, spawnSync, execSync } from "child_process";
-import { unlinkSync, existsSync, realpathSync, readFileSync } from "node:fs";
+import { unlinkSync, existsSync, realpathSync, readFileSync, writeFileSync } from "node:fs";
 import { randomUUID } from "crypto";
 import { isAbsolute, basename, join, dirname } from "node:path";
+import { tmpdir } from "node:os";
 import { pathToFileURL } from "url";
 import { buildCommand } from "./effort.js";
 import { resolveExeFor } from "./platform.js";
@@ -17,6 +18,7 @@ import { loadRoutingTable, buildCandidates, validatePresence, TASK_CATEGORIES, A
 import { createDeadlockWindow } from "./deadlock.js";
 import { createRulesetGate, RULESET_HARD_FAIL_MSG, } from "./ruleset.js";
 import * as orchestrationMarker from "./orchestration/marker.js";
+import { startLivenessHeartbeat } from "./orchestration/liveness.js";
 const agents = new Map();
 const MAX_CLAUDE = 5;
 const MAX_CODEX = 5;
@@ -114,13 +116,16 @@ reconcileInterval.unref();
 // initialize (per the MCP spec the initialize result has an `instructions`
 // field) rather than re-injecting it on every turn. The bundled per-turn hook
 // injects only a small compact reminder; this is the durable, full explanation.
-const ORCHESTRATION_INSTRUCTIONS = "ORCHESTRATION MODE (orchestration-mode tool). WHAT: per-project toggle for LONG-HORIZON work that would fill the context window if run inline. OPERATING MODEL: when ON, act as a workflow orchestrator, delegate-default — decompose and delegate/offload by default. INLINE BY RIGHT: steps bound to main-session-only capability may stay inline (MCP tools sub-agents can't inherit, interactive/consent tools, tight verify loops); state which and why. MUST DELEGATE/OFFLOAD: pure compute and any payload >50KB or >200 lines go via temp scratch-file path handoff (%TEMP% on Windows, /tmp on POSIX); keep the orchestrator context lean. CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default. A user tool-pin re-partitions work; it does not suspend mode. PERSISTENCE: enabling writes a per-project marker that PERSISTS across restarts/sessions until disabled with explicit user permission (does NOT reset on a new session). CARRYOVER: if mode was already ON at session start (inherited), the bundled hook prepends a CARRYOVER notice ONCE per marker; you MUST tell the user it auto-activated, ask whether to keep it ON, and advise whether it fits this session's request. DISABLE: never disable on your own initiative — only with EXPLICIT user permission. You MAY propose disabling when task fit is wrong (bounded, interactive, or MCP-bound). Either way, first explain WHAT mode is and WHY, then request permission via the provider tool: AskUserQuestion on Claude, request-user-input on Codex. Only explicit approval may call orchestration-mode enabled:false; if declined, continue under inline-by-right, ask once per topic, never re-nag. Per-turn injection fires only in CLI hosts loading the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).";
+const ORCHESTRATION_INSTRUCTIONS = "BINDING IN BOTH MODES - SOLE CHANNEL: while this server is connected, EVERY sub-agent launch goes through launch_agent; harness Task/Agent tools AND any other spawn path (shell claude -p/codex exec, skills) FORBIDDEN. 5-CALL RULE: >5 tool calls needed for the request (all turns, no reset), or >5 already spent? If yes you MUST use orchestration mode + this server; OFF -> ask the user before enabling, a decline authorizes inline for that request. ORCHESTRATION MODE (orchestration-mode tool). WHAT: per-project toggle for LONG-HORIZON work that would fill the context window inline. OPERATING MODEL: when ON you are a delegate-default orchestrator: decompose, DELEGATE/offload; EVERY reply starts: route: delegate|inline - <reason>. MUST DELEGATE/OFFLOAD: pure compute; any payload >50KB or >200 lines via temp scratch-file path handoff (%TEMP% / /tmp); mixed = SPLIT (one MCP-bound step != whole-task inline); keep the orchestrator context lean. INLINE BY RIGHT - the ONLY exemption: steps bound to main-session-only capability (non-inheritable MCP tools, interactive/consent tools, verify loops = re-run existing checks); state which and why. CONFLICT ORDER: safety-scope > user instruction this turn > 5-CALL RULE/delegate-default. User tool-pin re-partitions work; never suspends mode. PERSISTENCE: per-project marker; survives restarts/sessions until disabled with user permission. CARRYOVER: inherited-ON gets a notice ONCE per marker; you MUST tell the user it auto-activated, ask keep ON?, advise fit. DISABLE: never on own initiative. You MAY propose it on task-fit mismatch (bounded/interactive/MCP-bound): explain WHAT+WHY, ask via AskUserQuestion (Claude) / request-user-input (Codex); only explicit approval may call orchestration-mode enabled:false. Declined -> continue under inline-by-right; ask once per topic, never re-nag. Per-turn injection: CLI hosts with bundled hook only; desktop hosts toggle the marker but inject nothing.";
+const SUBAGENT_INSTRUCTIONS = "SUB-AGENT SESSION: you are a child process launched by subagent-mcp. Follow the parent prompt. Do not treat yourself as the orchestrator, do not re-trigger orchestration carryover, and do not launch further sub-agents unless the parent prompt explicitly assigns that.";
 const server = new McpServer({
     name: "subagent-mcp",
     version: "2.3.9",
     description: "Spawns the LOCALLY INSTALLED `claude` and `codex` CLI binaries as child processes. Does NOT call the Anthropic or OpenAI HTTP APIs directly (no API keys, no SDK) and there are no plans to — all model access is via the local CLIs.",
 }, {
-    instructions: ORCHESTRATION_INSTRUCTIONS,
+    instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"
+        ? SUBAGENT_INSTRUCTIONS
+        : ORCHESTRATION_INSTRUCTIONS,
 });
 // Best-effort removal of a candidate's temp ultracode settings file after a
 // LAUNCH-TIME failure (the agentState is never registered, so the close handler
@@ -389,14 +394,14 @@ function sameTriples(a, b) {
     return a.every((c, i) => c.provider === b[i].provider && c.model === b[i].model && c.effort === b[i].effort);
 }
 // Tool 1: launch_agent
-server.tool("launch_agent", "Spawn a sub-agent. AUTO MODE (preferred): pass only `prompt` + `task_category`; the server picks the best provider/model/effort for that category from its routing table, launches the top candidate, and silently falls back to the next-best on launch failure. `provider`/`model`/`effort` are OPTIONAL overrides — omit for auto-selection; if you pass `model` you must also pass `provider`, and if you pass `effort` you must pass both `provider` and `model`. Unsure which task_category fits? Don't submit one amorphous task — SPLIT into atomic steps that each map to a single category, one agent per step. ultracode effort is Opus-4.8+ only (induced via a temp `--settings {\"ultracode\":true}` file; the CLI rejects `--effort ultracode`). Each sub-agent is a separate claude/codex CLI child that does NOT inherit this session's MCP servers; children run with env SUBAGENT_MCP_SUBAGENT=1 so the orchestration hooks skip them (they are not orchestrators and don't re-trigger carryover). Launch returns status `processing` (alive); a later `stalled` is alive-but-quiet (thinking or awaiting a temp-file handoff), NOT dead — wait or re-poll, don't kill (see poll_agent). DEADLOCK RULE: you MUST ALWAYS set `deadlock=true` when more than 2 launch attempts have already been made for the SAME atomic task (i.e. the 3rd attempt onward), and NEVER otherwise.", {
+server.tool("launch_agent", "Spawn a sub-agent. AUTO MODE (mandatory first attempt unless an override is licensed below): pass only `prompt` + `task_category` and NO overrides; the server picks the best provider/model/effort for that category from its routing table, launches the top candidate, and silently falls back to the next-best on launch failure. `provider`/`model`/`effort` are overrides — licensed on 1st/2nd attempts ONLY when the task verifiably requires a specific capability; STATE that capability when overriding; if you pass `model` you must also pass `provider`, and if you pass `effort` you must pass both `provider` and `model`. SOLE CHANNEL: while this server is connected this tool is the ONLY sanctioned way to spawn sub-agents, in BOTH orchestration states — harness-native Task/Agent tools are FORBIDDEN for sub-agent launches. PROMPT RULE: the FIRST line of every `prompt` MUST be \"<this is a request from a parent process>\" (sub-agent self-identification). Unsure which task_category fits? Don't submit one amorphous task — SPLIT into atomic steps that each map to a single category, one agent per step. ultracode effort is Opus-4.8+ only (induced via a temp `--settings {\"ultracode\":true}` file; the CLI rejects `--effort ultracode`). Each sub-agent is a separate claude/codex CLI child that does NOT inherit this session's MCP servers; children run with env SUBAGENT_MCP_SUBAGENT=1 so the orchestration hooks skip them (they are not orchestrators and don't re-trigger carryover). Launch returns status `processing` (alive); a later `stalled` is alive-but-quiet (thinking or awaiting a temp-file handoff), NOT dead — wait or re-poll, don't kill (see poll_agent). DEADLOCK RULE: you MUST ALWAYS set `deadlock=true` when 2 launch attempts for the SAME atomic task have already failed or been unsatisfactory (the 3rd attempt onward; re-wording or re-splitting the prompt does NOT make it a different task), and NEVER otherwise — from the 3rd attempt deadlock outranks any capability override: drop provider/model/effort.", {
     task_category: z.enum(TASK_CATEGORIES).describe(TASK_CATEGORY_GLOSS),
     prompt: z.string().min(1),
     provider: z.enum(["claude", "codex"]).optional(),
     model: z.enum(["haiku", "sonnet", "opus", "opus-4-8", "gpt-5.5"]).optional(),
     effort: z.enum(["low", "medium", "high", "xhigh", "max", "ultracode"]).optional(),
     cwd: z.string().optional(),
-    deadlock: z.boolean().optional().describe("MANDATE: ALWAYS set deadlock=true when, and ONLY when, more than 2 launch attempts have already been made for the SAME atomic task — the 3rd attempt onward. NEVER set it on a 1st or 2nd attempt, NEVER for a different task, NEVER speculatively. Auto mode only: cannot be combined with provider/model/effort. Passing false is identical to omitting it."),
+    deadlock: z.boolean().optional().describe("MANDATE: ALWAYS set deadlock=true when, and ONLY when, 2 launch attempts for the SAME atomic task have already failed or been unsatisfactory — the 3rd attempt onward. Re-wording the prompt does NOT make it a different task; splitting a failed task does NOT reset attempts for its unchanged parts; re-launching for the same deliverable means the prior attempt COUNTS as failed/unsatisfactory ('partial progress' is not an exemption). NEVER set it on a 1st or 2nd attempt, NEVER for a different task, NEVER speculatively. Auto mode only: cannot be combined with provider/model/effort — from the 3rd attempt deadlock outranks any capability override, so drop those params. Passing false is identical to omitting it."),
 }, async (params) => {
     const { task_category, provider, model, effort, prompt, deadlock } = params;
     const agentCwd = params.cwd || process.cwd();
@@ -858,7 +863,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a terminal state
     };
 });
 // Tool 7: orchestration-mode
-server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF, omit = query current state. The FULL operating model + governance is carried in this server's MCP `instructions` (read once at initialize) — this is the operational summary only; do not act on the mode without that detail. WHAT: a per-project toggle for LONG-HORIZON work that would fill the context window if run to completion inline; when ON, act as an orchestrator with delegate-default, but steps bound to main-session-only capability stay INLINE BY RIGHT (state which + why). PERSISTENCE: a per-project marker keyed by cwd; absence of the marker = OFF = no injection; once ON it persists across restarts/sessions until a permitted disable (it does NOT reset on a new session). CARRYOVER: if ON was inherited from a PRIOR session (provenance = carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker, never per turn) — you MUST then notify the user it auto-activated and confirm whether to keep it ON. DISABLE: never on your own initiative; you MAY PROPOSE turning it OFF on task-fit mismatch, but only EXPLICIT user permission (AskUserQuestion on Claude, request-user-input on Codex) may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).", {
+server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF, omit = query current state. SOLE CHANNEL: the subagent MCP is the ONLY sanctioned channel for launching sub-agents whether this mode is ON or OFF, and the 5-CALL RULE (>5 tool calls needed for the request — all turns, no reset — or >5 already spent → ON: delegate via the subagent MCP; OFF: ask the user before enabling) binds in BOTH states — toggling OFF lifts neither obligation. The FULL operating model + governance is carried in this server's MCP `instructions` (read once at initialize) — this is the operational summary only; do not act on the mode without that detail. WHAT: a per-project toggle for LONG-HORIZON work that would fill the context window if run to completion inline; when ON, act as an orchestrator with delegate-default, but steps bound to main-session-only capability stay INLINE BY RIGHT (state which + why). PERSISTENCE: a per-project marker keyed by cwd; absence of the marker = OFF = no injection; once ON it persists across restarts/sessions until a permitted disable (it does NOT reset on a new session). CARRYOVER: if ON was inherited from a PRIOR session (provenance = carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker, never per turn) — you MUST then notify the user it auto-activated and confirm whether to keep it ON. DISABLE: never on your own initiative; you MAY PROPOSE turning it OFF on task-fit mismatch, but only EXPLICIT user permission (AskUserQuestion on Claude, request-user-input on Codex) may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).", {
     enabled: z.boolean().optional(),
 }, async (params) => {
     const cwd = process.cwd();
@@ -898,22 +903,26 @@ if (isMain) {
         "",
         "  (no command)       start the MCP stdio server (how vendor CLIs run it)",
         "  setup [--dry-run]  wire Claude Code CLI / Codex CLI (--dry-run: preview only)",
+        "  init, --init [flags]",
+        "                     upsert project instruction-file invariant blocks",
+        "                     flags: --dry-run --remove --force --root <dir> --files <csv> --copilot --cursor",
         "  doctor             check install and wiring health",
-        "  --update           update to the latest release (npm install -g)",
-        "  --version, -v      print the installed version",
-        "  --help, -h         show this help",
+        "  update, --update   update to the latest release (npm install -g)",
+        "  version, --version, -v",
+        "                     print the installed version",
+        "  help, --help, -h   show this help",
     ].join("\n");
     // dist/index.js -> ../package.json (the installed package manifest).
     const readPkg = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    if (arg === "--version" || arg === "-v") {
+    if (arg === "version" || arg === "--version" || arg === "-v") {
         console.log(readPkg().version);
         process.exit(0);
     }
-    if (arg === "--help" || arg === "-h") {
+    if (arg === "help" || arg === "--help" || arg === "-h") {
         console.log(usage);
         process.exit(0);
     }
-    if (arg === "--update") {
+    if (arg === "update" || arg === "--update") {
         const pkg = readPkg();
         const npmArgs = ["install", "-g", `${pkg.name}@latest`];
         console.log(`subagent-mcp ${pkg.version} -> npm ${npmArgs.join(" ")}`);
@@ -924,25 +933,70 @@ if (isMain) {
         // next to node_modules\npm). POSIX spawns the npm executable directly.
         const { findOnPath, resolveCmdShimNodeScript } = await import("./setup.js");
         const npm = findOnPath("npm") ?? "npm";
-        let r;
-        if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(npm)) {
+        const spawnNpm = (args, stdio) => {
             const sibling = join(dirname(npm), "node_modules", "npm", "bin", "npm-cli.js");
-            const js = resolveCmdShimNodeScript(npm) ?? (existsSync(sibling) ? sibling : null);
-            r = js
-                ? spawnSync(process.execPath, [js, ...npmArgs], { stdio: "inherit" })
-                : // Last resort: cmd.exe via shell. The arg vector is a fixed literal
-                    // list (safe charset only), so there is no quoting/injection surface.
-                    spawnSync("npm", npmArgs, { stdio: "inherit", shell: true });
+            if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(npm)) {
+                const js = resolveCmdShimNodeScript(npm) ?? (existsSync(sibling) ? sibling : null);
+                return js
+                    ? spawnSync(process.execPath, [js, ...args], {
+                        stdio: stdio === "pipe" ? ["ignore", "pipe", "pipe"] : stdio,
+                        encoding: stdio === "pipe" ? "utf8" : undefined,
+                    })
+                    : // Last resort: cmd.exe via shell. The arg vector is a fixed literal
+                        // list (safe charset only), so there is no quoting/injection surface.
+                        spawnSync("npm", args, {
+                            stdio: stdio === "pipe" ? ["ignore", "pipe", "pipe"] : stdio,
+                            shell: true,
+                            encoding: stdio === "pipe" ? "utf8" : undefined,
+                        });
+            }
+            return spawnSync(npm, args, {
+                stdio: stdio === "pipe" ? ["ignore", "pipe", "pipe"] : stdio,
+                encoding: stdio === "pipe" ? "utf8" : undefined,
+            });
+        };
+        const npmRoot = spawnNpm(["root", "-g"], "pipe");
+        if (npmRoot.error || npmRoot.status !== 0) {
+            console.error(`update failed to resolve npm global root: ${npmRoot.error?.message ?? npmRoot.stderr?.toString().trim() ?? "npm root -g failed"}`);
+            process.exit(npmRoot.status ?? 1);
         }
-        else {
-            r = spawnSync(npm, npmArgs, { stdio: "inherit" });
+        const installRoot = join(npmRoot.stdout.toString().trim(), ...pkg.name.split("/"));
+        const rulesetPath = join(installRoot, "dist", "advanced-ruleset.py");
+        let previousRuleset = null;
+        if (existsSync(rulesetPath)) {
+            previousRuleset = readFileSync(rulesetPath);
+            const backupPath = join(tmpdir(), `advanced-ruleset.py.bak-update-${Date.now()}`);
+            try {
+                writeFileSync(backupPath, previousRuleset);
+                console.log(`backed up user advanced-ruleset.py to ${backupPath}`);
+            }
+            catch (e) {
+                console.error(`update refused before install: failed to back up advanced-ruleset.py: ${e instanceof Error ? e.message : String(e)}`);
+                process.exit(1);
+            }
         }
+        const r = spawnNpm(npmArgs, "inherit");
         if (r.error) {
             console.error(`update failed to start npm: ${r.error.message}`);
             process.exit(1);
         }
         const code = r.status ?? 1;
         if (code === 0) {
+            if (previousRuleset !== null) {
+                try {
+                    const freshRuleset = existsSync(rulesetPath)
+                        ? readFileSync(rulesetPath)
+                        : null;
+                    if (freshRuleset === null || !previousRuleset.equals(freshRuleset)) {
+                        writeFileSync(rulesetPath, previousRuleset);
+                        console.log("restored user advanced-ruleset.py (package update never overwrites user edits)");
+                    }
+                }
+                catch (e) {
+                    console.error(`update failed to restore advanced-ruleset.py: ${e instanceof Error ? e.message : String(e)}`);
+                    process.exit(1);
+                }
+            }
             console.log("Update complete. Restart your CLI sessions so the MCP server picks up the new build.");
         }
         process.exit(code);
@@ -952,6 +1006,10 @@ if (isMain) {
         await runSetup();
         process.exit(0);
     }
+    if (arg === "init" || arg === "--init") {
+        const { runInit } = await import("./init.js");
+        process.exit(await runInit());
+    }
     if (arg === "doctor") {
         const { runDoctor } = await import("./doctor.js");
         process.exit(await runDoctor());
@@ -967,6 +1025,7 @@ if (isMain) {
     // until disabled with explicit user permission. On a new session the bundled
     // hook detects the carried-over marker and prompts the user to confirm.
     // (orchestrationMarker.disable is still used by the tool's enabled:false.)
+    startLivenessHeartbeat();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/init.js

@@ -0,0 +1,230 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+const BEGIN_RE = /<!-- subagent-mcp:begin[^>]*-->[\s\S]*?<!-- subagent-mcp:end -->/;
+export const INIT_BLOCK = [
+    "<!-- subagent-mcp:begin v1 -->",
+    "## subagent-mcp invariant - managed block, do not edit between markers",
+    "",
+    "BINDING WHILE CONNECTED. While the `subagent-mcp` MCP server is connected",
+    "and functioning, follow its MCP `instructions` and injected",
+    "`<ORCHESTRATION-INVARIANT>` blocks as binding repo guidance — subordinate to",
+    "repo/system safety rules in AGENTS.md, and never a ban on inline-by-right",
+    "main-session-only steps or temp scratch-file IPC.",
+    "",
+    "- ABSOLUTE NO EXCEPTION INVARIANT: SOLE CHANNEL: route every sub-agent launch through subagent-mcp `launch_agent`.",
+    "  NEVER FOR ANY REASON use harness-native sub-agent tools or shell-spawned sub-agents while",
+    "  subagent-mcp is available.",
+    "- 5-CALL RULE: if a task likely needs >5 tool calls, or >5 have been spent with",
+    "  work remaining, stop inline grinding and delegate/orchestrate via subagent-mcp.",
+    "- ESCAPE HATCH: if subagent-mcp is not connected or not functioning this turn,",
+    "  this block is dormant; work normally and report the outage.",
+    "<!-- subagent-mcp:end -->",
+].join("\n");
+function detectEol(s) {
+    const crlf = s.indexOf("\r\n");
+    const lf = s.replace(/\r\n/g, "").indexOf("\n");
+    return crlf >= 0 && (lf < 0 || crlf <= lf) ? "\r\n" : "\n";
+}
+function normalizeBlock(eol) {
+    return INIT_BLOCK.split("\n").join(eol);
+}
+function insertAfterFirstHeading(body, block, eol) {
+    const m = body.match(/^# .*(?:\r?\n|$)/m);
+    if (!m || m.index === undefined)
+        return `${block}${eol}${eol}${body}`;
+    const end = m.index + m[0].length;
+    return `${body.slice(0, end)}${eol}${block}${eol}${body.slice(end)}`;
+}
+function collapseBlankRuns(s, eol) {
+    return s.replace(new RegExp(`(?:${eol}){3,}`, "g"), `${eol}${eol}`);
+}
+function removeManagedBlock(body, eol) {
+    const match = body.match(BEGIN_RE);
+    const next = collapseBlankRuns(body.replace(BEGIN_RE, ""), eol);
+    if (!match || match.index !== 0)
+        return next;
+    let trimmed = next;
+    let removed = 0;
+    while (trimmed.startsWith(eol) && removed < 2) {
+        trimmed = trimmed.slice(eol.length);
+        removed++;
+    }
+    return trimmed;
+}
+function backupOnce(file) {
+    if (!existsSync(file))
+        return;
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${file}.bak-init-${stamp}`;
+    copyFileSync(file, backup);
+}
+function atomicWrite(file, data, force) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (force && existsSync(file))
+        chmodSync(file, 0o666);
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, file);
+}
+export function upsertInitBlock(file, opts = {}) {
+    const exists = existsSync(file);
+    const original = exists ? readFileSync(file, "utf8") : "";
+    const hadBom = original.charCodeAt(0) === 0xfeff;
+    const body = hadBom ? original.slice(1) : original;
+    const eol = exists ? detectEol(body) : "\n";
+    const block = normalizeBlock(eol);
+    let next = body;
+    let status;
+    if (opts.remove) {
+        if (!exists || !BEGIN_RE.test(body)) {
+            status = "absent";
+        }
+        else {
+            next = removeManagedBlock(body, eol);
+            status = "removed";
+        }
+    }
+    else if (!exists) {
+        next = `${block}${eol}`;
+        status = "created";
+    }
+    else if (BEGIN_RE.test(body)) {
+        const current = body.match(BEGIN_RE)?.[0] ?? "";
+        if (current === block) {
+            status = "ok";
+        }
+        else {
+            next = body.replace(BEGIN_RE, block);
+            status = "updated";
+        }
+    }
+    else {
+        next = insertAfterFirstHeading(body, block, eol);
+        status = "added";
+    }
+    const changed = !["ok", "absent"].includes(status);
+    if (changed && !opts.dryRun) {
+        const out = (hadBom ? "\ufeff" : "") + (next.endsWith(eol) ? next : next + eol);
+        backupOnce(file);
+        atomicWrite(file, out, opts.force === true);
+    }
+    return { file, status, changed };
+}
+function parseArgs(args) {
+    const parsed = {
+        dryRun: false,
+        remove: false,
+        force: false,
+        copilot: false,
+        cursor: false,
+        root: process.cwd(),
+        files: null,
+    };
+    const readValue = (args, i, flag) => {
+        const value = args[i + 1];
+        if (value === undefined || value === "" || value.startsWith("--")) {
+            throw new Error(`${flag} requires a value`);
+        }
+        return value;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--dry-run")
+            parsed.dryRun = true;
+        else if (a === "--remove" || a === "--uninstall")
+            parsed.remove = true;
+        else if (a === "--force")
+            parsed.force = true;
+        else if (a === "--copilot")
+            parsed.copilot = true;
+        else if (a === "--cursor")
+            parsed.cursor = true;
+        else if (a === "--root") {
+            parsed.root = readValue(args, i, a);
+            i++;
+        }
+        else if (a === "--files") {
+            parsed.files = readValue(args, i, a).split(",").filter(Boolean);
+            i++;
+        }
+        else
+            throw new Error(`unknown init argument: ${a}`);
+    }
+    if (!parsed.root)
+        throw new Error("--root requires a directory");
+    return parsed;
+}
+function isSelfRepo(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return pkg.name === "@heretyc/subagent-mcp";
+    }
+    catch {
+        return false;
+    }
+}
+function targetFiles(root, opts) {
+    const resolveTarget = (f) => {
+        const target = isAbsolute(f) ? resolve(f) : resolve(root, f);
+        const rel = relative(root, target);
+        if (rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))) {
+            return target;
+        }
+        throw new Error(`--files target escapes --root: ${f}`);
+    };
+    if (opts.files)
+        return opts.files.map(resolveTarget);
+    const rel = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+    if (opts.copilot)
+        rel.push(".github/copilot-instructions.md");
+    if (opts.cursor)
+        rel.push(".cursor/rules/subagent-mcp.mdc");
+    return rel.map(resolveTarget);
+}
+export async function runInit(args = process.argv.slice(3)) {
+    let opts;
+    try {
+        opts = parseArgs(args);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const root = resolve(opts.root);
+    if (isSelfRepo(root) && !opts.force) {
+        console.error("Refusing to run init inside the subagent-mcp source repo without --force.");
+        console.error("This repo keeps CLAUDE.md/GEMINI.md as thin redirects; use --root for a consumer repo.");
+        return 1;
+    }
+    let files;
+    try {
+        files = targetFiles(root, opts);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const issues = [];
+    const results = [];
+    for (const file of files) {
+        try {
+            const r = upsertInitBlock(file, opts);
+            results.push(r);
+            console.log(`${r.status.padEnd(7)} ${file}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            issues.push(`${file}: ${msg}`);
+            console.error(`failed  ${file}: ${msg}`);
+        }
+    }
+    if (opts.dryRun)
+        console.log("(dry-run: no files written)");
+    if (issues.length > 0) {
+        console.error("\nInit completed with issues:");
+        for (const i of issues)
+            console.error(`- ${i}`);
+        return 1;
+    }
+    return results.length > 0 ? 0 : 1;
+}

package/dist/orchestration/hook-core.js

@@ -11,8 +11,8 @@ import * as reminder from "./reminder.js";
  * turn) READS the marker here and decides what to inject. The hook now emits in
  * BOTH marker states, on a per-prompt counter (reminder.ts): every
  * REMINDER_PERIOD-th prompt injects the LONG mode-specific
- * <ORCHESTRATION-REMINDER-INVARIANT> block, every prompt between injects the
- * one-line pointer at it. Marker ON adds the claim machinery: the claim turn
+ * <ORCHESTRATION-INVARIANT> block, every prompt between injects the
+ * one-line rule carrier. Marker ON adds the claim machinery: the claim turn
  * (fresh enable or carryover re-claim) emits the FULL directive plus the ON
  * reminder block and re-baselines the counter. (Supersedes LOCKED DECISION 2's
  * same-session rel%5 FULL re-emission — owner directive 2026-06-11: steady
@@ -174,15 +174,15 @@ export function classifyClaim(owner_session, baseline_turn, current) {
 }
 /**
  * Per-prompt reminder cadence emission: the LONG block (longFile) on every
- * REMINDER_PERIOD-th counted prompt, the one-line pointer between. When the
+ * REMINDER_PERIOD-th counted prompt, the one-line rule carrier between. When the
  * counter could NOT persist, emit the LONG block — fail VISIBLE: a host whose
- * temp dir cannot hold the state file would otherwise inject the pointer on
- * every prompt at a block that never arrives.
+ * temp dir cannot hold the state file would otherwise inject only the compact
+ * rule carrier on every prompt and never refresh the LONG block.
  */
-function cadenceEmit(env, adapter, longFile, count, persisted) {
+function cadenceEmit(env, adapter, longFile, shortFile, count, persisted) {
     return !persisted || count % REMINDER_PERIOD === 0
         ? readDirective(env, longFile)
-        : readDirective(env, adapter.offTurnFile);
+        : readDirective(env, shortFile);
 }
 /**
  * Claim (or re-claim) an active marker for the current session and emit the
@@ -218,14 +218,14 @@ export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
  *     does not advance).
  *  2. marker not active for cwd -> OFF cadence: advance the session's counter
  *     (per-owner; a new session starts its own), LONG OFF-variant reminder when
- *     count % REMINDER_PERIOD === 0, else the one-line pointer.
+ *     count % REMINDER_PERIOD === 0, else the one-line rule carrier.
  *  3. marker active: classify the claim from marker state.
  *  4. FRESH / CARRYOVER -> claimAndEmit (FULL + ON reminder; CARRYOVER notice
  *     prepended once per marker; counter re-baselined). The transcript turn is
  *     read ONLY here — claim turns are the only consumer of the baseline, and
  *     the tail read is too expensive for the per-prompt steady state.
  *  5. SAME-SESSION -> ON cadence: LONG ON-variant reminder when
- *     count % REMINDER_PERIOD === 0, else the one-line pointer.
+ *     count % REMINDER_PERIOD === 0, else the one-line rule carrier.
  */
 export function runHook(payload, env, adapter) {
     try {
@@ -237,7 +237,7 @@ export function runHook(payload, env, adapter) {
         if (!marker.isActive(cwd)) {
             // OFF: no claim machinery — just the per-prompt reminder cadence.
             const r = reminder.advance(cwd, current);
-            return cadenceEmit(env, adapter, adapter.reminderOffFile, r.count, r.persisted);
+            return cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted);
         }
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
@@ -247,7 +247,7 @@ export function runHook(payload, env, adapter) {
         }
         // SAME-SESSION: per-prompt reminder cadence, ON variant.
         const r = reminder.advance(cwd, current);
-        return cadenceEmit(env, adapter, adapter.reminderOnFile, r.count, r.persisted);
+        return cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/orchestration/liveness.js

@@ -0,0 +1,32 @@
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "./marker.js";
+export const LIVENESS_TTL_MS = 120_000;
+export const LIVENESS_INTERVAL_MS = 30_000;
+export function alivePath() {
+    return join(stateDir, "alive.flag");
+}
+export function touchAlive(now = Date.now()) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(alivePath(), `${now}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Hooks fail open when liveness cannot be observed.
+    }
+}
+export function serverAlive(now = Date.now()) {
+    try {
+        const s = statSync(alivePath());
+        return now - s.mtimeMs <= LIVENESS_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+export function startLivenessHeartbeat() {
+    touchAlive();
+    const t = setInterval(() => touchAlive(), LIVENESS_INTERVAL_MS);
+    t.unref();
+    return t;
+}

package/dist/orchestration/pretool.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwdHash, stateDir } from "./marker.js";
+import { serverAlive } from "./liveness.js";
+import { sessionKey } from "./hook-core.js";
+export const INLINE_TOOL_LIMIT = 5;
+const NATIVE_SUBAGENT_TOOLS = new Set(["Task", "Agent", "Explore"]);
+const QUESTION_TOOLS = new Set(["AskUserQuestion", "ExitPlanMode"]);
+const SUBAGENT_MCP_TOOL_RE = /(^|__)subagent[-_]?mcp(__|$).*(launch_agent|poll_agent|wait|list_agents|send_message|kill_agent)$/i;
+function hash(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex").slice(0, 16);
+}
+function owner(payload) {
+    return sessionKey(payload) ?? "null";
+}
+function countPath(payload) {
+    const cwd = payload.cwd || process.cwd();
+    return join(stateDir, `pretool-${cwdHash(cwd)}-${hash(owner(payload))}.json`);
+}
+function readCount(payload) {
+    try {
+        const parsed = JSON.parse(readFileSync(countPath(payload), "utf8"));
+        return typeof parsed.count === "number" && parsed.count >= 0 ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeCount(payload, count) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(countPath(payload), JSON.stringify({ owner: owner(payload), count, updated_at: Date.now() }), { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Fail open: counter persistence is advisory enforcement, not host safety.
+    }
+}
+export function resetToolCount(payload) {
+    try {
+        if (existsSync(countPath(payload)))
+            unlinkSync(countPath(payload));
+    }
+    catch {
+        // Fail open.
+    }
+}
+function decision(permissionDecision, permissionDecisionReason, additionalContext) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason,
+            ...(additionalContext ? { additionalContext } : {}),
+        },
+    };
+}
+function isSubagentMcpTool(tool) {
+    return (SUBAGENT_MCP_TOOL_RE.test(tool) ||
+        [
+            "launch_agent",
+            "poll_agent",
+            "wait",
+            "list_agents",
+            "send_message",
+            "kill_agent",
+        ].includes(tool));
+}
+function exemptFromCounter(tool) {
+    return isSubagentMcpTool(tool) || QUESTION_TOOLS.has(tool);
+}
+export function runClaudePreTool(payload, env, now = Date.now()) {
+    try {
+        if (env.SUBAGENT_MCP_SUBAGENT === "1")
+            return null;
+        if (!serverAlive(now))
+            return null;
+        const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+        if (!tool)
+            return null;
+        if (NATIVE_SUBAGENT_TOOLS.has(tool)) {
+            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.");
+        }
+        if (exemptFromCounter(tool))
+            return null;
+        const next = readCount(payload) + 1;
+        writeCount(payload, next);
+        if (next <= INLINE_TOOL_LIMIT)
+            return null;
+        return decision("ask", `5-CALL RULE: this is tool call ${next} for the current user request. If work remains, delegate through subagent-mcp launch_agent; allow only for main-session-only capability or tight verification.`, "5-CALL RULE reached. Route remaining non-main-session work through subagent-mcp launch_agent; inline only for main-session-only capability or tight verification.");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/routing.js

@@ -241,7 +241,7 @@ export function validatePresence(p) {
     }
     // 2. deadlock cannot be combined with provider/model/effort.
     if (deadlock === true && (provider || model || effort)) {
-        return `Error: deadlock cannot be combined with provider, model, or effort. If repeated attempts at this task have failed, switch to pure auto mode — pass only prompt + task_category and let the server select — unless your assignment explicitly demands a specific model. Omit provider/model/effort and retry.\n${AUTO_HINT}`;
+        return `Error: deadlock cannot be combined with provider, model, or effort. From the 3rd attempt for the same atomic task, deadlock outranks capability overrides: drop provider/model/effort and retry.\n${AUTO_HINT}`;
     }
     // 3. effort present must come with provider AND model (checked before model rule).
     if (effort && !(provider && model)) {

package/dist/setup.js

@@ -34,6 +34,7 @@ export function serverPaths(root = INSTALL_ROOT) {
     return {
         server: `${f}/dist/index.js`,
         claudeHook: `${f}/dist/hooks/orchestration-claude.js`,
+        claudePreToolHook: `${f}/dist/hooks/orchestration-claude-pretool.js`,
         codexHook: `${f}/dist/hooks/orchestration-codex.js`,
     };
 }
@@ -61,37 +62,53 @@ export function findOnPath(cmd, env = process.env, platform = process.platform)
     return null;
 }
 /**
- * Reconcile the UserPromptSubmit hook in a parsed ~/.claude/settings.json.
+ * Reconcile the UserPromptSubmit and PreToolUse hooks in a parsed ~/.claude/settings.json.
  * Mutates `s` in place. Exact wiring present -> ok. A hook referencing
  * orchestration-claude.js at any OTHER path/shape -> repaired (rewritten to the
  * canonical exec form). Absent -> added. Unrelated hooks are never touched.
  */
-export function reconcileClaudeSettings(s, hookPath) {
+export function reconcileClaudeSettings(s, hookPath, preToolHookPath = hookPath.replace(/orchestration-claude\.js$/, "orchestration-claude-pretool.js")) {
     const hooksBlock = (s.hooks ?? {});
     s.hooks = hooksBlock;
-    const upsList = (hooksBlock.UserPromptSubmit ?? []);
-    hooksBlock.UserPromptSubmit = upsList;
-    for (const grp of upsList) {
-        for (const hk of grp.hooks ?? []) {
-            if (!JSON.stringify(hk).includes("orchestration-claude.js"))
-                continue;
-            const args = hk.args;
-            const exact = hk.command === "node" &&
-                Array.isArray(args) &&
-                args.length === 1 &&
-                args[0] === hookPath;
-            if (exact)
-                return { changed: false, status: "ok" };
-            hk.type = "command";
-            hk.command = "node";
-            hk.args = [hookPath];
-            return { changed: true, status: "repaired" };
+    const reconcile = (event, scriptName, desired) => {
+        const list = (hooksBlock[event] ?? []);
+        hooksBlock[event] = list;
+        for (const grp of list) {
+            for (const hk of grp.hooks ?? []) {
+                if (!JSON.stringify(hk).includes(scriptName))
+                    continue;
+                const args = hk.args;
+                const exact = hk.type === desired.type &&
+                    hk.command === desired.command &&
+                    Array.isArray(args) &&
+                    JSON.stringify(args) === JSON.stringify(desired.args) &&
+                    (desired.timeout === undefined || hk.timeout === desired.timeout);
+                if (exact)
+                    return { changed: false, status: "ok" };
+                Object.assign(hk, desired);
+                return { changed: true, status: "repaired" };
+            }
         }
-    }
-    upsList.push({
-        hooks: [{ type: "command", command: "node", args: [hookPath] }],
+        list.push({ hooks: [{ ...desired }] });
+        return { changed: true, status: "added" };
+    };
+    const prompt = reconcile("UserPromptSubmit", "orchestration-claude.js", {
+        type: "command",
+        command: "node",
+        args: [hookPath],
+    });
+    const pretool = reconcile("PreToolUse", "orchestration-claude-pretool.js", {
+        type: "command",
+        command: "node",
+        args: [preToolHookPath],
+        timeout: 5,
     });
-    return { changed: true, status: "added" };
+    const status = prompt.status === "repaired" || pretool.status === "repaired"
+        ? "repaired"
+        : prompt.status === "added" || pretool.status === "added"
+            ? "added"
+            : "ok";
+    return { changed: prompt.changed || pretool.changed, status };
 }
 /**
  * Reconcile the user-scope MCP server entry in a parsed ~/.claude.json.
@@ -211,10 +228,12 @@ export function verifyInstall(root = INSTALL_ROOT) {
         "dist/index.js",
         "dist/advanced-ruleset.py",
         "dist/hooks/orchestration-claude.js",
+        "dist/hooks/orchestration-claude-pretool.js",
         "dist/hooks/orchestration-codex.js",
         "directives/orchestration-claude.md",
         "directives/orchestration-codex.md",
-        "directives/off-turn-reminder.md",
+        "directives/short-on.md",
+        "directives/short-off.md",
         "directives/reminder-on.md",
         "directives/reminder-off-claude.md",
         "directives/reminder-off-codex.md",
@@ -358,8 +377,9 @@ function repairPromptFor(vendor, problem) {
             `The install root is "${fwd(INSTALL_ROOT)}". Please repair my Claude Code wiring: ` +
             `(1) register a user-scope MCP server named "subagent-mcp" running ` +
             `the global bin shim "subagent-mcp" (use 'claude mcp add subagent-mcp subagent-mcp -s user' or edit the mcpServers ` +
-            `key in ~/.claude.json), and (2) ensure ~/.claude/settings.json has a ` +
-            `hooks.UserPromptSubmit entry {type:"command", command:"node", args:["${p.claudeHook}"]}. ` +
+            `key in ~/.claude.json), and (2) ensure ~/.claude/settings.json has ` +
+            `hooks.UserPromptSubmit -> {type:"command", command:"node", args:["${p.claudeHook}"]} and ` +
+            `hooks.PreToolUse -> {type:"command", command:"node", args:["${p.claudePreToolHook}"], timeout:5}. ` +
             `Back up any file before editing it.`);
     }
     return (`subagent-mcp setup hit a problem on my machine: ${problem}. ` +
@@ -474,7 +494,7 @@ function wireClaude() {
     catch (e) {
         fail("claude", `could not register the MCP server: ${e.message}`);
     }
-    // 2) UserPromptSubmit hook in ~/.claude/settings.json.
+    // 2) UserPromptSubmit and PreToolUse hooks in ~/.claude/settings.json.
     try {
         const sfile = join(homedir(), ".claude", "settings.json");
         const s = readJson(sfile, {});
@@ -483,7 +503,7 @@ function wireClaude() {
             backup(sfile);
             writeFileSync(sfile, JSON.stringify(s, null, 2));
         }
-        describe(status, "UserPromptSubmit hook");
+        describe(status, "UserPromptSubmit + PreToolUse hooks");
         if (changed && DRY_RUN)
             console.log("    (dry-run: not written)");
     }
@@ -572,7 +592,7 @@ export function verifyWiring(root = INSTALL_ROOT, repair = false) {
             detail: registrationDetail(registered, attemptedRepair),
         });
         results.push({
-            label: "claude: UserPromptSubmit hook",
+            label: "claude: UserPromptSubmit + PreToolUse hooks",
             ok: hk.status === "ok",
             detail: hk.status === "ok" ? "wired" : `${hk.status === "repaired" ? "stale path" : "not wired"} - run: subagent-mcp setup`,
         });
@@ -588,7 +608,7 @@ export function verifyWiring(root = INSTALL_ROOT, repair = false) {
             detail: srv.status === "ok" ? "registered (file fallback)" : "config stale — run: subagent-mcp setup",
         });
         results.push({
-            label: "claude: UserPromptSubmit hook",
+            label: "claude: UserPromptSubmit + PreToolUse hooks",
             ok: hk.status === "ok",
             detail: hk.status === "ok" ? "wired" : `${hk.status === "repaired" ? "stale path" : "not wired"} - run: subagent-mcp setup`,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "MCP server that launches and manages local Claude Code and Codex CLI sub-agents as child processes (no direct Anthropic/OpenAI API).",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm test",
-    "test": "node test/effort.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-directives.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/cli-args.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+    "test": "node test/effort.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/cli-args.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
   },
   "author": "Lexi Blackburn",
   "license": "Apache-2.0",

package/scripts/postinstall.mjs

@@ -71,7 +71,7 @@ try {
   // Detected vendors — concrete, so the user knows what setup will touch.
   if (hasClaude || hasCodex) {
     line("  Detected on this machine:");
-    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit hook)");
+    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit/PreToolUse hooks)");
     if (hasCodex) line("    - Codex CLI        (will get MCP server + SessionStart/UserPromptSubmit hooks)");
   } else {
     line("  No Claude Code or Codex CLI detected yet. Install one,");

package/directives/off-turn-reminder.md

@@ -1 +0,0 @@
-Follow the directives in the last <ORCHESTRATION-REMINDER-INVARIANT> block; if none has appeared yet this session, await it — do not infer its content.