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

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { spawn, spawnSync, execSync } from "child_process";
-import { unlinkSync, existsSync, realpathSync, readFileSync, writeFileSync } from "node:fs";
+import { unlinkSync, existsSync, realpathSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { randomUUID } from "crypto";
 import { isAbsolute, basename, join, dirname } from "node:path";
 import { tmpdir } from "node:os";
@@ -11,19 +11,21 @@ import { pathToFileURL } from "url";
 import { buildCommand } from "./effort.js";
 import { createProviderDriver } from "./drivers.js";
 import { resolveExeFor } from "./platform.js";
-import { formatLocalIso, selectUnreported } from "./wait-helpers.js";
+import { formatLocalIso, selectUnreported, selectUnreportedPermissionRequested, } from "./wait-helpers.js";
 import { computeStatusTransition, buildLivenessFields, } 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";
 import { createDeadlockWindow } from "./deadlock.js";
 import { createRulesetGate, RULESET_HARD_FAIL_MSG, } from "./ruleset.js";
-import { CONFIG_FILENAME, NONBLOCKING_CULL_DEPS, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, defaultConfigPath, globalCapMessage, readSlotMetadata, readGlobalCap, releaseSlot, reserveSlot, slotDir, writeSlotMetadata, } from "./concurrency.js";
+import { CONFIG_FILENAME, NONBLOCKING_CULL_DEPS, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, defaultConfigPath, globalCapMessage, readSlotMetadata, readMergedPermissionConfig, readPermissionsCeiling, readGlobalCap, releaseSlot, reserveSlot, slotDir, writeSlotMetadata, } from "./concurrency.js";
+import { shouldReapTerminalButAlive } from "./zombie.js";
 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";
+import { pendingPermissionManager, } from "./pending-permissions.js";
 const agents = new Map();
 const deadlockWindow = createDeadlockWindow();
 const STDOUT_RING_BYTES = 2 * 1024 * 1024;
@@ -31,6 +33,60 @@ const STDOUT_RING_BYTES = 2 * 1024 * 1024;
 // scoping. The env-check runs lazily at the FIRST launch_agent call; success
 // latches enabled/disabled for the process lifetime, failure never latches.
 const rulesetGate = createRulesetGate();
+function ceilingRank(ceiling) {
+    return ceiling === "manual" ? 0 : ceiling === "auto" ? 1 : 2;
+}
+function buildPermissionSnapshot(cwd) {
+    const merged = readMergedPermissionConfig(cwd);
+    return {
+        ceiling: merged.permissionsCeiling,
+        escalation: merged.escalation,
+        rules: {
+            allow: merged.allow,
+            ask: merged.ask,
+            deny: merged.deny,
+        },
+        additionalDirectories: merged.additionalDirectories,
+        repoConfigChangedSinceFirstSeen: merged.repoConfigChangedSinceFirstSeen,
+    };
+}
+function isStalePermissive(agent) {
+    if (!isLiveAgent(agent))
+        return false;
+    const current = readPermissionsCeiling();
+    return ceilingRank(agent.permissionSnapshot.ceiling) > ceilingRank(current);
+}
+function pendingPermissionSummary(record, now = Date.now()) {
+    return {
+        request_id: record.request_id,
+        tool_name_or_method: record.tool_name_or_method,
+        harness_channel: record.harness_channel,
+        permission_ceiling: record.permission_ceiling,
+        escalation: record.escalation,
+        irreversible: record.irreversible,
+        escalate_to_human: record.escalate_to_human,
+        requested_at: formatLocalIso(record.requested_at),
+        age_seconds: Math.floor((now - record.requested_at) / 1000),
+    };
+}
+pendingPermissionManager.onAgentQueueChange((agentId, pendingCount) => {
+    const agent = agents.get(agentId);
+    if (!agent || 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;
+        agent.lastActivity = Date.now();
+        updateSlotMetadata(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
 // crash) — the attempt loop silently advances instead of falsely reporting
@@ -95,7 +151,9 @@ function slotHeartbeatIntervalMs() {
     return Math.max(1000, Math.min(30_000, Math.floor(zombieLiveIdleMs() / 3)));
 }
 function isLiveAgent(agent) {
-    return agent.status === "processing" || agent.status === "stalled";
+    return (agent.status === "processing" ||
+        agent.status === "permission_requested" ||
+        agent.status === "stalled");
 }
 function isSameOwnerSlot(agent, slotMeta) {
     if (!slotMeta)
@@ -171,6 +229,7 @@ function scheduleZombieForceKill(agent) {
     timer.unref();
 }
 function markZombieKilled(agent, reason, now) {
+    void pendingPermissionManager.closeAgent(agent.id, "agent stopped by operator");
     agent.status = "zombie_killed";
     agent.exitCode = agent.exitCode ?? -1;
     agent.exitedAt = agent.exitedAt ?? now;
@@ -209,6 +268,7 @@ function applyZombieRecord(record, now) {
     const agent = agents.get(record.agent_id);
     if (!agent || agent.status === "zombie_killed")
         return null;
+    void pendingPermissionManager.closeAgent(agent.id, "agent stopped by operator");
     agent.status = "zombie_killed";
     agent.exitCode = agent.exitCode ?? -1;
     agent.exitedAt = agent.exitedAt ?? now;
@@ -246,10 +306,7 @@ function runToolMaintenance() {
         }
         const slotMeta = agent.slotPath ? readSlotMetadata(agent.slotPath) : null;
         adoptNewerSlotActivity(agent, slotMeta);
-        const terminalButAlive = (agent.status === "finished" || agent.status === "errored" || agent.status === "stopped") &&
-            !agent.driver.closed &&
-            agent.exitedAt !== null &&
-            now - agent.exitedAt > zombieTerminalIdleMs();
+        const terminalButAlive = shouldReapTerminalButAlive(agent, now, zombieTerminalIdleMs());
         if (terminalButAlive) {
             const record = markZombieKilled(agent, "terminal_but_alive", now);
             records.push(record);
@@ -378,6 +435,8 @@ function handleCompletedStdoutLines(agent, lines, at) {
             agent.status = "finished";
             if (agent.exitedAt === null)
                 agent.exitedAt = at;
+            releaseSlot(agent.slotPath ?? null);
+            agent.slotPath = null;
         }
     }
 }
@@ -394,6 +453,15 @@ function cleanupUcSettings(agentState) {
         catch { }
         agentState.ucSettingsPath = undefined;
     }
+    if (agentState.ucSettingsDir) {
+        try {
+            if (existsSync(agentState.ucSettingsDir)) {
+                rmSync(agentState.ucSettingsDir, { recursive: true, force: true });
+            }
+        }
+        catch { }
+        agentState.ucSettingsDir = undefined;
+    }
 }
 // Synchronously reconcile a single agent's status against the pure transition
 // helper. Folds the live process exitCode into AgentState first so an already-
@@ -442,7 +510,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.3",
+    version: "2.12.5-beta.0",
     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"
@@ -452,7 +520,7 @@ const server = new McpServer({
 // Best-effort removal of a candidate's temp ultracode settings file after a
 // LAUNCH-TIME failure (the agentState is never registered, so the close handler
 // will not run cleanupUcSettings for it).
-function cleanupUcSettingsPath(ucSettingsPath) {
+function cleanupUcSettingsPath(ucSettingsPath, ucSettingsDir) {
     if (!ucSettingsPath)
         return;
     try {
@@ -460,6 +528,13 @@ function cleanupUcSettingsPath(ucSettingsPath) {
             unlinkSync(ucSettingsPath);
     }
     catch { }
+    if (!ucSettingsDir)
+        return;
+    try {
+        if (existsSync(ucSettingsDir))
+            rmSync(ucSettingsDir, { recursive: true, force: true });
+    }
+    catch { }
 }
 // Attempt to spawn + register a single candidate. Resolves to the agent_id on a
 // successful driver start, or a launch-time failure reason string (never throws/rejects).
@@ -472,14 +547,15 @@ function cleanupUcSettingsPath(ucSettingsPath) {
 // 'error' handler stays attached so a LATE spawn error can never crash the
 // process. Any launch-time failure cleans up and is reported so the attempt loop
 // silently advances to the next candidate.
-async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetInfo) {
+async function tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapshot, routingTier, rulesetInfo) {
     // Build the command. haiku ignores effort; pass "high" placeholder for the
     // "none" sentinel (buildCommand drops it for haiku anyway).
     const effortForBuild = candidate.effort === "none" ? "high" : candidate.effort;
+    const agentId = randomUUID();
     let buildResult;
     let cmd;
     try {
-        buildResult = buildCommand(candidate.provider, candidate.model, effortForBuild, agentCwd);
+        buildResult = buildCommand(candidate.provider, candidate.model, effortForBuild, agentCwd, agentId);
         cmd = resolveExe(candidate.provider);
     }
     catch (e) {
@@ -489,7 +565,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
     // Fast-fail absolute paths only. Bare names intentionally rely on PATH; spawn
     // below resolves them and reports ENOENT/EACCES through the same failure path.
     if (isAbsolute(cmd) && !existsSync(cmd)) {
-        cleanupUcSettingsPath(buildResult.ucSettingsPath);
+        cleanupUcSettingsPath(buildResult.ucSettingsPath, buildResult.ucSettingsDir);
         return { reason: `CLI executable not found: ${cmd}`, failure_type: "permanent" };
     }
     let driver;
@@ -503,11 +579,12 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
             model: candidate.model,
             effort: candidate.effort,
             ucSettingsPath: buildResult.ucSettingsPath,
+            ucSettingsDir: buildResult.ucSettingsDir,
         });
     }
     catch (error) {
         // Synchronous spawn throw (rare) — clean up and report as a launch failure.
-        cleanupUcSettingsPath(buildResult.ucSettingsPath);
+        cleanupUcSettingsPath(buildResult.ucSettingsPath, buildResult.ucSettingsDir);
         const reason = error instanceof Error ? error.message : String(error);
         return { reason, failure_type: classifyFailureReason(reason, "") };
     }
@@ -547,14 +624,13 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
             driver.kill();
         }
         catch { }
-        cleanupUcSettingsPath(buildResult.ucSettingsPath);
+        cleanupUcSettingsPath(buildResult.ucSettingsPath, buildResult.ucSettingsDir);
         const reason = err instanceof Error ? err.message : String(err);
         return { reason, failure_type: classifyFailureReason(reason, "") };
     }
     // Spawn succeeded. Register the agent exactly as before. Keep a persistent
     // 'error' handler so a LATE spawn error never crashes the process; fold it
     // into stderr rather than throwing.
-    const agentId = randomUUID();
     const now = Date.now();
     const agentState = {
         id: agentId,
@@ -580,7 +656,9 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         startedAt: now,
         lastActivity: now,
         cwd: agentCwd,
+        permissionSnapshot,
         ucSettingsPath: buildResult.ucSettingsPath,
+        ucSettingsDir: buildResult.ucSettingsDir,
         waitReported: false,
         visibleStream: [],
         streamBuf: "",
@@ -635,6 +713,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         });
     }
     childProcess.on("close", (code) => {
+        void pendingPermissionManager.closeAgent(agentState.id, "agent process exited while permission request was pending");
         // Flush any buffered trailing stdout line (final event may arrive without a
         // terminating newline) so its visible item is not lost.
         if (agentState.streamBuf) {
@@ -812,6 +891,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
     // mutates the body). This is what makes the child first-line exemption fire.
     const prompt = ensureParentMarker(params.prompt);
     const agentCwd = params.cwd || process.cwd();
+    const permissionSnapshot = buildPermissionSnapshot(agentCwd);
     // 1-5. Param-presence validation (zod already constrains task_category, but
     //       hard-validate so the spec error text — valid list + hints, and the
     //       effort-before-model ordering — is what the caller sees). Pure,
@@ -914,7 +994,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
     let launched = false;
     try {
         for (const candidate of candidates) {
-            const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
+            const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapshot, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
                 ? { applied: true, originalSelection: rulesetOriginalSelection }
                 : undefined);
             if ("agentId" in outcome) {
@@ -955,6 +1035,15 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
                                 model: candidate.model,
                                 effort: candidate.effort,
                                 task_category,
+                                permissions_applied: {
+                                    ceiling: permissionSnapshot.ceiling,
+                                    escalation: permissionSnapshot.escalation,
+                                    allow_count: permissionSnapshot.rules.allow?.length ?? 0,
+                                    ask_count: permissionSnapshot.rules.ask?.length ?? 0,
+                                    deny_count: permissionSnapshot.rules.deny?.length ?? 0,
+                                    additional_directories_count: permissionSnapshot.additionalDirectories?.length ?? 0,
+                                    repo_config_changed_since_first_seen: permissionSnapshot.repoConfigChangedSinceFirstSeen ?? false,
+                                },
                                 ...(rulesetApplied
                                     ? {
                                         ruleset_applied: true,
@@ -1012,7 +1101,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
 }) // 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.", {
+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. Polling refreshes the agent's idle clock. 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.", {
     agent_id: z.string(),
     verbose: z.boolean().optional().default(false),
 }, withMaintenance(async (params) => {
@@ -1032,6 +1121,7 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
     // completed/failed immediately (no up-to-10s health-monitor lag).
     const now = Date.now();
     reconcileAgent(agent, now);
+    agent.lastActivity = now;
     const escapedStdout = escapeUntrustedTags(agent.stdout);
     const escapedStderr = escapeUntrustedTags(agent.stderr);
     const stdoutTail = envelopeUntrustedOutput(escapedStdout.length > 2000
@@ -1055,6 +1145,17 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
                     last_activity: agent.lastActivity,
                     cwd: agent.cwd,
                     ...liveness,
+                    ...(pendingPermissionManager.pendingCount(agent.id) > 0
+                        ? {
+                            pending_permissions: pendingPermissionManager.pendingForAgent(agent.id),
+                        }
+                        : {}),
+                    ...(isStalePermissive(agent)
+                        ? {
+                            stale_permissive: true,
+                            stale_permissive_hint: "agent launched under a more permissive ceiling than current config; consider kill_agent",
+                        }
+                        : {}),
                     ...(agent.rulesetApplied
                         ? {
                             ruleset_applied: true,
@@ -1085,7 +1186,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.", {
+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. A finished agent is force-killed automatically after 6 minutes of no `send_message`/`poll_agent` activity; call `kill_agent` sooner to free resources immediately. No-op for already-terminal closed agents.", {
     agent_id: z.string(),
 }, withMaintenance(async (params) => {
     const agent = agents.get(params.agent_id);
@@ -1103,7 +1204,10 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
     // Kill applies to ALL live driver states (processing, stalled, or finished
     // current turn with an open interactive session). Closed terminal agents are
     // a no-op.
-    const isLive = (agent.status === "processing" || agent.status === "stalled" || agent.status === "finished") &&
+    const isLive = (agent.status === "processing" ||
+        agent.status === "permission_requested" ||
+        agent.status === "stalled" ||
+        agent.status === "finished") &&
         !agent.driver.closed;
     if (!isLive) {
         return {
@@ -1123,6 +1227,7 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
         // Immediately force-kill the managed process tree — no graceful SIGTERM
         // grace period. On Windows, taskkill /t /f tears down the whole tree; on
         // POSIX, SIGKILL the process (close handler records the real exit code).
+        await pendingPermissionManager.closeAgent(agent.id, "agent stopped by operator");
         agent.status = "stopped";
         agent.driver.kill();
         releaseSlot(agent.slotPath ?? null);
@@ -1164,7 +1269,52 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
         };
     }
 }));
-// Tool 4: send_message
+// Tool 4: respond_permission (parents only; children cannot approve other children)
+if (process.env.SUBAGENT_MCP_SUBAGENT !== "1") {
+    server.tool("respond_permission", "Answer a parked permission request for an agent. One-time only; does not create session-wide approvals. If request_id is omitted, answers the agent's oldest pending request.", {
+        agent_id: z.string(),
+        request_id: z.string().optional(),
+        decision: z.enum(["allow", "deny"]),
+        reason: z.string().optional(),
+    }, withMaintenance(async (params) => {
+        const agent = agents.get(params.agent_id);
+        if (!agent) {
+            return {
+                content: [{ type: "text", text: `Error: Agent ${params.agent_id} not found` }],
+                isError: true,
+            };
+        }
+        try {
+            const answered = await pendingPermissionManager.respond(agent.id, params.request_id, params.decision, params.reason);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            agent_id: agent.id,
+                            request_id: answered.request_id,
+                            decision: answered.answer,
+                            status: agent.status,
+                            pending_permission_count: pendingPermissionManager.pendingCount(agent.id),
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error responding to permission request: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+}
+// Tool 5: send_message
 server.tool("send_message", "Enqueue a user message for an open interactive agent session. Observe output with poll_agent or wait.", {
     agent_id: z.string(),
     message: z.string().min(1),
@@ -1181,7 +1331,10 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
             isError: true,
         };
     }
-    const isLive = (agent.status === "processing" || agent.status === "stalled" || agent.status === "finished") &&
+    const isLive = (agent.status === "processing" ||
+        agent.status === "permission_requested" ||
+        agent.status === "stalled" ||
+        agent.status === "finished") &&
         !agent.driver.closed;
     if (!isLive) {
         return {
@@ -1194,6 +1347,19 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
             isError: true,
         };
     }
+    const pendingCount = pendingPermissionManager.pendingCount(agent.id);
+    if (pendingCount > 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: agent has ${pendingCount} pending permission request(s); ` +
+                        `call respond_permission before sending further messages`,
+                },
+            ],
+            isError: true,
+        };
+    }
     try {
         await agent.driver.send(params.message);
         const now = Date.now();
@@ -1232,7 +1398,7 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
         };
     }
 }));
-// Tool 5: list_agents
+// Tool 6: list_agents
 server.tool("list_agents", "List all agents with token-efficient core metrics (status, `alive`, `idle_seconds`). `stalled` is ALIVE-but-quiet, NOT dead (full status semantics on poll_agent). Use `poll_agent` for per-agent stream items, hints, and final output.", {}, withMaintenance(async () => {
     const now = Date.now();
     const agentList = Array.from(agents.values()).map((agent) => {
@@ -1249,6 +1415,8 @@ server.tool("list_agents", "List all agents with token-efficient core metrics (s
             started_at: agent.startedAt,
             last_activity: agent.lastActivity,
             cwd_basename: basename(agent.cwd),
+            pending_permission_count: pendingPermissionManager.pendingCount(agent.id),
+            ...(isStalePermissive(agent) ? { stale_permissive: true } : {}),
             ...buildLivenessFields(agent.status, agent.exitCode, agent.lastActivity, now, false),
         };
     });
@@ -1261,8 +1429,8 @@ 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`.", {
+// Tool 7: 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`; `send_message`/`poll_agent` activity keeps it alive, and 6 minutes idle auto-kills it. 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),
 }, withMaintenance(async (params, zombieRecords) => {
     const { verbose } = params;
@@ -1291,15 +1459,43 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
         started_at_local: formatLocalIso(a.startedAt),
         last_activity_local: formatLocalIso(a.lastActivity),
         elapsed_ms: now - a.startedAt,
+        ...(isStalePermissive(a) ? { stale_permissive: true } : {}),
+        ...(a.status === "permission_requested"
+            ? {
+                pending_permissions: pendingPermissionManager
+                    .pendingForAgent(a.id)
+                    .map((p) => pendingPermissionSummary(p, now)),
+            }
+            : {}),
+    });
+    const buildPermissionRequestedEntry = (a, now) => ({
+        id: a.id,
+        provider: a.provider,
+        model: a.model,
+        status: a.status,
+        ...(isStalePermissive(a) ? { stale_permissive: true } : {}),
+        pending_permissions: pendingPermissionManager
+            .pendingForAgent(a.id)
+            .map((p) => pendingPermissionSummary(p, now)),
     });
     // Step 1: collect already-terminal unreported agents
     const allAgents = Array.from(agents.values());
     let unreported = selectUnreported(allAgents);
-    if (unreported.length > 0) {
+    let unreportedPermissionRequested = selectUnreportedPermissionRequested(allAgents);
+    if (unreported.length > 0 || unreportedPermissionRequested.length > 0) {
         // Mark reported synchronously before building return (single-threaded JS → atomic)
         for (const a of unreported)
             a.waitReported = true;
-        const payload = { finished: unreported.map(buildFinishedEntry) };
+        for (const a of unreportedPermissionRequested)
+            a.waitReported = true;
+        const payload = {
+            ...(unreported.length > 0 ? { finished: unreported.map(buildFinishedEntry) } : {}),
+            ...(unreportedPermissionRequested.length > 0
+                ? {
+                    permission_requested: unreportedPermissionRequested.map((a) => buildPermissionRequestedEntry(a, Date.now())),
+                }
+                : {}),
+        };
         return {
             content: [{ type: "text", text: JSON.stringify(payload) }],
         };
@@ -1308,6 +1504,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     // `stalled` is a LIVE state — it keeps the wait pending, it never ends it.
     const TERMINAL_SET = new Set(["finished", "errored", "stopped", "zombie_killed"]);
     const hasPending = Array.from(agents.values()).some((a) => a.status === "processing" ||
+        a.status === "permission_requested" ||
         a.status === "stalled" ||
         (TERMINAL_SET.has(a.status) && a.exitedAt === null));
     if (!hasPending) {
@@ -1322,12 +1519,23 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     // Step 3: block-poll until a terminal agent appears or deadline passes
     while (Date.now() < deadline) {
         await sleep(250);
-        unreported = selectUnreported(Array.from(agents.values()));
         zombieRecords.push(...runToolMaintenance());
-        if (unreported.length > 0) {
+        const loopAgents = Array.from(agents.values());
+        unreported = selectUnreported(loopAgents);
+        unreportedPermissionRequested = selectUnreportedPermissionRequested(loopAgents);
+        if (unreported.length > 0 || unreportedPermissionRequested.length > 0) {
             for (const a of unreported)
                 a.waitReported = true;
-            const payload = { finished: unreported.map(buildFinishedEntry) };
+            for (const a of unreportedPermissionRequested)
+                a.waitReported = true;
+            const payload = {
+                ...(unreported.length > 0 ? { finished: unreported.map(buildFinishedEntry) } : {}),
+                ...(unreportedPermissionRequested.length > 0
+                    ? {
+                        permission_requested: unreportedPermissionRequested.map((a) => buildPermissionRequestedEntry(a, Date.now())),
+                    }
+                    : {}),
+            };
             return {
                 content: [{ type: "text", text: JSON.stringify(payload) }],
             };
@@ -1335,7 +1543,9 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     }
     // Step 4: timeout — return still-running jobs
     const now = Date.now();
-    const stillRunning = Array.from(agents.values()).filter((a) => a.status === "processing" || a.status === "stalled");
+    const stillRunning = Array.from(agents.values()).filter((a) => a.status === "processing" ||
+        a.status === "permission_requested" ||
+        a.status === "stalled");
     const payload = {
         timed_out: true,
         elapsed_minutes: 15,
@@ -1346,7 +1556,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
         content: [{ type: "text", text: JSON.stringify(payload) }],
     };
 }));
-// Tool 7: orchestration-mode
+// 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 applies to THIS session only, resumes ON next new session (or after the 2h backstop), no mid-session re-enable. 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.", {
     enabled: z.boolean().optional(),
 }, withMaintenance(async (params) => {