@heretyc/subagent-mcp 2.12.5-beta.0 → 2.12.5-beta.2

package/dist/drivers.js

@@ -831,33 +831,52 @@ export class ClaudeSdkDriver {
             allowDangerouslySkipPermissions: isYolo,
             settingSources: [],
             tools: { type: "preset", preset: "claude_code" },
+            // Shared gate: the SINGLE source of truth for every permission decision.
+            // `harnessChannel` names the SDK surface that invoked it so parked prompts
+            // are attributable. canUseTool and the PreToolUse hook both route here.
             canUseTool: async (request) => {
-                const op = permissionOpFromClaudeRequest(request, options.cwd);
-                const engineResult = verdict(op, permissionSnapshot.rules);
-                if (isYolo && isBypassImmuneClaudeAsk(request, op)) {
-                    return denyClaudePermission("bypass-immune Claude safety prompt auto-denied under yolo");
-                }
-                const decision = applyPermissionCeiling(engineResult.verdict, permissionSnapshot.ceiling);
-                if (decision !== "ask") {
-                    return permissionDecisionToClaude(decision, engineResult.reason);
-                }
-                const pendingDecision = await requestPendingPermission({
-                    agentId: options.agentId,
-                    harnessChannel: "claude-canUseTool",
-                    toolNameOrMethod: op.tool,
-                    action: claudeToolInput(request),
-                    permissionCeiling: permissionSnapshot.ceiling,
-                    escalation: permissionSnapshot.escalation,
-                    irreversible: engineResult.irreversible,
-                    reason: engineResult.reason,
-                    suggestions: [],
-                    correlationId: claudeCorrelationId(request),
-                });
-                return permissionDecisionToClaude(pendingDecision.verdict, pendingDecision.reason);
+                return this.gateRequest(request, options, permissionSnapshot, isYolo, "claude-canUseTool");
             },
             maxTurns: 50,
             includePartialMessages: true,
         };
+        // PreToolUse hook: with permissionMode:"default" + settingSources:[] the SDK
+        // auto-approves Bash (and any tool it treats as pre-approved) WITHOUT calling
+        // canUseTool, so those calls would bypass the engine gate entirely. Register a
+        // PreToolUse hook (no matcher => every tool) that routes EVERY tool call
+        // through the same gate: allow -> continue, deny -> block with reason, ask ->
+        // park via requestPendingPermission and resolve on respond/timeout. The hook
+        // returns a concrete allow/deny, so canUseTool never double-fires for a tool
+        // the hook already decided (it remains as fallback for anything the hook does
+        // not cover). The yolo path stays hook-free — no gating there by design.
+        if (!isYolo) {
+            sdkOptions.hooks = {
+                PreToolUse: [
+                    {
+                        hooks: [
+                            async (input) => {
+                                const request = {
+                                    tool_name: input.tool_name,
+                                    tool_input: input.tool_input,
+                                    tool_use_id: input.tool_use_id,
+                                };
+                                const result = await this.gateRequest(request, options, permissionSnapshot, isYolo, "claude-pretooluse-hook");
+                                const allow = result.behavior === "allow";
+                                return {
+                                    hookSpecificOutput: {
+                                        hookEventName: "PreToolUse",
+                                        permissionDecision: allow ? "allow" : "deny",
+                                        permissionDecisionReason: allow
+                                            ? ""
+                                            : result.message,
+                                    },
+                                };
+                            },
+                        ],
+                    },
+                ],
+            };
+        }
         if (options.effort !== "none" && options.effort !== "ultracode") {
             sdkOptions.effort = options.effort;
         }
@@ -867,6 +886,33 @@ export class ClaudeSdkDriver {
         this.queryHandle = query;
         void this.pump(query);
     }
