@heretyc/subagent-mcp 2.12.19 → 2.12.21

package/README.md

@@ -27,7 +27,7 @@ of raw file context. The main invariants are:
 
 ### What You Need First
 
-- Node.js 18 or newer (`node --version`)
+- Node.js 20 or newer (`node --version`)
 - `claude` CLI, installed and signed in (`claude --version`)
 - `codex` CLI, installed and signed in (`codex --version`; optional if you only
   use Claude)
@@ -54,7 +54,8 @@ Installing the package only ships the program. It does not connect anything on
 its own. `subagent-mcp setup` finds your Claude Code or Codex install and
 registers both the server and the per-turn orchestration hooks. For Claude Code
 it also registers or wraps `statusLine` so the hook can read Claude's
-authoritative context percentage without replacing your custom statusline.
+authoritative context percentage without replacing your custom statusline, and
+deploys the `handoff-resume` Agent Skill to your Claude user scope.
 Preview first with `subagent-mcp setup --dry-run`.
 
 ### Restart, Then Turn On The Invariant

package/dist/doctor.js

@@ -11,9 +11,9 @@ import { verifyWiring } from "./setup.js";
 export async function runDoctor() {
     console.log("subagent-mcp doctor (checks wiring, including Claude statusLine; repairs missing MCP registrations via vendor CLIs)\n");
     const major = Number(process.versions.node.split(".")[0]);
-    console.log(`  ${major >= 18 ? "PASS" : "FAIL"}  node version — ${process.versions.node}` +
-        (major >= 18 ? "" : " (Node >= 18 required)"));
-    let failed = major < 18 ? 1 : 0;
+    console.log(`  ${major >= 20 ? "PASS" : "FAIL"}  node version — ${process.versions.node}` +
+        (major >= 20 ? "" : " (Node >= 20 required)"));
+    let failed = major < 20 ? 1 : 0;
     for (const r of verifyWiring(undefined, true)) {
         console.log(`  ${r.ok ? "PASS" : "FAIL"}  ${r.label} — ${r.detail}`);
         if (!r.ok)

package/dist/index.js

@@ -572,7 +572,7 @@ const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (fu
 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.19",
+    version: "2.12.21",
     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"
@@ -1696,7 +1696,7 @@ server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MOD
         ],
     };
 }));
