@chances-ai/engine 24.0.0

package/dist/tools/permission.d.ts

@@ -0,0 +1,120 @@
+import type { PermissionPolicy, ToolCategory } from "@chances-ai/runtime/config";
+import type { ApprovalMode } from "@chances-ai/runtime";
+import type { AuthorizationRequest, PermissionResolver, QuestionDecision, QuestionRequest } from "./types.js";
+/**
+ * (5.3) The full result of a permission check. `check()` returns just `allow`
+ * for backwards-compatible callers; `evaluate()` returns this so the engine can
+ * surface a precise reason (plan-mode block, deny-with-feedback) in the tool
+ * result.
+ */
+export interface PermissionEvaluation {
+    allow: boolean;
+    /** Why it was denied (or mode-allowed); surfaced in the tool result. */
+    reason?: string;
+    /** Which layer decided. `mode` = the session approval mode forced it. */
+    source?: "policy" | "mode" | "resolver";
+    /** Deny-with-feedback: free text the user wants relayed to the model. */
+    feedback?: string;
+}
+/**
+ * Chain of responsibility for a tool invocation:
+ *   per-tool rule -> category default -> (prompt|host-bridged) -> resolver.
+ * `allow` short-circuits true, `deny` short-circuits false, the rest delegate
+ * to the resolver (which is the interactive prompt, or an auto-policy in -p mode).
+ *
+ * **Session positive-decision cache.** Once the resolver returns `true` for a
+ * tool name with a `prompt`-category default, subsequent checks of the same
+ * tool name skip the resolver for the rest of this `PermissionGate`'s
+ * lifetime. This is scoped to MCP-bridged names (`mcp__*`) by default — the
+ * `cacheScope` predicate is overridable for tests and future expansion. The
+ * cache only stores positives; a `false` from the resolver always re-prompts
+ * (so a user who initially says "no" doesn't get silently locked out when
+ * they want to reconsider).
+ *
+ * Rationale: a freshly-added MCP server typically exposes 5–30 tools. Without
+ * a cache, the user is re-prompted on every single call for every single
+ * tool — claude-code and oh-my-pi both cache, and the trust signal is the
+ * user's act of adding the server to config in the first place. Per-tool
+ * explicit `deny` in `policy.tools` still wins (we check that first).
+ */
+export type PermissionCacheScope = (req: AuthorizationRequest) => boolean;
+export declare class PermissionGate {
+    private readonly policy;
+    private readonly resolver;
+    private readonly cacheScope;
+    private readonly getMode;
+    private readonly allowCache;
+    /**
+     * Promise chain that serialises every resolver invocation across the gate.
+     * Without this, two concurrent tool calls (e.g. parent's sync tool +
+     * background child's tool, post-3.4) both reach `this.resolver(...)`,
+     * and the TUI's view-model has exactly one `pending` slot — the second
+     * request overwrites the first, orphaning the first promise. Codex
+     * Round-1 MUST-FIX #1.
+     *
+     * The chain only wraps the actual resolver call: every fast-path
+     * decision (allow rule, deny rule, positive-decision cache hit) returns
+     * BEFORE acquiring the lock, so non-prompt categories stay O(1) and
+     * don't slow down with a queue of in-flight prompts.
+     */
+    private resolveLock;
+    constructor(policy: PermissionPolicy, resolver: PermissionResolver, cacheScope?: PermissionCacheScope, getMode?: () => ApprovalMode);
+    /** Boolean shim over {@link evaluate} for callers that only need the verdict
+     *  (RPC/ACP host, LSP resolver, legacy tests). */
+    check(req: AuthorizationRequest): Promise<boolean>;
+    /**
+     * (5.3) Whether the session mode blocks this whole tool category outright
+     * (plan's read-only floor), as a synchronous pre-check the engine runs
+     * BEFORE a tool's `permission()` null-bypass — so plan can't be skipped by an
+     * op that would otherwise bypass the gate (codex Round-1 MUST-FIX #1). Pure
+     * function of `(category, getMode())`; shares `isBlockedByMode` with
+     * `evaluate` so there's one source of truth.
+     */
+    blockByMode(category: ToolCategory): {
+        reason: string;
+    } | null;
+    /**
+     * Full decision. Precedence (docs/5.3-design.md D3) over the existing static
+     * lookup `tools[name] ?? defaults[category]`:
+     *   1. static `deny` (per-tool OR category) → DENY — the absolute floor no
+     *      mode overrides (codex Round-1 MUST-FIX #4: yolo must not bypass a
+     *      configured deny).
+     *   2. mode blocks the tier (plan) → DENY — overrides a standing `allow`.
+     *   3. static `allow` → ALLOW.
+     *   4. mode auto-approves the tier (yolo / auto-edit) → ALLOW, no prompt.
+     *   5. static `prompt`/`host-bridged` → positive-cache hit, else resolver.
+     */
+    evaluate(req: AuthorizationRequest): Promise<PermissionEvaluation>;
+    /**
+     * (5.10b SHOULD-FIX #2) Surgical extraction of the per-gate serialization lock
+     * shared by `evaluate` (authorization) and `ask` (question): snapshot the
+     * previous lock, install our own, await the snapshot (chaining works whether
+     * or not it rejected), run `fn`, release. Nothing evaluate-specific lives here.
+     */
+    private withResolverLock;
+    /**
+     * (5.10b) The QUESTION channel — used ONLY by the read-only `ask_user_question`
+     * tool (the engine fail-closes any other tool that emits a `question` request).
+     * Deliberately bypasses `evaluate`'s allow / auto-approve / positive-cache /
+     * mode precedence — a question is not an authorization — but PRESERVES the
+     * static `deny` floor (per-tool rule OR category default) so an operator can
+     * disable the asker. Shares `evaluate`'s serialization lock so a question and
+     * an authorization never race for the resolver's single `pending` slot. A
+     * non-question (or stray boolean) decision ⇒ declined (never auth-on-question).
+     */
+    ask(req: QuestionRequest): Promise<QuestionDecision>;
+    /**
+     * Drops one cache key from the positive-decision cache. The MCP host
+     * calls this with the tool name when a server is restarted or
+     * removed — without it, a previously approved tool name could silently
+     * authorize a *different* implementation after the server's tool set
+     * changed. (5.1) Op-enum tools call this with their per-op cache key
+     * (e.g. `pty.kill.SIGTERM/<session_id>`) when a session terminates so
+     * a re-used session id can't carry a stale approval.
+     */
+    invalidate(name: string): void;
+    /** Drops every cached positive decision. Useful for "I'm rotating creds,
+     * re-prompt me" UX or as a wholesale teardown when MCP is reloaded. */
+    invalidateAll(): void;
+}
+//# sourceMappingURL=permission.d.ts.map

