apex-code 0.0.1-alpha.1 → 0.0.1-alpha.2

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

@@ -0,0 +1,35 @@
+/**
+ * The permission gate: composes rule resolution (rules.ts), mode overlay
+ * (modes.ts), and interactive escalation (responder.ts) into a single decision,
+ * and adapts that decision to the `beforeToolCall` seam `agent-core` already
+ * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.
+ *
+ * Tool execution has exactly one call site downstream of this hook
+ * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),
+ * so wiring this in once at session setup is sufficient for "every registered tool
+ * passes the gate" to be true by construction — the universal-gate test (invariant
+ * 2) verifies this property holds, it does not have to work to make it hold.
+ */
+import type { BeforeToolCallContext, BeforeToolCallResult } from "apex-code-agent-core";
+import { type ToolContract } from "../tools/contract.ts";
+import type { PermissionResponder } from "./responder.ts";
+import type { PermissionMode, PermissionRuleStore } from "./store.ts";
+export interface PermissionGateOptions {
+    /** Resolve a tool's contract by name. Foreign tools with no contract get UNCLASSIFIED, never rejected or silently defaulted (ADR 0010). */
+    getContract: (toolName: string) => ToolContract | undefined;
+    store: PermissionRuleStore;
+    getMode: () => PermissionMode | Promise<PermissionMode>;
+    /** Absent in a non-interactive session: an `ask` resolution then fails closed (deny). */
+    responder?: PermissionResponder;
+    /** Resolves a responder at call time because the interactive UI binds after session construction. */
+    getResponder?: () => PermissionResponder | undefined;
+}
+export interface GateDecision {
+    block: boolean;
+    reason?: string;
+}
+/** Pure decision function, independent of the beforeToolCall adapter shape below — the part under direct test. */
+export declare function evaluateToolCall(toolName: string, params: unknown, options: PermissionGateOptions): Promise<GateDecision>;
+/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */
+export declare function createPermissionGate(options: PermissionGateOptions): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+//# sourceMappingURL=gate.d.ts.map

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

