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

package/dist/pending-permissions.js

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+const PARK_TIMEOUT_MS = 5 * 60 * 1000;
+const PER_AGENT_FIFO_CAP = 16;
+function publicRecord(record) {
+    return { ...record };
+}
+function shouldEscalateToHuman(input) {
+    return (input.permission_ceiling === "auto" &&
+        input.escalation !== "off" &&
+        input.irreversible === true);
+}
+export class PendingPermissionManager {
+    pendingById = new Map();
+    pendingByAgent = new Map();
+    askedCountByAgent = new Map();
+    history = [];
+    queueListeners = new Set();
+    telemetry = {
+        cap_overflow_auto_denies: 0,
+        park_timeout_auto_denies: 0,
+    };
+    onAgentQueueChange(listener) {
+        this.queueListeners.add(listener);
+        return () => this.queueListeners.delete(listener);
+    }
+    create(input) {
+        const queue = this.pendingByAgent.get(input.agent_id) ?? [];
+        const asked = (this.askedCountByAgent.get(input.agent_id) ?? 0) + 1;
+        this.askedCountByAgent.set(input.agent_id, asked);
+        if (queue.length >= PER_AGENT_FIFO_CAP) {
+            const record = {
+                request_id: randomUUID(),
+                agent_id: input.agent_id,
+                harness_channel: input.harness_channel,
+                tool_name_or_method: input.tool_name_or_method,
+                action: input.action,
+                permission_ceiling: input.permission_ceiling,
+                escalation: input.escalation,
+                irreversible: input.irreversible,
+                escalate_to_human: shouldEscalateToHuman(input),
+                reason: input.reason,
+                suggestions: input.suggestions,
+                requested_at: Date.now(),
+                correlation_id: input.correlation_id,
+                state: "auto_answered",
+                auto_answer_rule: "pending-queue cap reached",
+                asked_count_for_this_agent: asked,
+                answered_at: Date.now(),
+                answer: "deny",
+                answer_reason: "pending-queue cap reached",
+            };
+            this.telemetry.cap_overflow_auto_denies += 1;
+            this.history.push(publicRecord(record));
+            console.error(`[permissions] auto-deny ${record.request_id} for agent ${record.agent_id}: pending-queue cap reached`);
+            void Promise.resolve(input.resolve({
+                request_id: record.request_id,
+                agent_id: record.agent_id,
+                decision: "deny",
+                reason: record.answer_reason,
+            })).catch(() => { });
+            return publicRecord(record);
+        }
+        const request_id = randomUUID();
+        const record = {
+            request_id,
+            agent_id: input.agent_id,
+            harness_channel: input.harness_channel,
+            tool_name_or_method: input.tool_name_or_method,
+            action: input.action,
+            permission_ceiling: input.permission_ceiling,
+            escalation: input.escalation,
+            irreversible: input.irreversible,
+            escalate_to_human: shouldEscalateToHuman(input),
+            reason: input.reason,
+            suggestions: input.suggestions,
+            requested_at: Date.now(),
+            correlation_id: input.correlation_id,
+            state: "pending",
+            asked_count_for_this_agent: asked,
+            resolve: input.resolve,
+            timer: setTimeout(() => {
+                void this.autoDeny(request_id, "park-timeout: no decision within 5 minutes; auto-denied fail-closed");
+            }, PARK_TIMEOUT_MS),
+        };
+        record.timer.unref();
+        this.pendingById.set(request_id, record);
+        this.pendingByAgent.set(input.agent_id, [...queue, request_id]);
+        this.emitQueue(input.agent_id);
+        return publicRecord(record);
+    }
+    pendingForAgent(agentId) {
+        return (this.pendingByAgent.get(agentId) ?? [])
+            .map((id) => this.pendingById.get(id))
+            .filter((r) => Boolean(r))
+            .map(publicRecord);
+    }
+    pendingCount(agentId) {
+        return this.pendingByAgent.get(agentId)?.length ?? 0;
+    }
+    async respond(agentId, requestId, decision, reason) {
+        const targetId = requestId ?? this.pendingByAgent.get(agentId)?.[0];
+        if (!targetId)
+            throw new Error(`agent ${agentId} has no pending permission requests`);
+        const record = this.pendingById.get(targetId);
+        if (!record || record.agent_id !== agentId) {
+            throw new Error(`pending permission ${targetId} not found for agent ${agentId}`);
+        }
+        if (record.escalate_to_human === true && decision === "allow" && (!reason || reason.trim() === "")) {
+            throw new Error("allowing an escalated human permission request requires a non-empty reason");
+        }
+        return this.finish(record, decision, reason);
+    }
+    async closeAgent(agentId, reason) {
+        const ids = [...(this.pendingByAgent.get(agentId) ?? [])];
+        const closed = [];
+        for (const id of ids) {
+            const record = this.pendingById.get(id);
+            if (record)
+                closed.push(await this.finish(record, "deny", reason));
+        }
+        return closed;
+    }
+    async autoDeny(requestId, reason) {
+        const record = this.pendingById.get(requestId);
+        if (!record)
+            return;
+        this.telemetry.park_timeout_auto_denies += 1;
+        console.error(`[permissions] auto-deny ${requestId} for agent ${record.agent_id}: ${reason}`);
+        await this.finish(record, "deny", reason, "park-timeout");
+    }
+    async finish(record, decision, reason, autoRule) {
+        clearTimeout(record.timer);
+        this.pendingById.delete(record.request_id);
+        const queue = (this.pendingByAgent.get(record.agent_id) ?? []).filter((id) => id !== record.request_id);
+        if (queue.length > 0)
+            this.pendingByAgent.set(record.agent_id, queue);
+        else
+            this.pendingByAgent.delete(record.agent_id);
+        record.state = autoRule ? "auto_answered" : "answered";
+        record.auto_answer_rule = autoRule;
+        record.answered_at = Date.now();
+        record.answer = decision;
+        record.answer_reason = reason;
+        try {
+            await record.resolve({
+                request_id: record.request_id,
+                agent_id: record.agent_id,
+                decision,
+                reason,
+            });
+        }
+        catch (e) {
+            record.state = "errored";
+            record.answer_reason = e instanceof Error ? e.message : String(e);
+        }
+        this.history.push(publicRecord(record));
+        this.emitQueue(record.agent_id);
+        return publicRecord(record);
+    }
+    emitQueue(agentId) {
+        const count = this.pendingCount(agentId);
+        for (const listener of this.queueListeners)
+            listener(agentId, count);
+    }
+}
+export const pendingPermissionManager = new PendingPermissionManager();
+export function requestPendingPermission(input) {
+    if (!input.agentId) {
+        return Promise.resolve({
+            verdict: "deny",
+            reason: "permission request missing agent id; auto-denied fail-closed",
+        });
+    }
+    const agentId = input.agentId;
+    return new Promise((resolve) => {
+        pendingPermissionManager.create({
+            agent_id: agentId,
+            harness_channel: input.harnessChannel,
+            tool_name_or_method: input.toolNameOrMethod,
+            action: input.action,
+            permission_ceiling: input.permissionCeiling,
+            escalation: input.escalation,
+            irreversible: input.irreversible,
+            reason: input.reason,
+            suggestions: input.suggestions,
+            correlation_id: input.correlationId ?? "unknown",
+            resolve: (reply) => resolve({
+                verdict: reply.decision,
+                reason: reply.reason ?? `permission ${reply.decision}`,
+            }),
+        });
+    });
+}

