@heretyc/subagent-mcp 2.12.1 → 2.12.2

package/README.md

@@ -124,6 +124,11 @@ queue. You change the number in the `global-concurrency.jsonc` file in the
 install folder (minimum 10); the file is re-read on every launch, so no restart
 is needed.
 
+The same settings file includes `checkForUpdates` (default `true`). When a newer
+npm version exists, the per-turn hook can show a throttled notice to run
+`subagent-mcp update` and then `subagent-mcp setup`. Set `checkForUpdates` to
+`false`, or run with `SUBAGENT_UPDATE_CHECK=0` / `false`, to disable that check.
+
 ## Basic debugging
 
 - **"An agent looks stuck."** A quiet agent is usually **still alive**, not

package/dist/advanced-ruleset.py

@@ -12,9 +12,9 @@
       {"provider": "claude", "model": "sonnet",  "effort": "high",  "rank": 1},
       {"provider": "codex",  "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
     ]
-    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);
+    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8, fable (claude);
     gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
-    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
+    fable -> medium|high|xhigh|max; opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
     "rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
     invalid fails the launch hard — the server validates strictly.
 

package/dist/concurrency.js

@@ -6,6 +6,7 @@ import { CONCURRENCY_SCAFFOLD } from "./config-scaffold.js";
 import { cullStaleSlots, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, parseSlotMetadata, readSlotMetadata, slotPathForAgent, writeSlotMetadata, } from "./zombie.js";
 export const DEFAULT_CAP = 20;
 export const MIN_CAP = 10;
+export const DEFAULT_CHECK_FOR_UPDATES = true;
 export const CONFIG_FILENAME = "global-concurrency.jsonc";
 export { cullStaleSlots, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, parseSlotMetadata, readSlotMetadata, slotPathForAgent, writeSlotMetadata, };
 export function clampCap(raw) {
@@ -31,6 +32,16 @@ export function parseConcurrencyConfig(text) {
     }
     return clampCap(raw);
 }
+export function parseCheckForUpdatesConfig(text) {
+    try {
+        const raw = JSON.parse(stripJsoncComments(text))
+            ?.checkForUpdates;
+        return typeof raw === "boolean" ? raw : DEFAULT_CHECK_FOR_UPDATES;
+    }
+    catch {
+        return DEFAULT_CHECK_FOR_UPDATES;
+    }
+}
 export function defaultConfigPath() {
     return fileURLToPath(new URL("./" + CONFIG_FILENAME, import.meta.url));
 }
@@ -51,6 +62,15 @@ export function readGlobalCap(path = defaultConfigPath()) {
         return DEFAULT_CAP;
     }
 }