@@ -0,0 +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,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/** 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"]}

package/dist/core/permissions/gate.js

@@ -0,0 +1,72 @@
+/**
+ * The permission gate: composes rule resolution (rules.ts), mode overlay
+ * (modes.ts), and interactive escalation (responder.ts) into a single decision,
+ * and adapts that decision to the `beforeToolCall` seam `agent-core` already
+ * exposes (packages/agent/src/agent-loop.ts). No new hook, no agent-core change.
+ *
+ * Tool execution has exactly one call site downstream of this hook
+ * (`executePreparedToolCall`, fed only by the function that runs `beforeToolCall`),
+ * so wiring this in once at session setup is sufficient for "every registered tool
+ * passes the gate" to be true by construction — the universal-gate test (invariant
+ * 2) verifies this property holds, it does not have to work to make it hold.
+ */
+import { resolveToolContract } from "../tools/contract.js";
+import { resolveWithMode } from "./modes.js";
+import { resolvePermission } from "./rules.js";
+function describeDecision(contract, toolName, ruleContent) {
+    if (ruleContent !== undefined)
+        return contract.permission.describe(ruleContent);
+    return `${toolName} is not permitted by the current permission configuration.`;
+}
+/** 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;
+    const snapshot = await options.store.snapshot();
+    if (snapshot.errors.length > 0) {
+        const sources = [...new Set(snapshot.errors.map((entry) => entry.source))].join(", ");
+        return {
+            block: true,
+            reason: `Permission configuration could not be loaded (${sources}); refusing to run ${toolName}.`,
+        };
+    }
+    const ruleResolution = resolvePermission(snapshot.rules, toolName, spec, params);
+    const resolution = resolveWithMode(await options.getMode(), ruleResolution, contract.capabilities);
+    if (resolution.behavior === "allow")
+        return { block: false };
+    if (resolution.behavior === "deny") {
+        return { block: true, reason: describeDecision(contract, toolName, resolution.rule?.ruleContent) };
+    }
+    // ask
+    const responder = options.getResponder?.() ?? options.responder;
+    if (!responder) {
+        return {
+            block: true,
+            reason: `${toolName} requires approval, and no responder is available in this session.`,
+        };
+    }
+    const ruleForCall = spec.ruleForCall(params);
+    const answer = await responder.ask({
+        toolName,
+        description: ruleForCall !== null ? spec.describe(ruleForCall) : `Run ${toolName}`,
+    });
+    if (!answer.allow) {
+        return { block: true, reason: `${toolName} was declined.` };
+    }
+    if (answer.persist && ruleForCall !== null) {
+        await options.store.apply({
+            type: "addRules",
+            destination: "session",
+            rules: [{ toolName, behavior: "allow", ruleContent: ruleForCall }],
+        });
+    }
+    return { block: false };
+}
+/** Adapts evaluateToolCall() to the beforeToolCall seam agent-core already exposes. */
+export function createPermissionGate(options) {
+    return async ({ toolCall, args }) => {
+        const decision = await evaluateToolCall(toolCall.name, args, options);
+        return decision.block ? { block: true, reason: decision.reason } : undefined;
+    };
+}
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/core/permissions/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,mBAAmB,EAAqB,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmB/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,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,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,QAAQ;QACR,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE;KAClF,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,gBAAgB,EAAE,CAAC;IAC7D,CAAC;IACD,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,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;SAClE,CAAC,CAAC;IACJ,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 { 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/** 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"]}

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

@@ -0,0 +1,18 @@
+/**
+ * Permission modes (roadmap Phase 2a). A mode is a resolution layer applied on top
+ * of `resolvePermission()`'s rule-based result, driven entirely by a tool's
+ * declared `capabilities` — never by tool name, so a mode behaves correctly for a
+ * tool that does not exist yet.
+ *
+ * `plan` and `bypassPermissions` are absolute: they override even an explicit
+ * matching rule, because that is their entire purpose (a hard safety floor, and an
+ * explicit "trust everything" escape hatch, respectively). `acceptEdits` and
+ * `dontAsk` are conveniences that only ever act on the *absence* of an explicit
+ * rule — they change what a bare tool default resolves to, but never overrule a
+ * rule the user actually set.
+ */
+import type { Capability } from "../tools/contract.ts";
+import type { PermissionResolution } from "./rules.ts";
+import type { PermissionMode } from "./store.ts";
+export declare function resolveWithMode(mode: PermissionMode, ruleResolution: PermissionResolution, capabilities: ReadonlySet<Capability>): PermissionResolution;
+//# sourceMappingURL=modes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyBjD,wBAAgB,eAAe,CAC9B,IAAI,EAAE,cAAc,EACpB,cAAc,EAAE,oBAAoB,EACpC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,GACnC,oBAAoB,CAwBtB","sourcesContent":["/**\n * Permission modes (roadmap Phase 2a). A mode is a resolution layer applied on top\n * of `resolvePermission()`'s rule-based result, driven entirely by a tool's\n * declared `capabilities` — never by tool name, so a mode behaves correctly for a\n * tool that does not exist yet.\n *\n * `plan` and `bypassPermissions` are absolute: they override even an explicit\n * matching rule, because that is their entire purpose (a hard safety floor, and an\n * explicit \"trust everything\" escape hatch, respectively). `acceptEdits` and\n * `dontAsk` are conveniences that only ever act on the *absence* of an explicit\n * rule — they change what a bare tool default resolves to, but never overrule a\n * rule the user actually set.\n */\n\nimport type { Capability } from \"../tools/contract.ts\";\nimport type { PermissionResolution } from \"./rules.ts\";\nimport type { PermissionMode } from \"./store.ts\";\n\n/**\n * Plan mode's hard floor. `state` is deliberately excluded: an explicit harness-state\n * tool such as `todo_write` is how plan mode maintains the plan it is presenting, so\n * denying it outright would make plan mode unable to do its own job (spec\n * `2026-08-13-tool-surface.md`, \"The problem\" item 4).\n */\nconst PLAN_MODE_DENIED_CAPABILITIES: readonly Capability[] = [\"fs.write\", \"exec\", \"delegate\"];\n\nfunction isPlanModeDenied(capabilities: ReadonlySet<Capability>): boolean {\n\treturn PLAN_MODE_DENIED_CAPABILITIES.some((capability) => capabilities.has(capability));\n}\n\n/** fs.write only, with no exec/net/delegate/state — the shape acceptEdits auto-allows. */\nfunction isEditShaped(capabilities: ReadonlySet<Capability>): boolean {\n\treturn (\n\t\tcapabilities.has(\"fs.write\") &&\n\t\t!capabilities.has(\"exec\") &&\n\t\t!capabilities.has(\"net\") &&\n\t\t!capabilities.has(\"delegate\") &&\n\t\t!capabilities.has(\"state\")\n\t);\n}\n\nexport function resolveWithMode(\n\tmode: PermissionMode,\n\truleResolution: PermissionResolution,\n\tcapabilities: ReadonlySet<Capability>,\n): PermissionResolution {\n\t// Plan mode is a hard mutating safety floor. Managed policy is otherwise\n\t// explicitly non-overridable (ADR 0004); bypass remains an escape hatch only\n\t// for lower-precedence sources.\n\tif (mode === \"plan\" && isPlanModeDenied(capabilities)) {\n\t\treturn { behavior: \"deny\" };\n\t}\n\tif (ruleResolution.rule?.source === \"policy\") {\n\t\treturn ruleResolution;\n\t}\n\tif (mode === \"bypassPermissions\") {\n\t\treturn { behavior: \"allow\" };\n\t}\n\tif (ruleResolution.rule) {\n\t\t// An explicit matching rule is authoritative for every remaining mode.\n\t\treturn ruleResolution;\n\t}\n\tif (mode === \"dontAsk\" && ruleResolution.behavior === \"ask\") {\n\t\treturn { behavior: \"deny\" };\n\t}\n\tif (mode === \"acceptEdits\" && ruleResolution.behavior === \"ask\" && isEditShaped(capabilities)) {\n\t\treturn { behavior: \"allow\" };\n\t}\n\treturn ruleResolution;\n}\n"]}

package/dist/core/permissions/modes.js

@@ -0,0 +1,57 @@
+/**
+ * Permission modes (roadmap Phase 2a). A mode is a resolution layer applied on top
+ * of `resolvePermission()`'s rule-based result, driven entirely by a tool's
+ * declared `capabilities` — never by tool name, so a mode behaves correctly for a
+ * tool that does not exist yet.
+ *
+ * `plan` and `bypassPermissions` are absolute: they override even an explicit
+ * matching rule, because that is their entire purpose (a hard safety floor, and an
+ * explicit "trust everything" escape hatch, respectively). `acceptEdits` and
+ * `dontAsk` are conveniences that only ever act on the *absence* of an explicit
+ * rule — they change what a bare tool default resolves to, but never overrule a
+ * rule the user actually set.
+ */
+/**
+ * Plan mode's hard floor. `state` is deliberately excluded: an explicit harness-state
+ * tool such as `todo_write` is how plan mode maintains the plan it is presenting, so
+ * denying it outright would make plan mode unable to do its own job (spec
+ * `2026-08-13-tool-surface.md`, "The problem" item 4).
+ */
+const PLAN_MODE_DENIED_CAPABILITIES = ["fs.write", "exec", "delegate"];
+function isPlanModeDenied(capabilities) {
+    return PLAN_MODE_DENIED_CAPABILITIES.some((capability) => capabilities.has(capability));
+}
+/** fs.write only, with no exec/net/delegate/state — the shape acceptEdits auto-allows. */
+function isEditShaped(capabilities) {
+    return (capabilities.has("fs.write") &&
+        !capabilities.has("exec") &&
+        !capabilities.has("net") &&
+        !capabilities.has("delegate") &&
+        !capabilities.has("state"));
+}
+export function resolveWithMode(mode, ruleResolution, capabilities) {
+    // Plan mode is a hard mutating safety floor. Managed policy is otherwise
+    // explicitly non-overridable (ADR 0004); bypass remains an escape hatch only
+    // for lower-precedence sources.
+    if (mode === "plan" && isPlanModeDenied(capabilities)) {
+        return { behavior: "deny" };
+    }
+    if (ruleResolution.rule?.source === "policy") {
+        return ruleResolution;
+    }
+    if (mode === "bypassPermissions") {
+        return { behavior: "allow" };
+    }
+    if (ruleResolution.rule) {
+        // An explicit matching rule is authoritative for every remaining mode.
+        return ruleResolution;
+    }
+    if (mode === "dontAsk" && ruleResolution.behavior === "ask") {
+        return { behavior: "deny" };
+    }
+    if (mode === "acceptEdits" && ruleResolution.behavior === "ask" && isEditShaped(capabilities)) {
+        return { behavior: "allow" };
+    }
+    return ruleResolution;
+}
+//# sourceMappingURL=modes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modes.js","sourceRoot":"","sources":["../../../src/core/permissions/modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;;;GAKG;AACH,MAAM,6BAA6B,GAA0B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;AAE9F,SAAS,gBAAgB,CAAC,YAAqC,EAAW;IACzE,OAAO,6BAA6B,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;AAAA,CACxF;AAED,4FAA0F;AAC1F,SAAS,YAAY,CAAC,YAAqC,EAAW;IACrE,OAAO,CACN,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;QAC5B,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;QACzB,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QACxB,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;QAC7B,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAC1B,CAAC;AAAA,CACF;AAED,MAAM,UAAU,eAAe,CAC9B,IAAoB,EACpB,cAAoC,EACpC,YAAqC,EACd;IACvB,yEAAyE;IACzE,6EAA6E;IAC7E,gCAAgC;IAChC,IAAI,IAAI,KAAK,MAAM,IAAI,gBAAgB,CAAC,YAAY,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;QAClC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,EAAE,CAAC;QACzB,uEAAuE;QACvE,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IACD,IAAI,IAAI,KAAK,aAAa,IAAI,cAAc,CAAC,QAAQ,KAAK,KAAK,IAAI,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,cAAc,CAAC;AAAA,CACtB","sourcesContent":["/**\n * Permission modes (roadmap Phase 2a). A mode is a resolution layer applied on top\n * of `resolvePermission()`'s rule-based result, driven entirely by a tool's\n * declared `capabilities` — never by tool name, so a mode behaves correctly for a\n * tool that does not exist yet.\n *\n * `plan` and `bypassPermissions` are absolute: they override even an explicit\n * matching rule, because that is their entire purpose (a hard safety floor, and an\n * explicit \"trust everything\" escape hatch, respectively). `acceptEdits` and\n * `dontAsk` are conveniences that only ever act on the *absence* of an explicit\n * rule — they change what a bare tool default resolves to, but never overrule a\n * rule the user actually set.\n */\n\nimport type { Capability } from \"../tools/contract.ts\";\nimport type { PermissionResolution } from \"./rules.ts\";\nimport type { PermissionMode } from \"./store.ts\";\n\n/**\n * Plan mode's hard floor. `state` is deliberately excluded: an explicit harness-state\n * tool such as `todo_write` is how plan mode maintains the plan it is presenting, so\n * denying it outright would make plan mode unable to do its own job (spec\n * `2026-08-13-tool-surface.md`, \"The problem\" item 4).\n */\nconst PLAN_MODE_DENIED_CAPABILITIES: readonly Capability[] = [\"fs.write\", \"exec\", \"delegate\"];\n\nfunction isPlanModeDenied(capabilities: ReadonlySet<Capability>): boolean {\n\treturn PLAN_MODE_DENIED_CAPABILITIES.some((capability) => capabilities.has(capability));\n}\n\n/** fs.write only, with no exec/net/delegate/state — the shape acceptEdits auto-allows. */\nfunction isEditShaped(capabilities: ReadonlySet<Capability>): boolean {\n\treturn (\n\t\tcapabilities.has(\"fs.write\") &&\n\t\t!capabilities.has(\"exec\") &&\n\t\t!capabilities.has(\"net\") &&\n\t\t!capabilities.has(\"delegate\") &&\n\t\t!capabilities.has(\"state\")\n\t);\n}\n\nexport function resolveWithMode(\n\tmode: PermissionMode,\n\truleResolution: PermissionResolution,\n\tcapabilities: ReadonlySet<Capability>,\n): PermissionResolution {\n\t// Plan mode is a hard mutating safety floor. Managed policy is otherwise\n\t// explicitly non-overridable (ADR 0004); bypass remains an escape hatch only\n\t// for lower-precedence sources.\n\tif (mode === \"plan\" && isPlanModeDenied(capabilities)) {\n\t\treturn { behavior: \"deny\" };\n\t}\n\tif (ruleResolution.rule?.source === \"policy\") {\n\t\treturn ruleResolution;\n\t}\n\tif (mode === \"bypassPermissions\") {\n\t\treturn { behavior: \"allow\" };\n\t}\n\tif (ruleResolution.rule) {\n\t\t// An explicit matching rule is authoritative for every remaining mode.\n\t\treturn ruleResolution;\n\t}\n\tif (mode === \"dontAsk\" && ruleResolution.behavior === \"ask\") {\n\t\treturn { behavior: \"deny\" };\n\t}\n\tif (mode === \"acceptEdits\" && ruleResolution.behavior === \"ask\" && isEditShaped(capabilities)) {\n\t\treturn { behavior: \"allow\" };\n\t}\n\treturn ruleResolution;\n}\n"]}

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

@@ -0,0 +1,30 @@
+/** Interactive escalation for an `ask`-resolved permission decision. */
+export interface PermissionAskRequest {
+    toolName: string;
+    /** Human-readable rendering of what would be persisted, from the tool's own describe(). */
+    description: string;
+}
+export interface PermissionAnswer {
+    allow: boolean;
+    /** "Always allow this" — persist a session-source rule via the tool's own ruleForCall(). */
+    persist?: boolean;
+}
+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>;
+}
+/**
+ * Builds a PermissionResponder over the same live, mid-session prompt primitive
+ * extensions already use (ExtensionUIContext.select) — no new rendering
+ * dependency, per the roadmap's "Explicitly not building" a second TUI stack.
+ *
+ * Deliberately answers only `{allow, persist}`. It never constructs a rule string
+ * itself: generating one from `ruleForCall()` and persisting it is the gate's job
+ * (permissions/gate.ts), so the tool that owns the grammar is the only thing that
+ * ever writes a rule (ADR 0010).
+ */
+export declare function createInteractiveResponder(ui: SelectUI): PermissionResponder;
+//# sourceMappingURL=responder.d.ts.map

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

