@heretyc/subagent-mcp 2.12.8 → 2.12.9

package/dist/concurrency.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir, platform } from "node:os";
+import { homedir, platform, userInfo } from "node:os";
 import { dirname, join, parse as parsePath, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONCURRENCY_SCAFFOLD } from "./config-scaffold.js";
@@ -11,6 +11,7 @@ export const DEFAULT_CHECK_FOR_UPDATES = true;
 export const DEFAULT_PERMISSIONS_CEILING = "auto";
 export const DEFAULT_ESCALATION = "irreversible-only";
 export const DEFAULT_STRICT_READ_PARITY = "warn";
+export const DEFAULT_SANDBOX_NETWORK = false;
 export const CONFIG_FILENAME = "global-subagent-mcp-config.jsonc";
 export const LEGACY_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, };
@@ -83,6 +84,15 @@ export function parseStrictReadParityConfig(text) {
         return DEFAULT_STRICT_READ_PARITY;
     }
 }
+export function parseSandboxNetworkConfig(text) {
+    try {
+        const raw = parseJsonObject(text).sandboxNetwork;
+        return typeof raw === "boolean" ? raw : DEFAULT_SANDBOX_NETWORK;
+    }
+    catch {
+        return DEFAULT_SANDBOX_NETWORK;
+    }
+}
 export function defaultConfigPath() {
     return fileURLToPath(new URL("./" + CONFIG_FILENAME, import.meta.url));
 }