package/dist/permission-classes.json

@@ -0,0 +1,36 @@
+{
+    "schema": 1,
+    "safe": {
+        "tools": ["Read", "Glob", "Grep", "LS"],
+        "bashPrefixes": ["ls", "cat", "pwd", "echo", "git status", "git diff", "git log"],
+        "webFetchHosts": [
+            "docs.anthropic.com",
+            "docs.github.com",
+            "docs.npmjs.com",
+            "github.com",
+            "npmjs.com",
+            "registry.npmjs.org"
+        ]
+    },
+    "danger": {
+        "toolWritePathPrefixes": ["Edit", "MultiEdit", "Write", "NotebookEdit"],
+        "dangerousPathSegments": [".git", ".ssh", ".aws", ".claude", ".codex", ".vscode"],
+        "protectedFilenames": ["global-subagent-mcp-config.jsonc", "global-concurrency.jsonc"],
+        "bashRegexes": [
+            "\\brm\\b[\\s\\S]*(?:\\s-rf\\b|\\s-fr\\b|\\s-r\\s+-f\\b|\\s-f\\s+-r\\b|--force\\b)",
+            "\\bgit\\s+push\\b[\\s\\S]*\\s--force(?:-with-lease)?\\b",
+            "\\b(?:curl|wget)\\b[\\s\\S]*(?:\\|\\s*(?:sh|bash)\\b)",
+            "\\bsudo\\b",
+            "\\bchmod\\s+777\\b",
+            "\\b(?:npm|pnpm|yarn)\\s+publish\\b",
+            "\\b(?:mkfs|diskutil\\s+eraseDisk|format\\.com|format\\s+[A-Za-z]:)"
+        ],
+        "irreversibleBashRegexes": [
+            "\\bgit\\s+push\\b[\\s\\S]*\\s--force(?:-with-lease)?\\b",
+            "\\bgit\\s+(?:reset\\s+--hard|rebase|filter-branch)\\b",
+            "\\b(?:DROP|TRUNCATE)\\b[\\s\\S]*\\b(?:TABLE|DATABASE|SCHEMA)\\b",
+            "\\b(?:npm|pnpm|yarn)\\s+publish\\b",
+            "\\b(?:aws|gcloud|az)\\b[\\s\\S]*\\bdelete\\b"
+        ]
+    }
+}

