@praxis.guard/auditor-cli 0.0.30 → 0.0.33

package/dist/hooks/before-mcp-argv.d.ts

@@ -0,0 +1,17 @@
+import type { BeforeMCPExecutionPayload } from "./before-mcp-types.js";
+/**
+ * When Cursor encodes MCP tools as `MCP:<server>:<tool>` (see Cursor hooks docs / preToolUse), split into
+ * server + bare tool name for policy rows under `policies.mcp.<server>.<tool>`.
+ */
+export declare function splitMcpToolName(raw: string): {
+    serverGuess: string | null;
+    tool: string;
+};
+/**
+ * Maps hook payload → argv for `policies.v1.json` under tool key `mcp`.
+ * Omits raw `tool_input` from argv tokens so JSON metacharacters do not trip shell metachar heuristics.
+ */
+export declare function mcpHookArgvFromPayload(payload: BeforeMCPExecutionPayload): string[];
+export declare function stringifyToolInput(raw: unknown): string;
+export declare function preferredHookCwd(payload: BeforeMCPExecutionPayload): string | undefined;
+//# sourceMappingURL=before-mcp-argv.d.ts.map

package/dist/hooks/before-mcp-argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-argv.d.ts","sourceRoot":"","sources":["../../src/hooks/before-mcp-argv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa1F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,EAAE,CAkBnF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQvD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,GAAG,SAAS,CASvF"}

package/dist/hooks/before-mcp-argv.js

@@ -0,0 +1,67 @@
+/**
+ * When Cursor encodes MCP tools as `MCP:<server>:<tool>` (see Cursor hooks docs / preToolUse), split into
+ * server + bare tool name for policy rows under `policies.mcp.<server>.<tool>`.
+ */
+export function splitMcpToolName(raw) {
+    const t = raw.trim();
+    if (!t)
+        return { serverGuess: null, tool: "_" };
+    if (t.startsWith("MCP:")) {
+        const body = t.slice(4).trim();
+        const idx = body.lastIndexOf(":");
+        if (idx !== -1) {
+            const serverPart = body.slice(0, idx).trim();
+            const toolPart = body.slice(idx + 1).trim();
+            if (serverPart && toolPart)
+                return { serverGuess: serverPart, tool: toolPart };
+        }
+    }
+    return { serverGuess: null, tool: t };
+}
+/**
+ * Maps hook payload → argv for `policies.v1.json` under tool key `mcp`.
+ * Omits raw `tool_input` from argv tokens so JSON metacharacters do not trip shell metachar heuristics.
+ */
+export function mcpHookArgvFromPayload(payload) {
+    const rawName = typeof payload.tool_name === "string" ? payload.tool_name.trim() : "";
+    const { serverGuess, tool } = splitMcpToolName(rawName);
+    let server = "stdio";
+    if (typeof payload.url === "string" && payload.url.trim()) {
+        const u = payload.url.trim();
+        try {
+            server = new URL(u).host || u;
+        }
+        catch {
+            server = u;
+        }
+    }
+    else if (serverGuess) {
+        server = serverGuess;
+    }
+    else if (typeof payload.command === "string" && payload.command.trim()) {
+        server = payload.command.trim().slice(0, 400);
+    }
+    return ["mcp", server, tool || "_"];
+}
+export function stringifyToolInput(raw) {
+    if (raw === undefined || raw === null)
+        return "";
+    if (typeof raw === "string")
+        return raw;
+    try {
+        return JSON.stringify(raw);
+    }
+    catch {
+        return String(raw);
+    }
+}
+export function preferredHookCwd(payload) {
+    if (typeof payload.cwd === "string")
+        return payload.cwd;
+    if (Array.isArray(payload.workspace_roots) &&
+        typeof payload.workspace_roots[0] === "string") {
+        return payload.workspace_roots[0];
+    }
+    return undefined;
+}
+//# sourceMappingURL=before-mcp-argv.js.map

