indusagi-coding-agent 0.1.62 → 0.2.0

package/dist/types/conductor/permissions.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Permission rule engine + the `canUseTool` gate seam.
+ *
+ * This module is the product-side brain of the permission stack. It is split in
+ * two layers:
+ *
+ *   1. **A pure rule engine** — {@link resolveRuleDecision} maps a single tool
+ *      call `(toolName, input, mode, rules)` to a {@link PermissionBehavior}
+ *      (`allow` / `ask` / `deny`). It is total, synchronous, and side-effect free
+ *      so the precedence (deny > ask > mode auto-allow > allow) is exhaustively
+ *      unit-testable. Rule strings are induscode-style: a bare tool name
+ *      (`"Bash"`) or a tool name with an argument specifier
+ *      (`"Bash(npm run test:*)"`).
+ *
+ *   2. **A gate factory** — {@link createPermissionGate} turns that engine into a
+ *      framework {@link CanUseToolFn}: the hard async hook the framework agent
+ *      awaits immediately before every tool runs. An `ask` decision is routed to
+ *      an OPTIONAL host-supplied approval resolver; when the resolver is absent
+ *      (a non-interactive boot) `ask` denies with a clear message. An
+ *      `allow-always` approval appends a session-scoped allow rule so later
+ *      identical calls auto-allow.
+ *
+ * Backwards-compatibility: the framework `canUseTool` hook is itself optional, so
+ * a session that never builds a gate keeps today's allow-all behavior. A gate
+ * built from an empty rule set in `default` mode allows read-only tools and asks
+ * for everything else — and, with no resolver, the `ask` denials are explicit
+ * rather than silent.
+ */
+import type { PermissionMode } from "../settings";
+/** Re-exported so consumers of the engine get the mode vocabulary in one import. */
+export type { PermissionMode };
+/** The verdict the rule engine renders for a single tool call. */
+export type PermissionBehavior = "allow" | "ask" | "deny";
+/**
+ * One parsed permission rule: a behavior plus the tool it targets, with an
+ * optional argument specifier (`ruleContent`) that further narrows the match.
+ */
+export interface PermissionRule {
+    /** What happens when this rule matches a tool call. */
+    readonly ruleBehavior: PermissionBehavior;
+    /** The tool (and optional argument specifier) this rule selects. */
+    readonly ruleValue: {
+        /** The canonical tool name, e.g. `"Bash"` / `"bash"` (matched case-insensitively). */
+        readonly toolName: string;
+        /** An optional argument specifier, e.g. `"npm run test:*"`. Absent = bare match. */
+        readonly ruleContent?: string;
+    };
+}
+/**
+ * The framework's tool-permission verdict. Mirrors `indusagi/agent`'s
+ * `PermissionDecision`; re-declared here so the product engine never imports the
+ * framework just for a structural type (the gate is assignable to the
+ * framework's `CanUseToolFn` because the shapes coincide).
+ */
+export type PermissionDecision = {
+    behavior: "allow";
+    updatedInput?: unknown;
+} | {
+    behavior: "deny";
+    message: string;
+};
+/**
+ * The hard permission gate the framework agent awaits before each tool executes.
+ * Structurally identical to `indusagi/agent`'s `CanUseToolFn`, so a value of this
+ * type is accepted by `new Agent({ canUseTool })` with no cast.
+ */
+export type CanUseToolFn = (toolName: string, input: unknown, opts: {
+    signal?: AbortSignal;
+}) => Promise<PermissionDecision>;
+/**
+ * The outcome of the host approval prompt raised for an `ask` decision:
+ *   - `allow-once`   — run this single call, do not remember.
+ *   - `allow-always` — run it and append a session allow rule for the tool.
+ *   - `deny`         — block this call.
+ */
+export type ApprovalChoice = "allow-once" | "allow-always" | "deny";
+/**
+ * The OPTIONAL host approval resolver. When present, an `ask` decision awaits it;
+ * the host (an interactive overlay) returns the user's choice. It MUST resolve to
+ * `"deny"` on abort so a cancelled turn never hangs on a pending prompt. When the
+ * resolver is absent (non-interactive boot / oneshot / link), an `ask` decision
+ * deterministically denies.
+ */
+export type ApprovalResolver = (toolName: string, input: unknown, opts: {
+    signal?: AbortSignal;
+}) => Promise<ApprovalChoice>;
+/**
+ * Tool names known to only inspect state (never mutate). Mirrors the framework's
+ * `READ_ONLY_TOOL_NAMES`; matched case-insensitively. A tool the framework marks
+ * `readOnly: true` is also auto-allowed via {@link createPermissionGate}'s
+ * `readOnlyToolNames` option, so this set is the static fallback for callers that
+ * only know names.
+ */
+export declare const READ_ONLY_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Tool names that mutate the workspace by editing or writing files. Auto-allowed
+ * under `acceptEdits`, and (together with every other non-read-only tool) denied
+ * under `plan`.
+ */
+export declare const EDIT_TOOL_NAMES: ReadonlySet<string>;
+/** Whether `toolName` is a statically-known read-only tool. */
+export declare function isReadOnlyToolName(toolName: string, extra?: ReadonlySet<string>): boolean;
+/** Whether `toolName` is an edit/write tool (auto-allowed under `acceptEdits`). */
+export declare function isEditToolName(toolName: string): boolean;
+/**
+ * Parse an induscode-style rule string into its tool name and optional argument
+ * specifier.
+ *
+ *   - `"Bash"`                 → `{ toolName: "Bash" }`
+ *   - `"Bash(npm run test:*)"` → `{ toolName: "Bash", ruleContent: "npm run test:*" }`
+ *   - `"mcp__server"`          → `{ toolName: "mcp__server" }`
+ *
+ * Whitespace around the tool name is trimmed; an empty argument specifier
+ * (`"Bash()"`) is treated as a bare rule.
+ */
+export declare function parseRule(raw: string): {
+    toolName: string;
+    ruleContent?: string;
+};
+/**
+ * Build a {@link PermissionRule} from a behavior and an induscode-style rule
+ * string. The single place a raw settings list entry becomes a typed rule.
+ */
+export declare function makeRule(ruleBehavior: PermissionBehavior, raw: string): PermissionRule;
+/**
+ * Whether a tool call matches a rule (the ANY-match semantics used for deny/ask).
+ *
+ * The tool name must match (case-insensitive), with an `mcp__server` rule also
+ * matching every `mcp__server__tool` under it (the induscode MCP-wildcard
+ * convention). A bare rule (no specifier) matches any arguments.
+ *
+ * When the rule carries an argument specifier:
+ *   - for the **shell** tool the command is split into its constituent
+ *     sub-commands and the specifier is tested against EACH — a match on ANY
+ *     sub-command counts (so `Bash(rm:*)` denies `git status && rm x`);
+ *   - for any other tool the specifier is tested against the single rendered
+ *     subject (the command field, or a JSON encoding).
+ *
+ * The any-match semantics are correct for `deny` and `ask` (a single offending
+ * sub-command should trigger them). The `allow` branch needs ALL sub-commands
+ * covered instead — see {@link bashAllowCoversAll}.
+ */
+export declare function toolMatchesRule(toolName: string, input: unknown, rule: PermissionRule): boolean;
+/**
+ * Resolve the behavior for a single tool call against the rule set and mode.
+ *
+ * Precedence, highest first:
+ *   1. **deny rules** — any matching `deny` rule blocks, regardless of mode. Deny
+ *      wins across every tier (the caller concatenates the tiers before passing
+ *      the list in, and this scans all deny rules first).
+ *   2. **plan mode** — denies any mutating (non-read-only) tool outright.
+ *   3. **ask rules** — a matching `ask` rule forces a prompt (unless a deny
+ *      already fired). Mode auto-allow does NOT override an explicit ask.
+ *   4. **bypass mode** — allows everything not already denied/asked.
+ *   5. **read-only auto-allow** — a known read-only tool allows in any mode.
+ *   6. **acceptEdits mode** — auto-allows edit/write tools.
+ *   7. **allow rules** — a matching `allow` rule (or, for the shell tool, the
+ *      allow rule SET) allows.
+ *   8. **fallthrough** — `ask` (the safe default: prompt, then deny when no
+ *      resolver is wired).
+ *
+ * The catastrophic-command blocklist sits ABOVE all of this (step 0): a shell
+ * command on the built-in blocklist (`rm -rf /`, fork bombs, `curl | sh`, …) is
+ * denied regardless of rules or mode — even `bypass` cannot run it. See
+ * {@link evaluateCatastrophic}.
+ *
+ * Shell handling threads through the per-sub-command matching: a compound
+ * command (`a && b; c | d`) is split into its constituent commands and each rule
+ * is evaluated against each — a deny/ask on ANY sub-command fires, while
+ * auto-allow requires the allow rule set to cover EVERY sub-command.
+ *
+ * Pure and total: no I/O, no async, deterministic for a given input.
+ */
+export declare function resolveRuleDecision(toolName: string, input: unknown, rules: readonly PermissionRule[], mode: PermissionMode, readOnlyExtra?: ReadonlySet<string>): PermissionBehavior;
+/** Configuration for {@link createPermissionGate}. */
+export interface PermissionGateConfig {
+    /**
+     * The ordered rule set, already concatenated across the project/global tiers.
+     * Deny rules are scanned first so a deny anywhere in the list wins.
+     */
+    readonly rules: readonly PermissionRule[];
+    /** A live getter for the current permission mode (so a mode switch is honored). */
+    readonly mode: () => PermissionMode;
+    /**
+     * The OPTIONAL host approval resolver consulted on an `ask` decision. Absent on
+     * a non-interactive boot — then `ask` deterministically denies.
+     */
+    readonly requestApproval?: ApprovalResolver;
+    /**
+     * Append a session-scoped allow rule when the host returns `allow-always`. The
+     * conductor owns the mutable rule list and passes a setter here so the new rule
+     * is visible to subsequent calls within the session.
+     */
+    readonly appendAllowRule?: (rule: PermissionRule) => void;
+    /**
+     * Tool names (beyond {@link READ_ONLY_TOOL_NAMES}) to treat as read-only —
+     * derived from the deck's `readOnly: true` tool flags so MCP/custom read-only
+     * tools also auto-allow.
+     */
+    readonly readOnlyToolNames?: ReadonlySet<string>;
+}
+/**
+ * Build a framework {@link CanUseToolFn} from the rule engine + the current mode.
+ *
+ * The returned gate:
+ *   - resolves the behavior via {@link resolveRuleDecision},
+ *   - on `allow` proceeds (the framework keeps the validated args),
+ *   - on `deny` short-circuits with a clear message (the framework turns it into
+ *     an `isError` tool result so the model sees why),
+ *   - on `ask` awaits {@link PermissionGateConfig.requestApproval} when present —
+ *     `allow-once` proceeds, `allow-always` proceeds and appends a session allow
+ *     rule, `deny` blocks — and DENIES when no resolver is wired (the safe
+ *     non-interactive default).
+ *
+ * The result is assignable to `indusagi/agent`'s `CanUseToolFn`.
+ */
+export declare function createPermissionGate(config: PermissionGateConfig): CanUseToolFn;