@@ -0,0 +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"]}

package/dist/core/permissions/responder.js

@@ -0,0 +1,32 @@
+/** Interactive escalation for an `ask`-resolved permission decision. */
+const ALLOW_ONCE = "Allow once";
+const ALWAYS_ALLOW = "Always allow";
+const DENY = "Deny";
+/**
+ * Builds a PermissionResponder over the same live, mid-session prompt primitive
+ * extensions already use (ExtensionUIContext.select) — no new rendering
+ * dependency, per the roadmap's "Explicitly not building" a second TUI stack.
+ *
+ * Deliberately answers only `{allow, persist}`. It never constructs a rule string
+ * itself: generating one from `ruleForCall()` and persisting it is the gate's job
+ * (permissions/gate.ts), so the tool that owns the grammar is the only thing that
+ * ever writes a rule (ADR 0010).
+ */
+export function createInteractiveResponder(ui) {
+    return {
+        async ask({ toolName, description }) {
+            const choice = await ui.select(`Permission required — ${toolName}: ${description}`, [
+                ALLOW_ONCE,
+                ALWAYS_ALLOW,
+                DENY,
+            ]);
+            if (choice === ALLOW_ONCE)
+                return { allow: true };
+            if (choice === ALWAYS_ALLOW)
+                return { allow: true, persist: true };
+            // DENY, or no selection (cancelled/dismissed) — fail closed.
+            return { allow: false };
+        },
+    };
+}
+//# sourceMappingURL=responder.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,34 @@
+/**
+ * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never
+ * inspects a `ruleContent` grammar itself — it only calls the tool's own
+ * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions
+ * of its grammar and the engine never accumulates tool-specific matching.
+ */
+import type { Static, TSchema } from "typebox";
+import type { PermissionBehavior, PermissionSpec } from "../tools/contract.ts";
+/**
+ * Highest to lowest precedence. `flag` outranks config because it is a deliberate
+ * per-run operator override; `cliArg` sits below config because it is a per-run
+ * *default*, not an override. See ADR 0004 for why each source sits where it does.
+ */
+export declare const PERMISSION_SOURCES: readonly ["policy", "flag", "local", "project", "user", "cliArg", "command", "session"];
+export type PermissionSource = (typeof PERMISSION_SOURCES)[number];
+export interface PermissionRule {
+    source: PermissionSource;
+    behavior: PermissionBehavior;
+    toolName: string;
+    /** Undefined matches every call to this tool — a tool-wide rule. */
+    ruleContent?: string;
+}
+export interface PermissionResolution {
+    behavior: PermissionBehavior;
+    /** The winning rule, or undefined when no rule matched and the tool's own default applied. */
+    rule?: PermissionRule;
+}
+/**
+ * Resolve the effective behavior for one call. The highest-precedence *matching*
+ * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.
+ * With no matching rule, the tool's own `defaultBehavior` applies.
+ */
+export declare function resolvePermission<TParams extends TSchema>(rules: readonly PermissionRule[], toolName: string, spec: PermissionSpec<TParams>, params: Static<TParams>): PermissionResolution;
+//# sourceMappingURL=rules.d.ts.map

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

