apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/permissions/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,qBAAqB;IACrC,2IAA2I;IAC3I,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IAC5D,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,yFAAyF;IACzF,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,qGAAqG;IACrG,YAAY,CAAC,EAAE,MAAM,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD,oHAAkH;AAClH,wBAAsB,gBAAgB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,CA4CvB;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,qBAAqB,GAC5B,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAKrG","sourcesContent":["/**\n * The permission gate: composes rule resolution (rules.ts), mode overlay\n * (modes.ts), and interactive escalation (responder.ts) into a single decision,\n * and adapts that decision to the `beforeToolCall` seam `agent-core` already\n * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.\n *\n * Tool execution has exactly one call site downstream of this hook\n * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),\n * so wiring this in once at session setup is sufficient for \"every registered tool\n * passes the gate\" to be true by construction — the universal-gate test (invariant\n * 2) verifies this property holds, it does not have to work to make it hold.\n */\n\nimport type { BeforeToolCallContext, BeforeToolCallResult } from \"apex-code-agent-core\";\nimport { resolveToolContract, type ToolContract } from \"../tools/contract.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionResponder } from \"./responder.ts\";\nimport { resolvePermission } from \"./rules.ts\";\nimport type { PermissionMode, PermissionRuleStore } from \"./store.ts\";\n\nexport interface PermissionGateOptions {\n\t/** Resolve a tool's contract by name. Foreign tools with no contract get UNCLASSIFIED, never rejected or silently defaulted (ADR 0010). */\n\tgetContract: (toolName: string) => ToolContract | undefined;\n\tstore: PermissionRuleStore;\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/**\n\t * The `--permission-mode` value, when one was passed. Not used to decide\n\t * anything here — `getMode` already folds it in. It is carried so a UI that\n\t * offers to change the mode can tell the user their write is outranked\n\t * (permissions/startup.ts, resolveEffectiveModeWithOrigin).\n\t */\n\tflagMode?: PermissionMode;\n\t/** Absent in a non-interactive session: an `ask` resolution then fails closed (deny). */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\nexport interface GateDecision {\n\tblock: boolean;\n\treason?: string;\n}\n\nfunction describeDecision(contract: ToolContract, toolName: string, ruleContent: string | undefined): string {\n\tif (ruleContent !== undefined) return contract.permission.describe(ruleContent);\n\treturn `${toolName} is not permitted by the current permission configuration.`;\n}\n\n/** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */\nexport async function evaluateToolCall(\n\ttoolName: string,\n\tparams: unknown,\n\toptions: PermissionGateOptions,\n): Promise<GateDecision> {\n\tconst contract = resolveToolContract(options.getContract, toolName);\n\tconst spec = contract.permission;\n\tconst snapshot = await options.store.snapshot();\n\tif (snapshot.errors.length > 0) {\n\t\tconst sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(\", \");\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Permission configuration could not be loaded (${sources}); refusing to run ${toolName}.`,\n\t\t};\n\t}\n\tconst ruleResolution = resolvePermission(snapshot.rules, toolName, spec, params as never);\n\tconst resolution = resolveWithMode(await options.getMode(), ruleResolution, contract.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: describeDecision(contract, toolName, resolution.rule?.ruleContent) };\n\t}\n\n\t// ask\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `${toolName} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst ruleForCall = spec.ruleForCall(params as never);\n\tconst answer = await responder.ask({\n\t\ttoolName,\n\t\tdescription: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,\n\t});\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: `${toolName} was declined.` };\n\t}\n\tif (answer.persist && ruleForCall !== null) {\n\t\tawait options.store.apply({\n\t\t\ttype: \"addRules\",\n\t\t\tdestination: \"session\",\n\t\t\trules: [{ toolName, behavior: \"allow\", ruleContent: ruleForCall }],\n\t\t});\n\t}\n\treturn { block: false };\n}\n\n/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */\nexport function createPermissionGate(\n\toptions: PermissionGateOptions,\n): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined> {\n\treturn async ({ toolCall, args }) => {\n\t\tconst decision = await evaluateToolCall(toolCall.name, args, options);\n\t\treturn decision.block ? { block: true, reason: decision.reason } : undefined;\n\t};\n}\n"]}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEnG,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,qBAAqB;IACrC,2IAA2I;IAC3I,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IAC5D,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,yFAAyF;IACzF,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,qGAAqG;IACrG,YAAY,CAAC,EAAE,MAAM,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAwCD,oHAAkH;AAClH,wBAAsB,gBAAgB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAmDvB;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,qBAAqB,GAC5B,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAKrG","sourcesContent":["/**\n * The permission gate: composes rule resolution (rules.ts), mode overlay\n * (modes.ts), and interactive escalation (responder.ts) into a single decision,\n * and adapts that decision to the `beforeToolCall` seam `agent-core` already\n * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.\n *\n * Tool execution has exactly one call site downstream of this hook\n * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),\n * so wiring this in once at session setup is sufficient for \"every registered tool\n * passes the gate\" to be true by construction — the universal-gate test (invariant\n * 2) verifies this property holds, it does not have to work to make it hold.\n */\n\nimport type { BeforeToolCallContext, BeforeToolCallResult } from \"apex-code-agent-core\";\nimport { type PermissionSpec, resolveToolContract, type ToolContract } from \"../tools/contract.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionPreview, PermissionResponder } from \"./responder.ts\";\nimport { resolvePermission } from \"./rules.ts\";\nimport type { PermissionMode, PermissionRuleStore } from \"./store.ts\";\n\nexport interface PermissionGateOptions {\n\t/** Resolve a tool's contract by name. Foreign tools with no contract get UNCLASSIFIED, never rejected or silently defaulted (ADR 0010). */\n\tgetContract: (toolName: string) => ToolContract | undefined;\n\tstore: PermissionRuleStore;\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/**\n\t * The `--permission-mode` value, when one was passed. Not used to decide\n\t * anything here — `getMode` already folds it in. It is carried so a UI that\n\t * offers to change the mode can tell the user their write is outranked\n\t * (permissions/startup.ts, resolveEffectiveModeWithOrigin).\n\t */\n\tflagMode?: PermissionMode;\n\t/** Absent in a non-interactive session: an `ask` resolution then fails closed (deny). */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\nexport interface GateDecision {\n\tblock: boolean;\n\treason?: string;\n}\n\nfunction describeDecision(contract: ToolContract, toolName: string, ruleContent: string | undefined): string {\n\tif (ruleContent !== undefined) return contract.permission.describe(ruleContent);\n\treturn `${toolName} is not permitted by the current permission configuration.`;\n}\n\n/**\n * A denial, plus whatever the user said to do instead.\n *\n * The reason becomes the blocked tool result the model reads, so guidance is\n * bounded here rather than pasted whole: it is user-entered free text on a path\n * that reaches the transcript.\n */\nconst MAX_GUIDANCE_CHARS = 400;\n\n/**\n * Run the tool's preview producer, if it declares one, on the ask branch only.\n *\n * A producer reads a file to describe a change, so a call the user was never\n * asked about must not pay for it. A producer that throws degrades to a stated\n * reason rather than to silence: `readPreparedPath` throws precisely when the\n * target changed identity since authorization, which is the case a reader most\n * needs to see.\n */\nfunction producePreview(spec: PermissionSpec, params: unknown): PermissionPreview | undefined {\n\tif (!spec.previewCall) return undefined;\n\ttry {\n\t\treturn spec.previewCall(params as never);\n\t} catch (error) {\n\t\treturn { kind: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\nfunction describeDecline(toolName: string, guidance: string | undefined): string {\n\tconst trimmed = guidance?.trim().slice(0, MAX_GUIDANCE_CHARS);\n\tif (!trimmed) return `${toolName} was declined.`;\n\treturn `${toolName} was declined. The user asked for this instead. ${trimmed}`;\n}\n\n/** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */\nexport async function evaluateToolCall(\n\ttoolName: string,\n\tparams: unknown,\n\toptions: PermissionGateOptions,\n): Promise<GateDecision> {\n\tconst contract = resolveToolContract(options.getContract, toolName);\n\tconst spec = contract.permission;\n\tif (spec.prepareCall) spec.prepareCall(params as never);\n\tconst snapshot = await options.store.snapshot();\n\tif (snapshot.errors.length > 0) {\n\t\tconst sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(\", \");\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Permission configuration could not be loaded (${sources}); refusing to run ${toolName}.`,\n\t\t};\n\t}\n\tconst ruleResolution = resolvePermission(snapshot.rules, toolName, spec, params as never);\n\tconst resolution = resolveWithMode(await options.getMode(), ruleResolution, contract.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: describeDecision(contract, toolName, resolution.rule?.ruleContent) };\n\t}\n\n\t// ask\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `${toolName} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst ruleForCall = spec.ruleForCall(params as never);\n\tconst answer = await responder.ask({\n\t\tpreview: producePreview(spec, params),\n\t\ttoolName,\n\t\tdescription: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,\n\t\t// Only offer a session grant the persist branch below would actually write.\n\t\tsessionScope: ruleForCall !== null ? { description: spec.describe(ruleForCall) } : undefined,\n\t});\n\t// `persist` means the same thing on both branches: write the rule that decides\n\t// this exact call the way the user just decided it. Reading it only on the allow\n\t// branch is what let \"Reject always\" refuse once and then ask again.\n\tif (answer.persist && ruleForCall !== null) {\n\t\tawait options.store.apply({\n\t\t\ttype: \"addRules\",\n\t\t\tdestination: \"session\",\n\t\t\trules: [{ toolName, behavior: answer.allow ? \"allow\" : \"deny\", ruleContent: ruleForCall }],\n\t\t});\n\t}\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: describeDecline(toolName, answer.guidance) };\n\t}\n\treturn { block: false };\n}\n\n/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */\nexport function createPermissionGate(\n\toptions: PermissionGateOptions,\n): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined> {\n\treturn async ({ toolCall, args }) => {\n\t\tconst decision = await evaluateToolCall(toolCall.name, args, options);\n\t\treturn decision.block ? { block: true, reason: decision.reason } : undefined;\n\t};\n}\n"]}

package/dist/core/permissions/gate.js

@@ -18,10 +18,45 @@ function describeDecision(contract, toolName, ruleContent) {
         return contract.permission.describe(ruleContent);
     return `${toolName} is not permitted by the current permission configuration.`;
 }
