@heretyc/subagent-mcp 2.12.11 → 2.12.13

package/dist/global-concurrency.jsonc

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

package/dist/global-subagent-mcp-config.jsonc

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

package/dist/hooks/orchestration-claude.js

@@ -1,6 +1,6 @@
-import { realpathSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { countJsonlType, runHook, } from "../orchestration/hook-core.js";
+import { countJsonlType, runHook, TRANSCRIPT_READ_CAP, } from "../orchestration/hook-core.js";
 import { hasParentMarker } from "../launch-prompt.js";
 /**
  * Claude Code UserPromptSubmit hook entry. Reads the JSON payload from stdin,
@@ -22,6 +22,87 @@ const SUBAGENT_ENTRYPOINTS = new Set([
     "sdk-ts",
     "sdk-py",
 ]);
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function readTranscriptTail(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    let fd;
+    try {
+        const size = statSync(transcriptPath).size;
+        if (size <= TRANSCRIPT_READ_CAP) {
+            return readFileSync(transcriptPath, "utf8");
+        }
+        const start = size - TRANSCRIPT_READ_CAP;
+        const buf = Buffer.allocUnsafe(TRANSCRIPT_READ_CAP);
+        fd = openSync(transcriptPath, "r");
+        let offset = 0;
+        let pos = start;
+        while (offset < TRANSCRIPT_READ_CAP) {
+            const bytes = readSync(fd, buf, offset, TRANSCRIPT_READ_CAP - offset, pos);
+            if (bytes <= 0)
+                break;
+            offset += bytes;
+            pos += bytes;
+        }
+        const raw = buf.toString("utf8", 0, offset);
+        const firstNewline = raw.indexOf("\n");
+        return firstNewline === -1 ? "" : raw.slice(firstNewline + 1);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Ignore close failures. The hook must never fail the host turn.
+            }
+        }
+    }
+}
+function liftClaudeUsageFromTranscript(transcriptPath) {
+    const raw = readTranscriptTail(transcriptPath);
+    if (raw === null || !transcriptPath)
+        return null;
+    const lines = raw.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const trimmed = lines[i].trim();
+        if (!trimmed)
+            continue;
+        try {
+            const msg = JSON.parse(trimmed);
+            if (msg.type !== "assistant" || !msg.message?.usage)
+                continue;
+            if (typeof msg.message.model !== "string")
+                return null;
+            const usage = msg.message.usage;
+            return {
+                harness: "claude",
+                model: msg.message.model,
+                source_ref: transcriptPath,
+                usage: {
+                    input: finiteNumber(usage.input_tokens) ? usage.input_tokens : 0,
+                    output: finiteNumber(usage.output_tokens) ? usage.output_tokens : 0,
+                    cache_creation: finiteNumber(usage.cache_creation_input_tokens)
+                        ? usage.cache_creation_input_tokens
+                        : 0,
+                    cache_read: finiteNumber(usage.cache_read_input_tokens)
+                        ? usage.cache_read_input_tokens
+                        : 0,
+                },
+                harnessPercentage: null,
+            };
+        }
+        catch {
+            // Skip malformed transcript lines and keep scanning older completed turns.
+        }
+    }
+    return null;
+}
 export const claudeAdapter = {
     isSubagent(payload, env) {
         // subagent-mcp-spawned children inherit this guard and must not claim/nag.
@@ -45,6 +126,9 @@ export const claudeAdapter = {
     currentTurn(transcriptPath) {
         return countJsonlType(transcriptPath, "user");
     },
+    liftUsage(_payload, _env, transcriptPath) {
+        return liftClaudeUsageFromTranscript(transcriptPath);
+    },
     anonScope: "claude",
     fullDirectiveFile: "orchestration-claude.md",
     shortOnFile: "short-on.md",

package/dist/hooks/orchestration-codex.js

@@ -1,7 +1,8 @@
-import { realpathSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { claimAndEmit, classifyOwnerClaim, countJsonlType, cullHookZombies, ownerKey, runHook, } from "../orchestration/hook-core.js";
+import { claimAndEmit, classifyOwnerClaim, computeEffectiveActive, countJsonlType, cullHookZombies, ownerKey, runHook, TRANSCRIPT_READ_CAP, } from "../orchestration/hook-core.js";
 import * as marker from "../orchestration/marker.js";
+import { resolveContextWindow, } from "../orchestration/metering.js";
 import { hasParentMarker } from "../launch-prompt.js";
 /**
  * Codex CLI hook entry. Branches on payload.hook_event_name:
@@ -20,6 +21,142 @@ const SUBAGENT_SOURCE_STRINGS = new Set([
     "subAgentThreadSpawn",
     "subAgentOther",
 ]);
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function tailJsonlLines(transcriptPath) {
+    if (!transcriptPath)
+        return [];
+    let fd;
+    try {
+        const size = statSync(transcriptPath).size;
+        let raw;
+        let droppedPartialHead = false;
+        if (size <= TRANSCRIPT_READ_CAP) {
+            raw = readFileSync(transcriptPath, "utf8");
+        }
+        else {
+            const start = size - TRANSCRIPT_READ_CAP;
+            const buf = Buffer.allocUnsafe(TRANSCRIPT_READ_CAP);
+            fd = openSync(transcriptPath, "r");
+            let offset = 0;
+            let pos = start;
+            while (offset < TRANSCRIPT_READ_CAP) {
+                const bytes = readSync(fd, buf, offset, TRANSCRIPT_READ_CAP - offset, pos);
+                if (bytes <= 0)
+                    break;
+                offset += bytes;
+                pos += bytes;
+            }
+            raw = buf.toString("utf8", 0, offset);
+            droppedPartialHead = true;
+        }
+        const lines = raw.split("\n");
+        if (droppedPartialHead) {
+            lines.shift();
+        }
+        return lines.map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort close; never throw.
+            }
+        }
+    }
+}
+function nestedRecord(value, key) {
+    if (!value || typeof value !== "object")
+        return null;
+    const child = value[key];
+    return child && typeof child === "object"
+        ? child
+        : null;
+}
+function stringField(value, key) {
+    if (!value || typeof value !== "object")
+        return null;
+    const child = value[key];
+    return typeof child === "string" ? child : null;
+}
+function isTokenCountLine(obj) {
+    if (obj.type === "token_count")
+        return true;
+    const payload = nestedRecord(obj, "payload");
+    return payload?.type === "token_count";
+}
+function tokenInfo(obj) {
+    const direct = nestedRecord(obj, "info");
+    if (direct)
+        return direct;
+    return nestedRecord(nestedRecord(obj, "payload"), "info");
+}
+function modelFromTurnContext(obj) {
+    if (obj.type !== "turn_context")
+        return null;
+    return stringField(obj, "model") ?? stringField(nestedRecord(obj, "payload"), "model");
+}
+function liftCodexUsageFromRollout(transcriptPath) {
+    let latestTokenInfo = null;
+    let latestModel = null;
+    const lines = tailJsonlLines(transcriptPath);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const obj = JSON.parse(lines[i]);
+            if (!obj || typeof obj !== "object")
+                continue;
+            const record = obj;
+            if (!latestTokenInfo && isTokenCountLine(record)) {
+                latestTokenInfo = tokenInfo(record);
+            }
+            if (!latestModel) {
+                latestModel = modelFromTurnContext(record);
+            }
+            if (latestTokenInfo && latestModel)
+                break;
+        }
+        catch {
+            // Skip unparseable lines; never throw.
+        }
+    }
+    const total = nestedRecord(latestTokenInfo, "total_token_usage");
+    if (!total || !latestModel || !transcriptPath)
+        return null;
+    const input = total.input_tokens;
+    const output = total.output_tokens;
+    const cacheRead = total.cached_input_tokens;
+    if (!finiteNumber(input) || !finiteNumber(output) || !finiteNumber(cacheRead)) {
+        return null;
+    }
+    const modelContextWindow = latestTokenInfo?.model_context_window;
+    const totalTokens = total.total_tokens;
+    const harnessPercentage = finiteNumber(modelContextWindow) &&
+        modelContextWindow > 0 &&
+        finiteNumber(totalTokens)
+        ? (totalTokens / modelContextWindow) * 100
+        : null;
+    if (harnessPercentage === null && resolveContextWindow("codex", latestModel) === null) {
+        return null;
+    }
+    return {
+        harness: "codex",
+        model: latestModel,
+        source_ref: transcriptPath,
+        usage: {
+            input,
+            output,
+            cache_creation: 0,
+            cache_read: cacheRead,
+        },
+        harnessPercentage,
+    };
+}
 export const codexAdapter = {
     isSubagent(payload, env) {
         // subagent-mcp-spawned children inherit this guard and must not claim/nag.
@@ -47,6 +184,12 @@ export const codexAdapter = {
     currentTurn(transcriptPath) {
         return countJsonlType(transcriptPath, "turn_context");
     },
+    liftUsage(_payload, _env, transcriptPath) {
+        // Provider-specific lift ONLY. hook-core is the sole writer of the metering
+        // record (matching the Claude adapter contract); the adapter must not also
+        // self-write, or the same turn would persist the record twice.
+        return liftCodexUsageFromRollout(transcriptPath);
+    },
     anonScope: "codex",
     fullDirectiveFile: "orchestration-codex.md",
     shortOnFile: "short-on.md",
@@ -78,7 +221,13 @@ export function runCodexHook(payload, env, adapter = codexAdapter) {
             const cwd = payload.cwd || process.cwd();
             const current = ownerKey(payload, cwd, adapter);
             marker.writeCurrentSession(cwd, current);
-            if (!marker.isActive(cwd, current)) {
+            // Gate on the SAME effective-active computation runHook uses (disable /
+            // enable / latch / metering fail-safe), not the bare marker. SessionStart
+            // is turn 0 (grace window), so no metering fail-safe applies yet; passing
+            // false keeps a never-pre-enabled real session eligible for its turn-0
+            // directive via the latch/enable paths just like the UserPromptSubmit
+            // cadence would.
+            if (!computeEffectiveActive(cwd, current, Date.now(), false)) {
                 return "";
             }
             const turn = adapter.currentTurn(payload.transcript_path);

package/dist/index.js

@@ -22,6 +22,9 @@ import { CONFIG_FILENAME, NONBLOCKING_CULL_DEPS, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_L
 import { shouldReapTerminalButAlive } from "./zombie.js";
 import * as orchestrationMarker from "./orchestration/marker.js";
 import * as modelMode from "./orchestration/model-mode.js";
+import * as handoff from "./orchestration/handoff.js";
+import * as metering from "./orchestration/metering.js";
+import { computeEffectiveActive } from "./orchestration/hook-core.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
 import { checkForNpmUpdate } from "./orchestration/update-check.js";
 import { ensureParentMarker } from "./launch-prompt.js";
@@ -117,6 +120,21 @@ const TASK_CATEGORY_GLOSS = "REQUIRED. Task shape -> routing category (server pi
 function errorResult(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function computeEffectiveOrchestrationActive(cwd, key) {
+    const now = Date.now();
+    // Derive the metering fail-safe from the PERSISTED record only: a record that
+    // exists but cannot resolve a percentage is undetectable (fail-safe ON). The
+    // ABSENCE of a record is NOT fail-safed -- it matches the hook's turn-1 grace
+    // window (no completed turn yet), so the tool's report agrees with the hook's
+    // tag on turn 1 instead of spuriously flipping ON. Everything else flows
+    // through the one shared helper so the tool never diverges from the hook.
+    const record = key !== undefined ? metering.readMetering(key) : null;
+    const meteringUndetectableFailSafe = record !== null && record.used_percentage === null;
+    return computeEffectiveActive(cwd, key, now, meteringUndetectableFailSafe);
+}
 function currentLaunchDepth(env = process.env) {
     const raw = env.SUBAGENT_MCP_DEPTH;
     if (raw !== undefined && raw !== "") {
@@ -550,11 +568,11 @@ reconcileInterval.unref();
 // test/mirror-fragments.test.mjs while ORCHESTRATION_INSTRUCTIONS below stays
 // compressed under MCP metadata limits:
 // READ-ESCALATION LADDER (the orchestrator's only read channels, in order): (1) subagent-mcp `poll_agent` TAIL; (2) if the tail is insufficient, dispatch ONE sub-agent to return a single summary of <=100 lines, trusted as-is (no separate verification step); (3) anything larger: the USER reads the document directly. No reads or writes occur outside these channels. An empty or stalled tail means the agent is ALIVE, not dead — do NOT busy-loop poll_agent; learn completion via `wait`. Large inter-agent data: the orchestrator assigns scratch-file paths (%TEMP% on Windows, /tmp on POSIX) in prompts; the producing sub-agent writes, the consuming sub-agent reads; the orchestrator NEVER reads those files.
-const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (full spec: docs/spec/dev-loop/orchestration-directive-architecture.md).\n\nPRECEDENCE. The latest <subagent-mcp state=\"...\"> hook tag and repo/system safety rules are jointly binding; genuine conflict => STOP and ask. Only the hook flips ON/OFF; absence of any tag = UNKNOWN => fail-safe ON.\n\nSOLE CHANNEL. Every launch uses launch_agent; never harness Task/Agent or shell-spawned agents.\n\nORCHESTRATION ON. You are a delegate-ONLY orchestrator: use only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and /workflows. No direct reads/writes; inline-by-right does not exist. Non-delegable step: ask a one-time exception, do only that step, resume delegating.\n\nSUB-AGENT CONTRACT. Every prompt carries objective + output format + tools/sources + boundaries. SCALE: ~1 agent for a fact-find, 2-4 for comparisons; never one-shot multi-phase work; split into atomic steps, one agent each. FAN-OUT independents, sequence dependents, SERIALIZE writers over shared paths (no cwd lock). VERIFY code and non-trivial steps with a separate sub-agent first.\n\nREAD LADDER. poll_agent tail -> one <=100-line summarizer sub-agent, trusted as-is -> else the USER reads it. Large handoffs use scratch-file paths; producer writes, consumer reads, orchestrator never reads them. Empty/stalled tail means ALIVE; learn finish via wait, do not poll-loop.\n\nORCHESTRATION OFF. If context footprint since last upgrade ask exceeds 200 lines, after that turn STOP and ask whether to enable; reset count only when you ask.\n\nDROPOUT WHILE ON: HALT and ask until restored. SUB-AGENT EXEMPTION: a prompt whose literal FIRST LINE begins \"<this is a request from a parent process>\" skips this regime. DISABLE: user-only, never on your own initiative.\n\nMODEL SELECTION. Default smart auto-picks, rejects provider/model/effort selectors. user-approved-overrides honors them 30 min, expires lazily on launch_agent, needs user authorization.";
+const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (full spec: orchestration-directive-architecture.md).\n\nPRECEDENCE. The latest <subagent-mcp state=\"...\"> hook tag and repo/system safety rules are jointly binding; genuine conflict => STOP and ask. Only the hook flips ON/OFF; absence of any tag = UNKNOWN => fail-safe ON.\n\nSOLE CHANNEL. Every launch uses launch_agent; never harness Task/Agent or shell-spawned agents.\n\nORCHESTRATION ON. You are a delegate-ONLY orchestrator: use only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and /workflows. No direct reads/writes; inline-by-right does not exist. Non-delegable step: ask a one-time exception, do only that step, resume delegating.\n\nSUB-AGENT CONTRACT. Prompt carries objective + output format + tools/sources + boundaries. SCALE: ~1 fact-find agent, 2-4 for comparisons; split multi-phase work into atomic steps. FAN-OUT independents, sequence dependents, SERIALIZE writers over shared paths (no cwd lock). VERIFY code and non-trivial steps with a separate sub-agent first.\n\nREAD LADDER. poll_agent tail -> one <=100-line summarizer sub-agent, trusted as-is -> else the USER reads it. Large handoffs use scratch-file paths; producer writes, consumer reads, orchestrator never reads them. Empty/stalled tail means ALIVE; learn finish via wait, do not poll-loop.\n\nORCHESTRATION starts OFF each session. Hook meters provider-reported context (never tokenized); at 15% it latches ON and coaches a 5-question plan; at 50% it warns every turn and unlocks handoff-write/handoff-read/handoff-clear. Undetectable context size = fail-safe ON.\n\nDROPOUT WHILE ON: HALT and ask until restored. SUB-AGENT EXEMPTION: a prompt whose literal FIRST LINE begins \"<this is a request from a parent process>\" skips this regime. DISABLE: user-only, never on your own initiative.\n\nMODEL SELECTION. Default smart auto-picks, rejects provider/model/effort selectors. user-approved-overrides honors them 30 min, expires lazily on launch_agent, needs user authorization.";
 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. launch_agent is code-capped at 2 spawn levels below the main orchestrator: depth 1 may launch depth 2 workers; depth 2 workers cannot spawn further.\n\nMODEL SELECTION MODE (parallel to orchestration-mode, set via the model-selection-mode tool). DEFAULT is \"smart\" and is used whenever unset: in smart, launch_agent REJECTS any call supplying provider/model/effort selectors and the server auto-picks the best model. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (the mode reverts to smart on the next launch_agent call after 30 minutes) and re-enabling does NOT extend an active window. HONOR-BASED: you MUST NOT set \"user-approved-overrides\" without explicit interactive USER authorization via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex); never enable it on your own initiative.";
 const server = new McpServer({
     name: "subagent-mcp",
-    version: "2.12.11",
+    version: "2.12.13",
     description: "Launches always-interactive local Claude and Codex sub-agent sessions and is the orchestrator's sole launch channel. Claude runs via the Claude Agent SDK over the local Claude Code executable; Codex via `codex app-server` over stdio. The server never calls Anthropic or OpenAI HTTP APIs directly.",
 }, {
     instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"
@@ -1614,22 +1632,27 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     };
 }));
 // Tool 8: orchestration-mode
-server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF for THIS session only, omit = query. SOLE CHANNEL holds in BOTH states: subagent-mcp is the only sanctioned way to launch sub-agents; toggling OFF does not lift that. WHAT: default-ON mode for LONG-HORIZON work that would fill the context window if run inline; when ON act as a delegate-ONLY orchestrator — delegate every step, inline-by-right does not exist, a non-delegable atomic step needs a one-time user-approved exception via the structured-question tool (state which + why). OFF upgrade check: a long-horizon task = any whose TOTAL context footprint (input read + output produced) exceeds 200 lines, measured CUMULATIVELY since your last upgrade ask; after EVERY user turn, if it qualifies, STOP and ask whether to remain enabled (every qualifying turn; a decline does not latch; reset the count only when you ask). PERSISTENCE: a permitted disable is session-keyed only, applies to THIS session only, resumes ON next new session (or after the 2h backstop), no mid-session re-enable; keyless hosts get only the one-time non-persisted conversational opt-out. CARRYOVER: if ON was inherited from a prior session (carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker) — notify the user it auto-activated and confirm keeping it ON. DISABLE: never on your own initiative; you may PROPOSE 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). Full operating model is in this server's MCP `instructions` (read once at initialize) — this is the operational summary only.", {
+server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF for THIS session only, omit = query. SOLE CHANNEL holds in BOTH states: subagent-mcp is the only sanctioned way to launch sub-agents; toggling OFF does not lift that. WHAT: when ON act as a delegate-ONLY orchestrator; delegate every step, inline-by-right does not exist, a non-delegable atomic step needs a one-time user-approved exception via the structured-question tool. Default is now OFF each session (metering-driven latch/handoff supersede the old manual-upgrade-ask model); enabled:true explicitly turns ON early (before any latch); enabled:false remains a session-scoped 2h-TTL opt-out, HONORED even after the 15% latch or metering fail-safe forces ON. PERSISTENCE: a permitted disable is session-keyed only, applies to THIS session only, resumes ON next new session or after the 2h backstop; keyless hosts get only the one-time non-persisted conversational opt-out. DISABLE: never on your own initiative; you may PROPOSE OFF on task-fit mismatch, but only EXPLICIT user permission 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.", {
     enabled: z.boolean().optional(),
 }, withMaintenance(async (params) => {
     const cwd = process.cwd();
     const key = orchestrationMarker.readCurrentSession(cwd);
     if (params.enabled === true) {
-        if (!orchestrationMarker.isActive(cwd, key)) {
-            return errorResult("orchestration already disabled for this session, cannot re-enable mid-session; resumes ON automatically next new session (or after the 2h backstop).");
+        if (!key) {
+            return errorResult("cannot enable: no session pointer found for this project (the per-turn hook has not fired yet). Enable records are session-keyed only; send one prompt first, or check wiring with `subagent-mcp doctor`.");
         }
+        if (!orchestrationMarker.isSessionScopedKey(key)) {
+            return errorResult("cannot enable: this host supplies no session identity (no session_id/transcript_path in hook payloads) and enable records are session-keyed only. Orchestration remains fail-safe ON for this anonymous host.");
+        }
+        orchestrationMarker.removeDisable(key);
+        orchestrationMarker.writeEnable(key);
         return {
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
                         orchestration_mode: "ON",
-                        message: "orchestration is ON by default.",
+                        message: "orchestration is ON for this session.",
                     }),
                 },
             ],
@@ -1649,14 +1672,14 @@ server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MOD
                     type: "text",
                     text: JSON.stringify({
                         orchestration_mode: "disabled-this-session",
-                        message: "orchestration disabled for THIS session only; the next new session resumes ON automatically (or after the 2h backstop); no mid-session re-enable.",
+                        message: "orchestration disabled for THIS session only; this opt-out overrides the 15% latch and metering fail-safe until the next new session or the 2h backstop.",
                     }),
                 },
             ],
         };
     }
     // enabled === undefined -> query only; no marker mutation.
-    const active = orchestrationMarker.isActive(cwd, key);
+    const active = computeEffectiveOrchestrationActive(cwd, key);
     return {
         content: [
             {
@@ -1695,6 +1718,51 @@ server.tool("model-selection-mode", "Set or query per-project MODEL SELECTION MO
         ],
     };
 }));
+// Verbatim handoff post-write response (plan Section 1.1). Defined as a
+// top-level string constant here so mirror-fragments.test.mjs can assert
+// byte-identity against handoff.md via source-text regex. Kept in lockstep
+// with handoff.HANDOFF_WRITE_SUCCESS (single verbatim string, two surfaces).
+const HANDOFF_WRITE_SUCCESS_MESSAGE = "We are ready to start a new session, to avoid wasting tokens, use the structured question tool to confirm that the user is ready to use the `handoff-resume skill` in the next new session to resume work and has cleared the current /goal (if present) - or you will be compelled to keep working on a potential /goal that needs to be halted for a new session.";
+// Tool 10: handoff-write
+server.tool("handoff-write", "Write a handoff for this working directory so the NEXT session can resume cleanly. UNLOCKS only at >=50% context utilization with readable metering; below that, or if context size is undetectable, this tool returns an affirmative unavailable error (never silent). BEFORE calling, ask the user 10 clarifying questions via the structured-question tool to build a /goal prompt for the next session. content <=4000 chars; use overflow (<=8000 more chars) for anything beyond that, referenced by full path inside content. On success, relay the tool's exact response to the user verbatim.", {
+    content: z.string().min(1),
+    overflow: z.string().optional(),
+}, withMaintenance(async (params) => {
+    const cwd = process.cwd();
+    const key = orchestrationMarker.readCurrentSession(cwd);
+    if (!key)
+        return errorResult(handoff.UNAVAILABLE_NO_METERING);
+    const result = handoff.writeHandoffIfAvailable(cwd, {
+        content: params.content,
+        overflowContent: params.overflow,
+        createdBySession: key,
+    }, metering.readMetering(key));
+    if (!result.ok)
+        return errorResult(result.error);
+    return textResult(HANDOFF_WRITE_SUCCESS_MESSAGE);
+}));
+// Tool 11: handoff-read
+server.tool("handoff-read", "Read the saved handoff for this working directory (if any). BEFORE calling, confirm the user's intent via EXACTLY 5 structured questions (proves legitimacy, clears ambiguity). If found, this session becomes the ONLY session that gets the handoff re-appended to its periodic LONG reminders. If none is saved, explains that the previous session must write one first.", {}, withMaintenance(async () => {
+    const cwd = process.cwd();
+    const key = orchestrationMarker.readCurrentSession(cwd);
+    const record = handoff.readHandoff(cwd);
+    if (record === null)
+        return errorResult(handoff.NO_HANDOFF_FOUND);
+    const marked = key ? handoff.markRead(cwd, key) ?? record : record;
+    const overflowLine = marked.overflow_path
+        ? `\n\nOverflow file: ${marked.overflow_path}`
+        : "";
+    return textResult([
+        "Saved handoff:",
+        marked.content + overflowLine,
+        "Before using this handoff, confirm the user's intent via EXACTLY 5 structured questions. Confirm: resume objective, current blocker, files/state to preserve, next concrete action, and permission to proceed in this session.",
+    ].join("\n\n"));
+}));
+// Tool 12: handoff-clear
+server.tool("handoff-clear", "Delete the saved handoff for this working directory, including any overflow file. The write/read/clear cycle repeats at each successor session's own 50% threshold.", {}, withMaintenance(async () => {
+    handoff.clearHandoff(process.cwd());
+    return textResult("handoff cleared for this directory.");
+}));
 // Connect the stdio transport only when run as the entry point (the bin), NOT
 // when this module is imported (e.g. test/handler-validation.test.mjs importing
 // the exported validatePresence). Connecting on import would block the test on

package/dist/init.js

@@ -4,7 +4,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 const MIGRATE_RE = /<!-- subagent-mcp:(?:managed:)?begin\b[^>]*-->[\s\S]*?<!-- subagent-mcp:(?:managed:)?end -->/;
 const OWNER_CAP = 8;
 export const INIT_BLOCK = [
-    "<!-- subagent-mcp:managed:begin schema=3 -->",
+    "<!-- subagent-mcp:managed:begin schema=4 -->",
     "## subagent-mcp invariant — managed block, do not edit between markers",
     "",
     "Upserted by `subagent-mcp init` at user request; re-running init keeps it in sync.",
@@ -25,7 +25,7 @@ export const INIT_BLOCK = [
     "",
     "READ-ESCALATION LADDER (the orchestrator's only read channels, in order): (1) subagent-mcp `poll_agent` TAIL; (2) if the tail is insufficient, dispatch ONE sub-agent to return a single summary of <=100 lines, trusted as-is (no separate verification step); (3) anything larger: the USER reads the document directly. No reads or writes occur outside these channels. An empty or stalled tail means the agent is ALIVE, not dead — do NOT busy-loop poll_agent; learn completion via `wait`. Large inter-agent data: the orchestrator assigns scratch-file paths (%TEMP% on Windows, /tmp on POSIX) in prompts; the producing sub-agent writes, the consuming sub-agent reads; the orchestrator NEVER reads those files.",
     "",
-    "ORCHESTRATION OFF — a \"long-horizon task\" = any task whose TOTAL context footprint (input you read + output you produce) exceeds 200 lines of text. After EVERY user turn, measure the CUMULATIVE footprint accumulated since your last upgrade ask; reset that cumulative count to zero ONLY when you actually ask. If it qualifies, ask the user via the structured-question tool whether to switch orchestration ON. Ask on every qualifying turn; a decline does not suppress future asks. Never assert ON yourself — only ask.",
+    "ORCHESTRATION OFF BY DEFAULT -- each new session starts with orchestration OFF. A hook meters real provider-reported context usage (never tokenized, never self-estimated). At 15% utilization a persisted latch force-enables orchestration and coaches a 5-question planning stop. At 50% the hook warns every turn to wind down and unlocks handoff-write/handoff-read/handoff-clear for a clean session handoff. If context size cannot be measured, the hook fails safe to ON. Never assert a state yourself -- only the hook tag is authoritative.",
     "",
     "DROPOUT WHILE ON: if subagent-mcp stops responding while orchestration is ON, halt and ask the user; do nothing inline. Keep re-checking and stay halted until subagent-mcp is restored (no auto-degrade). The only user choices are keep-waiting (the default) or explicitly abandon the whole task; aborting ends the task, it never switches you to inline work.",
     "",