package/dist/types/conductor/permissions.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Permission rule engine + gate — unit tests.
+ *
+ * Exhaustively pins the pure decision ({@link resolveRuleDecision}) precedence
+ * (deny > plan-deny > ask > bypass > read-only > acceptEdits > allow > ask
+ * fallthrough), the induscode rule parsing/matching ({@link parseRule},
+ * {@link toolMatchesRule}, including argument specifiers and the `mcp__` wildcard),
+ * the mode behaviors, and the {@link createPermissionGate} `ask` routing — a host
+ * resolver returns allow-once / allow-always (which appends a session allow rule)
+ * / deny, and an ABSENT resolver denies. No framework, no network.
+ */
+export {};

package/dist/types/conductor/plan-mode.integration.test.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Plan-mode round-trip — integration across the gate + the conductor handshake.
+ *
+ * Two proofs, against the REAL wired pieces (the rule engine's gate + the live
+ * conductor), not mocks of an unwired module:
+ *
+ *   1. **The gate denies edits in plan mode.** A `createPermissionGate` whose mode
+ *      getter reads the conductor's LIVE `permissionMode()` allows an edit in
+ *      `default` mode, denies it once the conductor enters plan mode
+ *      (`togglePlanMode(true)` / `setPermissionMode('plan')`), and allows it again
+ *      once an approved exit restores the prior mode. This is the exact gate the
+ *      conductor threads into the framework `Agent`, so the deny lands where tools
+ *      execute.
+ *
+ *   2. **ExitPlanMode approval restores the mode, persists the plan, and resumes.**
+ *      A scripted fake agent emits a `tool_execution_end` carrying the
+ *      `{ exitPlan: true, plan }` detail the conductor intercepts. With an approval
+ *      resolver installed that approves, a turn run while in plan mode: restores
+ *      the captured pre-plan mode, writes the plan to a file under `plansDir`, and
+ *      enqueues the approved plan as a follow-up so the model proceeds from it. A
+ *      rejecting resolver keeps the session in plan mode and writes nothing.
+ */
+export {};