package/dist/hooks/before-mcp-argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-argv.js","sourceRoot":"","sources":["../../src/hooks/before-mcp-argv.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAChD,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,UAAU,IAAI,QAAQ;gBAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAkC;IACvE,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAExD,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1D,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,EAAE,CAAC;QACvB,MAAM,GAAG,WAAW,CAAC;IACvB,CAAC;SAAM,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QACzE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACjD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAkC;IACjE,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IACxD,IACE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC;QACtC,OAAO,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,QAAQ,EAC9C,CAAC;QACD,OAAO,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/hooks/before-mcp-mutate.d.ts

@@ -0,0 +1,23 @@
+import type { Tier } from "../policy/index.js";
+import type { BeforeMCPExecutionResponse } from "./before-mcp-types.js";
+export type MutateHookPermission = {
+    permission: BeforeMCPExecutionResponse["permission"];
+    ticketConsumed: boolean;
+    inlineApproval: {
+        request_id: string;
+        open_url: string;
+    } | null;
+    approvalFlowSignal: string | null;
+    reasons: string[];
+};
+export declare function resolveMutateHookPermission(input: {
+    argv: string[];
+    tier: Tier;
+    storageRoot: string;
+    toolInputHash: string | null;
+    rawToolName: string;
+    toolInputPreview: string;
+    policyRevision: number | null;
+    initialReasons: string[];
+}): Promise<MutateHookPermission>;
+//# sourceMappingURL=before-mcp-mutate.d.ts.map

package/dist/hooks/before-mcp-mutate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-mutate.d.ts","sourceRoot":"","sources":["../../src/hooks/before-mcp-mutate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAM/C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,0BAA0B,CAAC,YAAY,CAAC,CAAC;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,wBAAsB,2BAA2B,CAAC,KAAK,EAAE;IACvD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmFhC"}

package/dist/hooks/before-mcp-mutate.js