@@ -118,6 +128,7 @@ export function readGlobalConfig(path = defaultConfigPath()) {
             permissionsCeiling: parsePermissionsCeilingConfig(text),
             escalation: parseEscalationConfig(text),
             strictReadParity: parseStrictReadParityConfig(text),
+            sandboxNetwork: parseSandboxNetworkConfig(text),
             path: resolved.path,
             usedLegacyPath: resolved.usedLegacyPath,
             parseFailure: null,
@@ -130,6 +141,7 @@ export function readGlobalConfig(path = defaultConfigPath()) {
             permissionsCeiling: "manual",
             escalation: DEFAULT_ESCALATION,
             strictReadParity: DEFAULT_STRICT_READ_PARITY,
+            sandboxNetwork: DEFAULT_SANDBOX_NETWORK,
             path,
             usedLegacyPath: false,
             parseFailure: e instanceof Error ? e.message : String(e),
@@ -151,6 +163,9 @@ export function readEscalation(path = defaultConfigPath()) {
 export function readStrictReadParity(path = defaultConfigPath()) {
     return readGlobalConfig(path).strictReadParity;
 }
+export function readSandboxNetwork(path = defaultConfigPath()) {
+    return readGlobalConfig(path).sandboxNetwork;
+}
 let legacyConfigDeprecationPending = false;
 export function noteLegacyConfigIfUsed(path = defaultConfigPath()) {
     if (resolveGlobalConfigPath(path).usedLegacyPath)
@@ -208,7 +223,7 @@ function readClaudePermissions(source, path, userScoped) {
         }
         const disableBypass = userScoped && parsed.disableBypassPermissionsMode === "disable";
         return {
-            rules: { allow, deny, ask, additionalDirectories },
+            rules: { allow, deny, ask, additionalDirectories, sandboxNetwork: false },
             disableBypass,
             failure: null,
         };
@@ -227,6 +242,7 @@ function blanketMutatingAskRules() {
         deny: [],
         ask: ["Bash", "Edit", "Write", "NotebookEdit", "MultiEdit"],
         additionalDirectories: [],
+        sandboxNetwork: false,
     };
 }
 function mergeRules(target, next) {
@@ -234,6 +250,7 @@ function mergeRules(target, next) {
     target.deny.push(...next.deny);
     target.ask.push(...next.ask);
     target.additionalDirectories.push(...next.additionalDirectories);
+    target.sandboxNetwork ||= next.sandboxNetwork;
 }
 function unique(items) {
     return [...new Set(items)];
@@ -274,10 +291,14 @@ function readCodexConfig(path) {
     try {
         const text = readFileSync(path, "utf8");
         assertBasicTomlParsable(text);
-        const rules = { allow: [], deny: [], ask: [], additionalDirectories: [] };
+        const rules = { allow: [], deny: [], ask: [], additionalDirectories: [], sandboxNetwork: false };
         if (codexTomlValue(text, "sandbox_mode") === "read-only") {
             rules.deny.push("Edit", "Write", "NotebookEdit");
         }
+        if (/\bsandbox_workspace_write\.network_access\s*=\s*true\b/i.test(text) ||
+            /^\s*\[sandbox_workspace_write\][\s\S]*?^\s*network_access\s*=\s*true\b/im.test(text)) {
+            rules.sandboxNetwork = true;
+        }
         rules.additionalDirectories.push(...codexTomlArray(text, "writable_roots"));
         for (const m of text.matchAll(/^\s*path\s*=\s*["']([^"']+)["']\s*\r?\n\s*access\s*=\s*["']deny["']/gm)) {
             rules.deny.push(`Edit(${m[1]})`, `Write(${m[1]})`);
@@ -285,6 +306,10 @@ function readCodexConfig(path) {
         for (const m of text.matchAll(/^\s*domain\s*=\s*["']([^"']+)["']\s*\r?\n\s*access\s*=\s*["']deny["']/gm)) {
             rules.deny.push(`WebFetch(domain:${m[1]})`);
         }
+        for (const m of text.matchAll(/^\s*domain\s*=\s*["']([^"']+)["']\s*\r?\n\s*access\s*=\s*["']allow["']/gm)) {
+            rules.allow.push(`WebFetch(domain:${m[1]})`);
+            rules.sandboxNetwork = true;
+        }
         return { rules, failure: null };
     }
     catch (e) {
@@ -327,7 +352,13 @@ const firstRepoDigests = new Map();
 export function readMergedPermissionConfig(cwd, path = defaultConfigPath()) {
     const global = readGlobalConfig(path);
     noteLegacyConfigIfUsed(path);
-    const merged = { allow: [], deny: [], ask: [], additionalDirectories: [] };
+    const merged = {
+        allow: [],
+        deny: [],
+        ask: [],
+        additionalDirectories: [],
+        sandboxNetwork: global.sandboxNetwork,
+    };
     const failures = [];
     let ceiling = global.permissionsCeiling;
     if (global.parseFailure) {
@@ -377,6 +408,7 @@ export function readMergedPermissionConfig(cwd, path = defaultConfigPath()) {
         deny: unique(merged.deny),
         ask: unique(merged.ask),
         additionalDirectories: unique(merged.additionalDirectories).filter((p) => !protectedDirs.has(resolve(p))),
+        sandboxNetwork: merged.sandboxNetwork,
         permissionsCeiling: ceiling,
         escalation: global.escalation,
         strictReadParity: global.strictReadParity,
@@ -385,7 +417,24 @@ export function readMergedPermissionConfig(cwd, path = defaultConfigPath()) {
         selfProtectionDeny,
     };
 }
-export function slotDir() {
+function safeSlotNamespace(raw) {
+    const cleaned = raw.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return cleaned || createHash("sha256").update(raw || "unknown").digest("hex").slice(0, 16);
+}
+export function currentUserSlotNamespace() {
+    try {
+        const info = userInfo();
+        if (platform() !== "win32" && Number.isInteger(info.uid))
+            return `uid-${info.uid}`;
+        return safeSlotNamespace(info.username);
+    }
+    catch { }
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (typeof uid === "number")
+        return `uid-${uid}`;
+    return safeSlotNamespace(process.env.USERNAME || process.env.USER || "unknown");
+}
+export function slotBaseDir() {
     if (process.env.SUBAGENT_SLOT_DIR)
         return process.env.SUBAGENT_SLOT_DIR;
     if (platform() === "win32") {
@@ -393,6 +442,9 @@ export function slotDir() {
     }
     return "/tmp/subagent-mcp/slots";
 }
+export function slotDir() {
+    return join(slotBaseDir(), currentUserSlotNamespace());
+}
 export function countSlots(dir = slotDir()) {
     try {
         return readdirSync(dir).filter((f) => f.startsWith("slot-")).length;
@@ -410,7 +462,13 @@ export const NONBLOCKING_CULL_DEPS = {
 };
 export function reserveSlot(agentId, max, dir = slotDir(), cullDeps) {
     try {
-        mkdirSync(dir, { recursive: true, mode: 0o1777 });
+        if (dir === slotDir()) {
+            mkdirSync(slotBaseDir(), { recursive: true, mode: 0o1777 });
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        else {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
         cullStaleSlots(dir, cullDeps);
         const slotPath = slotPathForAgent(dir, agentId);
         const before = countSlots(dir);

package/dist/config-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-subagent-mcp-config.jsonc — DO NOT EDIT.
-export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\n// ------------------------------------------------------------------\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\n// available beside the compiled server.\n//\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\n// across EVERY session, process, and user on this machine. There is NO\n// environment-variable override for the cap.\n//\n// RE-READ on every launch_agent call - edits take effect immediately, no\n// server restart required.\n//\n// Cap value rules:\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// 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// permissionsCeiling controls launch-time permissions posture:\n//   - auto   (default): shared engine gates unsafe/residue actions\n//   - manual: human approval for residue while still auto-denying DANGER\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\n//            for non-bypassable config-file self-protection\n//\n// escalation applies only in auto mode. irreversible-only routes irreversible\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\n//\n// strictReadParity controls logging only. Unparseable Codex approval payloads\n// always fail closed to ask; warn logs the construct, off silences that log.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true,\n  \"permissionsCeiling\": \"auto\",\n  \"escalation\": \"irreversible-only\",\n  \"strictReadParity\": \"warn\"\n}\n";
+export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\n// ------------------------------------------------------------------\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\n// available beside the compiled server.\n//\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\n// across EVERY session, process, and user on this machine. There is NO\n// environment-variable override for the cap.\n//\n// RE-READ on every launch_agent call - edits take effect immediately, no\n// server restart required.\n//\n// Cap value rules:\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// 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// permissionsCeiling controls launch-time permissions posture:\n//   - auto   (default): shared engine gates unsafe/residue actions\n//   - manual: human approval for residue while still auto-denying DANGER\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\n//            for non-bypassable config-file self-protection\n//\n// escalation applies only in auto mode. irreversible-only routes irreversible\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\n//\n// strictReadParity controls logging only. Unparseable Codex approval payloads\n// always fail closed to ask; warn logs the construct, off silences that log.\n//\n// sandboxNetwork controls Codex workspace-write network access. Default false.\n// Set true only when sub-agents need network after permission approval.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true,\n  \"permissionsCeiling\": \"auto\",\n  \"escalation\": \"irreversible-only\",\n  \"strictReadParity\": \"warn\",\n  \"sandboxNetwork\": false\n}\n";

package/dist/drivers.js

@@ -217,9 +217,29 @@ function permissionSnapshotForLaunch(options) {
         additionalDirectories: merged.additionalDirectories,
         repoConfigChangedSinceFirstSeen: merged.repoConfigChangedSinceFirstSeen,
         strictReadParity: merged.strictReadParity,
+        sandboxNetwork: merged.sandboxNetwork,
     };
     return snapshot;
 }
+export function providerChildSpawnOptions(options, p = process.platform) {
+    return {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        detached: p !== "win32",
+    };
+}
+export function killProviderChildProcess(child, signal, p = process.platform, killGroup = process.kill) {
+    if (p !== "win32" && typeof child.pid === "number") {
+        try {
+            killGroup(-child.pid, signal);
+            return true;
+        }
+        catch { }
+    }
+    return child.kill(signal);
+}
 function claudeToolName(request) {
     for (const key of ["toolName", "tool_name", "name"]) {
         const value = request[key];
@@ -273,7 +293,7 @@ function resolveOpPaths(paths, cwd) {
         }
     });
 }
-function permissionOpFromClaudeRequest(request, cwd) {
+function permissionOpFromClaudeRequest(request, cwd, additionalDirectories) {
     const input = claudeToolInput(request);
     const command = stringField(input, ["command", "cmd"]);
     const url = stringField(input, ["url"]);
@@ -292,6 +312,7 @@ function permissionOpFromClaudeRequest(request, cwd) {
         ...(paths.length > 0 ? { paths, resolvedPaths: resolveOpPaths(paths, cwd) } : {}),
         ...(url || host ? { network: [{ ...(url ? { url } : {}), ...(host ? { host } : {}) }] } : {}),
         cwd,
+        ...(additionalDirectories ? { additionalDirectories } : {}),
         irreversible: Boolean(input.irreversible),
     };
 }
@@ -316,21 +337,38 @@ function isBypassImmuneClaudeAsk(request, op) {
 function permissionDecisionToClaude(decision, reason) {
     return decision === "allow" ? allowClaudePermission() : denyClaudePermission(reason);
 }
-function resolveCodexLaunchValues(snapshot) {
+function networkAllowRuleTriggersSandbox(rule) {
+    const trimmed = rule.trim();
+    if (/^WebFetch(?:\b|\()/i.test(trimmed))
+        return true;
+    if (/^Bash(?:\(\s*(?:\*|[\w./\\-]*\s*)?\)|$)/i.test(trimmed))
+        return true;
+    return /^Bash\([^)]*\b(?:git\s+(?:push|fetch|pull|clone|ls-remote)|gh|npm|pnpm|yarn|curl|wget)\b/i.test(trimmed);
+}
+export function resolveCodexLaunchValues(snapshot, logTranslation = true) {
     if (snapshot.ceiling === "yolo") {
         return {
             approvalPolicy: "never",
             threadSandbox: "danger-full-access",
             turnSandboxPolicy: { type: "dangerFullAccess" },
+            cliConfigArgs: [],
         };
     }
+    const driverSnapshot = snapshot;
+    const translatedNetworkAllow = (snapshot.rules.allow ?? []).some(networkAllowRuleTriggersSandbox);
+    const networkAccess = Boolean(driverSnapshot.sandboxNetwork || translatedNetworkAllow);
+    if (logTranslation && translatedNetworkAllow && !driverSnapshot.sandboxNetwork) {
+        console.error("[permissions] translated network allow rule(s) to Codex workspace-write network access");
+    }
     return {
         approvalPolicy: "untrusted",
         threadSandbox: "workspace-write",
         turnSandboxPolicy: {
             type: "workspaceWrite",
             writableRoots: snapshot.additionalDirectories ?? [],
+            ...(networkAccess ? { networkAccess: true } : {}),
         },
+        cliConfigArgs: networkAccess ? ["-c", "sandbox_workspace_write.network_access=true"] : [],
     };
 }
 function isCodexApprovalMethod(method) {
@@ -380,7 +418,7 @@ function codexCommandFromParams(params) {
         return { command: argv.join(" "), argv };
     return {};
 }
-export function codexApprovalOp(method, params, cwd) {
+export function codexApprovalOp(method, params, cwd, additionalDirectories) {
     if (method === "item/commandExecution/requestApproval" || method === "execCommandApproval") {
         const command = codexCommandFromParams(params);
         const opCwd = typeof params.cwd === "string" && params.cwd.length > 0 ? params.cwd : cwd;
@@ -389,6 +427,7 @@ export function codexApprovalOp(method, params, cwd) {
                 tool: "Bash",
                 ...command,
                 cwd: opCwd,
+                ...(additionalDirectories ? { additionalDirectories } : {}),
                 irreversible: Boolean(params.irreversible),
             },
             confidence: Boolean(command.command),
@@ -404,6 +443,7 @@ export function codexApprovalOp(method, params, cwd) {
                 tool: codexFileChangeTool(params.fileChanges),
                 ...(paths.length > 0 ? { paths, resolvedPaths: resolveOpPaths(paths, cwd) } : {}),
                 cwd,
+                ...(additionalDirectories ? { additionalDirectories } : {}),
                 irreversible: false,
             },
             confidence: paths.length > 0 || method === "item/fileChange/requestApproval",
@@ -413,6 +453,7 @@ export function codexApprovalOp(method, params, cwd) {
         op: {
             tool: "mcpServer/elicitation",
             cwd,
+            ...(additionalDirectories ? { additionalDirectories } : {}),
             irreversible: false,
         },
         confidence: false,
@@ -598,7 +639,7 @@ export class CodexAppServerDriver {
     kill() {
         this.process.killed = true;
         this.child.stdin?.destroy();
-        this.child.kill("SIGKILL");
+        killProviderChildProcess(this.child, "SIGKILL");
         this.process.kill("SIGKILL");
         this.rejectPending(new Error("codex app-server driver was killed"));
         this.queuedTurns.length = 0;
@@ -732,7 +773,7 @@ export class CodexAppServerDriver {
             return;
         }
         this.pendingApprovals.set(key, record);
-        const { op, confidence } = codexApprovalOp(method, params, this.options.cwd);
+        const { op, confidence } = codexApprovalOp(method, params, this.options.cwd, this.permissionSnapshot.additionalDirectories);
         const strictReadParity = this.permissionSnapshot.strictReadParity ?? "warn";
         if (!confidence && this.permissionSnapshot.ceiling !== "yolo" && strictReadParity === "warn") {
             console.error(`[permissions] strictReadParity warn: Codex approval payload for ${method} could not be matched with full confidence; routing to ask`);
@@ -890,7 +931,7 @@ export class ClaudeSdkDriver {
     // 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 op = permissionOpFromClaudeRequest(request, options.cwd, permissionSnapshot.additionalDirectories);
         const engineResult = verdict(op, permissionSnapshot.rules);
         if (isYolo && isBypassImmuneClaudeAsk(request, op)) {
             return denyClaudePermission("bypass-immune Claude safety prompt auto-denied under yolo");
@@ -1030,11 +1071,9 @@ export async function createProviderDriver(options) {
         driver.open(options);
         return driver;
     }
-    const child = spawn(options.command, options.args, {
-        cwd: options.cwd,
-        env: options.env,
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
-    });
-    return new CodexAppServerDriver(child, options);
+    const permissionSnapshot = permissionSnapshotForLaunch(options);
+    const launchValues = resolveCodexLaunchValues(permissionSnapshot, false);
+    const driverOptions = options.permissionSnapshot ? options : { ...options, permissionSnapshot };
+    const child = spawn(options.command, [...launchValues.cliConfigArgs, ...options.args], providerChildSpawnOptions(options));
+    return new CodexAppServerDriver(child, driverOptions);
 }

package/dist/global-concurrency.jsonc

@@ -30,10 +30,14 @@
 //
 // strictReadParity controls logging only. Unparseable Codex approval payloads
 // always fail closed to ask; warn logs the construct, off silences that log.
+//
+// sandboxNetwork controls Codex workspace-write network access. Default false.
+// Set true only when sub-agents need network after permission approval.
 {
   "globalConcurrentSubagents": 20,
   "checkForUpdates": true,
   "permissionsCeiling": "auto",
   "escalation": "irreversible-only",
-  "strictReadParity": "warn"
+  "strictReadParity": "warn",
+  "sandboxNetwork": false
 }

package/dist/global-subagent-mcp-config.jsonc

@@ -30,10 +30,14 @@
 //
 // strictReadParity controls logging only. Unparseable Codex approval payloads
 // always fail closed to ask; warn logs the construct, off silences that log.
+//
+// sandboxNetwork controls Codex workspace-write network access. Default false.
+// Set true only when sub-agents need network after permission approval.
 {
   "globalConcurrentSubagents": 20,
   "checkForUpdates": true,
   "permissionsCeiling": "auto",
   "escalation": "irreversible-only",
-  "strictReadParity": "warn"
+  "strictReadParity": "warn",
+  "sandboxNetwork": false
 }

package/dist/index.js

@@ -29,6 +29,7 @@ import { pendingPermissionManager, } from "./pending-permissions.js";
 const agents = new Map();
 const deadlockWindow = createDeadlockWindow();
 const STDOUT_RING_BYTES = 2 * 1024 * 1024;
+export const AGENT_RETENTION_MS = 30 * 60 * 1000;
 // Advanced-ruleset gate: per-process latch with exactly the deadlock-window
 // scoping. The env-check runs lazily at the FIRST launch_agent call; success
 // latches enabled/disabled for the process lifetime, failure never latches.
@@ -116,6 +117,15 @@ const TASK_CATEGORY_GLOSS = "REQUIRED. Task shape -> routing category (server pi
 function errorResult(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
+function currentLaunchDepth(env = process.env) {
+    const raw = env.SUBAGENT_MCP_DEPTH;
+    if (raw !== undefined && raw !== "") {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isInteger(parsed) && parsed >= 0 && String(parsed) === raw.trim())
+            return parsed;
+    }
+    return env.SUBAGENT_MCP_SUBAGENT === "1" ? 1 : 0;
+}
 function envDuration(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined || raw === "")
@@ -161,6 +171,33 @@ function isLiveAgent(agent) {
         agent.status === "permission_requested" ||
         agent.status === "stalled");
 }
+function isTerminalAgentStatus(status) {
+    return (status === "finished" ||
+        status === "errored" ||
+        status === "stopped" ||
+        status === "zombie_killed");
+}
+export function shouldEvictAgent(agent, now = Date.now(), retentionMs = AGENT_RETENTION_MS) {
+    if (!isTerminalAgentStatus(agent.status))
+        return false;
+    if (!agent.driver.closed)
+        return false;
+    if (!agent.waitReported)
+        return false;
+    if (agent.exitedAt === null)
+        return false;
+    return now - agent.exitedAt > retentionMs;
+}
+export function evictExpiredAgents(agentMap, now = Date.now(), retentionMs = AGENT_RETENTION_MS) {
+    let evicted = 0;
+    for (const [id, agent] of agentMap) {
+        if (!shouldEvictAgent(agent, now, retentionMs))
+            continue;
+        agentMap.delete(id);
+        evicted++;
+    }
+    return evicted;
+}
 function isSameOwnerSlot(agent, slotMeta) {
     if (!slotMeta)
         return true;
@@ -321,6 +358,7 @@ function runToolMaintenance() {
         }
         updateSlotMetadata(agent);
     }
+    evictExpiredAgents(agents, now);
     return records;
 }
 function withMaintenance(handler, options = {}) {
@@ -500,6 +538,7 @@ const reconcileInterval = setInterval(() => {
             });
         }
     }
+    evictExpiredAgents(agents, now);
 }, 10000);
 reconcileInterval.unref();
 // Heavy operating-model + governance guidance for ORCHESTRATION MODE. Carried in
@@ -512,10 +551,10 @@ reconcileInterval.unref();
 // compressed under MCP metadata limits:
 // READ-ESCALATION LADDER (the orchestrator's only read channels, in order): (1) subagent-mcp `poll_agent` TAIL; (2) if the tail is insufficient, dispatch ONE sub-agent to return a single summary of <=100 lines, trusted as-is (no separate verification step); (3) anything larger: the USER reads the document directly. No reads or writes occur outside these channels. An empty or stalled tail means the agent is ALIVE, not dead — do NOT busy-loop poll_agent; learn completion via `wait`. Large inter-agent data: the orchestrator assigns scratch-file paths (%TEMP% on Windows, /tmp on POSIX) in prompts; the producing sub-agent writes, the consuming sub-agent reads; the orchestrator NEVER reads those files.
 const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (full spec: docs/spec/dev-loop/orchestration-directive-architecture.md).\n\nPRECEDENCE. The latest <subagent-mcp state=\"...\"> hook tag and repo/system safety rules are jointly binding; genuine conflict => STOP and ask. Only the hook flips ON/OFF; absence of any tag = UNKNOWN => fail-safe ON.\n\nSOLE CHANNEL. Every launch uses launch_agent; never harness Task/Agent or shell-spawned agents.\n\nORCHESTRATION ON. You are a delegate-ONLY orchestrator: use only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and /workflows. No direct reads/writes; inline-by-right does not exist. Non-delegable step: ask a one-time exception, do only that step, resume delegating.\n\nSUB-AGENT CONTRACT. Every prompt carries objective + output format + tools/sources + boundaries. SCALE: ~1 agent for a fact-find, 2-4 for comparisons; never one-shot multi-phase work; split into atomic steps, one agent each. FAN-OUT independents, sequence dependents, SERIALIZE writers over shared paths (no cwd lock). VERIFY code and non-trivial steps with a separate sub-agent first.\n\nREAD LADDER. poll_agent tail -> one <=100-line summarizer sub-agent, trusted as-is -> else the USER reads it. Large handoffs use scratch-file paths; producer writes, consumer reads, orchestrator never reads them. Empty/stalled tail means ALIVE; learn finish via wait, do not poll-loop.\n\nORCHESTRATION OFF. If context footprint since last upgrade ask exceeds 200 lines, after that turn STOP and ask whether to enable; reset count only when you ask.\n\nDROPOUT WHILE ON: HALT and ask until restored. SUB-AGENT EXEMPTION: a prompt whose literal FIRST LINE begins \"<this is a request from a parent process>\" skips this regime. DISABLE: user-only, never on your own initiative.\n\nMODEL SELECTION. Default smart auto-picks, rejects provider/model/effort selectors. user-approved-overrides honors them 30 min, expires lazily on launch_agent, needs user authorization.";
-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 SUBAGENT_INSTRUCTIONS = "SUB-AGENT SESSION: you are a child process launched by subagent-mcp. Follow the parent prompt. Do not treat yourself as the orchestrator, do not re-trigger orchestration carryover, and do not launch further sub-agents unless the parent prompt explicitly assigns that. launch_agent is code-capped at 2 spawn levels below the main orchestrator: depth 1 may launch depth 2 workers; depth 2 workers cannot spawn further.\n\nMODEL SELECTION MODE (parallel to orchestration-mode, set via the model-selection-mode tool). DEFAULT is \"smart\" and is used whenever unset: in smart, launch_agent REJECTS any call supplying provider/model/effort selectors and the server auto-picks the best model. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (the mode reverts to smart on the next launch_agent call after 30 minutes) and re-enabling does NOT extend an active window. HONOR-BASED: you MUST NOT set \"user-approved-overrides\" without explicit interactive USER authorization via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex); never enable it on your own initiative.";
 const server = new McpServer({
     name: "subagent-mcp",
-    version: "2.12.8",
+    version: "2.12.9",
     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,7 +619,11 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, permissionSnapsho
             command: cmd,
             args: buildResult.args,
             cwd: agentCwd,
-            env: { ...process.env, SUBAGENT_MCP_SUBAGENT: "1" },
+            env: {
+                ...process.env,
+                SUBAGENT_MCP_SUBAGENT: "1",
+                SUBAGENT_MCP_DEPTH: String(currentLaunchDepth() + 1),
+            },
             model: candidate.model,
             effort: candidate.effort,
             ucSettingsPath: buildResult.ucSettingsPath,
@@ -894,6 +937,10 @@ server.tool("launch_agent", "Spawn a sub-agent session. CONTRACT: every `prompt`
     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."),
 }, withMaintenance(async (params) => {
     const { task_category, provider, model, effort, deadlock } = params;
+    const launchDepth = currentLaunchDepth();
+    if (launchDepth >= 2) {
+        return errorResult(`Error: launch_agent depth cap reached: current SUBAGENT_MCP_DEPTH=${launchDepth}. subagent-mcp permits exactly 2 spawn levels below the main orchestrator (depth 0 -> 1 -> 2); depth 2 workers cannot spawn further sub-agents.`);
+    }
     // D19/D20/S8: server silently upserts the parent-process marker as the TRUE
     // first line of every sub-agent prompt (idempotent; never duplicates; never
     // mutates the body). This is what makes the child first-line exemption fire.

package/dist/orchestration/pretool.js

@@ -23,8 +23,6 @@ function decision(permissionDecision, permissionDecisionReason, additionalContex
 export function runClaudePreTool(payload, env, now = Date.now()) {
     try {
         const zombieRecords = cullHookZombies();
-        if (env.SUBAGENT_MCP_SUBAGENT === "1")
-            return null;
         const maintenanceAllowedDecision = zombieRecords.length > 0
             ? decision("allow", "maintenance completed; allowing requested tool.")
             : null;
@@ -36,6 +34,8 @@ export function runClaudePreTool(payload, env, now = Date.now()) {
         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.");
         }
+        if (env.SUBAGENT_MCP_SUBAGENT === "1")
+            return maintenanceAllowedDecision;
         return maintenanceAllowedDecision;
     }
     catch {

package/dist/permission-engine.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import permissionClasses from "./permission-classes.json" with { type: "json" };
 const classes = permissionClasses;
 const safeTools = new Set(classes.safe.tools.map(normalizeToolName));
@@ -71,13 +72,20 @@ export function applyPermissionCeiling(engineVote, ceiling) {
 export function classifyPermissionOp(op) {
     const command = commandText(op);
     const irreversible = Boolean(op.irreversible) || (command !== "" && irreversibleRegexes.some((r) => r.test(command)));
-    if (isDangerousPathOp(op)) {
+    if (hasDangerousOrProtectedPath(op)) {
         return {
             classification: "danger",
             irreversible,
             reason: "dangerous or protected path",
         };
     }
+    if (isReadPathOutsideAllowedRoots(op)) {
+        return {
+            classification: "neutral",
+            irreversible,
+            reason: "read path outside allowed roots",
+        };
+    }
     if (normalizeToolName(op.tool) === "bash") {
         if (command === "")
             return { classification: "neutral", irreversible, reason: "empty bash command" };
@@ -170,8 +178,8 @@ function matchesAnyPath(op, pattern) {
         return normalized === rule || normalized.startsWith(`${rule}/`) || wildcardMatch(rule, normalized);
     });
 }
-function isDangerousPathOp(op) {
-    if (!writeTools.has(normalizeToolName(op.tool)))
+function hasDangerousOrProtectedPath(op) {
+    if (!isPathProtectedTool(op))
         return false;
     return allPaths(op).some((p) => {
         const normalized = normalizePathForMatch(p);
@@ -180,6 +188,26 @@ function isDangerousPathOp(op) {
         return parts.some((part) => dangerousPathSegments.has(part.toLowerCase())) || protectedFilenames.has(last);
     });
 }
+function isReadPathOutsideAllowedRoots(op) {
+    if (!safeTools.has(normalizeToolName(op.tool)))
+        return false;
+    return allPaths(op).some((p) => !isPathInsideAllowedRoots(p, op));
+}
+function isPathProtectedTool(op) {
+    const opTool = normalizeToolName(op.tool);
+    return writeTools.has(opTool) || safeTools.has(opTool);
+}
+function isPathInsideAllowedRoots(candidate, op) {
+    const roots = [op.cwd, ...(op.additionalDirectories ?? [])].map((root) => resolvePathForContainment(root, op.cwd));
+    const resolved = resolvePathForContainment(candidate, op.cwd);
+    return roots.some((root) => resolved === root || resolved.startsWith(`${root}/`));
+}
+function resolvePathForContainment(candidate, cwd) {
+    const normalized = normalizePathForMatch(candidate);
+    const isAbsolute = path.win32.isAbsolute(candidate) || path.posix.isAbsolute(candidate);
+    const joined = isAbsolute ? normalized : normalizePathForMatch(path.resolve(cwd, candidate));
+    return joined.replace(/\/$/, "");
+}
 function isSafeBashCommand(command) {
     const stripped = stripEnvPrefix(command, false);
     const tokens = tokenizeCommand(stripped);

package/dist/zombie.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { platform } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { platform, userInfo } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 export const ZOMBIE_LIVE_IDLE_MS = 6 * 60 * 1000;
 export const ZOMBIE_TERMINAL_IDLE_MS = 6 * 60 * 1000;
@@ -153,6 +154,58 @@ function defaultIsProcessAlive(pid) {
 function livePid(pid) {
     return typeof pid === "number" && Number.isInteger(pid) && pid > 0;
 }
+function safeSlotNamespace(raw) {
+    const cleaned = raw.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return cleaned || createHash("sha256").update(raw || "unknown").digest("hex").slice(0, 16);
+}
+function currentUserSlotNamespace() {
+    try {
+        const info = userInfo();
+        if (platform() !== "win32" && Number.isInteger(info.uid))
+            return `uid-${info.uid}`;
+        return safeSlotNamespace(info.username);
+    }
+    catch { }
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (typeof uid === "number")
+        return `uid-${uid}`;
+    return safeSlotNamespace(process.env.USERNAME || process.env.USER || "unknown");
+}
+function slotBaseDir() {
+    if (process.env.SUBAGENT_SLOT_DIR)
+        return process.env.SUBAGENT_SLOT_DIR;
+    if (platform() === "win32") {
+        return join(process.env.ProgramData || process.env.ALLUSERSPROFILE || "C:\\ProgramData", "subagent-mcp", "slots");
+    }
+    return "/tmp/subagent-mcp/slots";
+}
+function currentUserSlotDir() {
+    return join(slotBaseDir(), currentUserSlotNamespace());
+}
+function isCurrentUserSlotDir(dir) {
+    return resolve(dir).toLowerCase() === resolve(currentUserSlotDir()).toLowerCase();
+}
+function commandLooksLikeSubagentChild(text) {
+    const normalized = text.replace(/\0/g, " ").toLowerCase();
+    return /(^|[\\/.\s_-])(claude|codex|gemini)(\.cmd|\.exe)?([\\/.\s_-]|$)/.test(normalized);
+}
+function defaultIsSubagentChildProcess(pid, _metadata) {
+    try {
+        if (platform() === "win32") {
+            const output = execFileSync("powershell.exe", [
+                "-NoProfile",
+                "-Command",
+                `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}"; if ($p) { "$($p.ExecutablePath) $($p.CommandLine)" }`,
+            ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            return commandLooksLikeSubagentChild(output);
+        }
+        const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+        return commandLooksLikeSubagentChild(cmdline);
+    }
+    catch {
+        return false;
+    }
+}
 function defaultSleepMs(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -162,7 +215,9 @@ export function cullStaleSlots(dir, deps = {}) {
     const sleepMs = deps.sleepMs ?? defaultSleepMs;
     const forceGraceMs = deps.forceGraceMs?.() ?? ZOMBIE_FORCE_GRACE_MS;
     const isProcessAlive = deps.isProcessAlive ?? defaultIsProcessAlive;
+    const isSubagentChildProcess = deps.isSubagentChildProcess ?? defaultIsSubagentChildProcess;
     const p = deps.platform ?? platform();
+    const canKillFromDir = isCurrentUserSlotDir(dir);
     const records = [];
     let files;
     try {
@@ -189,8 +244,10 @@ export function cullStaleSlots(dir, deps = {}) {
         if (ownerAlive)
             continue;
         const pid = meta.child_pid;
-        // cull only when the owning server is dead/absent (true orphan); spare children of a live server
-        if ((ownerPid === null || !ownerAlive) && livePid(pid) && pid !== process.pid) {
+        const childAlive = livePid(pid) && pid !== process.pid && isProcessAlive(pid);
+        const verifiedChild = childAlive && canKillFromDir && isSubagentChildProcess(pid, meta);
+        // cull only verified children from the current user's namespace; never trust stale JSON alone
+        if (verifiedChild && (ownerPid === null || !ownerAlive)) {
             const commands = buildProcessTreeKillCommands(pid, p);
             try {
                 runCommand(commands.graceful.command, commands.graceful.args);

package/package.json

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