-// Tool 8: model-selection-mode
+// Tool 9: model-selection-mode
 server.tool("model-selection-mode", "Set or query per-project MODEL SELECTION MODE, which gates launch_agent's `provider`/`model`/`effort` selectors. `mode`: \"smart\" or \"user-approved-overrides\"; omit to query. \"smart\" is the DEFAULT (used whenever unset): launch_agent REJECTS any call supplying provider/model/effort and the server auto-picks the best model for the task_category. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (reverts to smart on the next launch_agent call after the 30 min elapse); re-enabling does NOT extend an active window. HONOR-BASED, parallel to orchestration-mode: 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; a plain yes/no if neither exists). This tool CANNOT verify that authorization — never enable on your own initiative. PERSISTENCE: state keyed by cwd; both the mode and the override-window timestamp survive server restarts (remaining window is restored, not reset).", {
     mode: z.enum(["smart", "user-approved-overrides"]).optional(),
 }, withMaintenance(async (params) => {

package/dist/setup.js

@@ -41,6 +41,12 @@ export function serverPaths(root = INSTALL_ROOT) {
         codexHook: `${f}/dist/hooks/orchestration-codex.js`,
     };
 }
+export function handoffResumeSkillPaths(root = INSTALL_ROOT, home = homedir()) {
+    return {
+        source: join(root, "skills", "handoff-resume", "SKILL.md"),
+        target: join(home, ".claude", "skills", "handoff-resume", "SKILL.md"),
+    };
+}
 function statuslineCommand(shimPath, innerCommand = "") {
     const inner = innerCommand.trim();
     return `node "${shimPath}"${inner ? ` ${quoteStatuslineInnerArg(inner)}` : ""}`;
@@ -480,6 +486,51 @@ function describe(status, what) {
     else
         console.log(`  ${what}: pointed at a stale path — repaired.`);
 }
+export function deployHandoffResumeSkill(root = INSTALL_ROOT, home = homedir()) {
+    const { source, target } = handoffResumeSkillPaths(root, home);
+    if (!existsSync(source)) {
+        return {
+            changed: false,
+            status: "missing-source",
+            source,
+            target,
+            detail: `source missing at ${source}; reinstall @heretyc/subagent-mcp, then run subagent-mcp setup`,
+        };
+    }
+    const desired = readFileSync(source, "utf8");
+    if (existsSync(target) && readFileSync(target, "utf8") === desired) {
+        return { changed: false, status: "ok", source, target, detail: "deployed" };
+    }
+    const status = existsSync(target) ? "repaired" : "added";
+    if (!DRY_RUN) {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, desired);
+    }
+    return { changed: true, status, source, target, detail: status === "added" ? "deployed" : "restored" };
+}
+export function verifyHandoffResumeSkill(root = INSTALL_ROOT, home = homedir()) {
+    const { source, target } = handoffResumeSkillPaths(root, home);
+    if (!existsSync(source)) {
+        return {
+            label: "claude: handoff-resume skill",
+            ok: false,
+            detail: "source missing from install - reinstall @heretyc/subagent-mcp",
+        };
+    }
+    if (!existsSync(target)) {
+        return {
+            label: "claude: handoff-resume skill",
+            ok: false,
+            detail: "missing - run subagent-mcp setup",
+        };
+    }
+    const ok = readFileSync(target, "utf8") === readFileSync(source, "utf8");
+    return {
+        label: "claude: handoff-resume skill",
+        ok,
+        detail: ok ? "deployed" : "stale - run subagent-mcp setup",
+    };
+}
 export function vendorWireSpecs(p = serverPaths(), home = homedir()) {
     const claudeFile = join(home, ".claude.json");
     const codexDir = join(home, ".codex");
@@ -585,12 +636,33 @@ function wireClaude() {
     catch (e) {
         fail("claude", `could not write the settings.json hook: ${e.message}`);
     }
+    // 3) Claude Agent Skill for resuming saved handoffs.
+    try {
+        const r = deployHandoffResumeSkill(INSTALL_ROOT);
+        if (r.status === "missing-source") {
+            fail("claude", r.detail);
+        }
+        else {
+            if (r.status === "ok")
+                console.log("  handoff-resume skill: already correct.");
+            else if (r.status === "added")
+                console.log("  handoff-resume skill: added.");
+            else
+                console.log("  handoff-resume skill: restored from package copy.");
+            if (r.changed && DRY_RUN)
+                console.log("    (dry-run: not written)");
+        }
+    }
+    catch (e) {
+        fail("claude", `could not deploy the handoff-resume skill: ${e.message}`);
+    }
 }
 function wireCodex() {
     console.log("\n--- Codex CLI ---");
     const p = serverPaths();
     const codexDir = join(homedir(), ".codex");
     const specs = vendorWireSpecs(p);
+    // Codex has no Agent Skill mechanism; MCP instructions carry handoff guidance.
     // 1) config.toml — MCP server block (created if the file is missing).
     try {
         const existed = existsSync(specs.codex.configFile);
@@ -696,6 +768,7 @@ export function verifyWiring(root = INSTALL_ROOT, repair = false) {
                     : "wired; waiting for Claude statusLine signal"
                 : `${sl.status === "repaired" ? "stale path" : "not wired"} - run: subagent-mcp setup`,
         });
+        results.push(verifyHandoffResumeSkill(root, home));
     }
     else if (hasClaudeConfig) {
         const cj = readJson(join(home, ".claude.json"), {});
@@ -722,6 +795,7 @@ export function verifyWiring(root = INSTALL_ROOT, repair = false) {
                     : "wired; waiting for Claude statusLine signal"
                 : `${sl.status === "repaired" ? "stale path" : "not wired"} - run: subagent-mcp setup`,
         });
+        results.push(verifyHandoffResumeSkill(root, home));
     }
     const hasCodexCli = findOnPath("codex") !== null;
     const hasCodex = hasCodexCli || existsSync(join(home, ".codex"));
@@ -770,8 +844,8 @@ export async function runSetup() {
     console.log(`subagent-mcp setup${DRY_RUN ? " (dry-run)" : ""}`);
     console.log(`Install root: ${INSTALL_ROOT}\n`);
     const major = Number(process.versions.node.split(".")[0]);
-    if (major < 18) {
-        console.error(`ERROR: Node ${process.versions.node} is too old — Node >= 18 required.`);
+    if (major < 20) {
+        console.error(`ERROR: Node ${process.versions.node} is too old. Node >= 20 required.`);
         process.exit(1);
     }
     const missing = verifyInstall();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.12.19",
+  "version": "2.12.21",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",
@@ -25,6 +25,7 @@
   "files": [
     "dist",
     "directives",
+    "skills/handoff-resume",
     "scripts/postinstall.mjs",
     "LICENSE",
     "NOTICE",
@@ -61,7 +62,7 @@
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/handoff-resume/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: handoff-resume
+version: 1.0.0
+description: Resume prior work from a saved subagent-mcp handoff when the user says "handoff-resume", "resume handoff", or "resume work"; call handoff-read, confirm intent with exactly 5 structured questions before acting, and know the handoff-write/read/clear lifecycle.
+author: Lexi Blackburn (https://github.com/Heretyc/)
+created: 2026-07-11
+updated: 2026-07-11
+---
+
+# Handoff Resume
+
+When triggered, call the `handoff-read` MCP tool for the current cwd, then confirm the user's intent with EXACTLY 5 structured questions before acting on the saved handoff. `handoff-write` saves a compact resume record once 50% context utilization unlocks it. `handoff-read` retrieves the saved record for this cwd and binds reminder re-append behavior to this reading session. `handoff-clear` deletes the saved record and overflow file, if any, for this cwd.