+/**
+ * A denial, plus whatever the user said to do instead.
+ *
+ * The reason becomes the blocked tool result the model reads, so guidance is
+ * bounded here rather than pasted whole: it is user-entered free text on a path
+ * that reaches the transcript.
+ */
+const MAX_GUIDANCE_CHARS = 400;
+/**
+ * Run the tool's preview producer, if it declares one, on the ask branch only.
+ *
+ * A producer reads a file to describe a change, so a call the user was never
+ * asked about must not pay for it. A producer that throws degrades to a stated
+ * reason rather than to silence: `readPreparedPath` throws precisely when the
+ * target changed identity since authorization, which is the case a reader most
+ * needs to see.
+ */
+function producePreview(spec, params) {
+    if (!spec.previewCall)
+        return undefined;
+    try {
+        return spec.previewCall(params);
+    }
+    catch (error) {
+        return { kind: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+function describeDecline(toolName, guidance) {
+    const trimmed = guidance?.trim().slice(0, MAX_GUIDANCE_CHARS);
+    if (!trimmed)
+        return `${toolName} was declined.`;
+    return `${toolName} was declined. The user asked for this instead. ${trimmed}`;
+}
 /** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */
 export async function evaluateToolCall(toolName, params, options) {
     const contract = resolveToolContract(options.getContract, toolName);
     const spec = contract.permission;
+    if (spec.prepareCall)
+        spec.prepareCall(params);
     const snapshot = await options.store.snapshot();
     if (snapshot.errors.length > 0) {
         const sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(", ");
@@ -47,19 +82,25 @@ export async function evaluateToolCall(toolName, params, options) {
     }
     const ruleForCall = spec.ruleForCall(params);
     const answer = await responder.ask({
+        preview: producePreview(spec, params),
         toolName,
         description: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,
+        // Only offer a session grant the persist branch below would actually write.
+        sessionScope: ruleForCall !== null ? { description: spec.describe(ruleForCall) } : undefined,
     });
-    if (!answer.allow) {
-        return { block: true, reason: `${toolName} was declined.` };
-    }
+    // `persist` means the same thing on both branches: write the rule that decides
+    // this exact call the way the user just decided it. Reading it only on the allow
+    // branch is what let "Reject always" refuse once and then ask again.
     if (answer.persist && ruleForCall !== null) {
         await options.store.apply({
             type: "addRules",
             destination: "session",
-            rules: [{ toolName, behavior: "allow", ruleContent: ruleForCall }],
+            rules: [{ toolName, behavior: answer.allow ? "allow" : "deny", ruleContent: ruleForCall }],
         });
     }
+    if (!answer.allow) {
+        return { block: true, reason: describeDecline(toolName, answer.guidance) };
+    }
     return { block: false };
 }
 /** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */

package/dist/core/permissions/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/core/permissions/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The permission gate: composes rule resolution (rules.ts), mode overlay\n * (modes.ts), and interactive escalation (responder.ts) into a single decision,\n * and adapts that decision to the `beforeToolCall` seam `agent-core` already\n * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.\n *\n * Tool execution has exactly one call site downstream of this hook\n * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),\n * so wiring this in once at session setup is sufficient for \"every registered tool\n * passes the gate\" to be true by construction — the universal-gate test (invariant\n * 2) verifies this property holds, it does not have to work to make it hold.\n */\n\nimport type { BeforeToolCallContext, BeforeToolCallResult } from \"apex-code-agent-core\";\nimport { resolveToolContract, type ToolContract } from \"../tools/contract.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionResponder } from \"./responder.ts\";\nimport { resolvePermission } from \"./rules.ts\";\nimport type { PermissionMode, PermissionRuleStore } from \"./store.ts\";\n\nexport interface PermissionGateOptions {\n\t/** Resolve a tool's contract by name. Foreign tools with no contract get UNCLASSIFIED, never rejected or silently defaulted (ADR 0010). */\n\tgetContract: (toolName: string) => ToolContract | undefined;\n\tstore: PermissionRuleStore;\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/**\n\t * The `--permission-mode` value, when one was passed. Not used to decide\n\t * anything here — `getMode` already folds it in. It is carried so a UI that\n\t * offers to change the mode can tell the user their write is outranked\n\t * (permissions/startup.ts, resolveEffectiveModeWithOrigin).\n\t */\n\tflagMode?: PermissionMode;\n\t/** Absent in a non-interactive session: an `ask` resolution then fails closed (deny). */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\nexport interface GateDecision {\n\tblock: boolean;\n\treason?: string;\n}\n\nfunction describeDecision(contract: ToolContract, toolName: string, ruleContent: string | undefined): string {\n\tif (ruleContent !== undefined) return contract.permission.describe(ruleContent);\n\treturn `${toolName} is not permitted by the current permission configuration.`;\n}\n\n/** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */\nexport async function evaluateToolCall(\n\ttoolName: string,\n\tparams: unknown,\n\toptions: PermissionGateOptions,\n): Promise<GateDecision> {\n\tconst contract = resolveToolContract(options.getContract, toolName);\n\tconst spec = contract.permission;\n\tconst snapshot = await options.store.snapshot();\n\tif (snapshot.errors.length > 0) {\n\t\tconst sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(\", \");\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Permission configuration could not be loaded (${sources}); refusing to run ${toolName}.`,\n\t\t};\n\t}\n\tconst ruleResolution = resolvePermission(snapshot.rules, toolName, spec, params as never);\n\tconst resolution = resolveWithMode(await options.getMode(), ruleResolution, contract.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: describeDecision(contract, toolName, resolution.rule?.ruleContent) };\n\t}\n\n\t// ask\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `${toolName} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst ruleForCall = spec.ruleForCall(params as never);\n\tconst answer = await responder.ask({\n\t\ttoolName,\n\t\tdescription: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,\n\t});\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: `${toolName} was declined.` };\n\t}\n\tif (answer.persist && ruleForCall !== null) {\n\t\tawait options.store.apply({\n\t\t\ttype: \"addRules\",\n\t\t\tdestination: \"session\",\n\t\t\trules: [{ toolName, behavior: \"allow\", ruleContent: ruleForCall }],\n\t\t});\n\t}\n\treturn { block: false };\n}\n\n/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */\nexport function createPermissionGate(\n\toptions: PermissionGateOptions,\n): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined> {\n\treturn async ({ toolCall, args }) => {\n\t\tconst decision = await evaluateToolCall(toolCall.name, args, options);\n\t\treturn decision.block ? { block: true, reason: decision.reason } : undefined;\n\t};\n}\n"]}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/core/permissions/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAuB,mBAAmB,EAAqB,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA0B/C,SAAS,gBAAgB,CAAC,QAAsB,EAAE,QAAgB,EAAE,WAA+B,EAAU;IAC5G,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAChF,OAAO,GAAG,QAAQ,4DAA4D,CAAC;AAAA,CAC/E;AAED;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,IAAoB,EAAE,MAAe,EAAiC;IAC7F,IAAI,CAAC,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC,MAAe,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAChG,CAAC;AAAA,CACD;AAED,SAAS,eAAe,CAAC,QAAgB,EAAE,QAA4B,EAAU;IAChF,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAC9D,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,QAAQ,gBAAgB,CAAC;IACjD,OAAO,GAAG,QAAQ,mDAAmD,OAAO,EAAE,CAAC;AAAA,CAC/E;AAED,oHAAkH;AAClH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,QAAgB,EAChB,MAAe,EACf,OAA8B,EACN;IACxB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC;IACjC,IAAI,IAAI,CAAC,WAAW;QAAE,IAAI,CAAC,WAAW,CAAC,MAAe,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAChD,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtF,OAAO;YACN,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,iDAAiD,OAAO,sBAAsB,QAAQ,GAAG;SACjG,CAAC;IACH,CAAC;IACD,MAAM,cAAc,GAAG,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAe,CAAC,CAAC;IAC1F,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IAEnG,IAAI,UAAU,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAE7D,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;IACpG,CAAC;IAED,MAAM;IACN,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IAChE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO;YACN,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,GAAG,QAAQ,oEAAoE;SACvF,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,MAAe,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC;QAClC,OAAO,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC;QACrC,QAAQ;QACR,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE;QAClF,4EAA4E;QAC5E,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;KAC5F,CAAC,CAAC;IACH,+EAA+E;IAC/E,iFAAiF;IACjF,qEAAqE;IACrE,IAAI,MAAM,CAAC,OAAO,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;YACzB,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,SAAS;YACtB,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;SAC1F,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAAA,CACxB;AAED,uFAAuF;AACvF,MAAM,UAAU,oBAAoB,CACnC,OAA8B,EACwE;IACtG,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACtE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAAA,CAC7E,CAAC;AAAA,CACF","sourcesContent":["/**\n * The permission gate: composes rule resolution (rules.ts), mode overlay\n * (modes.ts), and interactive escalation (responder.ts) into a single decision,\n * and adapts that decision to the `beforeToolCall` seam `agent-core` already\n * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.\n *\n * Tool execution has exactly one call site downstream of this hook\n * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),\n * so wiring this in once at session setup is sufficient for \"every registered tool\n * passes the gate\" to be true by construction — the universal-gate test (invariant\n * 2) verifies this property holds, it does not have to work to make it hold.\n */\n\nimport type { BeforeToolCallContext, BeforeToolCallResult } from \"apex-code-agent-core\";\nimport { type PermissionSpec, resolveToolContract, type ToolContract } from \"../tools/contract.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionPreview, PermissionResponder } from \"./responder.ts\";\nimport { resolvePermission } from \"./rules.ts\";\nimport type { PermissionMode, PermissionRuleStore } from \"./store.ts\";\n\nexport interface PermissionGateOptions {\n\t/** Resolve a tool's contract by name. Foreign tools with no contract get UNCLASSIFIED, never rejected or silently defaulted (ADR 0010). */\n\tgetContract: (toolName: string) => ToolContract | undefined;\n\tstore: PermissionRuleStore;\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/**\n\t * The `--permission-mode` value, when one was passed. Not used to decide\n\t * anything here — `getMode` already folds it in. It is carried so a UI that\n\t * offers to change the mode can tell the user their write is outranked\n\t * (permissions/startup.ts, resolveEffectiveModeWithOrigin).\n\t */\n\tflagMode?: PermissionMode;\n\t/** Absent in a non-interactive session: an `ask` resolution then fails closed (deny). */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\nexport interface GateDecision {\n\tblock: boolean;\n\treason?: string;\n}\n\nfunction describeDecision(contract: ToolContract, toolName: string, ruleContent: string | undefined): string {\n\tif (ruleContent !== undefined) return contract.permission.describe(ruleContent);\n\treturn `${toolName} is not permitted by the current permission configuration.`;\n}\n\n/**\n * A denial, plus whatever the user said to do instead.\n *\n * The reason becomes the blocked tool result the model reads, so guidance is\n * bounded here rather than pasted whole: it is user-entered free text on a path\n * that reaches the transcript.\n */\nconst MAX_GUIDANCE_CHARS = 400;\n\n/**\n * Run the tool's preview producer, if it declares one, on the ask branch only.\n *\n * A producer reads a file to describe a change, so a call the user was never\n * asked about must not pay for it. A producer that throws degrades to a stated\n * reason rather than to silence: `readPreparedPath` throws precisely when the\n * target changed identity since authorization, which is the case a reader most\n * needs to see.\n */\nfunction producePreview(spec: PermissionSpec, params: unknown): PermissionPreview | undefined {\n\tif (!spec.previewCall) return undefined;\n\ttry {\n\t\treturn spec.previewCall(params as never);\n\t} catch (error) {\n\t\treturn { kind: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\nfunction describeDecline(toolName: string, guidance: string | undefined): string {\n\tconst trimmed = guidance?.trim().slice(0, MAX_GUIDANCE_CHARS);\n\tif (!trimmed) return `${toolName} was declined.`;\n\treturn `${toolName} was declined. The user asked for this instead. ${trimmed}`;\n}\n\n/** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */\nexport async function evaluateToolCall(\n\ttoolName: string,\n\tparams: unknown,\n\toptions: PermissionGateOptions,\n): Promise<GateDecision> {\n\tconst contract = resolveToolContract(options.getContract, toolName);\n\tconst spec = contract.permission;\n\tif (spec.prepareCall) spec.prepareCall(params as never);\n\tconst snapshot = await options.store.snapshot();\n\tif (snapshot.errors.length > 0) {\n\t\tconst sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(\", \");\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Permission configuration could not be loaded (${sources}); refusing to run ${toolName}.`,\n\t\t};\n\t}\n\tconst ruleResolution = resolvePermission(snapshot.rules, toolName, spec, params as never);\n\tconst resolution = resolveWithMode(await options.getMode(), ruleResolution, contract.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: describeDecision(contract, toolName, resolution.rule?.ruleContent) };\n\t}\n\n\t// ask\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `${toolName} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst ruleForCall = spec.ruleForCall(params as never);\n\tconst answer = await responder.ask({\n\t\tpreview: producePreview(spec, params),\n\t\ttoolName,\n\t\tdescription: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,\n\t\t// Only offer a session grant the persist branch below would actually write.\n\t\tsessionScope: ruleForCall !== null ? { description: spec.describe(ruleForCall) } : undefined,\n\t});\n\t// `persist` means the same thing on both branches: write the rule that decides\n\t// this exact call the way the user just decided it. Reading it only on the allow\n\t// branch is what let \"Reject always\" refuse once and then ask again.\n\tif (answer.persist && ruleForCall !== null) {\n\t\tawait options.store.apply({\n\t\t\ttype: \"addRules\",\n\t\t\tdestination: \"session\",\n\t\t\trules: [{ toolName, behavior: answer.allow ? \"allow\" : \"deny\", ruleContent: ruleForCall }],\n\t\t});\n\t}\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: describeDecline(toolName, answer.guidance) };\n\t}\n\treturn { block: false };\n}\n\n/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */\nexport function createPermissionGate(\n\toptions: PermissionGateOptions,\n): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined> {\n\treturn async ({ toolCall, args }) => {\n\t\tconst decision = await evaluateToolCall(toolCall.name, args, options);\n\t\treturn decision.block ? { block: true, reason: decision.reason } : undefined;\n\t};\n}\n"]}