package/dist/tools/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/tools/permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC;AAsB1E,qBAAa,cAAc;IAkBvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAO3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IA1B1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,WAAW,CAAoC;gBAGpC,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,GAAE,oBAA0C,EAOtD,OAAO,GAAE,MAAM,YAA8B;IAGhE;sDACkD;IAC5C,KAAK,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxD;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAK9D;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkExE;;;;;OAKG;YACW,gBAAgB;IAc9B;;;;;;;;;OASG;IACG,GAAG,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAa1D;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B;2EACuE;IACvE,aAAa,IAAI,IAAI;CAGtB"}

package/dist/tools/permission.js

@@ -0,0 +1,208 @@
+import { isAutoApprovedByMode, isBlockedByMode, modeBlockReason } from "./approval.js";
+/**
+ * Default cache scope. Three cohorts are cached by default:
+ *   1. **MCP-bridged tools** (`mcp__*`) — pre-5.1 behaviour preserved.
+ *      The user's act of adding a server to config is the trust
+ *      signal; once they say "yes" to a tool, they shouldn't be
+ *      re-prompted on every call.
+ *   2. **Per-op cacheKey shapes** — any request that ships an
+ *      explicit `cacheKey` opts in to caching. The op-enum tools
+ *      (5.1's `pty`, future siblings) use this for per-`(session,
+ *      operation, arg-class)` scoping so e.g. approving SIGTERM on
+ *      session X does not pre-approve SIGKILL on the same session
+ *      (codex Round-2 MUST-FIX #2 — without this broadening the
+ *      hook's cacheKey was dead code).
+ *   3. Everything else stays un-cached so the user re-prompts per
+ *      call by default — that matches `web_fetch`'s per-URL gating
+ *      intent and the file-write defaults.
+ */
+const DEFAULT_CACHE_SCOPE = (req) => req.name.startsWith("mcp__") || req.cacheKey !== undefined;
+export class PermissionGate {
+    policy;
+    resolver;
+    cacheScope;
+    getMode;
+    allowCache = new Set();
+    /**
+     * Promise chain that serialises every resolver invocation across the gate.
+     * Without this, two concurrent tool calls (e.g. parent's sync tool +
+     * background child's tool, post-3.4) both reach `this.resolver(...)`,
+     * and the TUI's view-model has exactly one `pending` slot — the second
+     * request overwrites the first, orphaning the first promise. Codex
+     * Round-1 MUST-FIX #1.
+     *
+     * The chain only wraps the actual resolver call: every fast-path
+     * decision (allow rule, deny rule, positive-decision cache hit) returns
+     * BEFORE acquiring the lock, so non-prompt categories stay O(1) and
+     * don't slow down with a queue of in-flight prompts.
+     */
+    resolveLock = Promise.resolve();
+    constructor(policy, resolver, cacheScope = DEFAULT_CACHE_SCOPE, 
+    // (5.3) Session approval-mode getter. Optional 4th positional so every
+    // existing `new PermissionGate(policy, resolver[, cacheScope])` call site
+    // keeps working at `default` mode (codex Round-1 MUST-FIX #2 — back-compat).
+    // A getter (not the holder) keeps tools decoupled from runtime's
+    // ApprovalState; read fresh on every check so a mid-turn Shift+Tab lands
+    // immediately.
+    getMode = () => "default") {
+        this.policy = policy;
+        this.resolver = resolver;
+        this.cacheScope = cacheScope;
+        this.getMode = getMode;
+    }
+    /** Boolean shim over {@link evaluate} for callers that only need the verdict
+     *  (RPC/ACP host, LSP resolver, legacy tests). */
+    async check(req) {
+        return (await this.evaluate(req)).allow;
+    }
+    /**
+     * (5.3) Whether the session mode blocks this whole tool category outright
+     * (plan's read-only floor), as a synchronous pre-check the engine runs
+     * BEFORE a tool's `permission()` null-bypass — so plan can't be skipped by an
+     * op that would otherwise bypass the gate (codex Round-1 MUST-FIX #1). Pure
+     * function of `(category, getMode())`; shares `isBlockedByMode` with
+     * `evaluate` so there's one source of truth.
+     */
+    blockByMode(category) {
+        const mode = this.getMode();
+        return isBlockedByMode(category, mode) ? { reason: modeBlockReason(mode) } : null;
+    }
+    /**
+     * Full decision. Precedence (docs/5.3-design.md D3) over the existing static
+     * lookup `tools[name] ?? defaults[category]`:
+     *   1. static `deny` (per-tool OR category) → DENY — the absolute floor no
+     *      mode overrides (codex Round-1 MUST-FIX #4: yolo must not bypass a
+     *      configured deny).
+     *   2. mode blocks the tier (plan) → DENY — overrides a standing `allow`.
+     *   3. static `allow` → ALLOW.
+     *   4. mode auto-approves the tier (yolo / auto-edit) → ALLOW, no prompt.
+     *   5. static `prompt`/`host-bridged` → positive-cache hit, else resolver.
+     */
+    async evaluate(req) {
+        // (5.1) Cache key falls back to `name`. Per-op shapes set `cacheKey`.
+        const key = req.cacheKey ?? req.name;
+        const mode = this.getMode();
+        const staticDecision = this.policy.tools?.[req.name] ?? this.policy.defaults[req.category];
+        if (staticDecision === "deny") {
+            return { allow: false, reason: `denied by policy (${req.category})`, source: "policy" };
+        }
+        if (isBlockedByMode(req.category, mode)) {
+            return { allow: false, reason: modeBlockReason(mode), source: "mode" };
+        }
+        if (staticDecision === "allow")
+            return { allow: true, source: "policy" };
+        if (isAutoApprovedByMode(req.category, mode))
+            return { allow: true, source: "mode" };
+        // "prompt" / "host-bridged" defer to the resolver unless a positive
+        // decision for this key is already cached this session. The cache only
+        // holds keys that were intentionally remembered (scoped auto-cache OR an
+        // explicit `remember:true` "always"), so a hit is always honored —
+        // independent of `cacheScope`, which only governs *adding* below.
+        if (this.allowCache.has(key))
+            return { allow: true, source: "policy" };
+        // Acquire the per-gate serialisation lock, then run the resolver step. The
+        // post-wait cache re-check + mode re-read live INSIDE this callback (NOT in
+        // `withResolverLock`) — they are evaluate-specific, not generic to the lock
+        // (codex R1 SHOULD-FIX #2 — surgical extraction).
+        return this.withResolverLock(async () => {
+            // Re-check the cache after the wait — another queued call may have
+            // populated it (see the read-before-lock note above re: cacheScope).
+            if (this.allowCache.has(key))
+                return { allow: true, source: "policy" };
+            // (5.3 codex Round-1 SHOULD-FIX #1) Re-read the mode after the wait too:
+            // the user may have flipped to plan (→ block) or yolo (→ skip the now-
+            // stale prompt) while this request sat in the queue.
+            const modeNow = this.getMode();
+            if (isBlockedByMode(req.category, modeNow)) {
+                return { allow: false, reason: modeBlockReason(modeNow), source: "mode" };
+            }
+            if (isAutoApprovedByMode(req.category, modeNow))
+                return { allow: true, source: "mode" };
+            // (5.2 MUST-FIX #1 / 5.3) The resolver returns a bare boolean (legacy) or
+            // a PermissionDecision. Caching rule:
+            //   - bare boolean: cache iff `cacheScope` (legacy, scope-gated).
+            //   - {remember:false}: never cache (allow-once).
+            //   - {remember:true}: cache regardless of scope — an explicit human/host
+            //     "always" should stick even for un-scoped tools like file-write
+            //     (this is the TUI's "[a] yes, don't ask" path).
+            //   - {} (remember omitted): scope-gated, preserving 5.2 ACP semantics.
+            const decision = await this.resolver(req);
+            // (5.10b) A question decision must never reach the authorization path — it
+            // carries no allow/deny. Defensive: the engine only sends authorization
+            // requests here, so a stray question ⇒ treat as a denial.
+            if (typeof decision !== "boolean" && decision.kind === "question") {
+                return { allow: false, source: "resolver" };
+            }
+            const explicit = typeof decision !== "boolean";
+            const granted = explicit ? decision.allow : decision;
+            const remember = explicit ? decision.remember !== false : true;
+            const feedback = explicit ? decision.feedback : undefined;
+            const cacheIt = granted && remember && (this.cacheScope(req) || (explicit && decision.remember === true));
+            if (cacheIt)
+                this.allowCache.add(key);
+            return granted
+                ? { allow: true, source: "resolver" }
+                : { allow: false, source: "resolver", feedback };
+        });
+    }
+    /**
+     * (5.10b SHOULD-FIX #2) Surgical extraction of the per-gate serialization lock
+     * shared by `evaluate` (authorization) and `ask` (question): snapshot the
+     * previous lock, install our own, await the snapshot (chaining works whether
+     * or not it rejected), run `fn`, release. Nothing evaluate-specific lives here.
+     */
+    async withResolverLock(fn) {
+        const previousLock = this.resolveLock;
+        let release;
+        this.resolveLock = new Promise((r) => {
+            release = r;
+        });
+        try {
+            await previousLock.catch(() => { });
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * (5.10b) The QUESTION channel — used ONLY by the read-only `ask_user_question`
+     * tool (the engine fail-closes any other tool that emits a `question` request).
+     * Deliberately bypasses `evaluate`'s allow / auto-approve / positive-cache /
+     * mode precedence — a question is not an authorization — but PRESERVES the
+     * static `deny` floor (per-tool rule OR category default) so an operator can
+     * disable the asker. Shares `evaluate`'s serialization lock so a question and
+     * an authorization never race for the resolver's single `pending` slot. A
+     * non-question (or stray boolean) decision ⇒ declined (never auth-on-question).
+     */
+    async ask(req) {
+        const staticDecision = this.policy.tools?.[req.name] ?? this.policy.defaults[req.category];
+        if (staticDecision === "deny") {
+            return { kind: "question", answers: {}, declined: true };
+        }
+        return this.withResolverLock(async () => {
+            const decision = await this.resolver(req);
+            return typeof decision === "boolean" || decision.kind !== "question"
+                ? { kind: "question", answers: {}, declined: true }
+                : decision;
+        });
+    }
+    /**
+     * Drops one cache key from the positive-decision cache. The MCP host
+     * calls this with the tool name when a server is restarted or
+     * removed — without it, a previously approved tool name could silently
+     * authorize a *different* implementation after the server's tool set
+     * changed. (5.1) Op-enum tools call this with their per-op cache key
+     * (e.g. `pty.kill.SIGTERM/<session_id>`) when a session terminates so
+     * a re-used session id can't carry a stale approval.
+     */
+    invalidate(name) {
+        this.allowCache.delete(name);
+    }
+    /** Drops every cached positive decision. Useful for "I'm rotating creds,
+     * re-prompt me" UX or as a wholesale teardown when MCP is reloaded. */
+    invalidateAll() {
+        this.allowCache.clear();
+    }
+}
+//# sourceMappingURL=permission.js.map

package/dist/tools/permission.js.map

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

package/dist/tools/registry.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "./types.js";
+/** Registry pattern: built-in and plugin tools share one namespace. */
+export declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool): void;
+    /** Removes a tool by name, returning true if it existed. Used by PluginHost
+     * rollback when a plugin's onLoad throws after registering a tool. */
+    unregister(name: string): boolean;
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,uEAAuE;AACvE,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IAEjD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI1B;0EACsE;IACtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAInC,IAAI,IAAI,IAAI,EAAE;CAGf"}

package/dist/tools/registry.js

@@ -0,0 +1,19 @@
+/** Registry pattern: built-in and plugin tools share one namespace. */
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    /** Removes a tool by name, returning true if it existed. Used by PluginHost
+     * rollback when a plugin's onLoad throws after registering a tool. */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAEjD,QAAQ,CAAC,IAAU;QACjB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;0EACsE;IACtE,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/tools/types.d.ts

@@ -0,0 +1,244 @@
+import type { JSONValue } from "@chances-ai/runtime";
+import type { ToolCategory } from "@chances-ai/runtime/config";
+export type { ToolCategory };
+/** Minimum LSP host shape consumed by the `lsp` built-in tool. Kept
+ * narrow so this package doesn't depend on `@chances-ai/lsp` for
+ * types — the engine wires the real instance in at boot time and
+ * downcasts. (codex Round-1 MUST-FIX #1.) */
+export interface ToolLspHost {
+    execute(req: {
+        op: string;
+        filePath?: string;
+        line?: number;
+        character?: number;
+        query?: string;
+        cwd: string;
+        signal: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+}
+export interface ToolContext {
+    workspaceRoot: string;
+    cwd: string;
+    signal: AbortSignal;
+    /**
+     * (4.1) The parent (non-isolated) workspace root. Inside an isolated
+     * subagent, `workspaceRoot` and `cwd` flip to the worktree path, but
+     * **artifact persistence paths** (e.g. `bash`'s oversized-output dump
+     * under `.chances/tool-results/`) should land in the PARENT workspace
+     * so the parent's `.chances/` directory accumulates the durable
+     * record. Otherwise a clean-removed worktree could swallow the
+     * persisted file just as the tool returns its path.
+     *
+     * Outside isolation, this equals `workspaceRoot`. Tools that emit
+     * artifacts should prefer `parentWorkspaceRoot ?? workspaceRoot` so
+     * the contract is uniform across both branches. Round-2 SHOULD-FIX
+     * #4.
+     */
+    parentWorkspaceRoot?: string;
+    /**
+     * (4.2) Optional LSP host wired in at boot when the user has
+     * `vscode-jsonrpc` installed AND `config.lsp.enabled !== false`.
+     * Undefined when the peer is absent or LSP is disabled — the `lsp`
+     * tool fails fast with a labelled `ok:false` in that case.
+     * codex Round-1 MUST-FIX #1 — wrapper cannot reach a CLI-boot-time
+     * host without this engine plumbing.
+     */
+    lsp?: ToolLspHost;
+    /**
+     * (5.7) The engine's tool-call id for THIS execution — the same
+     * `callId` carried on the `tool:call` / `tool:result` bus events and
+     * the provider's `tool_call.id`. The engine stamps it on the ctx
+     * before both `permission()` and `execute()` (see `core/engine.ts`).
+     *
+     * Tools that persist oversized output use it to name the artifact
+     * directory (`.chances/tool-results/<callId>/…`) so a client can join
+     * the saved file to the `tool_result` it received — mirrors
+     * claude-code's `.claude/tool-results/<toolUseId>`. Undefined for
+     * non-engine callers (tests, plugins invoking a tool directly), where
+     * persistence falls back to a freshly-minted `createId`.
+     */
+    callId?: string;
+    /**
+     * (5.10b) The user's answers to an `ask_user_question` call. The engine
+     * populates this ONLY on the question branch — and ONLY for the read-only ask
+     * tool — immediately before `execute()`; `summarize()` and every other
+     * tool/branch never see it. The ask tool reads it to format the model-facing
+     * result string (the engine never serializes answers itself).
+     */
+    questionDecision?: QuestionDecision;
+}
+export interface ToolResult {
+    ok: boolean;
+    output: string;
+}
+/** Command pattern: each tool is a self-describing, executable unit. */
+export interface Tool {
+    name: string;
+    description: string;
+    category: ToolCategory;
+    /** JSON Schema for the args object (shared with the provider via core). */
+    parameters: JSONValue;
+    /** One-line, human-readable description of a specific invocation (used by the
+     * permission prompt and diff approval). Receives the same ctx as execute so
+     * that path-aware previews (e.g. create vs overwrite) resolve against the
+     * workspace, not process.cwd. */
+    summarize(args: JSONValue, ctx: ToolContext): string;
+    execute(args: JSONValue, ctx: ToolContext): Promise<ToolResult>;
+    /**
+     * (5.1) Per-call permission shape. When implemented, the engine asks
+     * this hook BEFORE calling `gate.check(...)`:
+     *   - Return `null` to bypass the gate entirely. Used by op-enum
+     *     tools (e.g. `pty.read`, `pty.resize`) whose ops are already
+     *     covered by a parent op's approval.
+     *   - Return a {@link PermissionRequest} (with optional `cacheKey`)
+     *     to override the legacy `{name, category, summarize(args)}`
+     *     shape — lets ops vary their category, prompt summary, and
+     *     positive-decision cache scope independently.
+     *
+     * When undefined (the default for all 10 existing builtins), the
+     * engine constructs a request from `{name, category, summarize(args),
+     * args}` exactly as in 1.x→5.0 — fully backwards compatible.
+     *
+     * Codex Round-1 MUST-FIX #1 (5.1 design) — without this hook a
+     * single op-enum tool can't bypass cheap ops while re-prompting
+     * destructive ones.
+     */
+    permission?(args: JSONValue, ctx: ToolContext): PermissionRequest | null;
+}
+/**
+ * (5.10b) A request to AUTHORIZE a side-effecting tool call — the original
+ * (1.x→5.x) permission shape. `kind` is optional and defaults to
+ * `"authorization"`, so every existing producer/resolver that omits it stays
+ * byte-identical at runtime. The `question` variant ({@link QuestionRequest})
+ * rides the SAME resolver channel but is NOT an authorization — see
+ * {@link PermissionGate.ask}.
+ */
+export interface AuthorizationRequest {
+    kind?: "authorization";
+    name: string;
+    category: ToolCategory;
+    summary: string;
+    args: JSONValue;
+    /**
+     * (5.1) Optional cache key for `PermissionGate`'s positive-decision
+     * cache. When undefined, the gate uses `name` (legacy behaviour). Use
+     * this to scope per-call cache decisions (e.g.
+     * `pty.kill.SIGTERM/<session_id>` so approving SIGTERM on session
+     * `pty_abc` doesn't pre-approve SIGTERM on session `pty_xyz`, and
+     * doesn't pre-approve SIGKILL on either). Distinct cache keys are
+     * also distinct invalidation targets via `gate.invalidate(cacheKey)`.
+     */
+    cacheKey?: string;
+    /**
+     * (5.2 codex Round-1 MUST-FIX #3) Optional id of the originating tool
+     * call. The engine stamps `call.callId` here before `gate.check`, so a
+     * resolver that surfaces the prompt to an out-of-process client (the RPC
+     * / ACP host) can ship a self-contained `request_permission` frame that
+     * the client joins to the preceding `tool_call.callId`. Undefined on
+     * direct/in-process resolvers (TUI, auto-policy) that don't need it.
+     */
+    callId?: string;
+}
+/** One option in a {@link QuestionSpec}. Schema-locked: the model declares these
+ *  options; the UI injects the "Other" free-text row itself (the model never
+ *  declares it). */
+export interface QuestionOption {
+    label: string;
+    description?: string;
+    /** Optional Markdown preview shown side-by-side when present (single-select). */
+    preview?: string;
+}
+/** One question in a {@link QuestionRequest}. Mirrors the `ask_user_question`
+ *  tool's zod schema, which validates it (1–4 questions, 2–4 options, unique
+ *  labels) BEFORE the request is built. */
+export interface QuestionSpec {
+    question: string;
+    header: string;
+    options: QuestionOption[];
+    multiSelect?: boolean;
+}
+/**
+ * (5.10b) A request to ASK the user structured questions — emitted ONLY by the
+ * read-only `ask_user_question` tool's `permission()` hook. It deliberately
+ * bypasses the allow/deny precedence in {@link PermissionGate.evaluate} (a
+ * question is not an authorization) but still honors a static `deny` floor via
+ * {@link PermissionGate.ask}. The engine FAIL-CLOSES any OTHER tool that emits
+ * this variant (it would otherwise be an authorization escape — codex R1).
+ */
+export interface QuestionRequest {
+    kind: "question";
+    name: string;
+    /** Read-only category of the asker (`search`). `gate.ask` reads it for the
+     *  static-deny floor; the engine asserts it is a read-only category. */
+    category: ToolCategory;
+    callId?: string;
+    questions: QuestionSpec[];
+}
+/**
+ * (5.10b) Discriminated union carried by the resolver channel. An omitted
+ * `kind` ⇒ authorization (back-compat: every existing producer builds the
+ * authorization shape untouched).
+ */
+export type PermissionRequest = AuthorizationRequest | QuestionRequest;
+/**
+ * (5.2 codex Round-1 MUST-FIX #1) A resolver decision richer than a bare
+ * boolean. `remember: false` tells the gate NOT to cache a positive
+ * decision (ACP `allow_once` vs `allow_always`) even when the request is
+ * cache-scoped (`mcp__*` / `cacheKey`). Omitted ⇒ `true` ⇒ the gate's
+ * pre-5.2 caching behaviour is preserved. `kind` omitted ⇒ authorization
+ * (a bare boolean is also an authorization allow/deny).
+ */
+export interface AuthorizationDecision {
+    kind?: "authorization";
+    allow: boolean;
+    remember?: boolean;
+    /**
+     * (5.3) On a denial (`allow: false`), optional free text the user typed via
+     * the "no, and tell the model what to do" prompt option. The gate passes it
+     * through to `PermissionEvaluation.feedback`; the engine appends it to the
+     * `ok:false` tool result so the model can adapt instead of just retrying.
+     * Ignored on an allow. Undefined for the plain "no".
+     */
+    feedback?: string;
+}
+/**
+ * (5.10b) The user's answers to a {@link QuestionRequest}, carried back through
+ * the resolver. `answers` maps each question text to the selected option labels
+ * (plus any free text typed into the "Other" row). `declined` is set when the
+ * user cancels OR the resolver is non-interactive (`-p` / RPC / ACP) — the ask
+ * tool turns either into a deterministic "declined" tool result.
+ */
+export interface QuestionDecision {
+    kind: "question";
+    answers: Record<string, string[]>;
+    annotations?: Record<string, {
+        preview?: string;
+        notes?: string;
+    }>;
+    declined?: boolean;
+}
+/** Discriminated union of resolver decisions. Omitted `kind` ⇒ authorization. */
+export type PermissionDecision = AuthorizationDecision | QuestionDecision;
+/**
+ * Asks an external decider (interactive prompt, or auto-policy) to approve a
+ * tool call OR answer questions. For an {@link AuthorizationRequest} the
+ * resolver returns a bare `boolean` (legacy, = `{allow, remember:true}`) or an
+ * {@link AuthorizationDecision}; for a {@link QuestionRequest} it returns a
+ * {@link QuestionDecision} (a non-interactive resolver returns
+ * `{kind:"question", answers:{}, declined:true}`). Resolvers MUST narrow on
+ * `req.kind` before reading authorization-only fields (codex R1 SHOULD-FIX).
+ */
+export type PermissionResolver = (req: PermissionRequest) => Promise<boolean | PermissionDecision>;
+/** The one tool name allowed to use the `question` permission channel. The
+ *  engine fail-closes any other tool that emits a `question` request (codex R1
+ *  MUST-FIX: the channel skips `gate.evaluate`, so it must be unreachable by a
+ *  side-effecting tool). */
+export declare const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+/** Read-only tool categories. The question channel is double-guarded: the asker
+ *  must BOTH be {@link ASK_USER_QUESTION_TOOL_NAME} AND declare a category in
+ *  this set, so a side-effecting category can never reach it. */
+export declare const READONLY_CATEGORIES: ReadonlySet<ToolCategory>;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"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"}

package/dist/tools/types.js

@@ -0,0 +1,15 @@
+/** The one tool name allowed to use the `question` permission channel. The
+ *  engine fail-closes any other tool that emits a `question` request (codex R1
+ *  MUST-FIX: the channel skips `gate.evaluate`, so it must be unreachable by a
+ *  side-effecting tool). */
+export const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+/** Read-only tool categories. The question channel is double-guarded: the asker
+ *  must BOTH be {@link ASK_USER_QUESTION_TOOL_NAME} AND declare a category in
+ *  this set, so a side-effecting category can never reach it. */
+export const READONLY_CATEGORIES = new Set([
+    "file-read",
+    "search",
+    "memory-read",
+    "network-read",
+]);
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAqPA;;;4BAG4B;AAC5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAE/D;;iEAEiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAA8B,IAAI,GAAG,CAAe;IAClF,WAAW;IACX,QAAQ;IACR,aAAa;IACb,cAAc;CACf,CAAC,CAAC"}