package/dist/types/conductor/post-edit-diagnostics.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Conductor-integration tests for the post-edit live-diagnostics seam.
+ *
+ * Drives a scripted {@link AgentLike} that emits a `tool_execution_start` for an
+ * `edit`/`write` tool during `prompt`, with an injected {@link DiagnosticsEngine}
+ * over a scripted in-memory runner (no real tsc spawn). Verifies:
+ *   - a turn that introduces a NEW diagnostic enqueues the summary follow-up;
+ *   - a clean edit (no new diagnostics) enqueues nothing;
+ *   - re-editing a file re-surfaces a previously-cleared diagnostic;
+ *   - a non-TS edit never triggers the checker;
+ *   - the injected follow-up turn (which edits nothing) does not loop.
+ */
+export {};

package/dist/types/conductor/transcript-store/serialize.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transcript serialization — head usage round-trip.
+ *
+ * Focused coverage for the cost-cmd durability seam: the head line now carries
+ * the session's cumulative {@link Usage}, and {@link encodeHead} →
+ * {@link parseSessionText} must round-trip it faithfully so resume can restore the
+ * running token/cost total instead of seeding zero. Heads without usage (legacy
+ * files, fresh sessions) must still parse cleanly with `usage` absent.
+ */
+export {};

package/dist/types/conductor/transcript-store/store.d.ts

