@heretyc/subagent-mcp 2.8.0 → 2.8.2

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).
 
@@ -69,8 +74,14 @@ For manual wiring, developer install from source, Gemini CLI, and Claude Desktop
 | `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
 | `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
 | `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
+| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
+| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
+| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
+| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
 | `fallback_default` | no category matches with confidence; prefer splitting work instead |
 
+The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
+
 **Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
 
 ---

package/directives/carryover-claude.md

@@ -1,17 +1,17 @@
-<!-- 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>
+<ORCHESTRATION-INVARIANT>
+Sub-agent sessions (first prompt began "<this is a request from a parent process>"): ignore this block.
+
+ORCHESTRATION MODE carried over ON from a PRIOR session of this project
+(persists until disabled with permission). Not user-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, or
+   core-bound to main-session-only MCP → propose OFF.
+
+Until answered, the mandates below still bind. Declines → orchestration-mode
+enabled:false. NEVER disable on own initiative. After answer: handshake done —
+do not re-raise.
+
+</ORCHESTRATION-INVARIANT>

package/directives/carryover-codex.md

@@ -1,17 +1,17 @@
-<!-- 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>
+<ORCHESTRATION-INVARIANT>
+Sub-agent sessions (first prompt began "<this is a request from a parent process>"): ignore this block.
+
+ORCHESTRATION MODE carried over ON from a PRIOR session of this project
+(persists until disabled with permission). Not user-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, or
+   core-bound to main-session-only MCP → propose OFF.
+
+Until answered, the mandates below still bind. Declines → orchestration-mode
+enabled:false. NEVER disable on own initiative. After answer: handshake done —
+do not re-raise.
+
+</ORCHESTRATION-INVARIANT>

package/directives/off-turn-reminder.md

@@ -1 +1 @@
-Follow the directives in the last <ORCHESTRATION-REMINDER-INVARIANT> block; if none has appeared yet this session, await it — do not infer its content.
+<ORCHESTRATION-INVARIANT> SUBAGENT MANDATES bind THIS turn. 5-CALL RULE APPLIES. SOLE CHANNEL: launch sub-agents ONLY via subagent-mcp. OFF: ask before enabling orchestration. ON replies must start: route: delegate|inline - <reason>. </ORCHESTRATION-INVARIANT>

package/directives/orchestration-claude.md

@@ -1,21 +1,14 @@
-<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<SUB-AGENT-INVARIANT priority="CRITICAL" override="NONE">
-
-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.
-
-</SUB-AGENT-INVARIANT>
+<ORCHESTRATION-INVARIANT>
+ORCHESTRATION ON. Delegate-default through subagent-mcp; route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps (non-inheritable MCP, interactive/consent, verify reruns); temp scratch-file IPC allowed. Repo/system safety rules outrank this.
+- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
+- Subagents ask questions through the orchestrator; answers
+return to subagents.
+- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
+- NEVER DISABLE ORCHESTRATION: never on own initiative. Propose via AskUserQuestion only; disable only after explicit user permission.
+Orchestration Steps:
+1. Map out work before orchestrating.
+2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
+3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
+
+- For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+</ORCHESTRATION-INVARIANT>

package/directives/orchestration-codex.md

@@ -1,22 +1,13 @@
-<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
-<SUB-AGENT-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.
-
-</SUB-AGENT-INVARIANT>
+<ORCHESTRATION-INVARIANT>
+SCOPE: this session's first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1? Sub-agent session — this ORCHESTRATION-INVARIANT does NOT apply; SKIP this block.
+ORCHESTRATION ON. Delegate-default through subagent-mcp; route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps (non-inheritable MCP, interactive/consent, verify reruns); temp scratch-file IPC allowed. Repo/system safety rules outrank this.
+- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
+- Subagents ask questions through the orchestrator; answers
+return to subagents.
+- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
+- NEVER DISABLE ORCHESTRATION: never on own initiative. Propose via request-user-input only; disable only after explicit user permission.
+Orchestration Steps:
+1. Map out work before orchestrating.
+2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
+3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
+</ORCHESTRATION-INVARIANT>

package/directives/reminder-off-claude.md

@@ -1,12 +1,9 @@
-<!-- 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>
+<ORCHESTRATION-INVARIANT>
+ZERO EXCEPTIONS SUBAGENT MANDATES:
+5-CALL RULE: >5 tool calls needed for this request (all turns, no reset), or >5 already spent? Count reads, greps, test runs. If yes do NOT grind on inline - STOP and ask via AskUserQuestion whether to switch orchestration ON. That STOP+ask satisfies this rule; if the user declines, inline is authorized for THIS request - do not re-ask it.
+Why this exists: agents grind through large work without ever considering orchestration.
+ORCHESTRATION OFF - still binding:
+INVARIANT ZERO EXCEPTIONS SOLE CHANNEL: ANY sub-agent launch goes ONLY via the subagent-mcp; harness-native Task/Agent tools are FORBIDDEN while this server is connected.
+Advisory: At all times, delegating via subagent-mcp auto routing is advisable - do not assume your training data is still current.
+For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+</ORCHESTRATION-INVARIANT>

package/directives/reminder-off-codex.md

@@ -1,12 +1,9 @@
-<!-- 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>
+<ORCHESTRATION-INVARIANT>
+ZERO EXCEPTIONS SUBAGENT MANDATES:
+5-CALL RULE: >5 tool calls needed for this request (all turns, no reset), or >5 already spent? Count reads, greps, test runs. If yes do NOT grind on inline - STOP and ask via request-user-input whether to switch orchestration ON. That STOP+ask satisfies this rule; if the user declines, inline is authorized for THIS request - do not re-ask it.
+Why this exists: agents grind through large work without ever considering orchestration.
+ORCHESTRATION OFF - still binding:
+INVARIANT ZERO EXCEPTIONS SOLE CHANNEL: ANY sub-agent launch goes ONLY via the subagent-mcp; harness-native Task/Agent tools are FORBIDDEN while this server is connected.
+Advisory: At all times, delegating via subagent-mcp auto routing is advisable - do not assume your training data is still current.
+For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+</ORCHESTRATION-INVARIANT>

package/directives/reminder-on.md

@@ -1,9 +1,15 @@
-<!-- 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.
-<SUB-AGENT-INVARIANT> governance applies — full model: server MCP instructions.
-Sub-agent sessions: ignore this block.
-
-</ORCHESTRATION-REMINDER-INVARIANT>
+<ORCHESTRATION-INVARIANT>
+ORCHESTRATION ON. Route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps; temp scratch-file IPC allowed. Repo/system safety rules outrank this.
+- Delegate-default. 5-CALL RULE is satisfied by delegation.
+EVERY reply starts: route: delegate|inline - <reason>
+- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
+- Subagents ask questions through the orchestrator; answers
+return to subagents.
+- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
+Orchestration Steps:
+1. Map out work before orchestrating.
+2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
+3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
+
+- For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+</ORCHESTRATION-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
@@ -47,6 +48,17 @@ export const claudeAdapter = {
     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 +83,7 @@ async function main() {
     }
     let out = "";
     try {
-        out = runHook(payload, process.env, claudeAdapter);
+        out = runClaudeHook(payload, process.env, claudeAdapter);
     }
     catch {
         out = "";

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;
@@ -45,7 +47,7 @@ const SPAWN_GRACE_MS = (() => {
 // so the handler-validation test can exercise them without importing this entry
 // module (which would open the stdio transport).
 // Caveman self-classification gloss for the task_category param (tool-description.md).
-const TASK_CATEGORY_GLOSS = "REQUIRED. Task shape -> routing category (the server picks the best model for it). Pick ONE: math_proof: proof/derivation/formally-checkable result; deductive step-validity under axioms; verified by a proof-checker not tests. security_review: security verdict/threat-assessment/demonstrated exploit; adversarial reasoning over attack surface — vuln, auth/authz, crypto, exploitability. debugging: verified fix/root-cause; ONLY with an observed failure (error, crash, red test, regression, flake); done when the symptom is resolved. quality_review: evaluative verdict on an existing NON-security artifact with NO observed failure; review diff/PR, compare A-vs-B, validate-vs-spec; never self-review. architecture: cross-module design/plan, NO code, NO execution loop; system structure, interface/migration strategy, decompose-into-tasks; >2 files or public API. agentic_execution: reach a target end-state by iterating in a mutating env (act/observe/adapt loop); run/deploy/provision/browse, tool/function-call, iterate-until-tests-pass. data_analysis: empirical finding/model ABOUT a structured dataset; query/SQL/dataframe answer, statistic, fit-model-report-drivers; the finding is the deliverable even if code runs. coding: bounded runnable code artifact, one-pass; implement function/module/feature/script, write tests, single-module refactor; compiles/passes tests. knowledge_synthesis: novel integrated prose over sources; synthesize/summarize/translate/draft/explain-across-files; judged by faithfulness/coherence not exact-match. mechanical: deterministic single-pass transform/leaf op, exact-match checkable; find/grep/list/rename/reformat/convert/extract-to-fixed-schema; minimal reasoning. fallback_default: no category fits with confidence (under-specified/mixed/tied); read-only sentinel — PREFER splitting the work into smaller atomic steps that each map to one category.";
+const TASK_CATEGORY_GLOSS = "REQUIRED. Task shape -> routing category (server picks best model for it). Pick ONE: math_proof: deliverable=proof/derivation/formally-checkable result; proof IS deliverable; deductive step-validity under axioms; verified by proof-checker not tests. security_review: deliverable=security verdict/threat-assessment/demonstrated-exploit; adversarial reasoning over attack surface; vuln, auth/authz, crypto, exploitability. debugging: deliverable=verified fix/root-cause; ONLY observed failure (error, crash, red test, regression, flake) preconditions work; done when symptom resolved. quality_review: deliverable=evaluative verdict on existing NON-security artifact, NO observed failure; review diff/PR, compare A-vs-B, validate-vs-spec; never self-review. architecture: deliverable=cross-module design/plan, NO code, NO execution loop; system structure, interface/migration strategy, decompose-into-tasks; >2 files or public API. agentic_execution: deliverable=target end-state via iterate in mutating env (act/observe/adapt loop); run/deploy/provision/browse, tool/function-call, iterate-until-tests-pass. data_analysis: deliverable=empirical finding/model ABOUT structured dataset; query/SQL/dataframe answer, statistic, fit-model-report-drivers; finding scored even if code runs. coding: deliverable=bounded runnable code artifact, one-pass; implement function/module/feature/script, write tests, single-module refactor; compiles/passes-tests. knowledge_synthesis: deliverable=novel integrated prose over sources; synthesize/summarize/translate/draft/explain-across-files; verified by faithfulness/coherence not exact-match. mechanical: deliverable=deterministic single-pass transform/leaf op, exact-match checkable; find/grep/list/rename/reformat/format-convert/extract-to-fixed-schema; minimal reasoning. prompt_engineering: deliverable=designed/optimized prompt or prompt-system steering an LLM/agent; author/refine/eval instructions; system prompt, few-shot, template, prompt rubric; comp-infer parents knowledge_synthesis+coding+quality_review; no direct benchmark. vulnerability_research: deliverable=NOVEL vuln discovery/root-cause/PoC, NOT broad CVE summary; find flaw, root-cause, build PoC; fuzzing, reverse-engineer, exploit primitive; comp-infer parents security_review+debugging+coding; no direct benchmark. molecular_biology: deliverable=reasoned molecular/computational-biology result; sequences, structures, pathways, -omics data; comp-infer parents knowledge_synthesis+data_analysis+math_proof; no direct benchmark. ml_accelerator_design: deliverable=hardware/software design for ML acceleration; dataflow, tiling, memory hierarchy, kernel, roofline; comp-infer parents architecture+coding+math_proof; no direct benchmark. fallback_default: no category matches with confidence (under-specified/mixed/tied); read-only; PREFER splitting work into smaller atomic steps each mapping to one category.";
 function errorResult(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
@@ -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);
 }