@heretyc/subagent-mcp 2.7.0 → 2.8.0

package/dist/hooks/orchestration-codex.js

@@ -1,17 +1,13 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { classifyClaim, countJsonlType, readDirective, runHook, sessionKey, } from "../orchestration/hook-core.js";
+import { claimAndEmit, classifyClaim, countJsonlType, runHook, sessionKey, } from "../orchestration/hook-core.js";
 import * as marker from "../orchestration/marker.js";
 /**
  * Codex CLI hook entry. Branches on payload.hook_event_name:
- *   - 'SessionStart'     -> if active and not a subagent, emit FULL (covers the
- *                           turn-0 directive before the first UserPromptSubmit).
- *   - 'UserPromptSubmit' -> the normal %5 runHook cadence.
- *
- * NOTE: the Python prototype carried inline 'alternating/odd-turn' comments;
- * those were STALE. The operative cadence is every 5th relative turn (%5),
- * matching INSTALL.md. The stale alternating comments are intentionally NOT
- * reproduced here.
+ *   - 'SessionStart'     -> if active and not a subagent, emit FULL + the ON
+ *                           reminder block (covers the turn-0 directive before
+ *                           the first UserPromptSubmit).
+ *   - 'UserPromptSubmit' -> the normal per-prompt reminder cadence (runHook).
  *
  * Compiles to dist/hooks/orchestration-codex.js and is invoked as:
  *   node "<PLUGIN_ROOT>/dist/hooks/orchestration-codex.js"
@@ -56,13 +52,16 @@ export const codexAdapter = {
     // Count JSONL lines whose parsed object.type === 'turn_context'. Delegates to
     // the bounded counter (reads at most the trailing window so a huge/
     // attacker-supplied transcript can't stall the inline host turn). Unreadable
-    // -> 0 (fail-safe: emits FULL rather than silently suppressing).
+    // -> 0 (fail-safe: the claim baseline stamps at 0; cadence is counter-driven
+    // and unaffected). Read on claim turns only.
     currentTurn(transcriptPath) {
         return countJsonlType(transcriptPath, "turn_context");
     },
     fullDirectiveFile: "orchestration-codex.md",
     offTurnFile: "off-turn-reminder.md",
     carryoverDirectiveFile: "carryover-codex.md",
+    reminderOnFile: "reminder-on.md",
+    reminderOffFile: "reminder-off-codex.md",
 };
 /**
  * Codex dispatcher. SessionStart fires once before the first prompt; it covers
@@ -89,19 +88,11 @@ export function runCodexHook(payload, env, adapter = codexAdapter) {
             const turn = adapter.currentTurn(payload.transcript_path);
             const m = marker.readMarker(cwd);
             const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
-            // Claim/re-claim for this session and baseline at the current turn.
-            const firstCarryover = kind === "carryover" && !m.carryover_ack;
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            if (kind === "carryover") {
-                m.provenance = "carried-over";
-                m.carryover_ack = true;
-            }
-            marker.writeMarker(cwd, m);
-            return firstCarryover
-                ? readDirective(env, adapter.carryoverDirectiveFile) +
-                    readDirective(env, adapter.fullDirectiveFile)
-                : readDirective(env, adapter.fullDirectiveFile);
+            // Claim/re-claim + emit via the SHARED claim path (one copy of the
+            // semantics — FULL + ON reminder, ack-latched CARRYOVER prepend, counter
+            // re-baseline). SessionStart claims even on SAME-SESSION (resume) so
+            // turn 0 is always covered.
+            return claimAndEmit(cwd, current, turn, m, kind, env, adapter);
         }
         // UserPromptSubmit (and any other event) -> normal cadence.
         return runHook(payload, env, adapter);

package/dist/index.js

@@ -2,10 +2,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { spawn, execSync } from "child_process";
-import { unlinkSync, existsSync, realpathSync } from "node:fs";
+import { spawn, spawnSync, execSync } from "child_process";
+import { unlinkSync, existsSync, realpathSync, readFileSync } from "node:fs";
 import { randomUUID } from "crypto";
-import { isAbsolute, basename } from "node:path";
+import { isAbsolute, basename, join, dirname } from "node:path";
 import { pathToFileURL } from "url";
 import { buildCommand } from "./effort.js";
 import { resolveExeFor } from "./platform.js";
@@ -888,15 +888,79 @@ server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MOD
 const isMain = process.argv[1] !== undefined &&
     import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
 if (isMain) {
-    if (process.argv[2] === "setup") {
+    // CLI argument guard — runs BEFORE the stdio transport connects. Any argv[2]
+    // other than the known commands used to fall through and silently start the
+    // MCP server, which blocks forever waiting on stdin (`subagent-mcp --version`
+    // hung indefinitely). Only a bare invocation may reach the server below.
+    const arg = process.argv[2];
+    const usage = [
+        "Usage: subagent-mcp [command]",
+        "",
+        "  (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)",
+        "  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",
+    ].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") {
+        console.log(readPkg().version);
+        process.exit(0);
+    }
+    if (arg === "--help" || arg === "-h") {
+        console.log(usage);
+        process.exit(0);
+    }
+    if (arg === "--update") {
+        const pkg = readPkg();
+        const npmArgs = ["install", "-g", `${pkg.name}@latest`];
+        console.log(`subagent-mcp ${pkg.version} -> npm ${npmArgs.join(" ")}`);
+        // npm on Windows is npm.cmd; spawning a .cmd without a shell fails
+        // (EINVAL on modern Node). Resolve the underlying npm-cli.js and run it
+        // with this same node binary: cmd-shim layout first (npm installed into a
+        // prefix), then the official Node-for-Windows layout (npm.cmd sitting
+        // 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 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 });
+        }
+        else {
+            r = spawnSync(npm, npmArgs, { stdio: "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) {
+            console.log("Update complete. Restart your CLI sessions so the MCP server picks up the new build.");
+        }
+        process.exit(code);
+    }
+    if (arg === "setup") {
         const { runSetup } = await import("./setup.js");
         await runSetup();
         process.exit(0);
     }
-    if (process.argv[2] === "doctor") {
+    if (arg === "doctor") {
         const { runDoctor } = await import("./doctor.js");
         process.exit(await runDoctor());
     }
+    if (arg !== undefined && arg !== "") {
+        console.error(`unknown argument: ${arg}`);
+        console.error(usage);
+        process.exit(1);
+    }
     // ORCHESTRATION MODE PERSISTS across restarts/sessions: the server does NOT
     // clear the marker on startup. DEFAULT OFF now means ABSENCE of a marker — a
     // project never enabled stays OFF; a project explicitly enabled persists ON

package/dist/orchestration/hook-core.js

@@ -3,6 +3,31 @@ import { closeSync, openSync, readFileSync, readSync, statSync, } from "node:fs"
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import * as marker from "./marker.js";
+import * as reminder from "./reminder.js";
+/**
+ * Provider-agnostic core of the UserPromptSubmit / SessionStart hook.
+ *
+ * The MCP tool only ever WRITES the marker. A SEPARATE hook process (one per
+ * 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
+ * (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
+ * state is the leaner tagged reminder, FULL fires on claim turns only.) The
+ * marker PERSISTS across sessions/restarts, so the first turn of a new session
+ * that inherits an already-ON marker emits a CARRYOVER notice (prepended to
+ * FULL) once per project marker, ack-latched in marker state, and re-claims
+ * for that session.
+ *
+ * The entire run is wrapped in try/catch: on ANY error we emit nothing. A hook
+ * must never crash or stall the host turn. "Emit" means RETURN the string; the
+ * entry shim is what writes it to process.stdout.
+ */
+/** Long-reminder cadence: every Nth counted prompt is a LONG turn. */
+export const REMINDER_PERIOD = 5;
 /**
  * Resolve the repo-root `directives/` dir at runtime. Honors an explicit plugin
  * root (Claude sets CLAUDE_PLUGIN_ROOT; a generic PLUGIN_ROOT is also accepted)
@@ -147,20 +172,60 @@ export function classifyClaim(owner_session, baseline_turn, current) {
     }
     return "same";
 }
+/**
+ * Per-prompt reminder cadence emission: the LONG block (longFile) on every
+ * REMINDER_PERIOD-th counted prompt, the one-line pointer 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.
+ */
+function cadenceEmit(env, adapter, longFile, count, persisted) {
+    return !persisted || count % REMINDER_PERIOD === 0
+        ? readDirective(env, longFile)
+        : readDirective(env, adapter.offTurnFile);
+}
+/**
+ * Claim (or re-claim) an active marker for the current session and emit the
+ * claim-turn payload: FULL directive + ON reminder block, with the CARRYOVER
+ * notice prepended on the first foreign-owner claim of a marker (ack-latched,
+ * so sub-agent/parallel-session marker ping-pong cannot re-fire it). The
+ * reminder counter re-baselines to 0 — the claim turn IS a LONG turn, so the
+ * next LONG fires exactly REMINDER_PERIOD prompts later. Shared by runHook's
+ * claim branch and the Codex SessionStart dispatcher (one copy of the claim
+ * semantics, no drift).
+ */
+export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
+    const firstCarryover = kind === "carryover" && !m.carryover_ack;
+    m.baseline_turn = turn;
+    m.owner_session = current ?? null;
+    if (kind === "carryover") {
+        m.provenance = "carried-over";
+        m.carryover_ack = true;
+    }
+    marker.writeMarker(cwd, m);
+    reminder.rebase(cwd, current, 0);
+    const full = readDirective(env, adapter.fullDirectiveFile) +
+        readDirective(env, adapter.reminderOnFile);
+    return firstCarryover
+        ? readDirective(env, adapter.carryoverDirectiveFile) + full
+        : full;
+}
 /**
  * Core hook logic. Returns the string to inject, or '' to inject nothing.
  *
  * Order:
- *  1. subagent -> '' (a subagent must never be nagged to delegate).
- *  2. marker not active for cwd -> '' (OFF; zero emission).
- *  3. read current turn + marker state, classify the claim.
- *  4. FRESH (never claimed) -> claim + baseline at this turn, persist, emit FULL
- *     (this is the freshly-enabled turn, relTurn 0).
- *  5. CARRYOVER (owned by another/prior session) -> re-claim + re-baseline at
- *     this turn, persist, emit the CARRYOVER notice prepended to FULL only
- *     before the marker's carryover_ack has latched.
- *  6. SAME-SESSION -> rel = turn - baseline; FULL when rel % 5 === 0, else
- *     off-turn.
+ *  1. subagent -> '' (a subagent must never be nagged to delegate; the counter
+ *     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.
+ *  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.
  */
 export function runHook(payload, env, adapter) {
     try {
@@ -168,38 +233,21 @@ export function runHook(payload, env, adapter) {
             return "";
         }
         const cwd = payload.cwd || process.cwd();
+        const current = sessionKey(payload);
         if (!marker.isActive(cwd)) {
-            return "";
+            // 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);
         }
-        const current = sessionKey(payload);
-        const turn = adapter.currentTurn(payload.transcript_path);
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
-        if (kind === "fresh") {
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            marker.writeMarker(cwd, m);
-            return readDirective(env, adapter.fullDirectiveFile);
-        }
-        if (kind === "carryover") {
-            // Re-claim for the current session and re-baseline at this turn so the
-            // notice fires once per project marker. The ack survives re-claims, so
-            // sub-agent/parallel-session marker ping-pong cannot re-fire it.
-            const firstTime = !m.carryover_ack;
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            m.provenance = "carried-over";
-            m.carryover_ack = true;
-            marker.writeMarker(cwd, m);
-            return firstTime
-                ? readDirective(env, adapter.carryoverDirectiveFile) +
-                    readDirective(env, adapter.fullDirectiveFile)
-                : readDirective(env, adapter.fullDirectiveFile);
+        if (kind === "fresh" || kind === "carryover") {
+            const turn = adapter.currentTurn(payload.transcript_path);
+            return claimAndEmit(cwd, current, turn, m, kind, env, adapter);
         }
-        const rel = turn - m.baseline_turn;
-        return rel % 5 === 0
-            ? readDirective(env, adapter.fullDirectiveFile)
-            : readDirective(env, adapter.offTurnFile);
+        // SAME-SESSION: per-prompt reminder cadence, ON variant.
+        const r = reminder.advance(cwd, current);
+        return cadenceEmit(env, adapter, adapter.reminderOnFile, r.count, r.persisted);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/orchestration/marker.js

@@ -3,6 +3,12 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 const markerDir = join(tmpdir(), "subagent-mcp");
+/**
+ * Shared per-project state dir for ALL hook state files (marker + reminder
+ * counter). Exported so sibling state modules key off the SAME location — a
+ * future move edits one constant, not N copies.
+ */
+export const stateDir = markerDir;
 /**
  * Canonicalize a working directory so two spellings of the same path hash
  * identically. Strip a leading Windows \\?\ extended-length prefix FIRST (on

package/dist/orchestration/reminder.js

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwdHash, stateDir } from "./marker.js";
+/** Bound the per-owner map so a busy multi-session cwd cannot grow it without
+ * limit; evicting ALL entries on overflow is crude but rare and self-heals. */
+const OWNER_CAP = 8;
+function ownerKey(current) {
+    return current ?? "null";
+}
+export function reminderPath(cwd) {
+    return join(stateDir, "remind-" + cwdHash(cwd) + ".json");
+}
+export function readReminder(cwd) {
+    try {
+        const raw = readFileSync(reminderPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        const counts = {};
+        if (parsed.counts && typeof parsed.counts === "object") {
+            for (const [owner, count] of Object.entries(parsed.counts)) {
+                if (typeof count === "number" && Number.isFinite(count)) {
+                    counts[owner] = count;
+                }
+            }
+        }
+        return { counts };
+    }
+    catch {
+        // Missing/corrupt state -> safe default (no owners counted yet).
+        return { counts: {} };
+    }
+}
+/** Persist the state. Returns true on success, false on any write failure. */
+export function writeReminder(cwd, obj) {
+    try {
+        // Owner-only perms (see marker.enable()): the state persists session keys.
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(reminderPath(cwd), JSON.stringify(obj), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        // Fail-safe: report the failure; never throw.
+        return false;
+    }
+}
+/**
+ * Count one user prompt for the current session and persist. Returns the
+ * session's advanced count plus whether the state persisted (persisted=false
+ * lets the caller fail visible instead of never reaching the LONG cadence).
+ */
+export function advance(cwd, current) {
+    const owner = ownerKey(current);
+    const state = readReminder(cwd);
+    if (!(owner in state.counts) && Object.keys(state.counts).length >= OWNER_CAP) {
+        state.counts = {};
+    }
+    const count = (state.counts[owner] ?? 0) + 1;
+    state.counts[owner] = count;
+    const persisted = writeReminder(cwd, state);
+    return { count, persisted };
+}
+/**
+ * Re-baseline the current session's count (claim turns set 0: the claim turn
+ * IS a LONG turn, so the next LONG fires exactly REMINDER_PERIOD prompts on).
+ */
+export function rebase(cwd, current, count) {
+    const state = readReminder(cwd);
+    state.counts[ownerKey(current)] = count;
+    writeReminder(cwd, state);
+}