package/dist/core/permissions/operations.d.ts

@@ -0,0 +1,20 @@
+/** Typed facts prepared by a tool-owned permission spec and consumed by execution. */
+export interface CanonicalPath {
+    readonly kind: "canonical-path";
+    readonly value: string;
+}
+export interface FileIdentity {
+    readonly device: number;
+    readonly inode: number;
+}
+export type PreparedPathOperation = {
+    readonly kind: "path-existing";
+    readonly path: CanonicalPath;
+    readonly identity: FileIdentity;
+} | {
+    readonly kind: "path-new";
+    readonly path: CanonicalPath;
+};
+export declare function setPreparedPathOperation(params: object, operation: PreparedPathOperation): void;
+export declare function getPreparedPathOperation(params: object): PreparedPathOperation | undefined;
+//# sourceMappingURL=operations.d.ts.map

package/dist/core/permissions/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/operations.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAC9B;IACA,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CAC/B,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC5B,CAAC;AAIL,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,GAAG,IAAI,CAE/F;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAE1F","sourcesContent":["/** Typed facts prepared by a tool-owned permission spec and consumed by execution. */\n\nexport interface CanonicalPath {\n\treadonly kind: \"canonical-path\";\n\treadonly value: string;\n}\n\nexport interface FileIdentity {\n\treadonly device: number;\n\treadonly inode: number;\n}\n\nexport type PreparedPathOperation =\n\t| {\n\t\t\treadonly kind: \"path-existing\";\n\t\t\treadonly path: CanonicalPath;\n\t\t\treadonly identity: FileIdentity;\n\t  }\n\t| {\n\t\t\treadonly kind: \"path-new\";\n\t\t\treadonly path: CanonicalPath;\n\t  };\n\nconst preparedPathOperations = new WeakMap<object, PreparedPathOperation>();\n\nexport function setPreparedPathOperation(params: object, operation: PreparedPathOperation): void {\n\tpreparedPathOperations.set(params, operation);\n}\n\nexport function getPreparedPathOperation(params: object): PreparedPathOperation | undefined {\n\treturn preparedPathOperations.get(params);\n}\n"]}

package/dist/core/permissions/operations.js

@@ -0,0 +1,9 @@
+/** Typed facts prepared by a tool-owned permission spec and consumed by execution. */
+const preparedPathOperations = new WeakMap();
+export function setPreparedPathOperation(params, operation) {
+    preparedPathOperations.set(params, operation);
+}
+export function getPreparedPathOperation(params) {
+    return preparedPathOperations.get(params);
+}
+//# sourceMappingURL=operations.js.map

package/dist/core/permissions/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/core/permissions/operations.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAuBtF,MAAM,sBAAsB,GAAG,IAAI,OAAO,EAAiC,CAAC;AAE5E,MAAM,UAAU,wBAAwB,CAAC,MAAc,EAAE,SAAgC,EAAQ;IAChG,sBAAsB,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAAA,CAC9C;AAED,MAAM,UAAU,wBAAwB,CAAC,MAAc,EAAqC;IAC3F,OAAO,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAAA,CAC1C","sourcesContent":["/** Typed facts prepared by a tool-owned permission spec and consumed by execution. */\n\nexport interface CanonicalPath {\n\treadonly kind: \"canonical-path\";\n\treadonly value: string;\n}\n\nexport interface FileIdentity {\n\treadonly device: number;\n\treadonly inode: number;\n}\n\nexport type PreparedPathOperation =\n\t| {\n\t\t\treadonly kind: \"path-existing\";\n\t\t\treadonly path: CanonicalPath;\n\t\t\treadonly identity: FileIdentity;\n\t  }\n\t| {\n\t\t\treadonly kind: \"path-new\";\n\t\t\treadonly path: CanonicalPath;\n\t  };\n\nconst preparedPathOperations = new WeakMap<object, PreparedPathOperation>();\n\nexport function setPreparedPathOperation(params: object, operation: PreparedPathOperation): void {\n\tpreparedPathOperations.set(params, operation);\n}\n\nexport function getPreparedPathOperation(params: object): PreparedPathOperation | undefined {\n\treturn preparedPathOperations.get(params);\n}\n"]}

package/dist/core/permissions/policy-command.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PS.1: the permission authority for configured commands (verification and
+ * formatter policies from the VF.2 loader). Tool calls reach the gate through
+ * `evaluateToolCall`; a configured command has no tool name and no rule
+ * grammar, so it cannot use that path. This is the second entry point to the
+ * *same* authority, not a second authority: it reuses `resolveWithMode`, so
+ * plan mode's `exec`/`fs.write` floor and the bypass escape hatch behave
+ * identically for a formatter and for the write tool.
+ *
+ * Two differences from `evaluateToolCall` are deliberate. A `deny` policy is
+ * refused before any mode is consulted, because the policy permission is the
+ * configuration author's ceiling and `bypassPermissions` must not raise it.
+ * And an approved `ask` never persists a rule, because there is no tool name to
+ * persist it against.
+ */
+import type { PolicyPermission } from "../policy-loader.ts";
+import type { Capability } from "../tools/contract.ts";
+import type { GateDecision } from "./gate.ts";
+import type { PermissionResponder } from "./responder.ts";
+import type { PermissionMode } from "./store.ts";
+/** The typed facts a configured command presents for authorization. */
+export interface ConfiguredCommandOperation {
+    policyId: string;
+    executable: string;
+    argv: readonly string[];
+    cwd: string;
+    /** Declared write patterns already intersected with the policy's pathScope, or undefined for a non-mutating command. */
+    writeScope: readonly string[] | undefined;
+    capabilities: ReadonlySet<Capability>;
+    permission: PolicyPermission;
+}
+export interface ConfiguredCommandAuthorizationOptions {
+    getMode: () => PermissionMode | Promise<PermissionMode>;
+    /** Absent in a non-interactive session: an `ask` policy then fails closed. */
+    responder?: PermissionResponder;
+    /** Resolves a responder at call time because the interactive UI binds after session construction. */
+    getResponder?: () => PermissionResponder | undefined;
+}
+/** Injected into the verification tracker and the formatter runner so neither imports the gate. */
+export type AuthorizeConfiguredCommand = (operation: ConfiguredCommandOperation) => Promise<GateDecision>;
+export declare function authorizeConfiguredCommand(operation: ConfiguredCommandOperation, options: ConfiguredCommandAuthorizationOptions): Promise<GateDecision>;
+//# sourceMappingURL=policy-command.d.ts.map