package/dist/permission-engine.js

@@ -0,0 +1,253 @@
+import permissionClasses from "./permission-classes.json" with { type: "json" };
+const classes = permissionClasses;
+const safeTools = new Set(classes.safe.tools.map(normalizeToolName));
+const safeBashPrefixes = classes.safe.bashPrefixes.map(tokenizeCommand);
+const safeWebFetchHosts = new Set(classes.safe.webFetchHosts.map((h) => h.toLowerCase()));
+const dangerRegexes = classes.danger.bashRegexes.map((p) => new RegExp(p, "i"));
+const irreversibleRegexes = classes.danger.irreversibleBashRegexes.map((p) => new RegExp(p, "i"));
+const writeTools = new Set(classes.danger.toolWritePathPrefixes.map(normalizeToolName));
+const dangerousPathSegments = new Set(classes.danger.dangerousPathSegments.map((p) => p.toLowerCase()));
+const protectedFilenames = new Set(classes.danger.protectedFilenames.map((p) => p.toLowerCase()));
+const mutatingTools = new Set(["bash", "edit", "multiedit", "write", "notebookedit"]);
+const safeEnvVars = new Set(["NODE_ENV", "GOOS", "LANG"]);
+const maxSubcommandsForSecurityCheck = 50;
+/**
+ * Shared trust-boundary decision point for Claude canUseTool and Codex approval
+ * payloads. It performs no I/O; callers must provide already-known resolved
+ * paths when they want symlink parity.
+ */
+export function verdict(op, rules = {}) {
+    const classified = classifyPermissionOp(op);
+    if (classified.classification === "danger") {
+        return {
+            verdict: "deny",
+            classification: "danger",
+            irreversible: classified.irreversible,
+            reason: classified.reason,
+        };
+    }
+    const ruleVote = evaluateRuleSet(op, rules);
+    if (ruleVote) {
+        return {
+            verdict: ruleVote.verdict,
+            classification: classified.classification,
+            irreversible: classified.irreversible,
+            matchedRule: ruleVote.rule,
+            reason: `${ruleVote.verdict} rule matched: ${ruleVote.rule}`,
+        };
+    }
+    if (classified.classification === "safe") {
+        return {
+            verdict: "allow",
+            classification: "safe",
+            irreversible: classified.irreversible,
+            reason: classified.reason,
+        };
+    }
+    return {
+        verdict: "ask",
+        classification: "neutral",
+        irreversible: classified.irreversible,
+        reason: "neutral residue defaults to ask",
+    };
+}
+/**
+ * Applies the launch ceiling after the engine vote. `yolo` bypasses normal
+ * gating; adapter-level bypass-immune denials must be enforced by the caller.
+ */
+export function applyPermissionCeiling(engineVote, ceiling) {
+    if (ceiling === "yolo")
+        return "allow";
+    if (ceiling === "manual")
+        return minVerdict(engineVote, "ask");
+    return minVerdict(engineVote, "allow");
+}
+export function classifyPermissionOp(op) {
+    const command = commandText(op);
+    const irreversible = Boolean(op.irreversible) || (command !== "" && irreversibleRegexes.some((r) => r.test(command)));
+    if (isDangerousPathOp(op)) {
+        return {
+            classification: "danger",
+            irreversible,
+            reason: "dangerous or protected path",
+        };
+    }
+    if (normalizeToolName(op.tool) === "bash") {
+        if (command === "")
+            return { classification: "neutral", irreversible, reason: "empty bash command" };
+        if (countSubcommands(command) > maxSubcommandsForSecurityCheck) {
+            return { classification: "neutral", irreversible, reason: "too many subcommands to classify safely" };
+        }
+        if (dangerRegexes.some((r) => r.test(command))) {
+            return { classification: "danger", irreversible, reason: "dangerous bash pattern" };
+        }
+        if (countSubcommands(command) > 1) {
+            return { classification: "neutral", irreversible, reason: "compound bash command requires review" };
+        }
+        if (isSafeBashCommand(command)) {
+            return { classification: "safe", irreversible, reason: "safe bash prefix" };
+        }
+        return { classification: "neutral", irreversible, reason: "unmatched bash command" };
+    }
+    if (normalizeToolName(op.tool) === "webfetch" && isPreapprovedWebFetch(op)) {
+        return { classification: "safe", irreversible, reason: "preapproved WebFetch host" };
+    }
+    if (safeTools.has(normalizeToolName(op.tool))) {
+        return { classification: "safe", irreversible, reason: "safe read-only tool" };
+    }
+    return { classification: "neutral", irreversible, reason: "unmatched tool" };
+}
+export function evaluateRuleSet(op, rules) {
+    return (firstRuleMatch(op, "deny", rules.deny) ??
+        firstRuleMatch(op, "ask", rules.ask) ??
+        firstRuleMatch(op, "allow", rules.allow));
+}
+export function parsePermissionRule(rule) {
+    const firstParen = rule.indexOf("(");
+    const lastParen = rule.lastIndexOf(")");
+    if (firstParen < 0 || lastParen <= firstParen) {
+        return { tool: rule.trim(), content: null };
+    }
+    return {
+        tool: rule.slice(0, firstParen).trim(),
+        content: rule.slice(firstParen + 1, lastParen),
+    };
+}
+function firstRuleMatch(op, vote, rules) {
+    for (const rule of rules ?? []) {
+        if (matchesRule(op, rule))
+            return { verdict: vote, rule };
+    }
+    return null;
+}
+function matchesRule(op, rawRule) {
+    const rule = parsePermissionRule(rawRule);
+    if (rule.tool === "")
+        return false;
+    const opTool = normalizeToolName(op.tool);
+    const ruleTool = normalizeToolName(rule.tool);
+    if (ruleTool !== "*" && ruleTool !== opTool)
+        return false;
+    if (rule.content === null || rule.content.trim() === "" || rule.content.trim() === "*")
+        return true;
+    if (opTool === "bash")
+        return matchesBashRule(commandText(op), rule.content);
+    if (opTool === "webfetch")
+        return matchesNetworkRule(op, rule.content);
+    if (writeTools.has(opTool) || op.paths?.length || op.resolvedPaths?.length) {
+        return matchesAnyPath(op, rule.content);
+    }
+    return wildcardMatch(rule.content, JSON.stringify(op));
+}
+function matchesBashRule(command, pattern) {
+    if (command === "")
+        return false;
+    const stripped = stripEnvPrefix(command, true);
+    const positive = pattern.trim();
+    const excludes = positive.split(/\s+&&\s+|\s*;\s*|\s+\|\|\s+/).filter((p) => p.trim() !== "");
+    if (excludes.length > 1 && positive === command)
+        return false;
+    if (positive.endsWith(":*")) {
+        const prefix = positive.slice(0, -2);
+        return hasWordBoundaryPrefix(stripped, prefix);
+    }
+    return wildcardMatch(positive, stripped) || hasWordBoundaryPrefix(stripped, positive);
+}
+function matchesNetworkRule(op, pattern) {
+    const needle = pattern.startsWith("domain:") ? pattern.slice("domain:".length) : pattern;
+    return networkHosts(op).some((host) => host === needle.toLowerCase() || host.endsWith(`.${needle.toLowerCase()}`));
+}
+function matchesAnyPath(op, pattern) {
+    return allPaths(op).some((p) => {
+        const normalized = normalizePathForMatch(p);
+        const rule = normalizePathForMatch(pattern);
+        return normalized === rule || normalized.startsWith(`${rule}/`) || wildcardMatch(rule, normalized);
+    });
+}
+function isDangerousPathOp(op) {
+    if (!writeTools.has(normalizeToolName(op.tool)))
+        return false;
+    return allPaths(op).some((p) => {
+        const normalized = normalizePathForMatch(p);
+        const parts = normalized.split("/").filter(Boolean);
+        const last = parts[parts.length - 1]?.toLowerCase() ?? "";
+        return parts.some((part) => dangerousPathSegments.has(part.toLowerCase())) || protectedFilenames.has(last);
+    });
+}
+function isSafeBashCommand(command) {
+    const stripped = stripEnvPrefix(command, false);
+    const tokens = tokenizeCommand(stripped);
+    if (tokens.length === 0)
+        return false;
+    return safeBashPrefixes.some((prefix) => startsWithTokens(tokens, prefix));
+}
+function isPreapprovedWebFetch(op) {
+    return networkHosts(op).some((host) => safeWebFetchHosts.has(host));
+}
+function commandText(op) {
+    if (op.command !== undefined)
+        return op.command;
+    if (op.argv && op.argv.length > 0)
+        return op.argv.join(" ");
+    return "";
+}
+function normalizeToolName(tool) {
+    const tail = tool.split("__").pop() ?? tool;
+    return tail.replace(/[^A-Za-z]/g, "").toLowerCase();
+}
+function stripEnvPrefix(command, denyMode) {
+    let out = command.trim();
+    while (true) {
+        const match = out.match(/^([A-Za-z_][A-Za-z0-9_]*)=(?:"[^"]*"|'[^']*'|\S+)\s+([\s\S]*)$/);
+        if (!match)
+            return out;
+        if (!denyMode && !safeEnvVars.has(match[1]))
+            return out;
+        out = match[2].trim();
+    }
+}
+function tokenizeCommand(command) {
+    return command.trim().split(/\s+/).filter(Boolean);
+}
+function startsWithTokens(tokens, prefix) {
+    if (prefix.length > tokens.length)
+        return false;
+    return prefix.every((part, i) => tokens[i] === part || tokens[i] === `${part}:`);
+}
+function hasWordBoundaryPrefix(command, prefix) {
+    if (!command.startsWith(prefix))
+        return false;
+    const next = command[prefix.length];
+    return next === undefined || /[\s:;|&]/.test(next);
+}
+function countSubcommands(command) {
+    return command.split(/&&|\|\||;|\|/).length;
+}
+function allPaths(op) {
+    return [...(op.paths ?? []), ...(op.resolvedPaths ?? [])];
+}
+function networkHosts(op) {
+    const hosts = [];
+    for (const target of op.network ?? []) {
+        if (target.host)
+            hosts.push(target.host.toLowerCase());
+        if (target.url) {
+            try {
+                hosts.push(new URL(target.url).hostname.toLowerCase());
+            }
+            catch { }
+        }
+    }
+    return hosts;
+}
+function normalizePathForMatch(path) {
+    return path.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "").toLowerCase();
+}
+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;
+}