@@ -27,6 +27,7 @@
  */
 import type { AgentMessage, SessionHead, TranscriptEntry, TranscriptRole } from "../contract";
 import { TRANSCRIPT_SCHEMA } from "../contract";
+import type { Usage } from "indusagi/ai";
 /**
  * Where a transcript's NDJSON log lives. The store appends lines and, on branch,
  * rewrites the whole file; a backend supplies those three primitives plus a way
@@ -101,6 +102,13 @@ export declare class TranscriptStore {
     get sessionId(): string;
     /** The current head (session id + active leaf). */
     get head(): SessionHead;
+    /**
+     * The cumulative session usage last persisted onto the head, or `undefined`
+     * when none has been written (a fresh session, or a legacy file without a
+     * usage-bearing head). `resume` reads this to restore the running token/cost
+     * total instead of seeding zero.
+     */
+    get usage(): Usage | undefined;
     /** Number of nodes currently in the transcript. */
     get size(): number;
     /** Backend location this session persists to (for diagnostics/UI). */
@@ -116,6 +124,16 @@ export declare class TranscriptStore {
      * a settled turn.
      */
     append(content: AgentMessage, role?: TranscriptRole, meta?: Readonly<Record<string, unknown>>): Promise<TranscriptEntry>;
+    /**
+     * Persist the session's cumulative usage onto the head and rewrite the backing
+     * file so the running token/cost total survives a reload. Distinct from
+     * {@link append}, which only appends an entry line and never rewrites the head:
+     * usage durability MUST flow through here so the re-emitted head line carries
+     * the latest tally. Leaves the node tree and active leaf untouched.
+     *
+     * @param usage the cumulative usage to pin on the head
+     */
+    persistUsage(usage: Usage): Promise<void>;
     /**
      * Repoint the head at an earlier node, forking a branch. The next {@link append}
      * becomes a child of `id`; existing nodes are untouched. Rewrites the head line.

package/dist/types/console/components/StatusBar.d.ts

@@ -10,6 +10,7 @@
  * (Renamed surface: the console's status strip.)
  */
 import { type InkThemeAdapter, type SessionSnapshot, type StatusMessage } from "indusagi/react-ink";
+import type { PermissionMode } from "../../settings";
 /** What the {@link StatusBar} renders. */
 export interface StatusBarProps {
     /** The framework adapter that turns token roles into terminal colours. */
@@ -22,10 +23,20 @@ export interface StatusBarProps {
     readonly providerCount: number;
     /** The transient status toast, when one is showing. */
     readonly status?: StatusMessage;
+    /**
+     * The active permission mode. When supplied, a small badge is rendered above the
+     * footer (parallel to the transient status toast) so the user can see at a glance
+     * which of the four cycled modes is live: `default` (tools prompt as usual),
+     * `acceptEdits` (edits auto-approved), `plan` (mutating tools blocked), or
+     * `bypass` (every tool auto-allowed — drawn in an alert colour). The
+     * `bypassPermissions` alias renders as `bypass`. Omitted renders nothing extra.
+     */
+    readonly permissionMode?: PermissionMode;
 }
 /**
- * Render the toast row above the footer strip.
+ * Render the toast row above the footer strip, plus an optional permission-mode
+ * badge when a non-default mode is active.
  *
- * @param props the snapshot + status to display
+ * @param props the snapshot + status (+ optional permission mode) to display
  */
-export declare function StatusBar({ theme, snapshot, branch, providerCount, status, }: StatusBarProps): JSX.Element;
+export declare function StatusBar({ theme, snapshot, branch, providerCount, status, permissionMode, }: StatusBarProps): JSX.Element;

package/dist/types/console/components/WorkingIndicator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * WorkingIndicator — the live "agent is working" affordance.
+ *
+ * While a turn is in flight (`busy`) this draws an animated braille spinner, a
+ * label, an elapsed-seconds clock, and an "esc to interrupt" hint. The label is
+ * a rotating whimsical word (changing every few seconds, induscode-style) for
+ * the general thinking/streaming case, and a concrete phase label while the
+ * agent runs tools or compacts context.
+ *
+ * It renders nothing when idle, and self-drives its animation via a short
+ * interval that ticks ONLY while busy (torn down the moment `busy` clears), so an
+ * idle console does no spinner work. It is a sibling row above the
+ * {@link Composer} and does NOT consume the sticky status toast — so a previous
+ * toast (e.g. the permission-mode line) can never mask that the agent is working.
+ */
+import type { InkThemeAdapter } from "indusagi/react-ink";
+/**
+ * The rotating "thinking" words shown while the agent reasons/streams. Whimsical
+ * present participles, in the spirit of induscode's spinner — purely cosmetic.
+ */
+export declare const WORKING_WORDS: readonly ["Cogitating", "Pondering", "Noodling", "Simmering", "Brewing", "Percolating", "Conjuring", "Tinkering", "Wrangling", "Synthesizing", "Computing", "Musing", "Scheming", "Hatching", "Whirring", "Crunching", "Spelunking", "Untangling", "Marinating", "Ruminating", "Architecting", "Finagling", "Concocting", "Deliberating", "Orchestrating", "Calibrating", "Channeling", "Vibing", "Forging", "Assembling"];
+/** Pick a working word by (wrapping, non-negative) index. Exported for testing. */
+export declare function pickWord(index: number): string;
+/** What the {@link WorkingIndicator} renders. */
+export interface WorkingIndicatorProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** Whether a turn is in flight. When false the indicator renders nothing. */
+    readonly busy: boolean;
+    /** The conductor snapshot phase, used to pick a concrete label when relevant. */
+    readonly phase?: string;
+}
+/**
+ * The concrete label for the phases where a specific word is more useful than a
+ * whimsical one. Returns null for the general thinking/streaming case (the caller
+ * then shows a rotating {@link WORKING_WORDS} word instead). Exported for testing.
+ */
+export declare function phaseLabel(phase: string | undefined): string | null;
+/**
+ * Render the animated working row, or nothing when idle.
+ *
+ * @param props the theme, the busy flag, and the snapshot phase
+ */
+export declare function WorkingIndicator({ theme, busy, phase, }: WorkingIndicatorProps): JSX.Element | null;

package/dist/types/console/components/WorkingIndicator.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * WorkingIndicator — unit tests for the pure label/word logic.
+ *
+ * The animated render is driven by an Ink-only timer that is impractical to
+ * assert headlessly; the load-bearing pure logic is {@link phaseLabel} (concrete
+ * labels for tool/compaction phases) and {@link pickWord} (the rotating whimsical
+ * word for the general thinking case).
+ */
+export {};

package/dist/types/console/contract.d.ts

@@ -244,8 +244,9 @@ export interface ViewRow {
  *   - `signOut`      — the provider sign-out confirmation.
  *   - `oauth`        — the in-flight OAuth device/redirect flow.
  *   - `plugin`       — a plugin-supplied select/confirm/input/custom overlay.
+ *   - `approval`     — a pending tool-permission prompt (allow once / always / deny).
  */
-export type ModalKind = "none" | "settings" | "models" | "scopedModels" | "theme" | "sessions" | "tree" | "userTurns" | "signIn" | "signOut" | "oauth" | "plugin";
+export type ModalKind = "none" | "settings" | "models" | "scopedModels" | "theme" | "sessions" | "tree" | "userTurns" | "signIn" | "signOut" | "oauth" | "plugin" | "approval";
 /**
  * The active modal plus any opaque payload the matching dialog needs.
  *

package/dist/types/console/input/keymap.d.ts

@@ -84,6 +84,15 @@ export interface KeyChord {
  *   Model / reasoning
  *     - `model:cycleThinking` — advance the reasoning-effort ladder one step.
  *
+ *   Permission mode
+ *     - `mode:cyclePermission` — cycle through ALL permission modes (Shift+Tab),
+ *       advancing one step per press: default → acceptEdits → plan → bypass →
+ *       (wrap) default. In `plan` mode every mutating tool is blocked; in `bypass`
+ *       every tool is auto-allowed.
+ *     - `mode:togglePlan` — toggle read-only plan mode on/off. Drives `/plan`; no
+ *       longer bound to Shift+Tab (which now cycles all modes). In plan mode every
+ *       mutating tool is blocked at the permission gate.
+ *
  *   Queue
  *     - `queue:dequeue`    — pull the most recently queued input back into the
  *       composer so it can be edited or dropped.
@@ -106,7 +115,7 @@ export interface KeyChord {
  *   Inert
  *     - `none`             — the keystroke carries no console meaning.
  */
-export type ConsoleVerb = "text:type" | "text:newline" | "edit:erasePrev" | "edit:eraseNext" | "edit:clearLine" | "nav:left" | "nav:right" | "nav:home" | "nav:end" | "nav:up" | "nav:down" | "flow:submit" | "flow:dismiss" | "flow:accept" | "flow:interrupt" | "flow:suspend" | "flow:cycleModel" | "model:cycleThinking" | "queue:dequeue" | "input:pasteImage" | "input:externalEditor" | "overlay:open" | "view:expandTools" | "view:toggleReasoning" | "none";
+export type ConsoleVerb = "text:type" | "text:newline" | "edit:erasePrev" | "edit:eraseNext" | "edit:clearLine" | "nav:left" | "nav:right" | "nav:home" | "nav:end" | "nav:up" | "nav:down" | "flow:submit" | "flow:dismiss" | "flow:accept" | "flow:interrupt" | "flow:suspend" | "flow:cycleModel" | "model:cycleThinking" | "mode:cyclePermission" | "mode:togglePlan" | "queue:dequeue" | "input:pasteImage" | "input:externalEditor" | "overlay:open" | "view:expandTools" | "view:toggleReasoning" | "none";
 /**
  * A classified keystroke: a {@link ConsoleVerb} plus the small payload a verb
  * may carry — the literal text for a `text:type` insert, or the target overlay

package/dist/types/console/overlays/approval-queue.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Approval queue — the headless, pure serializer behind the approval overlay.
+ *
+ * The permission gate may reach an `ask` decision while another approval prompt is
+ * already on screen (e.g. a turn that batches several tool calls). The UI shows ONE
+ * prompt at a time, so the pending requests are held in an ordered queue: each
+ * `enqueue` parks a request, the HEAD is the prompt currently shown, and `settle`
+ * resolves the head's parked promise then advances to the next. This module is a
+ * pure reducer over an immutable {@link ApprovalQueueState} plus a couple of tiny
+ * helpers — no React, no Ink, no timers — so the queue logic is unit-testable in
+ * isolation (the overlay component only renders the head and dispatches settles).
+ *
+ * Each queued entry carries the parked promise's `resolve` (the gate awaits it) and
+ * the request itself. Settling resolves with an {@link ApprovalChoice}; an
+ * abort/clear settles every outstanding entry with `"deny"` so a cancelled turn
+ * never hangs on a pending prompt.
+ */
+import type { ApprovalChoice } from "../../conductor";
+import type { ApprovalRequest } from "./approval";
+/** One parked approval request awaiting the user's choice. */
+export interface ApprovalEntry {
+    /** A stable id, unique within the queue's lifetime, used to settle the right one. */
+    readonly id: string;
+    /** The pending request the prompt renders. */
+    readonly request: ApprovalRequest;
+    /** Fulfil the gate's parked promise with the user's choice. Called exactly once. */
+    readonly resolve: (choice: ApprovalChoice) => void;
+}
+/**
+ * The immutable queue state. The array is ordered oldest-first; the head (index 0)
+ * is the request currently prompted. An empty queue means no prompt is showing.
+ */
+export interface ApprovalQueueState {
+    /** The parked entries, oldest first; `[0]` is the active prompt. */
+    readonly entries: readonly ApprovalEntry[];
+}
+/** The empty queue — no approval prompt pending. */
+export declare const EMPTY_APPROVAL_QUEUE: ApprovalQueueState;
+/**
+ * The closed action union the queue reducer folds:
+ *   - `enqueue` — park a new request at the tail.
+ *   - `settle`  — resolve the entry matching `id` with `choice` and drop it.
+ *   - `clear`   — drop EVERY entry (the caller resolves each with `"deny"`).
+ */
+export type ApprovalQueueEvent = {
+    readonly type: "enqueue";
+    readonly entry: ApprovalEntry;
+} | {
+    readonly type: "settle";
+    readonly id: string;
+} | {
+    readonly type: "clear";
+};
+/**
+ * Fold one {@link ApprovalQueueEvent} over the queue, returning a fresh state.
+ *
+ * Pure and total: it never resolves a promise itself (the caller does that around
+ * a `settle`/`clear`), it only mutates the ordered entry list. `enqueue` appends;
+ * `settle` removes the entry with the matching `id` (a no-op when absent, e.g. a
+ * double-settle); `clear` empties the queue.
+ *
+ * @param state the prior queue state
+ * @param event the action to apply
+ */
+export declare function approvalQueueReducer(state: ApprovalQueueState, event: ApprovalQueueEvent): ApprovalQueueState;
+/**
+ * The active prompt — the head entry — or `undefined` when the queue is empty.
+ *
+ * @param state the queue state
+ */
+export declare function activeApproval(state: ApprovalQueueState): ApprovalEntry | undefined;

package/dist/types/console/overlays/approval.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Approval overlay — the interactive tool-permission prompt.
+ *
+ * This group owns the single modal kind raised when the permission gate reaches an
+ * `ask` decision for a tool call: it shows the pending request (tool name, a short
+ * rendering of the arguments, and any suggested allow-rule) and lets the user pick
+ * one of three outcomes — allow this one call, allow it for the rest of the session
+ * (which the gate turns into a session allow-rule), or deny it. It is mounted
+ * unconditionally by {@link import("./host").OverlayHost}, which routes by
+ * {@link ModalState.kind}; this component renders a dialog body only for its own
+ * `approval` kind and is otherwise inert.
+ *
+ * The wiring is a parked promise: when the React layer builds the conductor's
+ * approval resolver it returns a promise and stashes the request (plus the
+ * promise's `resolve`) under {@link ModalState.payload}. This overlay reads that
+ * payload, renders the choices, and on a pick calls `payload.resolve(choice)` then
+ * closes the modal — handing control back to the gate, which proceeds or denies. An
+ * Esc (the dialog's own close) resolves `"deny"` so a dismissed prompt never hangs
+ * the in-flight turn. The actual select UI reuses the framework `ThemeDialog`
+ * (a labelled, navigable pick-from-list with descriptions), so the overlay needs no
+ * bespoke key handling.
+ *
+ * React/Ink are obtained the same way the other overlays do (default React export
+ * from `indusagi/react-host`, `Box`/`Text` from `indusagi/react-host/ink`).
+ */
+import { type ThemeDialogItem } from "indusagi/react-ink";
+import type { ApprovalChoice } from "../../conductor";
+import type { OverlayGroupProps } from "./pickers";
+/**
+ * The pending tool-permission request a prompt is raised for. Mirrors the
+ * arguments the conductor's approval resolver is handed for an `ask` decision.
+ */
+export interface ApprovalRequest {
+    /** The tool the model asked to run (e.g. `"Bash"`, `"Edit"`). */
+    readonly toolName: string;
+    /** The validated arguments the tool would run with. */
+    readonly input: unknown;
+    /**
+     * Optional human-readable allow-rule suggestions the prompt surfaces (e.g.
+     * `"Bash(npm run test:*)"`), so the user knows what an "allow always" remembers.
+     */
+    readonly suggestions?: readonly string[];
+}
+/**
+ * The opaque {@link ModalState.payload} the `approval` overlay narrows: the pending
+ * request plus the resolver of the parked approval promise. The overlay calls
+ * `resolve(choice)` exactly once, then closes the modal.
+ */
+export interface ApprovalPayload {
+    /** The pending request to render. */
+    readonly request: ApprovalRequest;
+    /** Fulfil the parked approval promise with the user's choice. */
+    readonly resolve: (choice: ApprovalChoice) => void;
+}
+/**
+ * The three offerable outcomes, in listing order. The `id` is the
+ * {@link ApprovalChoice} the gate consumes; `label`/`description` are what the
+ * prompt shows. Kept as data (not an `if`-ladder) so the choice→resolution mapping
+ * is a pure table the headless test asserts against.
+ */
+export declare const APPROVAL_CHOICES: readonly (ThemeDialogItem & {
+    id: ApprovalChoice;
+})[];
+/** The {@link ApprovalChoice} a dismissed (Esc) prompt resolves to. */
+export declare const DISMISS_CHOICE: ApprovalChoice;
+/**
+ * Map a selected dialog `id` back to the {@link ApprovalChoice} the gate consumes.
+ *
+ * Pure and total: a recognised id maps to itself; anything unrecognised falls back
+ * to {@link DISMISS_CHOICE} (`"deny"`) so a stray selection can never silently
+ * allow a tool. This is the unit the headless test pins.
+ *
+ * @param id the `id` the {@link ThemeDialog} reported on select
+ */
+export declare function choiceFromId(id: string): ApprovalChoice;
+/**
+ * Narrow the opaque modal payload into a typed {@link ApprovalPayload}, or
+ * `undefined` when it is not a well-formed approval request (a defensive guard —
+ * the overlay renders nothing rather than crash on a malformed payload).
+ *
+ * @param payload the opaque {@link ModalState.payload}
+ */
+export declare function readApprovalPayload(payload: unknown): ApprovalPayload | undefined;
+/**
+ * Render a tool call's arguments as a single short, human-readable line for the
+ * prompt body. A shell `command` (or any `command` field) shows verbatim;
+ * otherwise a compact JSON encoding is used. Long values are elided so the prompt
+ * never floods the terminal.
+ *
+ * @param input the validated tool arguments
+ */
+export declare function summarizeInput(input: unknown): string;
+/**
+ * The approval overlay group: the single `approval` modal kind.
+ *
+ * Renders the prompt body when the active modal is `approval` and its payload is a
+ * well-formed {@link ApprovalPayload}; every other kind (and a malformed payload)
+ * yields nothing. Unlike the session/auth groups this does NOT require the runtime
+ * services bundle — the payload carries everything the prompt needs — so it works
+ * on any mount path that wired a resolver.
+ *
+ * @param props the forwarded overlay props (modal, services, theme, dispatch, closer)
+ */
+export declare function ApprovalOverlays(props: OverlayGroupProps): JSX.Element | null;

package/dist/types/console/overlays/approval.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Approval overlay — headless unit tests for the pure logic behind the prompt.
+ *
+ * Rendering an Ink dialog headlessly is brittle, so these tests pin the two pure
+ * pieces the interactive overlay is built from — exactly the bar the task sets:
+ *
+ *   1. The choice→resolution mapping ({@link choiceFromId}) + the payload narrowing
+ *      ({@link readApprovalPayload}) + the argument summary ({@link summarizeInput}):
+ *      a selected dialog row maps to the {@link ApprovalChoice} the gate consumes, a
+ *      malformed payload is rejected, and a stray id falls back to `deny`.
+ *   2. The queue reducer ({@link approvalQueueReducer}) + head selector
+ *      ({@link activeApproval}): requests serialise oldest-first, a settle drops the
+ *      matching entry (and a double-settle is inert), and a clear empties the queue.
+ *
+ * No React, no Ink, no conductor — just the exported functions.
+ */
+export {};

package/dist/types/console/overlays/host.d.ts

@@ -10,9 +10,10 @@
  * owns a disjoint slice of the kind space and renders a body only for its own
  * kinds:
  *
- *   - {@link PickerOverlays}  — `models`, `scopedModels`, `theme`, `settings`.
- *   - {@link SessionOverlays} — `sessions`, `tree`, `userTurns`.
- *   - {@link AuthOverlays}    — `signIn`, `signOut`, `oauth`, `plugin`.
+ *   - {@link PickerOverlays}   — `models`, `scopedModels`, `theme`, `settings`.
+ *   - {@link SessionOverlays}  — `sessions`, `tree`, `userTurns`.
+ *   - {@link AuthOverlays}     — `signIn`, `signOut`, `oauth`, `plugin`.
+ *   - {@link ApprovalOverlays} — `approval` (the tool-permission prompt).
  *
  * When no overlay is raised (`kind === "none"`) the host renders nothing, so the
  * composer keeps focus and the groups are never mounted needlessly.