package/dist/core/permissions/policy-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-command.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/policy-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,wHAAwH;IACxH,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC1C,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACtC,UAAU,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,qCAAqC;IACrD,OAAO,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD,8EAA8E;IAC9E,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,qGAAqG;IACrG,YAAY,CAAC,EAAE,MAAM,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED,mGAAmG;AACnG,MAAM,MAAM,0BAA0B,GAAG,CAAC,SAAS,EAAE,0BAA0B,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAM1G,wBAAsB,0BAA0B,CAC/C,SAAS,EAAE,0BAA0B,EACrC,OAAO,EAAE,qCAAqC,GAC5C,OAAO,CAAC,YAAY,CAAC,CAyBvB","sourcesContent":["/**\n * PS.1: the permission authority for configured commands (verification and\n * formatter policies from the VF.2 loader). Tool calls reach the gate through\n * `evaluateToolCall`; a configured command has no tool name and no rule\n * grammar, so it cannot use that path. This is the second entry point to the\n * *same* authority, not a second authority: it reuses `resolveWithMode`, so\n * plan mode's `exec`/`fs.write` floor and the bypass escape hatch behave\n * identically for a formatter and for the write tool.\n *\n * Two differences from `evaluateToolCall` are deliberate. A `deny` policy is\n * refused before any mode is consulted, because the policy permission is the\n * configuration author's ceiling and `bypassPermissions` must not raise it.\n * And an approved `ask` never persists a rule, because there is no tool name to\n * persist it against.\n */\n\nimport type { PolicyPermission } from \"../policy-loader.ts\";\nimport type { Capability } from \"../tools/contract.ts\";\nimport type { GateDecision } from \"./gate.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionResponder } from \"./responder.ts\";\nimport type { PermissionMode } from \"./store.ts\";\n\n/** The typed facts a configured command presents for authorization. */\nexport interface ConfiguredCommandOperation {\n\tpolicyId: string;\n\texecutable: string;\n\targv: readonly string[];\n\tcwd: string;\n\t/** Declared write patterns already intersected with the policy's pathScope, or undefined for a non-mutating command. */\n\twriteScope: readonly string[] | undefined;\n\tcapabilities: ReadonlySet<Capability>;\n\tpermission: PolicyPermission;\n}\n\nexport interface ConfiguredCommandAuthorizationOptions {\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/** Absent in a non-interactive session: an `ask` policy then fails closed. */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\n/** Injected into the verification tracker and the formatter runner so neither imports the gate. */\nexport type AuthorizeConfiguredCommand = (operation: ConfiguredCommandOperation) => Promise<GateDecision>;\n\nfunction describe(operation: ConfiguredCommandOperation): string {\n\treturn [operation.executable, ...operation.argv].join(\" \");\n}\n\nexport async function authorizeConfiguredCommand(\n\toperation: ConfiguredCommandOperation,\n\toptions: ConfiguredCommandAuthorizationOptions,\n): Promise<GateDecision> {\n\tif (operation.permission === \"deny\") {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} is configured with permission \"deny\".` };\n\t}\n\n\tconst base = operation.permission === \"allow\" ? \"allow\" : \"ask\";\n\tconst resolution = resolveWithMode(await options.getMode(), { behavior: base }, operation.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} is not permitted in the current permission mode.` };\n\t}\n\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Policy ${operation.policyId} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst answer = await responder.ask({ toolName: operation.policyId, description: describe(operation) });\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} was declined.` };\n\t}\n\treturn { block: false };\n}\n"]}

package/dist/core/permissions/policy-command.js

@@ -0,0 +1,44 @@
+/**
+ * PS.1: the permission authority for configured commands (verification and
+ * formatter policies from the VF.2 loader). Tool calls reach the gate through
+ * `evaluateToolCall`; a configured command has no tool name and no rule
+ * grammar, so it cannot use that path. This is the second entry point to the
+ * *same* authority, not a second authority: it reuses `resolveWithMode`, so
+ * plan mode's `exec`/`fs.write` floor and the bypass escape hatch behave
+ * identically for a formatter and for the write tool.
+ *
+ * Two differences from `evaluateToolCall` are deliberate. A `deny` policy is
+ * refused before any mode is consulted, because the policy permission is the
+ * configuration author's ceiling and `bypassPermissions` must not raise it.
+ * And an approved `ask` never persists a rule, because there is no tool name to
+ * persist it against.
+ */
+import { resolveWithMode } from "./modes.js";
+function describe(operation) {
+    return [operation.executable, ...operation.argv].join(" ");
+}
+export async function authorizeConfiguredCommand(operation, options) {
+    if (operation.permission === "deny") {
+        return { block: true, reason: `Policy ${operation.policyId} is configured with permission "deny".` };
+    }
+    const base = operation.permission === "allow" ? "allow" : "ask";
+    const resolution = resolveWithMode(await options.getMode(), { behavior: base }, operation.capabilities);
+    if (resolution.behavior === "allow")
+        return { block: false };
+    if (resolution.behavior === "deny") {
+        return { block: true, reason: `Policy ${operation.policyId} is not permitted in the current permission mode.` };
+    }
+    const responder = options.getResponder?.() ?? options.responder;
+    if (!responder) {
+        return {
+            block: true,
+            reason: `Policy ${operation.policyId} requires approval, and no responder is available in this session.`,
+        };
+    }
+    const answer = await responder.ask({ toolName: operation.policyId, description: describe(operation) });
+    if (!answer.allow) {
+        return { block: true, reason: `Policy ${operation.policyId} was declined.` };
+    }
+    return { block: false };
+}
+//# sourceMappingURL=policy-command.js.map

package/dist/core/permissions/policy-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-command.js","sourceRoot":"","sources":["../../../src/core/permissions/policy-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA2B7C,SAAS,QAAQ,CAAC,SAAqC,EAAU;IAChE,OAAO,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA,CAC3D;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,SAAqC,EACrC,OAA8C,EACtB;IACxB,IAAI,SAAS,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QACrC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,SAAS,CAAC,QAAQ,wCAAwC,EAAE,CAAC;IACtG,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAChE,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAExG,IAAI,UAAU,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7D,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,SAAS,CAAC,QAAQ,mDAAmD,EAAE,CAAC;IACjH,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IAChE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO;YACN,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,UAAU,SAAS,CAAC,QAAQ,oEAAoE;SACxG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,SAAS,CAAC,QAAQ,gBAAgB,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAAA,CACxB","sourcesContent":["/**\n * PS.1: the permission authority for configured commands (verification and\n * formatter policies from the VF.2 loader). Tool calls reach the gate through\n * `evaluateToolCall`; a configured command has no tool name and no rule\n * grammar, so it cannot use that path. This is the second entry point to the\n * *same* authority, not a second authority: it reuses `resolveWithMode`, so\n * plan mode's `exec`/`fs.write` floor and the bypass escape hatch behave\n * identically for a formatter and for the write tool.\n *\n * Two differences from `evaluateToolCall` are deliberate. A `deny` policy is\n * refused before any mode is consulted, because the policy permission is the\n * configuration author's ceiling and `bypassPermissions` must not raise it.\n * And an approved `ask` never persists a rule, because there is no tool name to\n * persist it against.\n */\n\nimport type { PolicyPermission } from \"../policy-loader.ts\";\nimport type { Capability } from \"../tools/contract.ts\";\nimport type { GateDecision } from \"./gate.ts\";\nimport { resolveWithMode } from \"./modes.ts\";\nimport type { PermissionResponder } from \"./responder.ts\";\nimport type { PermissionMode } from \"./store.ts\";\n\n/** The typed facts a configured command presents for authorization. */\nexport interface ConfiguredCommandOperation {\n\tpolicyId: string;\n\texecutable: string;\n\targv: readonly string[];\n\tcwd: string;\n\t/** Declared write patterns already intersected with the policy's pathScope, or undefined for a non-mutating command. */\n\twriteScope: readonly string[] | undefined;\n\tcapabilities: ReadonlySet<Capability>;\n\tpermission: PolicyPermission;\n}\n\nexport interface ConfiguredCommandAuthorizationOptions {\n\tgetMode: () => PermissionMode | Promise<PermissionMode>;\n\t/** Absent in a non-interactive session: an `ask` policy then fails closed. */\n\tresponder?: PermissionResponder;\n\t/** Resolves a responder at call time because the interactive UI binds after session construction. */\n\tgetResponder?: () => PermissionResponder | undefined;\n}\n\n/** Injected into the verification tracker and the formatter runner so neither imports the gate. */\nexport type AuthorizeConfiguredCommand = (operation: ConfiguredCommandOperation) => Promise<GateDecision>;\n\nfunction describe(operation: ConfiguredCommandOperation): string {\n\treturn [operation.executable, ...operation.argv].join(\" \");\n}\n\nexport async function authorizeConfiguredCommand(\n\toperation: ConfiguredCommandOperation,\n\toptions: ConfiguredCommandAuthorizationOptions,\n): Promise<GateDecision> {\n\tif (operation.permission === \"deny\") {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} is configured with permission \"deny\".` };\n\t}\n\n\tconst base = operation.permission === \"allow\" ? \"allow\" : \"ask\";\n\tconst resolution = resolveWithMode(await options.getMode(), { behavior: base }, operation.capabilities);\n\n\tif (resolution.behavior === \"allow\") return { block: false };\n\tif (resolution.behavior === \"deny\") {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} is not permitted in the current permission mode.` };\n\t}\n\n\tconst responder = options.getResponder?.() ?? options.responder;\n\tif (!responder) {\n\t\treturn {\n\t\t\tblock: true,\n\t\t\treason: `Policy ${operation.policyId} requires approval, and no responder is available in this session.`,\n\t\t};\n\t}\n\tconst answer = await responder.ask({ toolName: operation.policyId, description: describe(operation) });\n\tif (!answer.allow) {\n\t\treturn { block: true, reason: `Policy ${operation.policyId} was declined.` };\n\t}\n\treturn { block: false };\n}\n"]}

package/dist/core/permissions/responder.d.ts

@@ -1,20 +1,67 @@
 /** Interactive escalation for an `ask`-resolved permission decision. */