+export function readCheckForUpdates(path = defaultConfigPath()) {
+    try {
+        ensureConcurrencyConfig(path);
+        return parseCheckForUpdatesConfig(readFileSync(path, "utf8"));
+    }
+    catch {
+        return DEFAULT_CHECK_FOR_UPDATES;
+    }
+}
 export function slotDir() {
     if (process.env.SUBAGENT_SLOT_DIR)
         return process.env.SUBAGENT_SLOT_DIR;

package/dist/config-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-concurrency.jsonc — DO NOT EDIT.
-export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\n// ------------------------------------------------------------------\n// SOLE source of truth for the machine-wide limit on how many subagents\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\n// machine. There is NO environment-variable override.\n//\n// The whole recursive descendant tree counts toward this ONE number: a\n// subagent that itself launches subagents adds to the same machine-wide\n// total, and OTHER active agentic sessions count too.\n//\n// RE-READ on every launch_agent call — edits take effect immediately, no\n// server restart required.\n//\n// Value rules (forcibly applied to the number below):\n//   - missing / unset / non-integer / 0 / negative  -> reset to default 20\n//   - 1 through 9                                    -> forced UP to minimum 10\n//   - 10 or greater                                 -> used as-is\n//\n// Zombie culling is always enabled. There is no config knob. Before cap\n// rejection, launch/tool/hook paths refresh live owned slots, preserve stale\n// slots whose owner server is still alive, and cull stale slots whose owner is\n// gone. Managed stale slots terminate the child process tree, then force-kill\n// after 20s when needed; unmanaged stale slots are only unlinked.\n//\n// When the cap is reached after culling, launch_agent is REJECTED (never\n// queued). Free a slot with list_agents + kill_agent, then retry.\n{\n  \"globalConcurrentSubagents\": 20\n}\n";
+export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\n// ------------------------------------------------------------------\n// SOLE source of truth for the machine-wide limit on how many subagents\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\n// machine. There is NO environment-variable override for the cap.\n//\n// The whole recursive descendant tree counts toward this ONE number: a\n// subagent that itself launches subagents adds to the same machine-wide\n// total, and OTHER active agentic sessions count too.\n//\n// RE-READ on every launch_agent call — edits take effect immediately, no\n// server restart required.\n//\n// Value rules (forcibly applied to the number below):\n//   - missing / unset / non-integer / 0 / negative  -> reset to default 20\n//   - 1 through 9                                    -> forced UP to minimum 10\n//   - 10 or greater                                 -> used as-is\n//\n// Zombie culling is always enabled. There is no config knob. Before cap\n// rejection, launch/tool/hook paths refresh live owned slots, preserve stale\n// slots whose owner server is still alive, and cull stale slots whose owner is\n// gone. Managed stale slots terminate the child process tree, then force-kill\n// after 20s when needed; unmanaged stale slots are only unlinked.\n//\n// When the cap is reached after culling, launch_agent is REJECTED (never\n// queued). Free a slot with list_agents + kill_agent, then retry.\n//\n// checkForUpdates controls the silent npmjs update check started when the MCP\n// server connects. Default true. Set to false to skip the registry fetch and\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true\n}\n";

package/dist/effort.js

@@ -6,6 +6,8 @@ export function mapModel(provider, model) {
     if (provider === "claude") {
         if (model === "opus" || model === "opus-4-8")
             return "claude-opus-4-8";
+        if (model === "fable")
+            return "claude-fable-5";
         return model; // haiku, sonnet as-is
     }
     else {
@@ -26,7 +28,7 @@ export function resolveEffort(provider, model, effort) {
     if (provider === "claude" && model === "haiku") {
         return { kind: "none" };
     }
-    if (provider === "claude" && ["sonnet", "opus", "opus-4-8"].includes(model)) {
+    if (provider === "claude" && ["sonnet", "opus", "opus-4-8", "fable"].includes(model)) {
         if (["medium", "high", "xhigh", "max"].includes(effort)) {
             return { kind: "flag", value: effort };
         }

package/dist/global-concurrency.jsonc

@@ -2,7 +2,7 @@
 // ------------------------------------------------------------------
 // SOLE source of truth for the machine-wide limit on how many subagents
 // may be ALIVE AT ONCE across EVERY session, process, and user on this
-// machine. There is NO environment-variable override.
+// machine. There is NO environment-variable override for the cap.
 //
 // The whole recursive descendant tree counts toward this ONE number: a
 // subagent that itself launches subagents adds to the same machine-wide
@@ -24,6 +24,11 @@
 //
 // When the cap is reached after culling, launch_agent is REJECTED (never
 // queued). Free a slot with list_agents + kill_agent, then retry.
+//
+// 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.
 {
-  "globalConcurrentSubagents": 20
+  "globalConcurrentSubagents": 20,
+  "checkForUpdates": true
 }

package/dist/hooks/orchestration-codex.js

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { claimAndEmit, appendHookZombieReport, classifyClaim, countJsonlType, cullHookZombies, runHook, sessionKey, } from "../orchestration/hook-core.js";
+import { claimAndEmit, classifyClaim, countJsonlType, cullHookZombies, runHook, sessionKey, } from "../orchestration/hook-core.js";
 import * as marker from "../orchestration/marker.js";
 /**
  * Codex CLI hook entry. Branches on payload.hook_event_name:
@@ -80,13 +80,13 @@ export const codexAdapter = {
 export function runCodexHook(payload, env, adapter = codexAdapter) {
     try {
         if (payload.hook_event_name === "SessionStart") {
-            const zombieRecords = cullHookZombies();
+            cullHookZombies();
             if (adapter.isSubagent(payload, env)) {
-                return appendHookZombieReport("", zombieRecords);
+                return "";
             }
             const cwd = payload.cwd || process.cwd();
             if (!marker.isActive(cwd)) {
-                return appendHookZombieReport("", zombieRecords);
+                return "";
             }
             const current = sessionKey(payload);
             const turn = adapter.currentTurn(payload.transcript_path);
@@ -96,7 +96,7 @@ export function runCodexHook(payload, env, adapter = codexAdapter) {
             // 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 appendHookZombieReport(claimAndEmit(cwd, current, turn, m, kind, env, adapter), zombieRecords);
+            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

@@ -22,6 +22,7 @@ import { CONFIG_FILENAME, NONBLOCKING_CULL_DEPS, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_L
 import * as orchestrationMarker from "./orchestration/marker.js";
 import * as modelMode from "./orchestration/model-mode.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
+import { checkForNpmUpdate } from "./orchestration/update-check.js";
 import { ensureParentMarker } from "./launch-prompt.js";
 const agents = new Map();
 const deadlockWindow = createDeadlockWindow();
@@ -263,7 +264,7 @@ function withMaintenance(handler, options = {}) {
     return async (params) => {
         const zombieRecords = runToolMaintenance();
         const result = await handler(params, zombieRecords);
-        if (options.omitZombieReport)
+        if (!options.includeZombieReport)
             return result;
         if (result && typeof result === "object" && "content" in result) {
             return withZombieReport(result, zombieRecords);
@@ -441,7 +442,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.\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.1",
+    version: "2.12.2",
     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"
@@ -800,7 +801,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
     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(),
+    model: z.enum(["haiku", "sonnet", "opus", "opus-4-8", "fable", "gpt-5.5"]).optional(),
     effort: z.enum(["medium", "high", "xhigh", "max", "ultracode"]).optional(),
     cwd: z.string().optional(),
     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."),
@@ -1008,7 +1009,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
         .map((s, i) => `  ${i + 1}. ${s.model}@${s.effort} (${s.provider}) [${s.failure_type}]: ${s.reason}`)
         .join("\n");
     return errorResult(`Error: all ${skipped.length} candidate launches failed for task_category ${task_category}:\n${lines}\n${SPLIT_HINT}\n${AUTO_HINT}`);
-}, { omitZombieReport: true }) // ponytail: launch_agent still reaps, but callers do not receive zombie_report.
+}) // ponytail: launch_agent still reaps, but callers do not receive zombie_report.
 );
 // Tool 2: poll_agent
 server.tool("poll_agent", "Get an agent's current status and output. `processing` = ALIVE with visible provider activity in the last 10 min; `stalled` = ALIVE but no visible provider stream item for 10 min (thinking, or awaiting a temp-file handoff) — NOT dead, so prefer `wait`/re-poll over killing. Always returns `alive` + `idle_seconds`, plus `recent_stream` (last 3 timestamped visible stream items) and a `hint` while stalled. `verbose: true` also returns `final_output`, the agent's final assistant turn from its captured stdout.", {
@@ -1080,7 +1081,7 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
             },
         ],
     };
-}));
+}, { includeZombieReport: true }));
 // Tool 3: kill_agent
 server.tool("kill_agent", "Terminate a live agent/session (status `processing`, `stalled`, or turn-finished but still interactive) by immediately force-killing its managed driver. No-op for already-terminal closed agents.", {
     agent_id: z.string(),
@@ -1257,7 +1258,7 @@ server.tool("list_agents", "List all agents with token-efficient core metrics (s
             },
         ],
     };
-}));
+}, { includeZombieReport: true }));
 // Tool 6: wait
 server.tool("wait", "Blocks until one or more sub-agents reach a reportable state (turn-finished, errored, stopped, or zombie_killed), returning exit code when known + local-time timestamp; or returns the live-job list after a 15-minute timeout. This is how you learn an agent finished — do NOT poll-loop. A `finished` agent with null exit_code is still alive and accepts `send_message`; a `stalled` agent is still ALIVE and does NOT end the wait. `verbose: true` adds each finished agent's `final_output`.", {
     verbose: z.boolean().optional().default(false),
@@ -1598,6 +1599,7 @@ if (isMain) {
     // (the tool's enabled:false writes a disable record via writeDisable /
     // writeDisableCwd; it does not call disable().)
     getNpmPrefix();
+    void checkForNpmUpdate().catch(() => { });
     startLivenessHeartbeat();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/orchestration/hook-core.js

@@ -5,6 +5,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import * as marker from "./marker.js";
 import * as reminder from "./reminder.js";
 import { cullStaleSlots, slotDir, ZOMBIE_FORCE_GRACE_MS, } from "../concurrency.js";
+import { appendUpdateNotice, readInstalledPackageInfo, } from "./update-check.js";
 /**
  * Provider-agnostic core of the UserPromptSubmit / SessionStart hook.
  *
@@ -240,15 +241,13 @@ export function cullHookZombies(deps = hookCullDeps()) {
         return [];
     }
 }
-export function hookZombieReportText(records) {
-    const ids = Array.from(new Set(records.map((r) => r.agent_id))).filter(Boolean);
-    return ids.length > 0 ? `zombies: ${ids.join(",")}` : "";
-}
-export function appendHookZombieReport(out, records) {
-    const report = hookZombieReportText(records);
-    if (!report)
+function appendHookUpdateNotice(out, current, env) {
+    try {
+        return appendUpdateNotice(out, readInstalledPackageInfo().version, current, env);
+    }
+    catch {
         return out;
-    return out ? `${out}\n${report}` : report;
+    }
 }
 /**
  * Core hook logic. Returns the string to inject, or '' to inject nothing.
@@ -269,28 +268,29 @@ export function appendHookZombieReport(out, records) {
  */
 export function runHook(payload, env, adapter) {
     try {
-        const zombieRecords = cullHookZombies();
+        cullHookZombies();
         if (adapter.isSubagent(payload, env)) {
-            return appendHookZombieReport("", zombieRecords);
+            return "";
         }
         const cwd = payload.cwd || process.cwd();
         const current = sessionKey(payload);
+        const updateNoticeSessionId = typeof payload.session_id === "string" ? payload.session_id : undefined;
         if (current)
             marker.writeCurrentSession(cwd, current);
         if (!marker.isActive(cwd, current)) {
             // OFF: no claim machinery — just the per-prompt reminder cadence.
             const r = reminder.advance(cwd, current);
-            return appendHookZombieReport(cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted), zombieRecords);
+            return appendHookUpdateNotice(cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted), updateNoticeSessionId, env);
         }
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
         if (kind === "fresh" || kind === "carryover") {
             const turn = adapter.currentTurn(payload.transcript_path);
-            return appendHookZombieReport(claimAndEmit(cwd, current, turn, m, kind, env, adapter), zombieRecords);
+            return appendHookUpdateNotice(claimAndEmit(cwd, current, turn, m, kind, env, adapter), updateNoticeSessionId, env);
         }
         // SAME-SESSION: per-prompt reminder cadence, ON variant.
         const r = reminder.advance(cwd, current);
-        return appendHookZombieReport(cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted), zombieRecords);
+        return appendHookUpdateNotice(cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted), updateNoticeSessionId, env);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/orchestration/pretool.js

@@ -1,5 +1,5 @@
 import { serverAlive } from "./liveness.js";
-import { cullHookZombies, hookZombieReportText } from "./hook-core.js";
+import { cullHookZombies } from "./hook-core.js";
 const NATIVE_SUBAGENT_TOOLS = new Set(["Task", "Agent", "Explore"]);
 function decision(permissionDecision, permissionDecisionReason, additionalContext) {
     return {
@@ -22,21 +22,21 @@ function decision(permissionDecision, permissionDecisionReason, additionalContex
  */
 export function runClaudePreTool(payload, env, now = Date.now()) {
     try {
-        const zombieReport = hookZombieReportText(cullHookZombies());
+        const zombieRecords = cullHookZombies();
         if (env.SUBAGENT_MCP_SUBAGENT === "1")
             return null;
-        const zombieAllowedDecision = zombieReport
-            ? decision("allow", "zombies culled; allowing requested tool.", zombieReport)
+        const maintenanceAllowedDecision = zombieRecords.length > 0
+            ? decision("allow", "maintenance completed; allowing requested tool.")
             : null;
         if (!serverAlive(now))
-            return zombieAllowedDecision;
+            return maintenanceAllowedDecision;
         const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
         if (!tool)
-            return zombieAllowedDecision;
+            return maintenanceAllowedDecision;
         if (NATIVE_SUBAGENT_TOOLS.has(tool)) {
-            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.", zombieReport || undefined);
+            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.");
         }
-        return zombieAllowedDecision;
+        return maintenanceAllowedDecision;
     }
     catch {
         return null;

package/dist/orchestration/update-check.js

@@ -0,0 +1,174 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { readCheckForUpdates } from "../concurrency.js";
+import { stateDir } from "./marker.js";
+export const UPDATE_NOTICE_TEXT = "Notice: An improved version of subagent-mcp is available via the CLI command `subagent-mcp update` and can then be fully installed with `subagent-mcp setup`. This will fix security issues and improve user experience.";
+export const UPDATE_CHECK_TIMEOUT_MS = 2500;
+export const UPDATE_NOTICE_INTERVAL_MS = 12 * 60 * 60 * 1000;
+function pendingNoticePath() {
+    return join(stateDir, "update-notice.json");
+}
+function emitRecordPath() {
+    return join(stateDir, "update-notice-emitted.json");
+}
+function atomicWriteJson(path, value) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(value), { encoding: "utf8", mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch {
+        // Fail-safe: update notices must never affect the host turn or MCP channel.
+    }
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function removeFile(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Fail-safe.
+    }
+}
+export function clearUpdateNoticeState() {
+    removeFile(pendingNoticePath());
+    removeFile(emitRecordPath());
+}
+export function writePendingUpdateNotice(latestVersion, now = Date.now()) {
+    atomicWriteJson(pendingNoticePath(), {
+        latest_version: latestVersion,
+        checked_at: new Date(now).toISOString(),
+    });
+}
+export function readPendingUpdateNotice() {
+    const parsed = readJson(pendingNoticePath());
+    if (parsed &&
+        typeof parsed.latest_version === "string" &&
+        typeof parsed.checked_at === "string") {
+        return { latest_version: parsed.latest_version, checked_at: parsed.checked_at };
+    }
+    return undefined;
+}
+export function readUpdateNoticeEmitRecord() {
+    const parsed = readJson(emitRecordPath());
+    if (!parsed || typeof parsed.notified_at !== "number")
+        return undefined;
+    return {
+        notified_at: parsed.notified_at,
+        ...(typeof parsed.session_id === "string" ? { session_id: parsed.session_id } : {}),
+    };
+}
+function writeUpdateNoticeEmitRecord(record) {
+    atomicWriteJson(emitRecordPath(), record);
+}
+export function updateCheckEnvDisabled(env = process.env) {
+    const raw = env.SUBAGENT_UPDATE_CHECK;
+    return typeof raw === "string" && /^(?:0|false)$/i.test(raw.trim());
+}
+export function shouldCheckForUpdates(env = process.env, configPath) {
+    if (updateCheckEnvDisabled(env))
+        return false;
+    return readCheckForUpdates(configPath);
+}
+export function compareNumericVersions(a, b) {
+    const parse = (value) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)(?:$|[^\d])/.exec(value.trim());
+        return match ? match.slice(1, 4).map((part) => Number.parseInt(part, 10)) : undefined;
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] < right[i])
+            return -1;
+        if (left[i] > right[i])
+            return 1;
+    }
+    return 0;
+}
+export function isVersionNewer(latest, installed) {
+    return compareNumericVersions(installed, latest) < 0;
+}
+export function readInstalledPackageInfo() {
+    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+}
+function registryPackageUrl(packageName, registryBaseUrl) {
+    const base = registryBaseUrl.replace(/\/+$/, "");
+    return `${base}/${packageName.replace("/", "%2F")}`;
+}
+async function fetchLatestVersion(packageName, deps) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), deps.timeoutMs);
+    try {
+        const response = await deps.fetch(registryPackageUrl(packageName, deps.registryBaseUrl), {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return undefined;
+        const metadata = (await response.json());
+        return typeof metadata?.["dist-tags"]?.latest === "string"
+            ? metadata["dist-tags"].latest
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function checkForNpmUpdate(deps = {}) {
+    try {
+        const env = deps.env ?? process.env;
+        if (!shouldCheckForUpdates(env, deps.configPath))
+            return;
+        const pkg = (deps.packageInfo ?? readInstalledPackageInfo)();
+        const latest = await fetchLatestVersion(pkg.name, {
+            fetch: deps.fetch ?? fetch,
+            registryBaseUrl: deps.registryBaseUrl ?? "https://registry.npmjs.org",
+            timeoutMs: deps.timeoutMs ?? UPDATE_CHECK_TIMEOUT_MS,
+        });
+        if (latest && isVersionNewer(latest, pkg.version)) {
+            writePendingUpdateNotice(latest, deps.now?.() ?? Date.now());
+        }
+    }
+    catch {
+        // Silent skip: never throw and never log to MCP stdio.
+    }
+}
+export function appendUpdateNotice(out, installedVersion, sessionId, env = process.env, now = Date.now(), configPath) {
+    try {
+        if (!out || !shouldCheckForUpdates(env, configPath))
+            return out;
+        const pending = readPendingUpdateNotice();
+        if (!pending)
+            return out;
+        if (!isVersionNewer(pending.latest_version, installedVersion)) {
+            removeFile(pendingNoticePath());
+            return out;
+        }
+        const emitted = readUpdateNoticeEmitRecord();
+        if (emitted?.session_id && sessionId && emitted.session_id === sessionId)
+            return out;
+        if (emitted && now - emitted.notified_at < UPDATE_NOTICE_INTERVAL_MS)
+            return out;
+        writeUpdateNoticeEmitRecord({
+            notified_at: now,
+            ...(sessionId ? { session_id: sessionId } : {}),
+        });
+        return `${out}\n${UPDATE_NOTICE_TEXT}`;
+    }
+    catch {
+        return out;
+    }
+}

package/dist/routing.js

@@ -12,7 +12,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** Launch model enum accepted by buildCommand. */
-export const LAUNCH_MODELS = ["haiku", "sonnet", "opus", "opus-4-8", "gpt-5.5"];
+export const LAUNCH_MODELS = ["haiku", "sonnet", "opus", "opus-4-8", "fable", "gpt-5.5"];
 /** Launch effort enum accepted by buildCommand/resolveEffort. */
 export const LAUNCH_EFFORTS = ["medium", "high", "xhigh", "max", "ultracode"];
 /** Sentinel reported (and passed-through harmlessly) for haiku, whose effort is ignored. */
@@ -28,12 +28,14 @@ const FULL_TO_SHORT = {
     "claude-opus-4-8": new Set(["opus", "opus-4-8"]),
     "claude-sonnet-4-6": "sonnet",
     "claude-haiku-4-5": "haiku",
+    "claude-fable-5": "fable",
     "gpt-5.5": "gpt-5.5",
     // Short ids may already appear in a hand-authored table; map them through.
     haiku: "haiku",
     sonnet: "sonnet",
     opus: "opus",
     "opus-4-8": "opus-4-8",
+    fable: "fable",
 };
 export const DEFAULT_BRANCH = "cost_efficiency";
 /** Resolve dist/routing-table.json relative to this module at runtime. */
@@ -76,6 +78,7 @@ export function mapModelToProvider(model) {
         model === "sonnet" ||
         model === "opus" ||
         model === "opus-4-8" ||
+        model === "fable" ||
         model.startsWith("claude-")) {
         return "claude";
     }
@@ -252,8 +255,8 @@ export function validatePresence(p) {
     }
     // provider+model must satisfy the existing match rule.
     if (provider && model) {
-        if (provider === "claude" && !["haiku", "sonnet", "opus", "opus-4-8"].includes(model)) {
-            return `Error: Claude provider only supports haiku, sonnet, opus, or opus-4-8. Got: ${model}`;
+        if (provider === "claude" && !["haiku", "sonnet", "opus", "opus-4-8", "fable"].includes(model)) {
+            return `Error: Claude provider only supports haiku, sonnet, opus, opus-4-8, or fable. Got: ${model}`;
         }
         if (provider === "codex" && model !== "gpt-5.5") {
             return `Error: Codex provider only supports gpt-5.5. Got: ${model}`;

package/dist/ruleset-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/advanced-ruleset.py — DO NOT EDIT.
-export const RULESET_SCAFFOLD = "#!/usr/bin/env python3\n\"\"\"advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.\n\n(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent\n    call. Slow rules slow every agent launch. Keep rules lean and low-latency —\n    no network calls, no heavy imports at module top. This is YOUR responsibility;\n    you have been warned.\n\n(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified\n    candidate list (reorder / filter / replace allowed). Template:\n    [\n      {\"provider\": \"claude\", \"model\": \"sonnet\",  \"effort\": \"high\",  \"rank\": 1},\n      {\"provider\": \"codex\",  \"model\": \"gpt-5.5\", \"effort\": \"xhigh\", \"rank\": 2}\n    ]\n    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);\n    gpt-5.5 (codex). Valid efforts: haiku -> \"none\" only; sonnet -> medium|high|xhigh|max;\n    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.\n    \"rank\" on output is ignored. An EMPTY array vetoes the launch. Anything else\n    invalid fails the launch hard — the server validates strictly.\n\n(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):\n    stdin receives one JSON object:\n    { \"candidates\": [ {\"provider\",\"model\",\"effort\",\"rank\"} ... ],   # rank 1..N best->worst\n      \"context\": { \"task_category\": str, \"cwd\": str,\n                   \"selection_mode\": \"auto\"|\"provider\"|\"provider_model\"|\"explicit\",\n                   \"provider\": str|None, \"model\": str|None, \"effort\": str|None } }\n    OS environment variables are visible natively (os.environ).\n\nENV-CHECK MODE (no arguments): prints {\"ready\": true|false, \"load-rules\": true|false}.\nRuns once per MCP server process. load-rules false => ruleset silently disabled\nfor the rest of the process. Set LOAD_RULES = True below to activate.\n\"\"\"\nimport json\nimport sys\n\nLOAD_RULES = False\n\n# --- Requirements stub (scaffold itself is stdlib-only) ----------------------\n# List third-party distributions your rules import, e.g.:\n# REQUIREMENTS = [\"requests\", \"pyyaml\"]\n# Install with:  <python> -m pip install <name> ...\nREQUIREMENTS = []\n\ndef missing_requirements():\n    \"\"\"pip-check helper: returns the REQUIREMENTS entries not importable here.\"\"\"\n    import importlib.util\n    return [r for r in REQUIREMENTS\n            if importlib.util.find_spec(r.replace(\"-\", \"_\")) is None]\n\ndef env_check():\n    missing = missing_requirements()\n    json.dump({\"ready\": not missing, \"load-rules\": bool(LOAD_RULES)}, sys.stdout)\n\ndef apply_rules(candidates, context):\n    \"\"\"YOUR RULES HERE. Default: passthrough (returns the list unchanged).\"\"\"\n    return candidates\n\ndef route():\n    payload = json.load(sys.stdin)\n    out = apply_rules(payload.get(\"candidates\", []), payload.get(\"context\", {}))\n    json.dump(out, sys.stdout)\n\nif __name__ == \"__main__\":\n    if len(sys.argv) > 1 and sys.argv[1] == \"route\":\n        route()\n    else:\n        env_check()\n";
+export const RULESET_SCAFFOLD = "#!/usr/bin/env python3\n\"\"\"advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.\n\n(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent\n    call. Slow rules slow every agent launch. Keep rules lean and low-latency —\n    no network calls, no heavy imports at module top. This is YOUR responsibility;\n    you have been warned.\n\n(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified\n    candidate list (reorder / filter / replace allowed). Template:\n    [\n      {\"provider\": \"claude\", \"model\": \"sonnet\",  \"effort\": \"high\",  \"rank\": 1},\n      {\"provider\": \"codex\",  \"model\": \"gpt-5.5\", \"effort\": \"xhigh\", \"rank\": 2}\n    ]\n    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8, fable (claude);\n    gpt-5.5 (codex). Valid efforts: haiku -> \"none\" only; sonnet -> medium|high|xhigh|max;\n    fable -> medium|high|xhigh|max; opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.\n    \"rank\" on output is ignored. An EMPTY array vetoes the launch. Anything else\n    invalid fails the launch hard — the server validates strictly.\n\n(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):\n    stdin receives one JSON object:\n    { \"candidates\": [ {\"provider\",\"model\",\"effort\",\"rank\"} ... ],   # rank 1..N best->worst\n      \"context\": { \"task_category\": str, \"cwd\": str,\n                   \"selection_mode\": \"auto\"|\"provider\"|\"provider_model\"|\"explicit\",\n                   \"provider\": str|None, \"model\": str|None, \"effort\": str|None } }\n    OS environment variables are visible natively (os.environ).\n\nENV-CHECK MODE (no arguments): prints {\"ready\": true|false, \"load-rules\": true|false}.\nRuns once per MCP server process. load-rules false => ruleset silently disabled\nfor the rest of the process. Set LOAD_RULES = True below to activate.\n\"\"\"\nimport json\nimport sys\n\nLOAD_RULES = False\n\n# --- Requirements stub (scaffold itself is stdlib-only) ----------------------\n# List third-party distributions your rules import, e.g.:\n# REQUIREMENTS = [\"requests\", \"pyyaml\"]\n# Install with:  <python> -m pip install <name> ...\nREQUIREMENTS = []\n\ndef missing_requirements():\n    \"\"\"pip-check helper: returns the REQUIREMENTS entries not importable here.\"\"\"\n    import importlib.util\n    return [r for r in REQUIREMENTS\n            if importlib.util.find_spec(r.replace(\"-\", \"_\")) is None]\n\ndef env_check():\n    missing = missing_requirements()\n    json.dump({\"ready\": not missing, \"load-rules\": bool(LOAD_RULES)}, sys.stdout)\n\ndef apply_rules(candidates, context):\n    \"\"\"YOUR RULES HERE. Default: passthrough (returns the list unchanged).\"\"\"\n    return candidates\n\ndef route():\n    payload = json.load(sys.stdin)\n    out = apply_rules(payload.get(\"candidates\", []), payload.get(\"context\", {}))\n    json.dump(out, sys.stdout)\n\nif __name__ == \"__main__\":\n    if len(sys.argv) > 1 and sys.argv[1] == \"route\":\n        route()\n    else:\n        env_check()\n";

package/dist/ruleset.js

@@ -169,7 +169,7 @@ const CODEX_EFFORTS = LAUNCH_EFFORTS.filter((e) => e !== "ultracode" && e !== "m
 function effortAllowed(model, effort) {
     if (model === "haiku")
         return effort === HAIKU_EFFORT;
-    if (model === "sonnet")
+    if (model === "sonnet" || model === "fable")
         return SONNET_EFFORTS.includes(effort);
     if (model === "opus" || model === "opus-4-8") {
         return LAUNCH_EFFORTS.includes(effort);
@@ -185,7 +185,7 @@ function effortAllowed(model, effort) {
  *
  * Per element: string provider/model/effort; provider ∈ {claude, codex};
  * model ∈ launch enum; provider↔model legality (claude↔{haiku,sonnet,opus,
- * opus-4-8}, codex↔gpt-5.5); per-model effort legality incl. haiku→"none".
+ * opus-4-8,fable}, codex↔gpt-5.5); per-model effort legality incl. haiku→"none".
  * Extra keys (incl. rank) are ignored on output; duplicates are allowed (the
  * attempt loop just tries them in order). An EMPTY array is VALID — it is the
  * limit case of the allowed filter operation and means "veto the launch"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.12.1",
+  "version": "2.12.2",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",
@@ -38,7 +38,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm test",
-    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/zombie.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/zombie.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
   },
   "author": "Lexi Blackburn",
   "license": "Apache-2.0",