+    // Single permission gate shared by canUseTool and the PreToolUse hook. Returns
+    // allow/deny; parks (early-returns to the parent, resolves on respond/timeout)
+    // when the engine verdict is "ask".
+    async gateRequest(request, options, permissionSnapshot, isYolo, harnessChannel) {
+        const op = permissionOpFromClaudeRequest(request, options.cwd);
+        const engineResult = verdict(op, permissionSnapshot.rules);
+        if (isYolo && isBypassImmuneClaudeAsk(request, op)) {
+            return denyClaudePermission("bypass-immune Claude safety prompt auto-denied under yolo");
+        }
+        const decision = applyPermissionCeiling(engineResult.verdict, permissionSnapshot.ceiling);
+        if (decision !== "ask") {
+            return permissionDecisionToClaude(decision, engineResult.reason);
+        }
+        const pendingDecision = await requestPendingPermission({
+            agentId: options.agentId,
+            harnessChannel,
+            toolNameOrMethod: op.tool,
+            action: claudeToolInput(request),
+            permissionCeiling: permissionSnapshot.ceiling,
+            escalation: permissionSnapshot.escalation,
+            irreversible: engineResult.irreversible,
+            reason: engineResult.reason,
+            suggestions: [],
+            correlationId: claudeCorrelationId(request),
+        });
+        return permissionDecisionToClaude(pendingDecision.verdict, pendingDecision.reason);
+    }
     start(message) {
         return this.send(message);
     }

package/dist/index.js

@@ -12,7 +12,7 @@ import { buildCommand } from "./effort.js";
 import { createProviderDriver } from "./drivers.js";
 import { resolveExeFor } from "./platform.js";
 import { formatLocalIso, selectUnreported, selectUnreportedPermissionRequested, } from "./wait-helpers.js";
-import { computeStatusTransition, buildLivenessFields, } from "./status-helpers.js";
+import { computeStatusTransition, buildLivenessFields, reconcilePermissionStatus, } from "./status-helpers.js";
 import { escapeUntrustedTags, envelopeUntrustedOutput, extractFinalTurn, } from "./output-helpers.js";
 import { consumeStreamChunk, flushStream, isTurnCompletedLine, retainLastN, } from "./stream-helpers.js";
 import { loadRoutingTable, buildCandidates, validatePresence, TASK_CATEGORIES, AUTO_HINT, SPLIT_HINT, } from "./routing.js";
@@ -69,23 +69,29 @@ function pendingPermissionSummary(record, now = Date.now()) {
         age_seconds: Math.floor((now - record.requested_at) / 1000),
     };
 }
-pendingPermissionManager.onAgentQueueChange((agentId, pendingCount) => {
-    const agent = agents.get(agentId);
-    if (!agent || agent.exitCode !== null)
+// Reconcile one agent's live status against its current pending-permission
+// depth. Used by the live queue listener AND at registration time (agents.set)
+// to recover a park whose queue event fired before the agent was registered —
+// the Codex approval race, where approvals arrive during driver.start() inside
+// the spawn-grace window, ahead of agents.set. Idempotent and no-op unless the
+// pure rule says the status must change.
+function reconcileAgentPermissionStatus(agent) {
+    if (agent.exitCode !== null)
         return;
-    if (pendingCount > 0) {
-        if (agent.status === "processing" || agent.status === "stalled") {
-            agent.status = "permission_requested";
-            agent.waitReported = false;
-            updateSlotMetadata(agent);
-        }
-    }
-    else if (agent.status === "permission_requested") {
-        agent.status = "processing";
-        agent.waitReported = false;
+    const { status, changed } = reconcilePermissionStatus(agent.status, pendingPermissionManager.pendingCount(agent.id));
+    if (!changed)
+        return;
+    agent.status = status;
+    agent.waitReported = false;
+    if (status === "processing")
         agent.lastActivity = Date.now();
-        updateSlotMetadata(agent);
-    }
+    updateSlotMetadata(agent);
+}
+pendingPermissionManager.onAgentQueueChange((agentId) => {
+    const agent = agents.get(agentId);
+    if (!agent)
+        return;
+    reconcileAgentPermissionStatus(agent);
 });
 // Post-spawn grace window (ms). A provider driver that exits within this window
 // after a successful driver start never launched (not logged in, expired auth, instant
@@ -510,7 +516,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.5-beta.0",
+    version: "2.12.5-beta.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"
@@ -580,6 +586,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapsho
             effort: candidate.effort,
             ucSettingsPath: buildResult.ucSettingsPath,
             ucSettingsDir: buildResult.ucSettingsDir,
+            agentId,
         });
     }
     catch (error) {
@@ -848,6 +855,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapsho
             const startedBeforeStartError = await readStartedBoundary();
             if (startedBeforeStartError) {
                 agents.set(agentId, agentState);
+                reconcileAgentPermissionStatus(agentState);
                 return { agentId };
             }
             // Lived past the grace window but the startup write failed: the child is
@@ -865,6 +873,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapsho
         }
     }
     agents.set(agentId, agentState);