+/**
+ * What the prompt shows about the change it is authorizing.
+ *
+ * `unavailable` is a first-class variant rather than an absent field, because a
+ * reader who is shown nothing cannot tell "this changes nothing" from "we could
+ * not read it". Only the second one should stop them approving.
+ */
+export type PermissionPreview = {
+    kind: "diff";
+    path: string;
+    lines: readonly string[];
+    omittedLines: number;
+} | {
+    kind: "summary";
+    lines: readonly string[];
+} | {
+    kind: "unavailable";
+    reason: string;
+};
 export interface PermissionAskRequest {
     toolName: string;
     /** Human-readable rendering of what would be persisted, from the tool's own describe(). */
     description: string;
+    /**
+     * Present only when the tool's `ruleForCall()` yields something to persist.
+     *
+     * The gate silently ignores `persist` when there is no rule, so offering the
+     * choice in that case promised a grant nothing would write.
+     */
+    sessionScope?: {
+        description: string;
+    };
+    /**
+     * Produced by the tool's `previewCall`, after the gate decides to ask and never
+     * before. Absent when the tool declares no producer.
+     */
+    preview?: PermissionPreview;
 }
 export interface PermissionAnswer {
     allow: boolean;
-    /** "Always allow this" — persist a session-source rule via the tool's own ruleForCall(). */
+    /**
+     * Persist a session-source rule via the tool's own ruleForCall(), matching the
+     * answer: an allow writes an allow rule, a refusal writes a deny one. Either
+     * way it ends with the session.
+     */
     persist?: boolean;
+    /**
+     * On a denial, what the user wants done instead. The gate bounds it and carries
+     * it in `GateDecision.reason`, which the agent loop already turns into the
+     * blocked tool result, so no second message queue is involved.
+     */
+    guidance?: string;
 }
 export interface PermissionResponder {
     ask(request: PermissionAskRequest): Promise<PermissionAnswer>;
 }
 /** The subset of ExtensionUIContext (core/extensions/types.ts) this responder needs. */
 export interface SelectUI {
-    select(title: string, options: string[]): Promise<string | undefined>;
+    select(title: string, options: string[], opts?: {
+        preview?: PermissionPreview;
+    }): Promise<string | undefined>;
+    /** Absent on hosts that cannot collect free text; the guidance choice is then not offered. */
+    input?(title: string, placeholder?: string): Promise<string | undefined>;
 }
 /**
  * Builds a PermissionResponder over the same live, mid-session prompt primitive

package/dist/core/permissions/responder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responder.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/responder.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,8FAA4F;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IACnC,GAAG,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9D;AAMD,wFAAwF;AACxF,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,QAAQ,GAAG,mBAAmB,CAc5E","sourcesContent":["/** Interactive escalation for an `ask`-resolved permission decision. */\n\nexport interface PermissionAskRequest {\n\ttoolName: string;\n\t/** Human-readable rendering of what would be persisted, from the tool's own describe(). */\n\tdescription: string;\n}\n\nexport interface PermissionAnswer {\n\tallow: boolean;\n\t/** \"Always allow this\" — persist a session-source rule via the tool's own ruleForCall(). */\n\tpersist?: boolean;\n}\n\nexport interface PermissionResponder {\n\task(request: PermissionAskRequest): Promise<PermissionAnswer>;\n}\n\nconst ALLOW_ONCE = \"Allow once\";\nconst ALWAYS_ALLOW = \"Always allow\";\nconst DENY = \"Deny\";\n\n/** The subset of ExtensionUIContext (core/extensions/types.ts) this responder needs. */\nexport interface SelectUI {\n\tselect(title: string, options: string[]): Promise<string | undefined>;\n}\n\n/**\n * Builds a PermissionResponder over the same live, mid-session prompt primitive\n * extensions already use (ExtensionUIContext.select) — no new rendering\n * dependency, per the roadmap's \"Explicitly not building\" a second TUI stack.\n *\n * Deliberately answers only `{allow, persist}`. It never constructs a rule string\n * itself: generating one from `ruleForCall()` and persisting it is the gate's job\n * (permissions/gate.ts), so the tool that owns the grammar is the only thing that\n * ever writes a rule (ADR 0010).\n */\nexport function createInteractiveResponder(ui: SelectUI): PermissionResponder {\n\treturn {\n\t\tasync ask({ toolName, description }) {\n\t\t\tconst choice = await ui.select(`Permission required — ${toolName}: ${description}`, [\n\t\t\t\tALLOW_ONCE,\n\t\t\t\tALWAYS_ALLOW,\n\t\t\t\tDENY,\n\t\t\t]);\n\t\t\tif (choice === ALLOW_ONCE) return { allow: true };\n\t\t\tif (choice === ALWAYS_ALLOW) return { allow: true, persist: true };\n\t\t\t// DENY, or no selection (cancelled/dismissed) — fail closed.\n\t\t\treturn { allow: false };\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"responder.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/responder.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IACnC,GAAG,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9D;AAQD,wFAAwF;AACxF,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9G,8FAA8F;IAC9F,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,QAAQ,GAAG,mBAAmB,CA2B5E","sourcesContent":["/** Interactive escalation for an `ask`-resolved permission decision. */\n\n/**\n * What the prompt shows about the change it is authorizing.\n *\n * `unavailable` is a first-class variant rather than an absent field, because a\n * reader who is shown nothing cannot tell \"this changes nothing\" from \"we could\n * not read it\". Only the second one should stop them approving.\n */\nexport type PermissionPreview =\n\t| { kind: \"diff\"; path: string; lines: readonly string[]; omittedLines: number }\n\t| { kind: \"summary\"; lines: readonly string[] }\n\t| { kind: \"unavailable\"; reason: string };\n\nexport interface PermissionAskRequest {\n\ttoolName: string;\n\t/** Human-readable rendering of what would be persisted, from the tool's own describe(). */\n\tdescription: string;\n\t/**\n\t * Present only when the tool's `ruleForCall()` yields something to persist.\n\t *\n\t * The gate silently ignores `persist` when there is no rule, so offering the\n\t * choice in that case promised a grant nothing would write.\n\t */\n\tsessionScope?: { description: string };\n\t/**\n\t * Produced by the tool's `previewCall`, after the gate decides to ask and never\n\t * before. Absent when the tool declares no producer.\n\t */\n\tpreview?: PermissionPreview;\n}\n\nexport interface PermissionAnswer {\n\tallow: boolean;\n\t/**\n\t * Persist a session-source rule via the tool's own ruleForCall(), matching the\n\t * answer: an allow writes an allow rule, a refusal writes a deny one. Either\n\t * way it ends with the session.\n\t */\n\tpersist?: boolean;\n\t/**\n\t * On a denial, what the user wants done instead. The gate bounds it and carries\n\t * it in `GateDecision.reason`, which the agent loop already turns into the\n\t * blocked tool result, so no second message queue is involved.\n\t */\n\tguidance?: string;\n}\n\nexport interface PermissionResponder {\n\task(request: PermissionAskRequest): Promise<PermissionAnswer>;\n}\n\nconst ALLOW_ONCE = \"Allow once\";\n/** Named for what the gate actually writes: an `addRules` update whose destination is \"session\". */\nconst ALLOW_SESSION = \"Allow for this session\";\nconst REJECT_WITH_GUIDANCE = \"Reject and say what to do instead\";\nconst DENY = \"Deny\";\n\n/** The subset of ExtensionUIContext (core/extensions/types.ts) this responder needs. */\nexport interface SelectUI {\n\tselect(title: string, options: string[], opts?: { preview?: PermissionPreview }): Promise<string | undefined>;\n\t/** Absent on hosts that cannot collect free text; the guidance choice is then not offered. */\n\tinput?(title: string, placeholder?: string): Promise<string | undefined>;\n}\n\n/**\n * Builds a PermissionResponder over the same live, mid-session prompt primitive\n * extensions already use (ExtensionUIContext.select) — no new rendering\n * dependency, per the roadmap's \"Explicitly not building\" a second TUI stack.\n *\n * Deliberately answers only `{allow, persist}`. It never constructs a rule string\n * itself: generating one from `ruleForCall()` and persisting it is the gate's job\n * (permissions/gate.ts), so the tool that owns the grammar is the only thing that\n * ever writes a rule (ADR 0010).\n */\nexport function createInteractiveResponder(ui: SelectUI): PermissionResponder {\n\treturn {\n\t\tasync ask({ toolName, description, sessionScope, preview }) {\n\t\t\tconst options = [ALLOW_ONCE];\n\t\t\tif (sessionScope) options.push(ALLOW_SESSION);\n\t\t\tif (ui.input) options.push(REJECT_WITH_GUIDANCE);\n\t\t\toptions.push(DENY);\n\n\t\t\t// The preview travels as data. Drawing it belongs to whatever is hosting\n\t\t\t// the prompt, which keeps this file free of a rendering dependency.\n\t\t\tconst choice = await ui.select(\n\t\t\t\t`Permission required — ${toolName}: ${description}`,\n\t\t\t\toptions,\n\t\t\t\tpreview ? { preview } : undefined,\n\t\t\t);\n\t\t\tif (choice === ALLOW_ONCE) return { allow: true };\n\t\t\tif (choice === ALLOW_SESSION) return { allow: true, persist: true };\n\t\t\tif (choice === REJECT_WITH_GUIDANCE && ui.input) {\n\t\t\t\tconst guidance = await ui.input(`What should Apex do instead of ${toolName}?`);\n\t\t\t\t// A dismissed guidance prompt is still a denial. Failing closed here\n\t\t\t\t// matches every other path out of this function.\n\t\t\t\treturn guidance?.trim() ? { allow: false, guidance: guidance.trim() } : { allow: false };\n\t\t\t}\n\t\t\t// DENY, or no selection (cancelled/dismissed) — fail closed.\n\t\t\treturn { allow: false };\n\t\t},\n\t};\n}\n"]}

package/dist/core/permissions/responder.js

@@ -1,6 +1,8 @@
 /** Interactive escalation for an `ask`-resolved permission decision. */
 const ALLOW_ONCE = "Allow once";
