@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/dist/shared/approval-fingerprint.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Approval fingerprint — the exact-match enforcement identity for the HITL Tool
+ * Execution Gateway (Phase 2).
+ *
+ * A fingerprint is `HMAC-SHA256(key, canonicalForm)` over a canonicalized tool
+ * action (see {@link file://./approval-canonicalize.ts}). It answers exactly one
+ * question at the moment of side effect: "is *this* action the one the user
+ * approved?" An approval is bound to the canonical identity of the action, not to
+ * the transient id of the proposing tool call, so a re-driven action that differs
+ * from what was approved is re-asked — never silently executed.
+ *
+ * Why HMAC and not a bare SHA-256 (binding canonical decision,
+ * design-decisions/approval-fingerprint-vs-march-rollback.md, Rule 4): the
+ * fingerprint is an authorization token, not a correlation key. Keying it under a
+ * Stigmer-held secret means a model (or a compromised workspace) cannot forge a
+ * value that the gateway will accept. In Phase 2 the fingerprint is
+ * recompute-and-compare at one trusted layer (no bearer token crosses a wire), so
+ * the anti-forgery property is forward-looking — it earns its keep when a lease
+ * later becomes a server-issued bearer token (Phase 7). We pay the small cost now
+ * to avoid a migration that re-keys every persisted approval later.
+ *
+ * Two fidelities share this one canonicalization core, because the two
+ * enforcement substrates differ (see the Phase-2 plan, "two enforcement
+ * substrates, not one"):
+ *
+ *  - FULL ({@link computeApprovalFingerprint}) — HMAC over the full canonical
+ *    action (tool + paths + shellCommand + args). Used by the in-process
+ *    deep-agent gateway, where approve-time and execute-time observe the same
+ *    arg shape (LangGraph checkpoint replay), so the action can be matched at
+ *    full fidelity.
+ *  - COARSE ({@link computeCoarseApprovalFingerprint}) — HMAC over
+ *    (category, salient) only. Used by the out-of-process Cursor deny-oracle
+ *    hook, whose stdin payload names the same action with a different taxonomy
+ *    (`Write` vs `edit`, `file_path` vs `path`) and cannot reproduce the full
+ *    args. The coarse projection is the documented, substrate-forced coarsening
+ *    that lets the hook-side and stream-side fingerprints agree; it is the
+ *    successor identity for execute-cursor's grant token.
+ *
+ * The fingerprint is enforcement-only and never a correlation key — correlation
+ * stays `approval_request_id` + `tool_call_id`.
+ */
+import { type BinaryLike } from "node:crypto";
+import { type ToolActionInput } from "./approval-canonicalize.js";
+/**
+ * Version tag prefixed to every fingerprint. Bumping it is the migration lever
+ * if the canonical form or the MAC primitive ever changes: an old lease and a
+ * new computation will not compare equal, so a version skew re-asks (safe) rather
+ * than silently mismatching. Keep in lockstep with the Go/Java editions.
+ */
+export declare const APPROVAL_FINGERPRINT_VERSION = "v1";
+/** The HMAC key. Raw bytes (Buffer) in production; a UTF-8 string in tests. */
+export type FingerprintKey = BinaryLike;
+/**
+ * Full-fidelity fingerprint for the in-process deep-agent gateway. Distinct
+ * actions (different tool, paths, command, or args) yield distinct fingerprints;
+ * the same action is byte-stable across re-invocations.
+ */
+export declare function computeApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string;
+/**
+ * The substrate-coarsened identity of a tool action — the only fidelity the
+ * Cursor deny-oracle hook can reproduce from its stdin payload.
+ *
+ * Mirrors execute-cursor's `toolIdentity` so the two converge on one definition:
+ * - `tool` is the cross-taxonomy {@link toolApprovalCategory} (`write`/`delete`/
+ *   `shell`) for gated built-ins, the tool name for MCP tools (whose name is
+ *   stable across layers), or the trimmed tool name for non-gated built-ins
+ *   (never lease-matched, so the fallback is harmless).
+ * - `salient` is the single resource the action targets (a normalized path or the
+ *   shell command), reusing the full form's normalization so one rule governs
+ *   both fidelities. Empty for MCP tools, which are matched by `tool` alone.
+ */
+export interface CoarseToolIdentity {
+    tool: string;
+    mcpServerSlug: string;
+    salient: string;
+}
+export declare function coarseToolIdentity(input: ToolActionInput): CoarseToolIdentity;
+/**
+ * Fingerprint an already-reduced {@link CoarseToolIdentity}. Split out from
+ * {@link computeCoarseApprovalFingerprint} so a substrate that has *already*
+ * reduced a tool call to its (tool, mcpServerSlug, salient) identity — the Cursor
+ * harness, whose hook and stream both key on a raw, un-normalized salient that
+ * the bash hook can reproduce without a workspace root — can fingerprint that
+ * exact identity through the one shared HMAC+canonical-JSON path, instead of
+ * re-deriving the salient via {@link canonicalizeToolAction} (which normalizes
+ * paths and would diverge from the hook's raw value).
+ */
+export declare function fingerprintCoarseIdentity(key: FingerprintKey, identity: CoarseToolIdentity): string;
+/**
+ * Coarse fingerprint for the out-of-process Cursor hook. By construction, two
+ * actions that name the same operation in different taxonomies (`Write` vs
+ * `edit`) over the same resource collapse to one fingerprint — this is what makes
+ * the hook-side (deny/grant) and stream-side (reconciliation) values agree.
+ */
+export declare function computeCoarseApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string;
+/**
+ * Derive the per-execution fingerprint key from a runner-held master secret.
+ *
+ * The key is scoped to one `execution_id`: stable across Temporal re-invocations
+ * of the same execution (the gateway approves on one invocation and enforces on
+ * the next), and isolated between executions so a fingerprint approved for one
+ * cannot be replayed against another. The master-secret source is wired when the
+ * gateway first consumes the fingerprint (Slices C/D); until then this is
+ * exercised only by tests against a fixed master secret.
+ */
+export declare function deriveExecutionFingerprintKey(masterSecret: FingerprintKey, executionId: string): Buffer;

package/dist/shared/approval-fingerprint.js

@@ -0,0 +1,113 @@
+/**
+ * Approval fingerprint — the exact-match enforcement identity for the HITL Tool
+ * Execution Gateway (Phase 2).
+ *
+ * A fingerprint is `HMAC-SHA256(key, canonicalForm)` over a canonicalized tool
+ * action (see {@link file://./approval-canonicalize.ts}). It answers exactly one
+ * question at the moment of side effect: "is *this* action the one the user
+ * approved?" An approval is bound to the canonical identity of the action, not to
+ * the transient id of the proposing tool call, so a re-driven action that differs
+ * from what was approved is re-asked — never silently executed.
+ *
+ * Why HMAC and not a bare SHA-256 (binding canonical decision,
+ * design-decisions/approval-fingerprint-vs-march-rollback.md, Rule 4): the
+ * fingerprint is an authorization token, not a correlation key. Keying it under a
+ * Stigmer-held secret means a model (or a compromised workspace) cannot forge a
+ * value that the gateway will accept. In Phase 2 the fingerprint is
+ * recompute-and-compare at one trusted layer (no bearer token crosses a wire), so
+ * the anti-forgery property is forward-looking — it earns its keep when a lease
+ * later becomes a server-issued bearer token (Phase 7). We pay the small cost now
+ * to avoid a migration that re-keys every persisted approval later.
+ *
+ * Two fidelities share this one canonicalization core, because the two
+ * enforcement substrates differ (see the Phase-2 plan, "two enforcement
+ * substrates, not one"):
+ *
+ *  - FULL ({@link computeApprovalFingerprint}) — HMAC over the full canonical
+ *    action (tool + paths + shellCommand + args). Used by the in-process
+ *    deep-agent gateway, where approve-time and execute-time observe the same
+ *    arg shape (LangGraph checkpoint replay), so the action can be matched at
+ *    full fidelity.
+ *  - COARSE ({@link computeCoarseApprovalFingerprint}) — HMAC over
+ *    (category, salient) only. Used by the out-of-process Cursor deny-oracle
+ *    hook, whose stdin payload names the same action with a different taxonomy
+ *    (`Write` vs `edit`, `file_path` vs `path`) and cannot reproduce the full
+ *    args. The coarse projection is the documented, substrate-forced coarsening
+ *    that lets the hook-side and stream-side fingerprints agree; it is the
+ *    successor identity for execute-cursor's grant token.
+ *
+ * The fingerprint is enforcement-only and never a correlation key — correlation
+ * stays `approval_request_id` + `tool_call_id`.
+ */
+import { createHmac } from "node:crypto";
+import { canonicalJson, canonicalToolActionJson, canonicalizeToolAction, } from "./approval-canonicalize.js";
+import { toolApprovalCategory } from "./tool-kind.js";
+/**
+ * Version tag prefixed to every fingerprint. Bumping it is the migration lever
+ * if the canonical form or the MAC primitive ever changes: an old lease and a
+ * new computation will not compare equal, so a version skew re-asks (safe) rather
+ * than silently mismatching. Keep in lockstep with the Go/Java editions.
+ */
+export const APPROVAL_FINGERPRINT_VERSION = "v1";
+/**
+ * Full-fidelity fingerprint for the in-process deep-agent gateway. Distinct
+ * actions (different tool, paths, command, or args) yield distinct fingerprints;
+ * the same action is byte-stable across re-invocations.
+ */
+export function computeApprovalFingerprint(key, input) {
+    return tagged(hmacHex(key, canonicalToolActionJson(input)));
+}
+export function coarseToolIdentity(input) {
+    const canonical = canonicalizeToolAction(input);
+    if (canonical.mcpServerSlug) {
+        return { tool: input.toolName.trim(), mcpServerSlug: canonical.mcpServerSlug, salient: "" };
+    }
+    const category = toolApprovalCategory(input.toolName);
+    return {
+        tool: category ?? input.toolName.trim(),
+        mcpServerSlug: "",
+        salient: canonical.paths[0] || canonical.shellCommand || "",
+    };
+}
+/**
+ * Fingerprint an already-reduced {@link CoarseToolIdentity}. Split out from
+ * {@link computeCoarseApprovalFingerprint} so a substrate that has *already*
+ * reduced a tool call to its (tool, mcpServerSlug, salient) identity — the Cursor
+ * harness, whose hook and stream both key on a raw, un-normalized salient that
+ * the bash hook can reproduce without a workspace root — can fingerprint that
+ * exact identity through the one shared HMAC+canonical-JSON path, instead of
+ * re-deriving the salient via {@link canonicalizeToolAction} (which normalizes
+ * paths and would diverge from the hook's raw value).
+ */
+export function fingerprintCoarseIdentity(key, identity) {
+    return tagged(hmacHex(key, canonicalJson(identity)));
+}
+/**
+ * Coarse fingerprint for the out-of-process Cursor hook. By construction, two
+ * actions that name the same operation in different taxonomies (`Write` vs
+ * `edit`) over the same resource collapse to one fingerprint — this is what makes
+ * the hook-side (deny/grant) and stream-side (reconciliation) values agree.
+ */
+export function computeCoarseApprovalFingerprint(key, input) {
+    return fingerprintCoarseIdentity(key, coarseToolIdentity(input));
+}
+/**
+ * Derive the per-execution fingerprint key from a runner-held master secret.
+ *
+ * The key is scoped to one `execution_id`: stable across Temporal re-invocations
+ * of the same execution (the gateway approves on one invocation and enforces on
+ * the next), and isolated between executions so a fingerprint approved for one
+ * cannot be replayed against another. The master-secret source is wired when the
+ * gateway first consumes the fingerprint (Slices C/D); until then this is
+ * exercised only by tests against a fixed master secret.
+ */
+export function deriveExecutionFingerprintKey(masterSecret, executionId) {
+    return createHmac("sha256", masterSecret).update(executionId, "utf8").digest();
+}
+function hmacHex(key, canonical) {
+    return createHmac("sha256", key).update(canonical, "utf8").digest("hex");
+}
+function tagged(mac) {
+    return `${APPROVAL_FINGERPRINT_VERSION}:${mac}`;
+}
+//# sourceMappingURL=approval-fingerprint.js.map

package/dist/shared/approval-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-fingerprint.js","sourceRoot":"","sources":["../../src/shared/approval-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,sBAAsB,GAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAKjD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAmB,EAAE,KAAsB;IACpF,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAqBD,MAAM,UAAU,kBAAkB,CAAC,KAAsB;IACvD,MAAM,SAAS,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,SAAS,CAAC,aAAa,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC9F,CAAC;IACD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO;QACL,IAAI,EAAE,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE;QACvC,aAAa,EAAE,EAAE;QACjB,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,YAAY,IAAI,EAAE;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAmB,EAAE,QAA4B;IACzF,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAAC,GAAmB,EAAE,KAAsB;IAC1F,OAAO,yBAAyB,CAAC,GAAG,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,6BAA6B,CAAC,YAA4B,EAAE,WAAmB;IAC7F,OAAO,UAAU,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AACjF,CAAC;AAED,SAAS,OAAO,CAAC,GAAmB,EAAE,SAAiB;IACrD,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,MAAM,CAAC,GAAW;IACzB,OAAO,GAAG,4BAA4B,IAAI,GAAG,EAAE,CAAC;AAClD,CAAC"}

package/dist/shared/approval-policy.d.ts

@@ -5,41 +5,211 @@
  * 1. McpServerStatus.tool_approvals — system-generated defaults
  * 2. McpServerSpec.pinned_tool_approvals — manual overrides
  * 3. McpServerUsage.tool_approval_overrides — per-agent customization
- * 4. AgentExecutionSpec.auto_approve_all — runtime bypass
+ * 4. Active approval leases — the runtime bypass, now SCOPED: the pre-armed
+ *    spec.auto_approve_all is a whole-run global bypass, while an interactive
+ *    APPROVE_ALL ("approve all of this kind") grants a run-lifetime lease for
+ *    only that action's scope (its built-in category, or its MCP server). See
+ *    {@link ActiveLeases}.
  *
  * Used by both ExecuteCursor (hook-deny model) and ExecuteDeepAgent
  * (middleware interruptOn model) to determine which tools need approval.
  */
 import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { type ToolApprovalCategory } from "./tool-kind.js";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 /**
- * Returns true if any tool call in the execution history (root or sub-agent)
- * carries an APPROVE_ALL decision.
+ * The set of run-lifetime approval leases active for an execution.
  *
- * This is the runner-side realization of the APPROVE_ALL contract (see the
- * ApprovalAction doc in enum.proto): once a user has chosen "approve and don't
- * ask again" at any gate, the rest of THIS execution runs un-gated — exactly as
- * if spec.auto_approve_all were true. Both harnesses (native deepagents and
- * cursor) call this so the behavior is defined in exactly one place.
+ * A lease is the scoped successor to the old all-or-nothing "approve all". When
+ * a user chooses APPROVE_ALL ("approve and don't ask again") at a gate it no
+ * longer disables the entire gate — it grants a lease for ONLY that action's
+ * scope, for the remainder of THIS execution: a mutating built-in category
+ * ({@link ToolApprovalCategory}) for a built-in tool, or an MCP server slug for
+ * an MCP tool. A different class of action proposed later is still gated.
+ *
+ * This is the DERIVED form of the lease — it is not (yet) a persisted proto.
+ * Each lease rides the `ToolCall.approval_action == APPROVE_ALL` decision that
+ * is already persisted and preserved (Go PreserveApprovalFields / Java
+ * ApprovalFieldPreserver), and its scope is recomputed on read from the tool's
+ * name + mcp_server_slug. Keeping it derived means one source of truth with
+ * nothing to drift; a persisted/transmitted `ApprovalLease` proto is warranted
+ * only once a lease must cross a trust boundary (a later phase).
+ *
+ * `global` is the one remaining UNSCOPED bypass: the deliberate, pre-armed
+ * spec.auto_approve_all ("trust this whole run", set before the run via
+ * CLI/API/CI). It is intentionally distinct from the interactive scoped leases.
+ */
+export interface ActiveLeases {
+    /** Pre-armed spec.auto_approve_all: the whole gate is inert for the run. */
+    readonly global: boolean;
+    /** Built-in approval categories with a run-lifetime lease. */
+    readonly categories: ReadonlySet<ToolApprovalCategory>;
+    /** MCP server slugs with a run-lifetime lease (covers all of the server's tools). */
+    readonly servers: ReadonlySet<string>;
+}
+/**
+ * The class an APPROVE_ALL leases for a single tool call: an MCP tool leases its
+ * whole `server`, a gated built-in leases its `category`. `undefined` means the
+ * tool has no leasable scope (a read-only built-in, an unknown name).
+ *
+ * A discriminated union (not a `{ category?, server? }` bag) so callers cannot
+ * construct or observe the impossible "both set" / "neither set" states.
+ */
+export type LeaseScope = {
+    readonly kind: "category";
+    readonly category: ToolApprovalCategory;
+} | {
+    readonly kind: "server";
+    readonly server: string;
+};
+/**
+ * Reduce a single tool call to the scope its APPROVE_ALL would lease — the core
+ * of {@link deriveActiveLeases}, extracted so the cross-edition lease-scope
+ * corpus (apis/testdata/hitl/lease-scope) can exercise it directly.
+ *
+ * The MCP server slug takes precedence over the built-in category and is used
+ * RAW (the server's identity, not case-folded), matching the Go
+ * {@link DeriveLeaseScope} and Java {@link LeaseScope.deriveKey} byte-for-byte.
+ * The category lookup reuses {@link toolApprovalCategory}, the shared oracle, so
+ * a built-in resolves to write/delete/shell (read-only built-ins are ungated and
+ * return `undefined`).
+ */
+export declare function deriveLeaseScope(toolName: string, mcpServerSlug: string): LeaseScope | undefined;
+/**
+ * Derive the active approval leases for an execution.
+ *
+ * The scoped successor to the former all-or-nothing hasApproveAllDecision:
+ * instead of "any APPROVE_ALL anywhere disables the whole gate", each
+ * APPROVE_ALL decision is reduced (via {@link deriveLeaseScope}) to the SCOPE of
+ * the tool it was made on — the built-in category for a built-in tool (read-only
+ * tools are never gated, so a built-in lease is always write/delete/shell), or
+ * the MCP server slug for an MCP tool — and only that scope is auto-approved for
+ * the rest of the run.
+ *
+ * Scans root and sub-agent tool calls so a lease granted anywhere applies
+ * execution-wide (matching the prior cross-sub-agent behavior, now bounded by
+ * scope). Both harnesses call this so the contract is defined in exactly one
+ * place. The scope derivation reuses {@link toolApprovalCategory}, the same
+ * corpus-tested oracle the Go and Java editions mirror, so the backend's
+ * scope-aware bulk-approve and this runner-side evaluation can never disagree.
+ */
+export declare function deriveActiveLeases(execution: AgentExecution): ActiveLeases;
+/**
+ * Provenance of a gate decision: which policy layer (or decision point) is
+ * responsible for the final requires-approval verdict.
+ *
+ * Mirrors the proto {@link ApprovalPolicySource} one for one (see
+ * {@link toProtoPolicySource}); persisted on `ToolCall.approval_policy_source`
+ * so every authorization is auditable, and still stamped on the shadow
+ * ExecutionReceipt as a defense-in-depth audit signal.
+ *
+ * `annotation_destructive_tighten` is first-class: the connect-time tightener
+ * (see applyDestructiveHintTightener) marks its force-gated entries with
+ * `ToolApprovalPolicy.from_destructive_hint`, which {@link mergeApprovalPolicies}
+ * reads to attribute the gate to the annotation rather than collapsing it into
+ * the classifier default.
+ */
+export type PolicySource = "classifier_default" | "pinned_override" | "agent_override" | "auto_approve_all" | "approval_lease" | "builtin_category" | "file_capture" | "annotation_destructive_tighten";
+/**
+ * Monotonic identifier of the policy-engine logic that produced a decision,
+ * persisted on `ToolCall.policy_engine_version`. Bumped when the
+ * merge/classification semantics change so decisions made by different engine
+ * versions remain distinguishable in audits. Phase 7 made
+ * `annotation_destructive_tighten` a distinct, persisted source.
+ */
+export declare const POLICY_ENGINE_VERSION = "phase-7";
+/**
+ * Map the runner-internal {@link PolicySource} to the persisted proto
+ * {@link ApprovalPolicySource}. `undefined` (a tool no policy layer governs —
+ * e.g. a read-only built-in) maps to UNSPECIFIED, so the persisted field is left
+ * at its default exactly as an unclassified `tool_kind` is. The 1:1 mapping keeps
+ * the runner's union and the proto enum from drifting (asserted by the
+ * cross-edition corpus).
+ */
+export declare function toProtoPolicySource(source: PolicySource | undefined): ApprovalPolicySource;
+/**
+ * Derive the authorization provenance — which policy layer governs this tool —
+ * for persisting on `ToolCall.approval_policy_source`.
+ *
+ * This is the read-side twin of the gate's decision logic: same layered
+ * precedence, but it answers "which layer governs this call?" for EVERY tool
+ * (gated or auto-approved), so the StatusBuilders can stamp provenance on the
+ * tool call exactly where they stamp `tool_kind`. It returns `undefined` for a
+ * plain read-only built-in that no policy layer touches (the proto's
+ * APPROVAL_POLICY_SOURCE_UNSPECIFIED).
+ *
+ * Precedence:
+ * 1. Whole-run global bypass (pre-armed auto_approve_all) governs everything —
+ *    it is *why* anything ran ungated, so it wins.
+ * 2. MCP tool: the merged policy carries the responsible layer when gated; an
+ *    absent entry means the four-level chain cleared it (classifier base). A
+ *    server-scoped lease also surfaces as an absent entry — distinguishing it
+ *    would need the lease set threaded here and is deferred with the rest of the
+ *    per-server lease provenance, so a lease-cleared MCP tool reads
+ *    classifier_default (matching the gate).
+ * 3. Built-in: a mutating category is governed (leased → approval_lease, else
+ *    builtin_category); a read-only built-in is governed by no layer → undefined.
+ */
+export declare function resolveApprovalProvenance(toolName: string, serverSlug: string, policies: ReadonlyMap<string, MergedToolPolicy>, leasedCategories: ReadonlySet<ToolApprovalCategory>, globalBypass: boolean): PolicySource | undefined;
+/**
+ * A single MCP tool's merged approval decision after evaluating all policy
+ * layers. This is the single, canonical shape shared by every harness; the
+ * Cursor harness re-exports it from here so the two harnesses can never drift.
  */
-export declare function hasApproveAllDecision(execution: AgentExecution): boolean;
 export interface MergedToolPolicy {
     toolName: string;
     mcpServerSlug: string;
     requiresApproval: boolean;
     approvalMessage: string;
+    /** Which policy layer set this verdict (provenance for the shadow receipt). */
+    source: PolicySource;
 }
 /**
  * Merge approval policies from all four levels into a single lookup map.
  *
- * Keys are "serverSlug/toolName" to avoid collisions between servers.
- * When autoApproveAll is true, the returned map is empty.
+ * Each MCP server contributes its own set of policies, so the map is keyed by
+ * "serverSlug/toolName" to avoid collisions between servers.
+ *
+ * Policy chain (each level overrides the previous):
+ * 1. status.toolApprovals — system-generated defaults; presence = requires approval
+ * 2. spec.pinnedToolApprovals — manual overrides; presence = requires approval
+ * 3. agent tool_approval_overrides — explicit boolean per tool (enable OR disable)
+ * 4. active leases — runtime bypass (highest priority), now scoped
+ *
+ * The map carries ONLY the tools that require approval — a tool's absence means
+ * "auto-approved". Leases shape that absence:
+ * - On a global pre-arm ({@link ActiveLeases.global}) the map is empty.
+ * - A server-scoped lease drops that server's tools from the map entirely. This
+ *   single omission makes EVERY substrate treat the server as auto-approved with
+ *   no extra code — the deep-agent gate and StatusBuilder read the map, and the
+ *   Cursor hook's mcpToolPolicies is built from it (the hook is not itself
+ *   server-aware, so omission is the only way to lease an MCP server there).
+ * Built-in CATEGORY leases are NOT applied here — built-ins are not in this map;
+ * they are cleared at the gate (deep-agent) and the hook (Cursor) instead.
+ *
+ * Used by both ExecuteCursor (hook-deny model) and ExecuteDeepAgent (middleware
+ * interruptOn model), so the four-level semantics are defined in exactly one
+ * place.
+ */
+export declare function mergeApprovalPolicies(resolvedServers: ResolvedMcpServer[], agentOverrides: ToolApprovalOverride[], leases: ActiveLeases): Map<string, MergedToolPolicy>;
+/**
+ * Look up whether an MCP tool requires approval.
+ *
+ * @param toolName - The actual MCP tool name (e.g., "apply_cloud_resource")
+ * @param mcpServerSlug - The MCP server slug (e.g., "planton")
+ * @param policies - The merged policy map from {@link mergeApprovalPolicies}
+ * @returns The policy if approval is required, undefined if auto-approved
  */
-export declare function mergeApprovalPolicies(resolvedServers: ResolvedMcpServer[], agentOverrides: ToolApprovalOverride[], autoApproveAll: boolean): Map<string, MergedToolPolicy>;
 export declare function lookupMcpToolPolicy(toolName: string, mcpServerSlug: string, policies: Map<string, MergedToolPolicy>): MergedToolPolicy | undefined;
 /**
  * Resolve {{args.field}} placeholders in an approval message using the
  * tool's actual arguments.
+ *
+ * Placeholder syntax matches the proto-documented format:
+ * - {{args.field_name}} — replaced with the argument value
+ * - {{tool_name}} — replaced with the tool name
+ * - Missing fields are replaced with "<unknown>"
  */
 export declare function resolveApprovalMessage(template: string, toolName: string, args: Record<string, unknown>): string;