@praxis.guard/auditor-cli 0.0.33 → 0.0.35

package/dist/hooks/agent-message.js

@@ -1,6 +1,26 @@
 function reasonsSummary(reasons) {
     return reasons.length > 0 ? reasons.join(",") : "policy";
 }
+/** First lines in user_message — Cursor delivers this on deny, not agent_message. */
+function mutateGuardWaitUserLead() {
+    return ("Required next step: call MCP tool `guard_wait` on the Praxis guard server before retrying this action.\n\n");
+}
+function mutateGuardWaitUserAgentBlock(proposalKind, argvJson, inline) {
+    if (inline) {
+        return (`Agent: MUST call MCP \`guard_wait\` now with \`context.approval.request_id\` = "${inline.request_id}", ` +
+            `\`context.wait_ms\` = 120000, and \`proposal\` matching this block ` +
+            `(\`kind\`: "${proposalKind}", \`argv\`: ${argvJson}). ` +
+            `Do not retry the command until \`guard_wait\` resolves. ` +
+            `Do not call \`guard\` instead of \`guard_wait\`. ` +
+            `Do not suggest running this command in the user's terminal or via another tool.`);
+    }
+    return (`Agent: MUST call MCP \`guard_wait\` now with \`context.wait_ms\` = 120000 and \`proposal\` matching this block ` +
+        `(\`kind\`: "${proposalKind}", \`argv\`: ${argvJson}). ` +
+        `If \`guard_wait\` returns \`require_approval\`, pass \`context.approval.request_id\` from the response and call \`guard_wait\` again until redeemed. ` +
+        `Direct the human to \`approval.open_url\` when shown. After \`guard_wait\` succeeds, retry this exact invocation once. ` +
+        `Do not call \`guard\` instead of \`guard_wait\`. ` +
+        `Do not suggest running this command in the user's terminal or via another tool.`);
+}
 export function formatHookDenyMessages(input) {
     const reasons = reasonsSummary(input.reasons);
     const argvJson = JSON.stringify([...input.argv]);
@@ -23,20 +43,12 @@ export function formatHookDenyMessages(input) {
     if (input.tier === "MUTATE") {
         const proposalKind = input.hook === "beforeMCPExecution" ? "mcp" : "shell";
         const inline = input.inlineApproval;
-        const userMessage = inline
-            ? `${blockedLabel}. Human approval required.\n` +
-                `Approval request ${inline.request_id} is pending — open ${inline.open_url}\n\n` +
-                `Agent: MUST call MCP \`guard_wait\` now with \`context.approval.request_id\` = "${inline.request_id}", ` +
-                `\`context.wait_ms\` = 120000, and \`proposal\` matching this block ` +
-                `(\`kind\`: "${proposalKind}", \`argv\`: ${argvJson}). ` +
-                `Do not retry the command until \`guard_wait\` resolves. ` +
-                `Do not suggest running this command in the user's terminal or via another tool.`
-            : `${blockedLabel}. Human approval required.\n\n` +
-                `Agent: call MCP \`guard_wait\` (preferred) or \`guard\` with \`mode\`: "enforce" and \`proposal\` matching this block ` +
-                `(\`kind\`: "${proposalKind}", \`argv\`: ${argvJson}). ` +
-                `On \`require_approval\`, direct the human to \`approval.open_url\` or Praxis Approvals. ` +
-                `After approval, retry this exact invocation once (hook consumes execution ticket). ` +
-                `Do not suggest running this command in the user's terminal or via another tool.`;
+        const userMessage = mutateGuardWaitUserLead() +
+            `${blockedLabel}. Human approval required (MUTATE policy).\n` +
+            (inline
+                ? `Approval request ${inline.request_id} is pending — human may open ${inline.open_url} while you run \`guard_wait\`.\n\n`
+                : "\n") +
+            mutateGuardWaitUserAgentBlock(proposalKind, argvJson, inline ?? null);
         const inlineAgent = inline
             ? ` Pending approval request_id=${inline.request_id} open_url=${inline.open_url}. ` +
                 `MUST call MCP \`guard_wait\` with this request_id, \`context.wait_ms\` (e.g. 120000), and the same proposal before any retry. ` +

package/dist/hooks/agent-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-message.js","sourceRoot":"","sources":["../../src/hooks/agent-message.ts"],"names":[],"mappings":"AAsBA,SAAS,cAAc,CAAC,OAA0B;IAChD,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,YAAY,GAChB,KAAK,CAAC,IAAI,KAAK,oBAAoB;QACjC,CAAC,CAAC,KAAK,CAAC,QAAQ;YACd,CAAC,CAAC,0BAA0B,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,QAAQ,EAAE;YAC5D,CAAC,CAAC,0BAA0B,KAAK,CAAC,IAAI,GAAG;QAC3C,CAAC,CAAC,0BAA0B,KAAK,CAAC,IAAI,GAAG,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACjC,OAAO;YACL,YAAY,EACV,GAAG,YAAY,iDAAiD;gBAChE,wFAAwF;gBACxF,6EAA6E;YAC/E,aAAa,EACX,qGAAqG;gBACrG,8EAA8E;gBAC9E,8HAA8H;gBAC9H,WAAW,OAAO,UAAU,QAAQ,EAAE;SACzC,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC;QAEpC,MAAM,WAAW,GAAG,MAAM;YACxB,CAAC,CAAC,GAAG,YAAY,8BAA8B;gBAC7C,oBAAoB,MAAM,CAAC,UAAU,sBAAsB,MAAM,CAAC,QAAQ,MAAM;gBAChF,mFAAmF,MAAM,CAAC,UAAU,KAAK;gBACzG,qEAAqE;gBACrE,eAAe,YAAY,gBAAgB,QAAQ,KAAK;gBACxD,0DAA0D;gBAC1D,iFAAiF;YACnF,CAAC,CAAC,GAAG,YAAY,gCAAgC;gBAC/C,wHAAwH;gBACxH,eAAe,YAAY,gBAAgB,QAAQ,KAAK;gBACxD,0FAA0F;gBAC1F,qFAAqF;gBACrF,iFAAiF,CAAC;QAEtF,MAAM,WAAW,GAAG,MAAM;YACxB,CAAC,CAAC,gCAAgC,MAAM,CAAC,UAAU,aAAa,MAAM,CAAC,QAAQ,IAAI;gBACjF,gIAAgI;gBAChI,8FAA8F;YAChG,CAAC,CAAC,EAAE,CAAC;QAEP,OAAO;YACL,YAAY,EAAE,WAAW;YACzB,aAAa,EACX,sCAAsC,OAAO,UAAU,QAAQ,IAAI;gBACnE,mIAAmI;gBACnI,WAAW;gBACX,CAAC,MAAM;oBACL,CAAC,CAAC,2DAA2D;wBAC3D,eAAe,YAAY,wFAAwF;oBACrH,CAAC,CAAC,kHAAkH;wBAClH,eAAe,YAAY,8DAA8D;wBACzF,wFAAwF;wBACxF,oFAAoF,CAAC;SAC5F,CAAC;IACJ,CAAC;IAED,OAAO;QACL,YAAY,EAAE,GAAG,YAAY,GAAG;QAChC,aAAa,EACX,0BAA0B,KAAK,CAAC,IAAI,cAAc,OAAO,UAAU,QAAQ,IAAI;YAC/E,8EAA8E;KACjF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,IAEnD;IACC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,OAAO,2FAA2F,CAAC;IACrG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"agent-message.js","sourceRoot":"","sources":["../../src/hooks/agent-message.ts"],"names":[],"mappings":"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"}

package/dist/hooks/before-shell-io.d.ts

@@ -0,0 +1,3 @@
+export declare function readStdinJson<T>(): Promise<T>;
+export declare function tryAppendAuditEvent(evt: Record<string, unknown>, auditLogRoot?: string): Promise<void>;
+//# sourceMappingURL=before-shell-io.d.ts.map

package/dist/hooks/before-shell-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-io.d.ts","sourceRoot":"","sources":["../../src/hooks/before-shell-io.ts"],"names":[],"mappings":"AAEA,wBAAsB,aAAa,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAanD;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,iBAO5F"}

package/dist/hooks/before-shell-io.js

@@ -0,0 +1,26 @@
+import { appendAuditJsonl } from "../audit/jsonl.js";
+export async function readStdinJson() {
+    return await new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => {
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    });
+}
+export 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`);
+    }
+}
+//# sourceMappingURL=before-shell-io.js.map

package/dist/hooks/before-shell-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-io.js","sourceRoot":"","sources":["../../src/hooks/before-shell-io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;QACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YAC3B,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,CAAC,CAAC,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAA4B,EAAE,YAAqB;IAC3F,IAAI,CAAC;QACH,MAAM,gBAAgB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC5C,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;AACH,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { Tier } from "../policy/index.js";
+import type { ShellAnalysis } from "../shell/analyze-command.js";
+import type { BeforeShellExecutionResponse } from "./before-shell-types.js";
+export type ShellMutateHookPermission = {
+    permission: BeforeShellExecutionResponse["permission"];
+    ticketConsumed: boolean;
+    inlineApproval: {
+        request_id: string;
+        open_url: string;
+    } | null;
+    approvalFlowSignal: string | null;
+    reasons: string[];
+};
+export declare function resolveShellMutateHookPermission(input: {
+    tier: Tier;
+    argv: string[];
+    analysis: ShellAnalysis;
+    storageRoot: string;
+    rawDisplay: string;
+    policyRevision: number | null;
+    initialReasons: string[];
+}): Promise<ShellMutateHookPermission>;
+//# sourceMappingURL=before-shell-mutate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-mutate.d.ts","sourceRoot":"","sources":["../../src/hooks/before-shell-mutate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAM/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAE5E,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,4BAA4B,CAAC,YAAY,CAAC,CAAC;IACvD,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,gCAAgC,CAAC,KAAK,EAAE;IAC5D,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAyErC"}

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

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+import { resolveShellApprovalHash } from "../approval/argv-fingerprint.js";
+import { tryHookInlineApprovalRequest } from "../approval/hook-inline-approval.js";
+import { resolveMutateApproval } from "../approval/mcp-flow.js";
+import { readPendingApprovalIndex } from "../bridge/pending-approval-index.js";
+import { tryConsumeExecutionTicket } from "../bridge/execution-ticket.js";
+export async function resolveShellMutateHookPermission(input) {
+    const { tier, argv, analysis, storageRoot, rawDisplay, policyRevision, initialReasons } = input;
+    const reasons = [...initialReasons];
+    let permission = tier === "READ" ? "allow" : "deny";
+    let ticketConsumed = false;
+    let approvalFlowSignal = null;
+    let inlineApproval = null;
+    if (tier !== "MUTATE") {
+        return { permission, ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+    }
+    const approvalHash = resolveShellApprovalHash({
+        kind: "shell",
+        argv,
+        approval_fingerprint: analysis.approval_fingerprint_payload,
+    });
+    ticketConsumed = await tryConsumeExecutionTicket(argv, {
+        storageRoot,
+        kind: "shell",
+        approval_fingerprint: analysis.approval_fingerprint_payload,
+    });
+    if (ticketConsumed) {
+        return { permission: "allow", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+    }
+    const pending = await readPendingApprovalIndex(approvalHash, { storageRoot });
+    if (pending) {
+        const autoRedeem = await resolveMutateApproval({
+            argv: [...argv],
+            proposalKind: "shell",
+            storageRoot,
+            rawDisplay,
+            eventId: randomUUID(),
+            policyRevision,
+            reasons,
+            approval: { request_id: pending.request_id },
+            waitMs: 0,
+            approval_fingerprint: analysis.approval_fingerprint_payload,
+        });
+        if (autoRedeem.kind === "allow" && autoRedeem.ticketRecorded) {
+            ticketConsumed = await tryConsumeExecutionTicket(argv, {
+                storageRoot,
+                kind: "shell",
+                approval_fingerprint: analysis.approval_fingerprint_payload,
+            });
+            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: "shell",
+        rawDisplay,
+        policyRevision,
+        reasons,
+        eventId: randomUUID(),
+        storageRoot,
+        approval_fingerprint: analysis.approval_fingerprint_payload,
+    });
+    if (created) {
+        inlineApproval = { request_id: created.request_id, open_url: created.open_url };
+    }
+    return { permission: "deny", ticketConsumed, inlineApproval, approvalFlowSignal, reasons };
+}
+//# sourceMappingURL=before-shell-mutate.js.map

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

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

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

@@ -0,0 +1,11 @@
+import type { ShellAnalysis } from "../shell/analyze-command.js";
+import type { BeforeShellExecutionPayload } from "./before-shell-types.js";
+export declare function handleSkippedShellHook(input: {
+    payload: BeforeShellExecutionPayload;
+    skipReason: string;
+    policyRevision: number | null;
+    auditLogRoot: string;
+    decisionStarted: number;
+    analysis?: ShellAnalysis;
+}): Promise<void>;
+//# sourceMappingURL=before-shell-skipped.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-skipped.d.ts","sourceRoot":"","sources":["../../src/hooks/before-shell-skipped.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,KAAK,EAAE,2BAA2B,EAAgC,MAAM,yBAAyB,CAAC;AAEzG,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,OAAO,EAAE,2BAA2B,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

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

@@ -0,0 +1,49 @@
+import { getInstallId } from "../cli/install-id.js";
+import { sendGuardEvent } from "../telemetry/guard-events.js";
+import { tryAppendAuditEvent } from "./before-shell-io.js";
+export async function handleSkippedShellHook(input) {
+    const { payload, skipReason, policyRevision, auditLogRoot, decisionStarted, analysis } = input;
+    const latency_ms = performance.now() - decisionStarted;
+    await tryAppendAuditEvent({
+        ts: new Date().toISOString(),
+        hook: "beforeShellExecution",
+        cwd: payload.cwd,
+        command: payload.command,
+        ...(analysis
+            ? { segments: analysis.segments }
+            : {}),
+        status: "skipped",
+        skipped: true,
+        skip_reason: skipReason,
+        tier: "READ",
+        permission: "allow",
+        ticketConsumed: false,
+        reasons: [`${skipReason}(policy_not_evaluated)`],
+        latency_ms,
+    }, auditLogRoot);
+    const response = { permission: "allow" };
+    process.stdout.write(JSON.stringify(response, null, 2));
+    await sendGuardEvent({
+        ts: new Date().toISOString(),
+        status: "skipped",
+        skipped: true,
+        skip_reason: skipReason,
+        tool: "auditor-hook",
+        command_path: null,
+        verb: null,
+        resource: null,
+        reason: skipReason,
+        cmd: payload.command,
+        tier: "READ",
+        decision: "allow",
+        latency_ms,
+        installId: getInstallId(),
+        kind: "shell",
+        ...(policyRevision !== null ? { policy_revision: policyRevision } : {}),
+        meta: {
+            hook: "beforeShellExecution",
+            ticketConsumed: false,
+        },
+    });
+}
+//# sourceMappingURL=before-shell-skipped.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-skipped.js","sourceRoot":"","sources":["../../src/hooks/before-shell-skipped.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAO5C;IACC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC/F,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;IAEvD,MAAM,mBAAmB,CACvB;QACE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,IAAI,EAAE,sBAAsB;QAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,QAAQ;YACV,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YACjC,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,UAAU;QACvB,IAAI,EAAE,MAAM;QACZ,UAAU,EAAE,OAAO;QACnB,cAAc,EAAE,KAAK;QACrB,OAAO,EAAE,CAAC,GAAG,UAAU,wBAAwB,CAAC;QAChD,UAAU;KACX,EACD,YAAY,CACb,CAAC;IAEF,MAAM,QAAQ,GAAiC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAExD,MAAM,cAAc,CAAC;QACnB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,UAAU;QACvB,IAAI,EAAE,cAAc;QACpB,YAAY,EAAE,IAAI;QAClB,IAAI,EAAE,IAAI;QACV,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,UAAU;QAClB,GAAG,EAAE,OAAO,CAAC,OAAO;QACpB,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,OAAO;QACjB,UAAU;QACV,SAAS,EAAE,YAAY,EAAE;QACzB,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,EAAE;YACJ,IAAI,EAAE,sBAAsB;YAC5B,cAAc,EAAE,KAAK;SACtB;KACF,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,12 @@
+/** Cursor `beforeShellExecution` stdin (see https://cursor.com/docs/hooks.md). */
+export type BeforeShellExecutionPayload = {
+    command: string;
+    cwd?: string;
+    sandbox?: boolean;
+};
+export type BeforeShellExecutionResponse = {
+    permission: "allow" | "deny" | "ask";
+    user_message?: string;
+    agent_message?: string;
+};
+//# sourceMappingURL=before-shell-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"before-shell-types.d.ts","sourceRoot":"","sources":["../../src/hooks/before-shell-types.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,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-shell-types.js

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

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

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

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

@@ -1,13 +1,5 @@
-export type BeforeShellExecutionPayload = {
-    command: string;
-    cwd?: string;
-    sandbox?: boolean;
-};
-export type BeforeShellExecutionResponse = {
-    permission: "allow" | "deny" | "ask";
-    user_message?: string;
-    agent_message?: string;
-};
+import type { BeforeShellExecutionResponse } from "./before-shell-types.js";
+export type { BeforeShellExecutionPayload, BeforeShellExecutionResponse } from "./before-shell-types.js";
 /**
  * Cursor `beforeShellExecution` contract: read one JSON object from stdin, write one JSON object to stdout.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"run-before-shell.d.ts","sourceRoot":"","sources":["../../src/hooks/run-before-shell.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA+BF;;GAEG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAyMjE;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,4BAA4B,CAMtF"}
+{"version":3,"file":"run-before-shell.d.ts","sourceRoot":"","sources":["../../src/hooks/run-before-shell.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAA+B,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAEzG,YAAY,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAOzG;;GAEG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAsJjE;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,4BAA4B,CAMtF"}

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

@@ -1,168 +1,87 @@
-import { classifyArgv, loadPoliciesV1, readPoliciesV1Revision } from "../policy/index.js";
-import { appendAuditJsonl } from "../audit/jsonl.js";
+import { loadPoliciesV1, readPoliciesV1Revision } from "../policy/index.js";
 import { getInstallId } from "../cli/install-id.js";
-import { DEFAULT_GOVERNED_SHELL_TOOLS } from "../shell/governed-tools.js";
-import { parseCommandToArgv } from "../shell/parse.js";
-import { stripTrailingBenignShellRedirectsForMetacharCheck } from "../shell/strip-trailing-benign-shell-redirs.js";
+import { analyzeShellCommand } from "../shell/analyze-command.js";
+import { commandMayContainGovernedTool } from "../shell/governed-tools.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 { 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";
+import { resolveShellMutateHookPermission } from "./before-shell-mutate.js";
+import { readStdinJson, tryAppendAuditEvent } from "./before-shell-io.js";
+import { handleSkippedShellHook } from "./before-shell-skipped.js";
+import { formatHookAllowViaCredentialMessage, formatHookDenyMessages, } from "./agent-message.js";
 function tierToPermission(tier) {
     if (tier === "READ")
         return "allow";
     return "deny";
 }
-async function readStdinJson() {
-    return await new Promise((resolve, reject) => {
-        let data = "";
-        process.stdin.setEncoding("utf8");
-        process.stdin.on("data", (chunk) => (data += chunk));
-        process.stdin.on("end", () => {
-            try {
-                resolve(JSON.parse(data));
-            }
-            catch (e) {
-                reject(e);
-            }
-        });
-    });
-}
-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`);
-    }
-}
 /**
  * Cursor `beforeShellExecution` contract: read one JSON object from stdin, write one JSON object to stdout.
  */
 export async function runBeforeShellHookFromStdin() {
     const payload = await readStdinJson();
     const decisionStarted = performance.now();
-    const argv = parseCommandToArgv(payload.command);
-    const commandForRawMeta = stripTrailingBenignShellRedirectsForMetacharCheck(payload.command);
-    const rawMetacharacters = /(;|&&|\|\||\||`|>|<|\$\()/.test(commandForRawMeta);
-    const tool = argv[0];
-    if (!tool || !DEFAULT_GOVERNED_SHELL_TOOLS.includes(tool)) {
-        const skipReason = !tool ? "no_command" : "ungoverned_shell_tool";
+    const command = payload.command;
+    if (!commandMayContainGovernedTool(command)) {
+        const skipReason = command.trim() ? "no_governed_invocation" : "no_command";
         const auditLogRoot = typeof payload.cwd === "string" && payload.cwd.trim() ? payload.cwd.trim() : undefined;
-        // Decision is known here; do not await policy meta read before NET decision latency.
-        const latency_ms = performance.now() - decisionStarted;
-        await tryAppendAuditEvent({
-            ts: new Date().toISOString(),
-            hook: "beforeShellExecution",
-            cwd: payload.cwd,
-            command: payload.command,
-            argv,
-            status: "skipped",
-            skipped: true,
-            skip_reason: skipReason,
-            tier: "READ",
-            permission: "allow",
-            ticketConsumed: false,
-            reasons: [`${skipReason}(policy_not_evaluated)`],
-            latency_ms,
-        }, auditLogRoot);
-        const response = { permission: "allow" };
-        process.stdout.write(JSON.stringify(response, null, 2));
         const policyRevision = await readPoliciesV1Revision();
-        await sendGuardEvent({
-            ts: new Date().toISOString(),
-            status: "skipped",
-            skipped: true,
-            skip_reason: skipReason,
-            tool: "auditor-hook",
-            command_path: argv[0] ?? null,
-            verb: argv[1] ?? null,
-            resource: argv.length > 2 ? argv.slice(2).join(" ") : null,
-            reason: skipReason,
-            cmd: payload.command,
-            tier: "READ",
-            decision: "allow",
-            latency_ms,
-            installId: getInstallId(),
-            kind: "shell",
-            ...(policyRevision !== null ? { policy_revision: policyRevision } : {}),
-            meta: {
-                hook: "beforeShellExecution",
-                ticketConsumed: false,
-            },
+        await handleSkippedShellHook({
+            payload,
+            skipReason,
+            policyRevision,
+            auditLogRoot: auditLogRoot ?? "",
+            decisionStarted,
         });
         return;
     }
     const [policy, policyRevision] = await Promise.all([loadPoliciesV1(), readPoliciesV1Revision()]);
-    const { classification, flags } = classifyArgv(policy, argv);
-    let tier = classification.tier;
+    const analysis = analyzeShellCommand(command, policy);
+    const storageRoot = resolveGuardStorageRoot(typeof payload.cwd === "string" ? payload.cwd : undefined);
+    if (analysis.skipped) {
+        await handleSkippedShellHook({
+            payload,
+            skipReason: "no_governed_invocation",
+            policyRevision,
+            auditLogRoot: storageRoot,
+            decisionStarted,
+            analysis,
+        });
+        return;
+    }
+    const argv = analysis.primary.canonical_argv;
+    const evaluation = analysis.primary.evaluation;
+    const tier = analysis.tier;
     const reasons = [];
-    if (!classification.matched)
+    if (!evaluation.classification.matched)
         reasons.push("unknown_command(default_deny)");
-    if (flags.metacharacters || rawMetacharacters)
+    if (evaluation.flags.metacharacters || analysis.raw_metacharacters)
         reasons.push("metacharacters");
-    if (flags.dangerous_flags)
+    if (evaluation.flags.dangerous_flags)
         reasons.push("dangerous_flags");
-    if ((flags.metacharacters || rawMetacharacters) && tier === "READ")
-        tier = "MUTATE";
-    if (flags.dangerous_flags)
-        tier = "DESTRUCTIVE";
-    const storageRoot = resolveGuardStorageRoot(typeof payload.cwd === "string" ? payload.cwd : undefined);
+    if (analysis.fail_closed)
+        reasons.push("unparseable(fail_closed)");
+    if (analysis.invocations.length > 1) {
+        reasons.push(`multiple_governed_invocations(${analysis.invocations.length})`);
+    }
     let permission = tierToPermission(tier);
     let ticketConsumed = false;
     let approvalFlowSignal = null;
-    if (permission === "deny" && tier === "MUTATE") {
-        ticketConsumed = await tryConsumeExecutionTicket(argv, { storageRoot, kind: "shell" });
-        if (ticketConsumed)
-            permission = "allow";
-    }
     let inlineApproval = null;
     if (permission === "deny" && tier === "MUTATE") {
-        const pending = await readPendingApprovalIndex(argvSha256(argv), { storageRoot });
-        if (pending) {
-            const autoRedeem = await resolveMutateApproval({
-                argv: [...argv],
-                proposalKind: "shell",
-                storageRoot,
-                rawDisplay: payload.command,
-                eventId: randomUUID(),
-                policyRevision,
-                reasons,
-                approval: { request_id: pending.request_id },
-                waitMs: 0,
-            });
-            if (autoRedeem.kind === "allow" && autoRedeem.ticketRecorded) {
-                ticketConsumed = await tryConsumeExecutionTicket(argv, { storageRoot, kind: "shell" });
-                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: "shell",
-                rawDisplay: payload.command,
-                policyRevision,
-                reasons,
-                eventId: randomUUID(),
-                storageRoot,
-            });
-            if (created) {
-                inlineApproval = { request_id: created.request_id, open_url: created.open_url };
-            }
-        }
+        const mutate = await resolveShellMutateHookPermission({
+            tier,
+            argv,
+            analysis,
+            storageRoot,
+            rawDisplay: payload.command,
+            policyRevision,
+            initialReasons: reasons,
+        });
+        permission = mutate.permission;
+        ticketConsumed = mutate.ticketConsumed;
+        approvalFlowSignal = mutate.approvalFlowSignal;
+        inlineApproval = mutate.inlineApproval;
+        reasons.length = 0;
+        reasons.push(...mutate.reasons);
     }
     const allowMessage = formatHookAllowViaCredentialMessage({ ticketConsumed });
     const denyMessages = permission === "deny"
@@ -184,7 +103,6 @@ export async function runBeforeShellHookFromStdin() {
             user_message: denyMessages.user_message,
             agent_message: denyMessages.agent_message,
         };
-    const auditLogRoot = storageRoot;
     const latency_ms = performance.now() - decisionStarted;
     await tryAppendAuditEvent({
         ts: new Date().toISOString(),
@@ -192,8 +110,12 @@ export async function runBeforeShellHookFromStdin() {
         cwd: payload.cwd,
         command: payload.command,
         argv,
-        classification,
-        flags,
+        governed_argv: argv,
+        invocation_count: analysis.invocations.length,
+        segments: analysis.segments,
+        operators: analysis.operators,
+        classification: evaluation.classification,
+        flags: evaluation.flags,
         tier,
         permission,
         ticketConsumed,
@@ -201,10 +123,8 @@ export async function runBeforeShellHookFromStdin() {
         reasons,
         approval_flow_signal: approvalFlowSignal,
         latency_ms,
-    }, auditLogRoot);
-    // Write stdout immediately so Cursor gets the response without waiting for network.
+    }, storageRoot);
     process.stdout.write(JSON.stringify(response, null, 2));
-    // Upload event to backend (keep process alive until done).
     const status = permission === "allow" ? "passed" : "blocked";
     await sendGuardEvent({
         ts: new Date().toISOString(),
@@ -226,6 +146,7 @@ export async function runBeforeShellHookFromStdin() {
             ticketConsumed,
             approval_request_id: inlineApproval?.request_id ?? null,
             approval_flow_signal: approvalFlowSignal,
+            invocation_count: analysis.invocations.length,
         },
     });
 }