@@ -0,0 +1,76 @@
+import { randomUUID } from "node:crypto";
+import { argvSha256 } from "../approval/argv-fingerprint.js";
+import { resolveMutateApproval } from "../approval/mcp-flow.js";
+import { tryHookInlineApprovalRequest } from "../approval/hook-inline-approval.js";
+import { readPendingApprovalIndex } from "../bridge/pending-approval-index.js";
+import { tryConsumeExecutionTicket } from "../bridge/execution-ticket.js";
+export async function resolveMutateHookPermission(input) {
+    const { argv, tier, storageRoot, toolInputHash, rawToolName, toolInputPreview, policyRevision, initialReasons, } = input;
+    const reasons = [...initialReasons];
+    let permission = "deny";
+    let ticketConsumed = false;
+    let approvalFlowSignal = null;
+    let inlineApproval = null;
+    if (tier !== "MUTATE") {
+        return {
+            permission: tier === "READ" ? "allow" : "deny",
+            ticketConsumed,
+            inlineApproval,
+            approvalFlowSignal,
+            reasons,
+        };
+    }
+    ticketConsumed = await tryConsumeExecutionTicket(argv, {
+        storageRoot,
+        kind: "mcp",
+        tool_input_sha256: toolInputHash,
+    });
+    if (ticketConsumed) {
+        return { permission: "allow", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+    }
+    const hash = argvSha256(argv);
+    const pending = await readPendingApprovalIndex(hash, { storageRoot });
+    if (pending) {
+        const autoRedeem = await resolveMutateApproval({
+            argv: [...argv],
+            proposalKind: "mcp",
+            storageRoot,
+            rawDisplay: `${rawToolName} ${toolInputPreview}`,
+            eventId: randomUUID(),
+            policyRevision,
+            reasons,
+            approval: { request_id: pending.request_id },
+            waitMs: 0,
+            tool_input_sha256: toolInputHash,
+        });
+        if (autoRedeem.kind === "allow" && autoRedeem.ticketRecorded) {
+            ticketConsumed = await tryConsumeExecutionTicket(argv, {
+                storageRoot,
+                kind: "mcp",
+                tool_input_sha256: toolInputHash,
+            });
+            if (ticketConsumed) {
+                return { permission: "allow", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+            }
+        }
+        approvalFlowSignal = "retry_without_guard_wait_resolve";
+        reasons.push("retry_without_guard_wait_resolve");
+        inlineApproval = { request_id: pending.request_id, open_url: pending.open_url };
+        return { permission: "deny", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+    }
+    const created = await tryHookInlineApprovalRequest({
+        argv: [...argv],
+        kind: "mcp",
+        rawDisplay: `${rawToolName} ${toolInputPreview}`,
+        policyRevision,
+        reasons,
+        eventId: randomUUID(),
+        storageRoot,
+        tool_input_sha256: toolInputHash,
+    });
+    if (created) {
+        inlineApproval = { request_id: created.request_id, open_url: created.open_url };
+    }
+    return { permission: "deny", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+}
+//# sourceMappingURL=before-mcp-mutate.js.map

package/dist/hooks/before-mcp-mutate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-mutate.js","sourceRoot":"","sources":["../../src/hooks/before-mcp-mutate.ts"],"names":[],"mappings":"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"}

package/dist/hooks/before-mcp-skipped.d.ts

@@ -0,0 +1,14 @@
+import type { Tier } from "../policy/index.js";
+import type { BeforeMCPExecutionPayload } from "./before-mcp-types.js";
+export declare function handleSkippedMcpHook(input: {
+    payload: BeforeMCPExecutionPayload;
+    rawToolName: string;
+    bareTool: string;
+    argv: string[];
+    tier: Tier;
+    reasons: string[];
+    policyRevision: number | null;
+    auditLogRoot: string;
+    decisionStarted: number;
+}): Promise<void>;
+//# sourceMappingURL=before-mcp-skipped.d.ts.map

package/dist/hooks/before-mcp-skipped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-skipped.d.ts","sourceRoot":"","sources":["../../src/hooks/before-mcp-skipped.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,yBAAyB,EAA8B,MAAM,uBAAuB,CAAC;AAGnG,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,OAAO,EAAE,yBAAyB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkEhB"}

package/dist/hooks/before-mcp-skipped.js

@@ -0,0 +1,56 @@
+import { appendAuditJsonl } from "../audit/jsonl.js";
+import { getInstallId } from "../cli/install-id.js";
+import { sendGuardEvent } from "../telemetry/guard-events.js";
+import { stringifyToolInput } from "./before-mcp-argv.js";
+export async function handleSkippedMcpHook(input) {
+    const { payload, rawToolName, bareTool, argv, tier, reasons, policyRevision, auditLogRoot, decisionStarted, } = input;
+    const latency_ms = performance.now() - decisionStarted;
+    const toolInputStr = stringifyToolInput(payload.tool_input);
+    try {
+        await appendAuditJsonl({
+            ts: new Date().toISOString(),
+            hook: "beforeMCPExecution",
+            tool_name: rawToolName,
+            bare_tool: bareTool,
+            tool_input: toolInputStr.slice(0, 8000),
+            argv,
+            status: "skipped",
+            skipped: true,
+            skip_reason: "mcp_policy_unmatched",
+            tier,
+            permission: "allow",
+            ticketConsumed: false,
+            reasons,
+            latency_ms,
+        }, auditLogRoot);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`[auditor] audit log append failed: ${msg}\n`);
+    }
+    const skipResponse = { permission: "allow" };
+    process.stdout.write(JSON.stringify(skipResponse, null, 2));
+    await sendGuardEvent({
+        ts: new Date().toISOString(),
+        status: "skipped",
+        skipped: true,
+        skip_reason: "mcp_policy_unmatched",
+        tool: "auditor-hook-mcp",
+        command_path: argv[1] ?? null,
+        verb: argv[2] ?? null,
+        resource: toolInputStr ? toolInputStr.slice(0, 500) : null,
+        reason: reasons[0] ?? "mcp_policy_unmatched",
+        cmd: `${rawToolName}`,
+        tier,
+        decision: "allow",
+        latency_ms,
+        installId: getInstallId(),
+        kind: "mcp",
+        ...(policyRevision !== null ? { policy_revision: policyRevision } : {}),
+        meta: {
+            hook: "beforeMCPExecution",
+            ticketConsumed: false,
+        },
+    });
+}
+//# sourceMappingURL=before-mcp-skipped.js.map

package/dist/hooks/before-mcp-skipped.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-skipped.js","sourceRoot":"","sources":["../../src/hooks/before-mcp-skipped.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAU1C;IACC,MAAM,EACJ,OAAO,EACP,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,GAAG,KAAK,CAAC;IAEV,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;IACvD,MAAM,YAAY,GAAG,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE5D,IAAI,CAAC;QACH,MAAM,gBAAgB,CACpB;YACE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,IAAI,EAAE,oBAAoB;YAC1B,SAAS,EAAE,WAAW;YACtB,SAAS,EAAE,QAAQ;YACnB,UAAU,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;YACvC,IAAI;YACJ,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,sBAAsB;YACnC,IAAI;YACJ,UAAU,EAAE,OAAO;YACnB,cAAc,EAAE,KAAK;YACrB,OAAO;YACP,UAAU;SACX,EACD,YAAY,CACb,CAAC;IACJ,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,GAAG,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,YAAY,GAA+B,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE5D,MAAM,cAAc,CAAC;QACnB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,sBAAsB;QACnC,IAAI,EAAE,kBAAkB;QACxB,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;QAC7B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;QACrB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;QAC1D,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,sBAAsB;QAC5C,GAAG,EAAE,GAAG,WAAW,EAAE;QACrB,IAAI;QACJ,QAAQ,EAAE,OAAO;QACjB,UAAU;QACV,SAAS,EAAE,YAAY,EAAE;QACzB,IAAI,EAAE,KAAK;QACX,GAAG,CAAC,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,EAAE;YACJ,IAAI,EAAE,oBAAoB;YAC1B,cAAc,EAAE,KAAK;SACtB;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/hooks/before-mcp-types.d.ts

@@ -0,0 +1,15 @@
+/** Cursor `beforeMCPExecution` stdin (see https://cursor.com/docs/hooks.md). */
+export type BeforeMCPExecutionPayload = {
+    tool_name?: unknown;
+    tool_input?: unknown;
+    url?: unknown;
+    command?: unknown;
+    cwd?: unknown;
+    workspace_roots?: unknown;
+};
+export type BeforeMCPExecutionResponse = {
+    permission: "allow" | "deny" | "ask";
+    user_message?: string;
+    agent_message?: string;
+};
+//# sourceMappingURL=before-mcp-types.d.ts.map

package/dist/hooks/before-mcp-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-types.d.ts","sourceRoot":"","sources":["../../src/hooks/before-mcp-types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC"}

package/dist/hooks/before-mcp-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=before-mcp-types.js.map

package/dist/hooks/before-mcp-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-mcp-types.js","sourceRoot":"","sources":["../../src/hooks/before-mcp-types.ts"],"names":[],"mappings":""}

package/dist/hooks/run-before-mcp.d.ts

@@ -1,30 +1,6 @@
-/** Cursor `beforeMCPExecution` stdin (see https://cursor.com/docs/hooks.md). */
-export type BeforeMCPExecutionPayload = {
-    tool_name?: unknown;
-    tool_input?: unknown;
-    url?: unknown;
-    command?: unknown;
-    cwd?: unknown;
-    workspace_roots?: unknown;
-};
-export type BeforeMCPExecutionResponse = {
-    permission: "allow" | "deny" | "ask";
-    user_message?: string;
-    agent_message?: string;
-};
-/**
- * When Cursor encodes MCP tools as `MCP:<server>:<tool>` (see Cursor hooks docs / preToolUse), split into
- * server + bare tool name for policy rows under `policies.mcp.<server>.<tool>`.
- */
-export declare function splitMcpToolName(raw: string): {
-    serverGuess: string | null;
-    tool: string;
-};
-/**
- * Maps hook payload → argv for `policies.v1.json` under tool key `mcp`.
- * Omits raw `tool_input` from argv tokens so JSON metacharacters do not trip shell metachar heuristics.
- */
-export declare function mcpHookArgvFromPayload(payload: BeforeMCPExecutionPayload): string[];
+import type { BeforeMCPExecutionResponse } from "./before-mcp-types.js";
+export type { BeforeMCPExecutionPayload, BeforeMCPExecutionResponse } from "./before-mcp-types.js";
+export { mcpHookArgvFromPayload, splitMcpToolName } from "./before-mcp-argv.js";
 /**
  * Cursor `beforeMCPExecution`: stdin JSON → stdout JSON (`permission` only contract).
  */

package/dist/hooks/run-before-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-before-mcp.d.ts","sourceRoot":"","sources":["../../src/hooks/run-before-mcp.ts"],"names":[],"mappings":"AAmBA,gFAAgF;AAChF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAiBF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa1F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,EAAE,CAkBnF;AA0BD;;GAEG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CA6N/D;AAED,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,OAAO,GAAG,0BAA0B,CAM7F"}
+{"version":3,"file":"run-before-mcp.d.ts","sourceRoot":"","sources":["../../src/hooks/run-before-mcp.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnG,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAsBhF;;GAEG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkJ/D;AAED,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,OAAO,GAAG,0BAA0B,CAM7F"}

package/dist/hooks/run-before-mcp.js

@@ -3,77 +3,13 @@ import { appendAuditJsonl } from "../audit/jsonl.js";
 import { getInstallId } from "../cli/install-id.js";
 import { evaluateMcpProposal } from "../shell/evaluate.js";
 import { resolveGuardStorageRoot } from "../bridge/guard-storage-root.js";
-import { tryConsumeExecutionTicket } from "../bridge/execution-ticket.js";
-import { tryHookInlineApprovalRequest } from "../approval/hook-inline-approval.js";
-import { readPendingApprovalIndex } from "../bridge/pending-approval-index.js";
-import { argvSha256 } from "../approval/argv-fingerprint.js";
 import { toolInputSha256 } from "../approval/fingerprint.js";
-import { resolveMutateApproval } from "../approval/mcp-flow.js";
 import { formatHookAllowViaCredentialMessage, formatHookDenyMessages, } from "./agent-message.js";
-import { randomUUID } from "node:crypto";
 import { sendGuardEvent } from "../telemetry/guard-events.js";
-function tierToPermission(tier) {
-    if (tier === "READ")
-        return "allow";
-    return "deny";
-}
-function stringifyToolInput(raw) {
-    if (raw === undefined || raw === null)
-        return "";
-    if (typeof raw === "string")
-        return raw;
-    try {
-        return JSON.stringify(raw);
-    }
-    catch {
-        return String(raw);
-    }
-}
-/**
- * When Cursor encodes MCP tools as `MCP:<server>:<tool>` (see Cursor hooks docs / preToolUse), split into
- * server + bare tool name for policy rows under `policies.mcp.<server>.<tool>`.
- */
-export function splitMcpToolName(raw) {
-    const t = raw.trim();
-    if (!t)
-        return { serverGuess: null, tool: "_" };
-    if (t.startsWith("MCP:")) {
-        const body = t.slice(4).trim();
-        const idx = body.lastIndexOf(":");
-        if (idx !== -1) {
-            const serverPart = body.slice(0, idx).trim();
-            const toolPart = body.slice(idx + 1).trim();
-            if (serverPart && toolPart)
-                return { serverGuess: serverPart, tool: toolPart };
-        }
-    }
-    return { serverGuess: null, tool: t };
-}
-/**
- * Maps hook payload → argv for `policies.v1.json` under tool key `mcp`.
- * Omits raw `tool_input` from argv tokens so JSON metacharacters do not trip shell metachar heuristics.
- */
-export function mcpHookArgvFromPayload(payload) {
-    const rawName = typeof payload.tool_name === "string" ? payload.tool_name.trim() : "";
-    const { serverGuess, tool } = splitMcpToolName(rawName);
-    let server = "stdio";
-    if (typeof payload.url === "string" && payload.url.trim()) {
-        const u = payload.url.trim();
-        try {
-            server = new URL(u).host || u;
-        }
-        catch {
-            server = u;
-        }
-    }
-    else if (serverGuess) {
-        server = serverGuess;
-    }
-    else if (typeof payload.command === "string" && payload.command.trim()) {
-        server = payload.command.trim().slice(0, 400);
-    }
-    return ["mcp", server, tool || "_"];
-}
+import { mcpHookArgvFromPayload, preferredHookCwd, stringifyToolInput, } from "./before-mcp-argv.js";
+import { resolveMutateHookPermission } from "./before-mcp-mutate.js";
+import { handleSkippedMcpHook } from "./before-mcp-skipped.js";
+export { mcpHookArgvFromPayload, splitMcpToolName } from "./before-mcp-argv.js";
 async function readStdinJson() {
     return await new Promise((resolve, reject) => {
         let data = "";
@@ -89,14 +25,10 @@ async function readStdinJson() {
         });
     });
 }
-async function tryAppendAuditEvent(evt, auditLogRoot) {
-    try {
-        await appendAuditJsonl(evt, auditLogRoot);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        process.stderr.write(`[auditor] audit log append failed: ${msg}\n`);
-    }
+function tierToPermission(tier) {
+    if (tier === "READ")
+        return "allow";
+    return "deny";
 }
 /**
  * Cursor `beforeMCPExecution`: stdin JSON → stdout JSON (`permission` only contract).
@@ -119,121 +51,45 @@ export async function runBeforeMcpHookFromStdin() {
     const [policy, policyRevision] = await Promise.all([loadPoliciesV1(), readPoliciesV1Revision()]);
     const { skipped, evaluation } = evaluateMcpProposal(policy, argv);
     const { classification, flags, tier } = evaluation;
-    const reasons = evaluation.reasons.map((r) => r.message);
-    const preferredCwd = typeof payload.cwd === "string"
-        ? payload.cwd
-        : Array.isArray(payload.workspace_roots) &&
-            typeof payload.workspace_roots[0] === "string"
-            ? payload.workspace_roots[0]
-            : undefined;
-    const storageRoot = resolveGuardStorageRoot(preferredCwd);
+    const initialReasons = evaluation.reasons.map((r) => r.message);
+    const storageRoot = resolveGuardStorageRoot(preferredHookCwd(payload));
     const auditLogRoot = storageRoot;
     const toolInputHash = toolInputSha256(payload.tool_input);
     if (skipped) {
-        const latency_ms = performance.now() - decisionStarted;
-        const toolInputStr = stringifyToolInput(payload.tool_input);
-        await tryAppendAuditEvent({
-            ts: new Date().toISOString(),
-            hook: "beforeMCPExecution",
-            tool_name: rawToolName,
-            bare_tool: bareTool,
-            tool_input: toolInputStr.slice(0, 8000),
+        await handleSkippedMcpHook({
+            payload,
+            rawToolName,
+            bareTool,
             argv,
-            status: "skipped",
-            skipped: true,
-            skip_reason: "mcp_policy_unmatched",
-            tier,
-            permission: "allow",
-            ticketConsumed: false,
-            reasons,
-            latency_ms,
-        }, auditLogRoot);
-        const skipResponse = { permission: "allow" };
-        process.stdout.write(JSON.stringify(skipResponse, null, 2));
-        await sendGuardEvent({
-            ts: new Date().toISOString(),
-            status: "skipped",
-            skipped: true,
-            skip_reason: "mcp_policy_unmatched",
-            tool: "auditor-hook-mcp",
-            command_path: argv[1] ?? null,
-            verb: argv[2] ?? null,
-            resource: toolInputStr ? toolInputStr.slice(0, 500) : null,
-            reason: reasons[0] ?? "mcp_policy_unmatched",
-            cmd: `${rawToolName}`,
             tier,
-            decision: "allow",
-            latency_ms,
-            installId: getInstallId(),
-            kind: "mcp",
-            ...(policyRevision !== null ? { policy_revision: policyRevision } : {}),
-            meta: {
-                hook: "beforeMCPExecution",
-                ticketConsumed: false,
-            },
+            reasons: initialReasons,
+            policyRevision,
+            auditLogRoot,
+            decisionStarted,
         });
         return;
     }
     let permission = tierToPermission(tier);
     let ticketConsumed = false;
+    let inlineApproval = null;
     let approvalFlowSignal = null;
+    let reasons = initialReasons;
     if (permission === "deny" && tier === "MUTATE") {
-        ticketConsumed = await tryConsumeExecutionTicket(argv, {
+        const mutate = await resolveMutateHookPermission({
+            argv,
+            tier,
             storageRoot,
-            kind: "mcp",
-            tool_input_sha256: toolInputHash,
+            toolInputHash,
+            rawToolName,
+            toolInputPreview: stringifyToolInput(payload.tool_input).slice(0, 200),
+            policyRevision,
+            initialReasons,
         });
-        if (ticketConsumed)
-            permission = "allow";
-    }
-    let inlineApproval = null;
-    if (permission === "deny" && tier === "MUTATE") {
-        const hash = argvSha256(argv);
-        const pending = await readPendingApprovalIndex(hash, { storageRoot });
-        if (pending) {
-            const autoRedeem = await resolveMutateApproval({
-                argv: [...argv],
-                proposalKind: "mcp",
-                storageRoot,
-                rawDisplay: `${rawToolName} ${stringifyToolInput(payload.tool_input).slice(0, 200)}`,
-                eventId: randomUUID(),
-                policyRevision,
-                reasons,
-                approval: { request_id: pending.request_id },
-                waitMs: 0,
-                tool_input_sha256: toolInputHash,
-            });
-            if (autoRedeem.kind === "allow" && autoRedeem.ticketRecorded) {
-                ticketConsumed = await tryConsumeExecutionTicket(argv, {
-                    storageRoot,
-                    kind: "mcp",
-                    tool_input_sha256: toolInputHash,
-                });
-                if (ticketConsumed) {
-                    permission = "allow";
-                }
-            }
-            if (permission === "deny") {
-                approvalFlowSignal = "retry_without_guard_wait_resolve";
-                reasons.push("retry_without_guard_wait_resolve");
-                inlineApproval = { request_id: pending.request_id, open_url: pending.open_url };
-            }
-        }
-        else {
-            const created = await tryHookInlineApprovalRequest({
-                argv: [...argv],
-                kind: "mcp",
-                rawDisplay: `${rawToolName} ${stringifyToolInput(payload.tool_input).slice(0, 200)}`,
-                policyRevision,
-                reasons,
-                eventId: randomUUID(),
-                storageRoot,
-                tool_input_sha256: toolInputHash,
-            });
-            if (created) {
-                inlineApproval = { request_id: created.request_id, open_url: created.open_url };
-            }
-        }
+        permission = mutate.permission;
+        ticketConsumed = mutate.ticketConsumed;
+        inlineApproval = mutate.inlineApproval;
+        approvalFlowSignal = mutate.approvalFlowSignal;
+        reasons = mutate.reasons;
     }
     const latency_ms = performance.now() - decisionStarted;
     const toolInputStr = stringifyToolInput(payload.tool_input);
@@ -258,24 +114,30 @@ export async function runBeforeMcpHookFromStdin() {
             user_message: denyMessages.user_message,
             agent_message: denyMessages.agent_message,
         };
-    await tryAppendAuditEvent({
-        ts: new Date().toISOString(),
-        hook: "beforeMCPExecution",
-        tool_name: rawToolName,
-        bare_tool: bareTool,
-        tool_input: toolInputStr.slice(0, 8000),
-        argv,
-        classification,
-        flags,
-        tier,
-        permission,
-        ticketConsumed,
-        inline_request_id: inlineApproval?.request_id ?? null,
-        tool_input_sha256: toolInputHash,
-        reasons,
-        approval_flow_signal: approvalFlowSignal,
-        latency_ms,
-    }, auditLogRoot);
+    try {
+        await appendAuditJsonl({
+            ts: new Date().toISOString(),
+            hook: "beforeMCPExecution",
+            tool_name: rawToolName,
+            bare_tool: bareTool,
+            tool_input: toolInputStr.slice(0, 8000),
+            argv,
+            classification,
+            flags,
+            tier,
+            permission,
+            ticketConsumed,
+            inline_request_id: inlineApproval?.request_id ?? null,
+            tool_input_sha256: toolInputHash,
+            reasons,
+            approval_flow_signal: approvalFlowSignal,
+            latency_ms,
+        }, auditLogRoot);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`[auditor] audit log append failed: ${msg}\n`);
+    }
     process.stdout.write(JSON.stringify(response, null, 2));
     const status = permission === "allow" ? "passed" : "blocked";
     await sendGuardEvent({