@@ -0,0 +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"]}

package/dist/core/permissions/rules.js

@@ -0,0 +1,74 @@
+/**
+ * The permission rule model (ADR 0004). Pure and tool-agnostic: this module never
+ * inspects a `ruleContent` grammar itself — it only calls the tool's own
+ * `PermissionSpec.matches()`, per ADR 0010's rule that a tool owns both directions
+ * of its grammar and the engine never accumulates tool-specific matching.
+ */
+/**
+ * Highest to lowest precedence. `flag` outranks config because it is a deliberate
+ * per-run operator override; `cliArg` sits below config because it is a per-run
+ * *default*, not an override. See ADR 0004 for why each source sits where it does.
+ */
+export const PERMISSION_SOURCES = [
+    "policy",
+    "flag",
+    "local",
+    "project",
+    "user",
+    "cliArg",
+    "command",
+    "session",
+];
+const SOURCE_RANK = new Map(PERMISSION_SOURCES.map((source, index) => [source, index]));
+function ruleMatchesCall(rule, spec, params) {
+    if (rule.ruleContent === undefined)
+        return true;
+    return spec.matches(rule.ruleContent, params);
+}
+/**
+ * Deterministic tie-break for two matching rules at the *same* source, independent
+ * of array order: a rule with `ruleContent` (specific) outranks a tool-wide rule
+ * with none (blanket); between two specific rules, the longer `ruleContent` wins
+ * (a proxy for "more specific"); a final lexical comparison guarantees a total,
+ * order-independent order for the residual case of equal-length content.
+ */
+function compareSameSourceRules(a, b) {
+    const aSpecific = a.ruleContent !== undefined;
+    const bSpecific = b.ruleContent !== undefined;
+    if (aSpecific !== bSpecific)
+        return aSpecific ? -1 : 1; // specific wins (negative = a first)
+    if (!aSpecific)
+        return 0; // both blanket at the same source: no further distinction needed
+    const lengthDelta = b.ruleContent.length - a.ruleContent.length;
+    if (lengthDelta !== 0)
+        return lengthDelta;
+    return a.ruleContent.localeCompare(b.ruleContent);
+}
+/**
+ * Resolve the effective behavior for one call. The highest-precedence *matching*
+ * rule wins, whatever its behavior — `deny` does not automatically outrank `allow`.
+ * With no matching rule, the tool's own `defaultBehavior` applies.
+ */
+export function resolvePermission(rules, toolName, spec, params) {
+    let winner;
+    for (const candidate of rules) {
+        if (candidate.toolName !== toolName)
+            continue;
+        if (!ruleMatchesCall(candidate, spec, params))
+            continue;
+        if (!winner) {
+            winner = candidate;
+            continue;
+        }
+        const candidateRank = SOURCE_RANK.get(candidate.source) ?? Number.POSITIVE_INFINITY;
+        const winnerRank = SOURCE_RANK.get(winner.source) ?? Number.POSITIVE_INFINITY;
+        if (candidateRank < winnerRank) {
+            winner = candidate;
+        }
+        else if (candidateRank === winnerRank && compareSameSourceRules(candidate, winner) < 0) {
+            winner = candidate;
+        }
+    }
+    return winner ? { behavior: winner.behavior, rule: winner } : { behavior: spec.defaultBehavior };
+}
+//# sourceMappingURL=rules.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,33 @@
+/**
+ * Startup-time permission mode resolution (ADR 0004). A misconfigured
+ * non-interactive run should fail fast, at startup, with an actionable message —
+ * not deny every tool call mid-run in a way that looks like a bug (see the ADR's
+ * "ask fails closed, and a session that cannot ask refuses to start").
+ */
+import { type PermissionMode, type WritablePermissionSource } from "./store.ts";
+export type PermissionModeStartupResult = {
+    ok: true;
+    mode: PermissionMode;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * `requestedMode` is assumed already validated against `PERMISSION_MODES` (args.ts
+ * rejects an unknown value at parse time) — this only decides whether a session may
+ * start *without* one. Interactive sessions may: an `ask` there has a human to
+ * resolve it. Non-interactive sessions may not: with no responder, `ask` fails
+ * closed to `deny`, and discovering that per-call, mid-run, is the exact bad
+ * failure mode this check exists to avoid.
+ */
+export declare function resolvePermissionModeForStartup(options: {
+    interactive: boolean;
+    requestedMode: PermissionMode | undefined;
+}): PermissionModeStartupResult;
+/**
+ * The `--permission-mode` flag outranks every persisted mode, including a project
+ * rule a team committed — a deliberate per-run operator decision should not be
+ * silently overridden by checked-in config (ADR 0004).
+ */
+export declare function resolveEffectiveMode(flagMode: PermissionMode | undefined, modesBySource: ReadonlyMap<WritablePermissionSource, PermissionMode>): PermissionMode;
+//# sourceMappingURL=startup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/startup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAoB,KAAK,cAAc,EAAE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAElG,MAAM,MAAM,2BAA2B,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9G;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACxD,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC;CAC1C,GAAG,2BAA2B,CAW9B;AAYD;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,aAAa,EAAE,WAAW,CAAC,wBAAwB,EAAE,cAAc,CAAC,GAClE,cAAc,CAUhB","sourcesContent":["/**\n * Startup-time permission mode resolution (ADR 0004). A misconfigured\n * non-interactive run should fail fast, at startup, with an actionable message —\n * not deny every tool call mid-run in a way that looks like a bug (see the ADR's\n * \"ask fails closed, and a session that cannot ask refuses to start\").\n */\n\nimport { PERMISSION_MODES, type PermissionMode, type WritablePermissionSource } from \"./store.ts\";\n\nexport type PermissionModeStartupResult = { ok: true; mode: PermissionMode } | { ok: false; message: string };\n\n/**\n * `requestedMode` is assumed already validated against `PERMISSION_MODES` (args.ts\n * rejects an unknown value at parse time) — this only decides whether a session may\n * start *without* one. Interactive sessions may: an `ask` there has a human to\n * resolve it. Non-interactive sessions may not: with no responder, `ask` fails\n * closed to `deny`, and discovering that per-call, mid-run, is the exact bad\n * failure mode this check exists to avoid.\n */\nexport function resolvePermissionModeForStartup(options: {\n\tinteractive: boolean;\n\trequestedMode: PermissionMode | undefined;\n}): PermissionModeStartupResult {\n\tif (options.requestedMode !== undefined) {\n\t\treturn { ok: true, mode: options.requestedMode };\n\t}\n\tif (!options.interactive) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `Non-interactive sessions require an explicit --permission-mode. Valid modes: ${PERMISSION_MODES.join(\", \")}.`,\n\t\t};\n\t}\n\treturn { ok: true, mode: \"default\" };\n}\n\n/** Sources a mode can come from, in precedence order — mirrors PERMISSION_SOURCES (rules.ts), restricted to the sources that can plausibly set one. */\nconst MODE_SOURCE_ORDER: readonly [\"flag\", ...WritablePermissionSource[]] = [\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"command\",\n\t\"session\",\n];\n\n/**\n * The `--permission-mode` flag outranks every persisted mode, including a project\n * rule a team committed — a deliberate per-run operator decision should not be\n * silently overridden by checked-in config (ADR 0004).\n */\nexport function resolveEffectiveMode(\n\tflagMode: PermissionMode | undefined,\n\tmodesBySource: ReadonlyMap<WritablePermissionSource, PermissionMode>,\n): PermissionMode {\n\tfor (const source of MODE_SOURCE_ORDER) {\n\t\tif (source === \"flag\") {\n\t\t\tif (flagMode !== undefined) return flagMode;\n\t\t\tcontinue;\n\t\t}\n\t\tconst mode = modesBySource.get(source);\n\t\tif (mode !== undefined) return mode;\n\t}\n\treturn \"default\";\n}\n"]}

package/dist/core/permissions/startup.js

@@ -0,0 +1,55 @@
+/**
+ * Startup-time permission mode resolution (ADR 0004). A misconfigured
+ * non-interactive run should fail fast, at startup, with an actionable message —
+ * not deny every tool call mid-run in a way that looks like a bug (see the ADR's
+ * "ask fails closed, and a session that cannot ask refuses to start").
+ */
+import { PERMISSION_MODES } from "./store.js";
+/**
+ * `requestedMode` is assumed already validated against `PERMISSION_MODES` (args.ts
+ * rejects an unknown value at parse time) — this only decides whether a session may
+ * start *without* one. Interactive sessions may: an `ask` there has a human to
+ * resolve it. Non-interactive sessions may not: with no responder, `ask` fails
+ * closed to `deny`, and discovering that per-call, mid-run, is the exact bad
+ * failure mode this check exists to avoid.
+ */
+export function resolvePermissionModeForStartup(options) {
+    if (options.requestedMode !== undefined) {
+        return { ok: true, mode: options.requestedMode };
+    }
+    if (!options.interactive) {
+        return {
+            ok: false,
+            message: `Non-interactive sessions require an explicit --permission-mode. Valid modes: ${PERMISSION_MODES.join(", ")}.`,
+        };
+    }
+    return { ok: true, mode: "default" };
+}
+/** Sources a mode can come from, in precedence order — mirrors PERMISSION_SOURCES (rules.ts), restricted to the sources that can plausibly set one. */
+const MODE_SOURCE_ORDER = [
+    "flag",
+    "local",
+    "project",
+    "user",
+    "command",
+    "session",
+];
+/**
+ * The `--permission-mode` flag outranks every persisted mode, including a project
+ * rule a team committed — a deliberate per-run operator decision should not be
+ * silently overridden by checked-in config (ADR 0004).
+ */
+export function resolveEffectiveMode(flagMode, modesBySource) {
+    for (const source of MODE_SOURCE_ORDER) {
+        if (source === "flag") {
+            if (flagMode !== undefined)
+                return flagMode;
+            continue;
+        }
+        const mode = modesBySource.get(source);
+        if (mode !== undefined)
+            return mode;
+    }
+    return "default";
+}
+//# sourceMappingURL=startup.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"startup.js","sourceRoot":"","sources":["../../../src/core/permissions/startup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAsD,MAAM,YAAY,CAAC;AAIlG;;;;;;;GAOG;AACH,MAAM,UAAU,+BAA+B,CAAC,OAG/C,EAA+B;IAC/B,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC1B,OAAO;YACN,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,gFAAgF,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SACvH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAAA,CACrC;AAED,yJAAuJ;AACvJ,MAAM,iBAAiB,GAAqD;IAC3E,MAAM;IACN,OAAO;IACP,SAAS;IACT,MAAM;IACN,SAAS;IACT,SAAS;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAoC,EACpC,aAAoE,EACnD;IACjB,KAAK,MAAM,MAAM,IAAI,iBAAiB,EAAE,CAAC;QACxC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACvB,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,QAAQ,CAAC;YAC5C,SAAS;QACV,CAAC;QACD,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IACrC,CAAC;IACD,OAAO,SAAS,CAAC;AAAA,CACjB","sourcesContent":["/**\n * Startup-time permission mode resolution (ADR 0004). A misconfigured\n * non-interactive run should fail fast, at startup, with an actionable message —\n * not deny every tool call mid-run in a way that looks like a bug (see the ADR's\n * \"ask fails closed, and a session that cannot ask refuses to start\").\n */\n\nimport { PERMISSION_MODES, type PermissionMode, type WritablePermissionSource } from \"./store.ts\";\n\nexport type PermissionModeStartupResult = { ok: true; mode: PermissionMode } | { ok: false; message: string };\n\n/**\n * `requestedMode` is assumed already validated against `PERMISSION_MODES` (args.ts\n * rejects an unknown value at parse time) — this only decides whether a session may\n * start *without* one. Interactive sessions may: an `ask` there has a human to\n * resolve it. Non-interactive sessions may not: with no responder, `ask` fails\n * closed to `deny`, and discovering that per-call, mid-run, is the exact bad\n * failure mode this check exists to avoid.\n */\nexport function resolvePermissionModeForStartup(options: {\n\tinteractive: boolean;\n\trequestedMode: PermissionMode | undefined;\n}): PermissionModeStartupResult {\n\tif (options.requestedMode !== undefined) {\n\t\treturn { ok: true, mode: options.requestedMode };\n\t}\n\tif (!options.interactive) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `Non-interactive sessions require an explicit --permission-mode. Valid modes: ${PERMISSION_MODES.join(\", \")}.`,\n\t\t};\n\t}\n\treturn { ok: true, mode: \"default\" };\n}\n\n/** Sources a mode can come from, in precedence order — mirrors PERMISSION_SOURCES (rules.ts), restricted to the sources that can plausibly set one. */\nconst MODE_SOURCE_ORDER: readonly [\"flag\", ...WritablePermissionSource[]] = [\n\t\"flag\",\n\t\"local\",\n\t\"project\",\n\t\"user\",\n\t\"command\",\n\t\"session\",\n];\n\n/**\n * The `--permission-mode` flag outranks every persisted mode, including a project\n * rule a team committed — a deliberate per-run operator decision should not be\n * silently overridden by checked-in config (ADR 0004).\n */\nexport function resolveEffectiveMode(\n\tflagMode: PermissionMode | undefined,\n\tmodesBySource: ReadonlyMap<WritablePermissionSource, PermissionMode>,\n): PermissionMode {\n\tfor (const source of MODE_SOURCE_ORDER) {\n\t\tif (source === \"flag\") {\n\t\t\tif (flagMode !== undefined) return flagMode;\n\t\t\tcontinue;\n\t\t}\n\t\tconst mode = modesBySource.get(source);\n\t\tif (mode !== undefined) return mode;\n\t}\n\treturn \"default\";\n}\n"]}