+    reconcileAgentPermissionStatus(agentState);
     return { agentId };
 }
 // Order-sensitive (provider, model, effort) list equality. Detects whether the
@@ -1147,7 +1156,9 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
                     ...liveness,
                     ...(pendingPermissionManager.pendingCount(agent.id) > 0
                         ? {
-                            pending_permissions: pendingPermissionManager.pendingForAgent(agent.id),
+                            pending_permissions: pendingPermissionManager
+                                .pendingForAgent(agent.id)
+                                .map((p) => pendingPermissionSummary(p, now)),
                         }
                         : {}),
                     ...(isStalePermissive(agent)

package/dist/pending-permissions.js

@@ -2,7 +2,14 @@ import { randomUUID } from "node:crypto";
 const PARK_TIMEOUT_MS = 5 * 60 * 1000;
 const PER_AGENT_FIFO_CAP = 16;
 function publicRecord(record) {
-    return { ...record };
+    // record may be a StoredPendingPermission at runtime, which carries a live
+    // NodeJS.Timeout and a resolve closure. Both are non-serializable (the timer
+    // is circular via TimersList), so strip them — a leaked timer crashes any
+    // JSON.stringify of a public record (e.g. poll_agent's pending_permissions).
+    const { timer, resolve, ...clean } = record;
+    void timer;
+    void resolve;
+    return clean;
 }
 function shouldEscalateToHuman(input) {
     return (input.permission_ceiling === "auto" &&

package/dist/permission-engine.js

@@ -58,9 +58,15 @@ export function verdict(op, rules = {}) {
 export function applyPermissionCeiling(engineVote, ceiling) {
     if (ceiling === "yolo")
         return "allow";
-    if (ceiling === "manual")
-        return minVerdict(engineVote, "ask");
-    return minVerdict(engineVote, "allow");
+    // The ceilings are NOT points on a permissiveness total order (the J2-9
+    // "total-order-over-modes" mistake). Neither `auto` nor `manual` may demote
+    // the engine's allow (SAFE) or deny (DANGER) decisions: SAFE always
+    // auto-allows, DANGER always auto-denies, and only NEUTRAL residue ("ask")
+    // parks. The auto/manual difference is solely *who* answers an "ask" —
+    // `auto` escalates only irreversible residue to a human while `manual` routes
+    // all residue to a human — which is decided downstream (see pending-permissions
+    // `escalate_to_human`), never by mapping SAFE ops to "ask" here.
+    return engineVote;
 }
 export function classifyPermissionOp(op) {
     const command = commandText(op);
@@ -247,7 +253,3 @@ function wildcardMatch(pattern, value) {
     const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[\\s\\S]*");
     return new RegExp(`^${escaped}$`, "i").test(value);
 }
-function minVerdict(a, b) {
-    const rank = { deny: 0, ask: 1, allow: 2 };
-    return rank[a] <= rank[b] ? a : b;
-}

package/dist/status-helpers.js

@@ -45,6 +45,21 @@ export function computeStatusTransition(input) {
     }
     return { status, exitedAt: input.exitedAt };
 }
+// Pure reconciliation of an agent's live status against its pending-permission
+// queue depth. Mirrors the onAgentQueueChange listener so registration-time
+// reconciliation and the live listener share one rule. A park that fires BEFORE
+// the agent is registered (the Codex approval race: approvals arrive during
+// driver.start(), inside the spawn-grace window, before agents.set) loses its
+// queue event; re-running this after registration recovers the flip.
+export function reconcilePermissionStatus(status, pendingCount) {
+    if (pendingCount > 0 && (status === "processing" || status === "stalled")) {
+        return { status: "permission_requested", changed: true };
+    }
+    if (pendingCount === 0 && status === "permission_requested") {
+        return { status: "processing", changed: true };
+    }
+    return { status, changed: false };
+}
 // Pure formatter for the per-agent liveness fields shared by poll_agent and
 // list_agents. `hint` is present ONLY when status === "stalled" AND the caller
 // opts in (poll_agent does; list_agents omits it to stay token-efficient).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.12.5-beta.0",
+  "version": "2.12.5-beta.2",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",