-const ALWAYS_ALLOW = "Always allow";
+/** Named for what the gate actually writes: an `addRules` update whose destination is "session". */
+const ALLOW_SESSION = "Allow for this session";
+const REJECT_WITH_GUIDANCE = "Reject and say what to do instead";
 const DENY = "Deny";
 /**
  * Builds a PermissionResponder over the same live, mid-session prompt primitive
@@ -14,16 +16,26 @@ const DENY = "Deny";
  */
 export function createInteractiveResponder(ui) {
     return {
-        async ask({ toolName, description }) {
-            const choice = await ui.select(`Permission required — ${toolName}: ${description}`, [
-                ALLOW_ONCE,
-                ALWAYS_ALLOW,
-                DENY,
-            ]);
+        async ask({ toolName, description, sessionScope, preview }) {
+            const options = [ALLOW_ONCE];
+            if (sessionScope)
+                options.push(ALLOW_SESSION);
+            if (ui.input)
+                options.push(REJECT_WITH_GUIDANCE);
+            options.push(DENY);
+            // The preview travels as data. Drawing it belongs to whatever is hosting
+            // the prompt, which keeps this file free of a rendering dependency.
+            const choice = await ui.select(`Permission required — ${toolName}: ${description}`, options, preview ? { preview } : undefined);
             if (choice === ALLOW_ONCE)
                 return { allow: true };
-            if (choice === ALWAYS_ALLOW)
+            if (choice === ALLOW_SESSION)
                 return { allow: true, persist: true };
+            if (choice === REJECT_WITH_GUIDANCE && ui.input) {
+                const guidance = await ui.input(`What should Apex do instead of ${toolName}?`);
+                // A dismissed guidance prompt is still a denial. Failing closed here
+                // matches every other path out of this function.
+                return guidance?.trim() ? { allow: false, guidance: guidance.trim() } : { allow: false };
+            }
             // DENY, or no selection (cancelled/dismissed) — fail closed.
             return { allow: false };
         },

package/dist/core/permissions/responder.js.map

@@ -1 +1 @@
-{"version":3,"file":"responder.js","sourceRoot":"","sources":["../../../src/core/permissions/responder.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAkBxE,MAAM,UAAU,GAAG,YAAY,CAAC;AAChC,MAAM,YAAY,GAAG,cAAc,CAAC;AACpC,MAAM,IAAI,GAAG,MAAM,CAAC;AAOpB;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,EAAY,EAAuB;IAC7E,OAAO;QACN,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE;YACpC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,2BAAyB,QAAQ,KAAK,WAAW,EAAE,EAAE;gBACnF,UAAU;gBACV,YAAY;gBACZ,IAAI;aACJ,CAAC,CAAC;YACH,IAAI,MAAM,KAAK,UAAU;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAClD,IAAI,MAAM,KAAK,YAAY;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACnE,+DAA6D;YAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAAA,CACxB;KACD,CAAC;AAAA,CACF","sourcesContent":["/** Interactive escalation for an `ask`-resolved permission decision. */\n\nexport interface PermissionAskRequest {\n\ttoolName: string;\n\t/** Human-readable rendering of what would be persisted, from the tool's own describe(). */\n\tdescription: string;\n}\n\nexport interface PermissionAnswer {\n\tallow: boolean;\n\t/** \"Always allow this\" — persist a session-source rule via the tool's own ruleForCall(). */\n\tpersist?: boolean;\n}\n\nexport interface PermissionResponder {\n\task(request: PermissionAskRequest): Promise<PermissionAnswer>;\n}\n\nconst ALLOW_ONCE = \"Allow once\";\nconst ALWAYS_ALLOW = \"Always allow\";\nconst DENY = \"Deny\";\n\n/** The subset of ExtensionUIContext (core/extensions/types.ts) this responder needs. */\nexport interface SelectUI {\n\tselect(title: string, options: string[]): Promise<string | undefined>;\n}\n\n/**\n * Builds a PermissionResponder over the same live, mid-session prompt primitive\n * extensions already use (ExtensionUIContext.select) — no new rendering\n * dependency, per the roadmap's \"Explicitly not building\" a second TUI stack.\n *\n * Deliberately answers only `{allow, persist}`. It never constructs a rule string\n * itself: generating one from `ruleForCall()` and persisting it is the gate's job\n * (permissions/gate.ts), so the tool that owns the grammar is the only thing that\n * ever writes a rule (ADR 0010).\n */\nexport function createInteractiveResponder(ui: SelectUI): PermissionResponder {\n\treturn {\n\t\tasync ask({ toolName, description }) {\n\t\t\tconst choice = await ui.select(`Permission required — ${toolName}: ${description}`, [\n\t\t\t\tALLOW_ONCE,\n\t\t\t\tALWAYS_ALLOW,\n\t\t\t\tDENY,\n\t\t\t]);\n\t\t\tif (choice === ALLOW_ONCE) return { allow: true };\n\t\t\tif (choice === ALWAYS_ALLOW) return { allow: true, persist: true };\n\t\t\t// DENY, or no selection (cancelled/dismissed) — fail closed.\n\t\t\treturn { allow: false };\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"responder.js","sourceRoot":"","sources":["../../../src/core/permissions/responder.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAoDxE,MAAM,UAAU,GAAG,YAAY,CAAC;AAChC,oGAAoG;AACpG,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAC/C,MAAM,oBAAoB,GAAG,mCAAmC,CAAC;AACjE,MAAM,IAAI,GAAG,MAAM,CAAC;AASpB;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,EAAY,EAAuB;IAC7E,OAAO;QACN,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE;YAC3D,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;YAC7B,IAAI,YAAY;gBAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC9C,IAAI,EAAE,CAAC,KAAK;gBAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACjD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEnB,yEAAyE;YACzE,oEAAoE;YACpE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAC7B,2BAAyB,QAAQ,KAAK,WAAW,EAAE,EACnD,OAAO,EACP,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CACjC,CAAC;YACF,IAAI,MAAM,KAAK,UAAU;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAClD,IAAI,MAAM,KAAK,aAAa;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACpE,IAAI,MAAM,KAAK,oBAAoB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;gBACjD,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,kCAAkC,QAAQ,GAAG,CAAC,CAAC;gBAC/E,qEAAqE;gBACrE,iDAAiD;gBACjD,OAAO,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC1F,CAAC;YACD,+DAA6D;YAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAAA,CACxB;KACD,CAAC;AAAA,CACF","sourcesContent":["/** Interactive escalation for an `ask`-resolved permission decision. */\n\n/**\n * What the prompt shows about the change it is authorizing.\n *\n * `unavailable` is a first-class variant rather than an absent field, because a\n * reader who is shown nothing cannot tell \"this changes nothing\" from \"we could\n * not read it\". Only the second one should stop them approving.\n */\nexport type PermissionPreview =\n\t| { kind: \"diff\"; path: string; lines: readonly string[]; omittedLines: number }\n\t| { kind: \"summary\"; lines: readonly string[] }\n\t| { kind: \"unavailable\"; reason: string };\n\nexport interface PermissionAskRequest {\n\ttoolName: string;\n\t/** Human-readable rendering of what would be persisted, from the tool's own describe(). */\n\tdescription: string;\n\t/**\n\t * Present only when the tool's `ruleForCall()` yields something to persist.\n\t *\n\t * The gate silently ignores `persist` when there is no rule, so offering the\n\t * choice in that case promised a grant nothing would write.\n\t */\n\tsessionScope?: { description: string };\n\t/**\n\t * Produced by the tool's `previewCall`, after the gate decides to ask and never\n\t * before. Absent when the tool declares no producer.\n\t */\n\tpreview?: PermissionPreview;\n}\n\nexport interface PermissionAnswer {\n\tallow: boolean;\n\t/**\n\t * Persist a session-source rule via the tool's own ruleForCall(), matching the\n\t * answer: an allow writes an allow rule, a refusal writes a deny one. Either\n\t * way it ends with the session.\n\t */\n\tpersist?: boolean;\n\t/**\n\t * On a denial, what the user wants done instead. The gate bounds it and carries\n\t * it in `GateDecision.reason`, which the agent loop already turns into the\n\t * blocked tool result, so no second message queue is involved.\n\t */\n\tguidance?: string;\n}\n\nexport interface PermissionResponder {\n\task(request: PermissionAskRequest): Promise<PermissionAnswer>;\n}\n\nconst ALLOW_ONCE = \"Allow once\";\n/** Named for what the gate actually writes: an `addRules` update whose destination is \"session\". */\nconst ALLOW_SESSION = \"Allow for this session\";\nconst REJECT_WITH_GUIDANCE = \"Reject and say what to do instead\";\nconst DENY = \"Deny\";\n\n/** The subset of ExtensionUIContext (core/extensions/types.ts) this responder needs. */\nexport interface SelectUI {\n\tselect(title: string, options: string[], opts?: { preview?: PermissionPreview }): Promise<string | undefined>;\n\t/** Absent on hosts that cannot collect free text; the guidance choice is then not offered. */\n\tinput?(title: string, placeholder?: string): Promise<string | undefined>;\n}\n\n/**\n * Builds a PermissionResponder over the same live, mid-session prompt primitive\n * extensions already use (ExtensionUIContext.select) — no new rendering\n * dependency, per the roadmap's \"Explicitly not building\" a second TUI stack.\n *\n * Deliberately answers only `{allow, persist}`. It never constructs a rule string\n * itself: generating one from `ruleForCall()` and persisting it is the gate's job\n * (permissions/gate.ts), so the tool that owns the grammar is the only thing that\n * ever writes a rule (ADR 0010).\n */\nexport function createInteractiveResponder(ui: SelectUI): PermissionResponder {\n\treturn {\n\t\tasync ask({ toolName, description, sessionScope, preview }) {\n\t\t\tconst options = [ALLOW_ONCE];\n\t\t\tif (sessionScope) options.push(ALLOW_SESSION);\n\t\t\tif (ui.input) options.push(REJECT_WITH_GUIDANCE);\n\t\t\toptions.push(DENY);\n\n\t\t\t// The preview travels as data. Drawing it belongs to whatever is hosting\n\t\t\t// the prompt, which keeps this file free of a rendering dependency.\n\t\t\tconst choice = await ui.select(\n\t\t\t\t`Permission required — ${toolName}: ${description}`,\n\t\t\t\toptions,\n\t\t\t\tpreview ? { preview } : undefined,\n\t\t\t);\n\t\t\tif (choice === ALLOW_ONCE) return { allow: true };\n\t\t\tif (choice === ALLOW_SESSION) return { allow: true, persist: true };\n\t\t\tif (choice === REJECT_WITH_GUIDANCE && ui.input) {\n\t\t\t\tconst guidance = await ui.input(`What should Apex do instead of ${toolName}?`);\n\t\t\t\t// A dismissed guidance prompt is still a denial. Failing closed here\n\t\t\t\t// matches every other path out of this function.\n\t\t\t\treturn guidance?.trim() ? { allow: false, guidance: guidance.trim() } : { allow: false };\n\t\t\t}\n\t\t\t// DENY, or no selection (cancelled/dismissed) — fail closed.\n\t\t\treturn { allow: false };\n\t\t},\n\t};\n}\n"]}

package/dist/core/permissions/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yFASrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,cAAc,CAAC;CACtB;AA8BD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,OAAO,EACxD,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,EAC7B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,GACrB,oBAAoB,CAkBtB","sourcesContent":["/**\n * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never\n * inspects a `ruleContent` grammar itself — it only calls the tool's own\n * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions\n * of its grammar and the engine never accumulates tool-specific matching.\n */\n\nimport type { Static, TSchema } from \"typebox\";\nimport type { PermissionBehavior, PermissionSpec } from \"../tools/contract.ts\";\n\n/**\n * Highest to lowest precedence. `flag` outranks config because it is a deliberate\n * per-run operator override; `cliArg` sits below config because it is a per-run\n * *default*, not an override. See ADR 0004 for why each source sits where it does.\n */\nexport const PERMISSION_SOURCES = [\n\t\"policy\",\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"cliArg\",\n\t\"command\",\n\t\"session\",\n] as const;\n\nexport type PermissionSource = (typeof PERMISSION_SOURCES)[number];\n\nexport interface PermissionRule {\n\tsource: PermissionSource;\n\tbehavior: PermissionBehavior;\n\ttoolName: string;\n\t/** Undefined matches every call to this tool — a tool-wide rule. */\n\truleContent?: string;\n}\n\nexport interface PermissionResolution {\n\tbehavior: PermissionBehavior;\n\t/** The winning rule, or undefined when no rule matched and the tool's own default applied. */\n\trule?: PermissionRule;\n}\n\nconst SOURCE_RANK = new Map<PermissionSource, number>(PERMISSION_SOURCES.map((source, index) => [source, index]));\n\nfunction ruleMatchesCall<TParams extends TSchema>(\n\trule: PermissionRule,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): boolean {\n\tif (rule.ruleContent === undefined) return true;\n\treturn spec.matches(rule.ruleContent, params);\n}\n\n/**\n * Deterministic tie-break for two matching rules at the *same* source, independent\n * of array order: a rule with `ruleContent` (specific) outranks a tool-wide rule\n * with none (blanket); between two specific rules, the longer `ruleContent` wins\n * (a proxy for \"more specific\"); a final lexical comparison guarantees a total,\n * order-independent order for the residual case of equal-length content.\n */\nfunction compareSameSourceRules(a: PermissionRule, b: PermissionRule): number {\n\tconst aSpecific = a.ruleContent !== undefined;\n\tconst bSpecific = b.ruleContent !== undefined;\n\tif (aSpecific !== bSpecific) return aSpecific ? -1 : 1; // specific wins (negative = a first)\n\tif (!aSpecific) return 0; // both blanket at the same source: no further distinction needed\n\tconst lengthDelta = (b.ruleContent as string).length - (a.ruleContent as string).length;\n\tif (lengthDelta !== 0) return lengthDelta;\n\treturn (a.ruleContent as string).localeCompare(b.ruleContent as string);\n}\n\n/**\n * Resolve the effective behavior for one call. The highest-precedence *matching*\n * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.\n * With no matching rule, the tool's own `defaultBehavior` applies.\n */\nexport function resolvePermission<TParams extends TSchema>(\n\trules: readonly PermissionRule[],\n\ttoolName: string,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): PermissionResolution {\n\tlet winner: PermissionRule | undefined;\n\tfor (const candidate of rules) {\n\t\tif (candidate.toolName !== toolName) continue;\n\t\tif (!ruleMatchesCall(candidate, spec, params)) continue;\n\t\tif (!winner) {\n\t\t\twinner = candidate;\n\t\t\tcontinue;\n\t\t}\n\t\tconst candidateRank = SOURCE_RANK.get(candidate.source) ?? Number.POSITIVE_INFINITY;\n\t\tconst winnerRank = SOURCE_RANK.get(winner.source) ?? Number.POSITIVE_INFINITY;\n\t\tif (candidateRank < winnerRank) {\n\t\t\twinner = candidate;\n\t\t} else if (candidateRank === winnerRank && compareSameSourceRules(candidate, winner) < 0) {\n\t\t\twinner = candidate;\n\t\t}\n\t}\n\treturn winner ? { behavior: winner.behavior, rule: winner } : { behavior: spec.defaultBehavior };\n}\n"]}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yFASrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,cAAc,CAAC;CACtB;AAoCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,OAAO,EACxD,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,EAC7B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,GACrB,oBAAoB,CAoBtB","sourcesContent":["/**\n * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never\n * inspects a `ruleContent` grammar itself — it only calls the tool's own\n * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions\n * of its grammar and the engine never accumulates tool-specific matching.\n */\n\nimport type { Static, TSchema } from \"typebox\";\nimport type { PermissionBehavior, PermissionSpec } from \"../tools/contract.ts\";\n\n/**\n * Highest to lowest precedence. `flag` outranks config because it is a deliberate\n * per-run operator override; `cliArg` sits below config because it is a per-run\n * *default*, not an override. See ADR 0004 for why each source sits where it does.\n */\nexport const PERMISSION_SOURCES = [\n\t\"policy\",\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"cliArg\",\n\t\"command\",\n\t\"session\",\n] as const;\n\nexport type PermissionSource = (typeof PERMISSION_SOURCES)[number];\n\nexport interface PermissionRule {\n\tsource: PermissionSource;\n\tbehavior: PermissionBehavior;\n\ttoolName: string;\n\t/** Undefined matches every call to this tool — a tool-wide rule. */\n\truleContent?: string;\n}\n\nexport interface PermissionResolution {\n\tbehavior: PermissionBehavior;\n\t/** The winning rule, or undefined when no rule matched and the tool's own default applied. */\n\trule?: PermissionRule;\n}\n\nconst SOURCE_RANK = new Map<PermissionSource, number>(PERMISSION_SOURCES.map((source, index) => [source, index]));\n\nfunction ruleMatchesCall<TParams extends TSchema>(\n\trule: PermissionRule,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): boolean {\n\tif (spec.isUnknown?.(params)) {\n\t\tif (rule.behavior === \"allow\") return false;\n\t\tif (rule.behavior === \"deny\") return true;\n\t}\n\tif (rule.ruleContent === undefined) return true;\n\tif (rule.behavior === \"deny\")\n\t\treturn spec.matchesDeny?.(rule.ruleContent, params) ?? spec.matches(rule.ruleContent, params);\n\treturn spec.matches(rule.ruleContent, params);\n}\n\n/**\n * Deterministic tie-break for two matching rules at the *same* source, independent\n * of array order: a rule with `ruleContent` (specific) outranks a tool-wide rule\n * with none (blanket); between two specific rules, the longer `ruleContent` wins\n * (a proxy for \"more specific\"); a final lexical comparison guarantees a total,\n * order-independent order for the residual case of equal-length content.\n */\nfunction compareSameSourceRules(a: PermissionRule, b: PermissionRule): number {\n\tconst aSpecific = a.ruleContent !== undefined;\n\tconst bSpecific = b.ruleContent !== undefined;\n\tif (aSpecific !== bSpecific) return aSpecific ? -1 : 1; // specific wins (negative = a first)\n\tif (!aSpecific) return 0; // both blanket at the same source: no further distinction needed\n\tconst lengthDelta = (b.ruleContent as string).length - (a.ruleContent as string).length;\n\tif (lengthDelta !== 0) return lengthDelta;\n\treturn (a.ruleContent as string).localeCompare(b.ruleContent as string);\n}\n\n/**\n * Resolve the effective behavior for one call. The highest-precedence *matching*\n * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.\n * With no matching rule, the tool's own `defaultBehavior` applies.\n */\nexport function resolvePermission<TParams extends TSchema>(\n\trules: readonly PermissionRule[],\n\ttoolName: string,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): PermissionResolution {\n\tlet winner: PermissionRule | undefined;\n\tfor (const candidate of rules) {\n\t\tif (candidate.toolName !== toolName) continue;\n\t\tif (!ruleMatchesCall(candidate, spec, params)) continue;\n\t\tif (!winner) {\n\t\t\twinner = candidate;\n\t\t\tcontinue;\n\t\t}\n\t\tconst candidateRank = SOURCE_RANK.get(candidate.source) ?? Number.POSITIVE_INFINITY;\n\t\tconst winnerRank = SOURCE_RANK.get(winner.source) ?? Number.POSITIVE_INFINITY;\n\t\tif (candidateRank < winnerRank) {\n\t\t\twinner = candidate;\n\t\t} else if (candidateRank === winnerRank && compareSameSourceRules(candidate, winner) < 0) {\n\t\t\twinner = candidate;\n\t\t}\n\t}\n\treturn winner\n\t\t? { behavior: winner.behavior, rule: winner }\n\t\t: { behavior: spec.defaultBehaviorFor?.(params) ?? spec.defaultBehavior };\n}\n"]}

package/dist/core/permissions/rules.js

@@ -21,8 +21,16 @@ export const PERMISSION_SOURCES = [
 ];
 const SOURCE_RANK = new Map(PERMISSION_SOURCES.map((source, index) => [source, index]));
 function ruleMatchesCall(rule, spec, params) {
+    if (spec.isUnknown?.(params)) {
+        if (rule.behavior === "allow")
+            return false;
+        if (rule.behavior === "deny")
+            return true;
+    }
     if (rule.ruleContent === undefined)
         return true;
+    if (rule.behavior === "deny")
+        return spec.matchesDeny?.(rule.ruleContent, params) ?? spec.matches(rule.ruleContent, params);
     return spec.matches(rule.ruleContent, params);
 }
 /**
@@ -69,6 +77,8 @@ export function resolvePermission(rules, toolName, spec, params) {
             winner = candidate;
         }
     }
-    return winner ? { behavior: winner.behavior, rule: winner } : { behavior: spec.defaultBehavior };
+    return winner
+        ? { behavior: winner.behavior, rule: winner }
+        : { behavior: spec.defaultBehaviorFor?.(params) ?? spec.defaultBehavior };
 }
 //# sourceMappingURL=rules.js.map

package/dist/core/permissions/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC,QAAQ;IACR,MAAM;IACN,OAAO;IACP,SAAS;IACT,MAAM;IACN,QAAQ;IACR,SAAS;IACT,SAAS;CACA,CAAC;AAkBX,MAAM,WAAW,GAAG,IAAI,GAAG,CAA2B,kBAAkB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAElH,SAAS,eAAe,CACvB,IAAoB,EACpB,IAA6B,EAC7B,MAAuB,EACb;IACV,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAAA,CAC9C;AAED;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,CAAiB,EAAE,CAAiB,EAAU;IAC7E,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC;IAC9C,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC;IAC9C,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,qCAAqC;IAC7F,IAAI,CAAC,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,iEAAiE;IAC3F,MAAM,WAAW,GAAI,CAAC,CAAC,WAAsB,CAAC,MAAM,GAAI,CAAC,CAAC,WAAsB,CAAC,MAAM,CAAC;IACxF,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IAC1C,OAAQ,CAAC,CAAC,WAAsB,CAAC,aAAa,CAAC,CAAC,CAAC,WAAqB,CAAC,CAAC;AAAA,CACxE;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAChC,KAAgC,EAChC,QAAgB,EAChB,IAA6B,EAC7B,MAAuB,EACA;IACvB,IAAI,MAAkC,CAAC;IACvC,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,QAAQ,KAAK,QAAQ;YAAE,SAAS;QAC9C,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC;YAAE,SAAS;QACxD,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,GAAG,SAAS,CAAC;YACnB,SAAS;QACV,CAAC;QACD,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,iBAAiB,CAAC;QACpF,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,iBAAiB,CAAC;QAC9E,IAAI,aAAa,GAAG,UAAU,EAAE,CAAC;YAChC,MAAM,GAAG,SAAS,CAAC;QACpB,CAAC;aAAM,IAAI,aAAa,KAAK,UAAU,IAAI,sBAAsB,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1F,MAAM,GAAG,SAAS,CAAC;QACpB,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC;AAAA,CACjG","sourcesContent":["/**\n * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never\n * inspects a `ruleContent` grammar itself — it only calls the tool's own\n * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions\n * of its grammar and the engine never accumulates tool-specific matching.\n */\n\nimport type { Static, TSchema } from \"typebox\";\nimport type { PermissionBehavior, PermissionSpec } from \"../tools/contract.ts\";\n\n/**\n * Highest to lowest precedence. `flag` outranks config because it is a deliberate\n * per-run operator override; `cliArg` sits below config because it is a per-run\n * *default*, not an override. See ADR 0004 for why each source sits where it does.\n */\nexport const PERMISSION_SOURCES = [\n\t\"policy\",\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"cliArg\",\n\t\"command\",\n\t\"session\",\n] as const;\n\nexport type PermissionSource = (typeof PERMISSION_SOURCES)[number];\n\nexport interface PermissionRule {\n\tsource: PermissionSource;\n\tbehavior: PermissionBehavior;\n\ttoolName: string;\n\t/** Undefined matches every call to this tool — a tool-wide rule. */\n\truleContent?: string;\n}\n\nexport interface PermissionResolution {\n\tbehavior: PermissionBehavior;\n\t/** The winning rule, or undefined when no rule matched and the tool's own default applied. */\n\trule?: PermissionRule;\n}\n\nconst SOURCE_RANK = new Map<PermissionSource, number>(PERMISSION_SOURCES.map((source, index) => [source, index]));\n\nfunction ruleMatchesCall<TParams extends TSchema>(\n\trule: PermissionRule,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): boolean {\n\tif (rule.ruleContent === undefined) return true;\n\treturn spec.matches(rule.ruleContent, params);\n}\n\n/**\n * Deterministic tie-break for two matching rules at the *same* source, independent\n * of array order: a rule with `ruleContent` (specific) outranks a tool-wide rule\n * with none (blanket); between two specific rules, the longer `ruleContent` wins\n * (a proxy for \"more specific\"); a final lexical comparison guarantees a total,\n * order-independent order for the residual case of equal-length content.\n */\nfunction compareSameSourceRules(a: PermissionRule, b: PermissionRule): number {\n\tconst aSpecific = a.ruleContent !== undefined;\n\tconst bSpecific = b.ruleContent !== undefined;\n\tif (aSpecific !== bSpecific) return aSpecific ? -1 : 1; // specific wins (negative = a first)\n\tif (!aSpecific) return 0; // both blanket at the same source: no further distinction needed\n\tconst lengthDelta = (b.ruleContent as string).length - (a.ruleContent as string).length;\n\tif (lengthDelta !== 0) return lengthDelta;\n\treturn (a.ruleContent as string).localeCompare(b.ruleContent as string);\n}\n\n/**\n * Resolve the effective behavior for one call. The highest-precedence *matching*\n * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.\n * With no matching rule, the tool's own `defaultBehavior` applies.\n */\nexport function resolvePermission<TParams extends TSchema>(\n\trules: readonly PermissionRule[],\n\ttoolName: string,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): PermissionResolution {\n\tlet winner: PermissionRule | undefined;\n\tfor (const candidate of rules) {\n\t\tif (candidate.toolName !== toolName) continue;\n\t\tif (!ruleMatchesCall(candidate, spec, params)) continue;\n\t\tif (!winner) {\n\t\t\twinner = candidate;\n\t\t\tcontinue;\n\t\t}\n\t\tconst candidateRank = SOURCE_RANK.get(candidate.source) ?? Number.POSITIVE_INFINITY;\n\t\tconst winnerRank = SOURCE_RANK.get(winner.source) ?? Number.POSITIVE_INFINITY;\n\t\tif (candidateRank < winnerRank) {\n\t\t\twinner = candidate;\n\t\t} else if (candidateRank === winnerRank && compareSameSourceRules(candidate, winner) < 0) {\n\t\t\twinner = candidate;\n\t\t}\n\t}\n\treturn winner ? { behavior: winner.behavior, rule: winner } : { behavior: spec.defaultBehavior };\n}\n"]}
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never\n * inspects a `ruleContent` grammar itself — it only calls the tool's own\n * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions\n * of its grammar and the engine never accumulates tool-specific matching.\n */\n\nimport type { Static, TSchema } from \"typebox\";\nimport type { PermissionBehavior, PermissionSpec } from \"../tools/contract.ts\";\n\n/**\n * Highest to lowest precedence. `flag` outranks config because it is a deliberate\n * per-run operator override; `cliArg` sits below config because it is a per-run\n * *default*, not an override. See ADR 0004 for why each source sits where it does.\n */\nexport const PERMISSION_SOURCES = [\n\t\"policy\",\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"cliArg\",\n\t\"command\",\n\t\"session\",\n] as const;\n\nexport type PermissionSource = (typeof PERMISSION_SOURCES)[number];\n\nexport interface PermissionRule {\n\tsource: PermissionSource;\n\tbehavior: PermissionBehavior;\n\ttoolName: string;\n\t/** Undefined matches every call to this tool — a tool-wide rule. */\n\truleContent?: string;\n}\n\nexport interface PermissionResolution {\n\tbehavior: PermissionBehavior;\n\t/** The winning rule, or undefined when no rule matched and the tool's own default applied. */\n\trule?: PermissionRule;\n}\n\nconst SOURCE_RANK = new Map<PermissionSource, number>(PERMISSION_SOURCES.map((source, index) => [source, index]));\n\nfunction ruleMatchesCall<TParams extends TSchema>(\n\trule: PermissionRule,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): boolean {\n\tif (spec.isUnknown?.(params)) {\n\t\tif (rule.behavior === \"allow\") return false;\n\t\tif (rule.behavior === \"deny\") return true;\n\t}\n\tif (rule.ruleContent === undefined) return true;\n\tif (rule.behavior === \"deny\")\n\t\treturn spec.matchesDeny?.(rule.ruleContent, params) ?? spec.matches(rule.ruleContent, params);\n\treturn spec.matches(rule.ruleContent, params);\n}\n\n/**\n * Deterministic tie-break for two matching rules at the *same* source, independent\n * of array order: a rule with `ruleContent` (specific) outranks a tool-wide rule\n * with none (blanket); between two specific rules, the longer `ruleContent` wins\n * (a proxy for \"more specific\"); a final lexical comparison guarantees a total,\n * order-independent order for the residual case of equal-length content.\n */\nfunction compareSameSourceRules(a: PermissionRule, b: PermissionRule): number {\n\tconst aSpecific = a.ruleContent !== undefined;\n\tconst bSpecific = b.ruleContent !== undefined;\n\tif (aSpecific !== bSpecific) return aSpecific ? -1 : 1; // specific wins (negative = a first)\n\tif (!aSpecific) return 0; // both blanket at the same source: no further distinction needed\n\tconst lengthDelta = (b.ruleContent as string).length - (a.ruleContent as string).length;\n\tif (lengthDelta !== 0) return lengthDelta;\n\treturn (a.ruleContent as string).localeCompare(b.ruleContent as string);\n}\n\n/**\n * Resolve the effective behavior for one call. The highest-precedence *matching*\n * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.\n * With no matching rule, the tool's own `defaultBehavior` applies.\n */\nexport function resolvePermission<TParams extends TSchema>(\n\trules: readonly PermissionRule[],\n\ttoolName: string,\n\tspec: PermissionSpec<TParams>,\n\tparams: Static<TParams>,\n): PermissionResolution {\n\tlet winner: PermissionRule | undefined;\n\tfor (const candidate of rules) {\n\t\tif (candidate.toolName !== toolName) continue;\n\t\tif (!ruleMatchesCall(candidate, spec, params)) continue;\n\t\tif (!winner) {\n\t\t\twinner = candidate;\n\t\t\tcontinue;\n\t\t}\n\t\tconst candidateRank = SOURCE_RANK.get(candidate.source) ?? Number.POSITIVE_INFINITY;\n\t\tconst winnerRank = SOURCE_RANK.get(winner.source) ?? Number.POSITIVE_INFINITY;\n\t\tif (candidateRank < winnerRank) {\n\t\t\twinner = candidate;\n\t\t} else if (candidateRank === winnerRank && compareSameSourceRules(candidate, winner) < 0) {\n\t\t\twinner = candidate;\n\t\t}\n\t}\n\treturn winner\n\t\t? { behavior: winner.behavior, rule: winner }\n\t\t: { behavior: spec.defaultBehaviorFor?.(params) ?? spec.defaultBehavior };\n}\n"]}

package/dist/core/permissions/store.d.ts

@@ -62,21 +62,39 @@ export interface CreateFilePermissionRuleStoreOptions {
     agentDir?: string;
     /** Overrides the managed policy file path. Defaults to $APEX_CODE_POLICY_PATH, else an OS-specific system location. */
     policyPath?: string;
+    /**
+     * The supervisor's captured host `policy` and `user` scopes. Defaults to
+     * $APEX_CODE_POLICY_SNAPSHOT_PATH, which only a sandbox supervisor sets. When present
+     * it replaces both `policyPath` and the `user` file for reading; `apply()` still
+     * writes a `user` update to this process's own agent directory, which is how an
+     * in-session approval persists without the child's copy becoming an authority source.
+     */
+    policySnapshotPath?: string;
     /** Test seam: inject backends for the three writable file-backed sources instead of touching real files. */
     backends?: Partial<Record<FileBackedSource, AuthStorageBackend>>;
     /** Immutable argv layers (`flag` / `cliArg`), validated by the CLI before construction. */
     initialRules?: readonly PermissionRule[];
+    /** Resolved before construction. False excludes both project-controlled scopes. */
+    projectTrusted?: boolean;
 }
 /** File-backed store for policy/local/project/user, in-memory for command/session. */
 export declare class FilePermissionRuleStore implements PermissionRuleStore {
     private readonly backends;
     private readonly policyPath;
+    private readonly policySnapshotPath?;
     private readonly initialRules;
     private readonly runtimeRules;
     private readonly runtimeModes;
+    private readonly projectTrusted;
+    private readonly fileScopes;
+    private snapshotScope?;
+    private readonly fileScopeUpdates;
     constructor(options: CreateFilePermissionRuleStoreOptions);
+    private capturedFileBackedScope;
     private readFileBackedScope;
     private readPolicy;
+    private readPolicySnapshot;
+    private capturedPolicyAndUser;
     snapshot(): Promise<PermissionStoreSnapshot>;
     apply(update: PermissionUpdate): Promise<void>;
     private applyRuntime;