@gaunt-sloth/core 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/core/plainToolIndication.js

@@ -0,0 +1,148 @@
+/**
+ * @module plainToolIndication
+ * TUI-C30 — compact tool-call indication for the PLAIN surface (`--no-tui` readline sessions,
+ * piped/single-shot `ask`/`exec`/`review`/`pr`). The Ink TUI renders tool calls from the typed
+ * event stream; the plain surface streams strings, so until now a tool call only surfaced
+ * through the tools' own transient notices (`📁 Reading file: …`, `🔧 Executing …` + raw child
+ * output via the tool-output channel's default sink). This module watches the SAME LangGraph
+ * message stream the string path already iterates and, when each `ToolMessage` lands, prints
+ * one compact indication built from the shared {@link toolDisplay} registry:
+ *
+ *     ✓ 📁 read_file(path=README.md)
+ *         # Readme            ← up to the canonical 10 preview lines, dim
+ *         … (+42 more lines)
+ *
+ * Stream discipline (matches how the plain surface prints tool activity today): the block is
+ * emitted at INFO level through `displayToolIndication` — same stdout channel, same
+ * `consoleLevel` gate and session-log treatment as the existing tool notices — so scripted
+ * consumers that already silence INFO chatter silence this too. Colour is used only when
+ * `useColour` is on AND stdout is a TTY; otherwise the block degrades to clean monochrome
+ * (DL-7), with diff lines still readable via their `+`/`-` prefixes.
+ *
+ * Live-output dedupe: shell-shaped results (`<COMMAND_OUTPUT>`) belong to tools whose child
+ * output ALREADY streamed raw via the channel's default sink, so those render with
+ * `liveOutputAlreadyShown` and show only the closing status line — never a repeat of output
+ * the user just watched.
+ */
+import { AIMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import { buildToolPreviewLines, getToolGlyph, parseCommandOutputResult, renderToolLineAnsi, summariseToolCall, } from '#src/core/toolDisplay.js';
+import { displayToolIndication } from '#src/utils/consoleUtils.js';
+import { getUseColour, stdout } from '#src/utils/systemUtils.js';
+const INDENT = '    ';
+/**
+ * Create the per-stream observer. State is scoped to one stream (one `agent.stream()` call);
+ * tool_call deltas are accumulated from `tool_call_chunks` (keyed by the provider's chunk
+ * `index`, which restarts per LLM round — the map is flushed into the by-id map whenever a
+ * `ToolMessage` arrives, mirroring `processEventStream`'s reset-per-round). Deliberately does
+ * NOT `concat()` whole `AIMessageChunk`s: only the tool-call slices are needed, which also
+ * sidesteps the TUI-C29 `__raw_response` aggregation-growth trap entirely.
+ *
+ * `emit` is injectable for tests; production uses the INFO-level `displayToolIndication`.
+ */
+export function createPlainToolIndication(emit = displayToolIndication) {
+    /** Streaming tool-call deltas for the CURRENT round, keyed by tool_call_chunk index. */
+    const streaming = new Map();
+    /** Completed calls awaiting their ToolMessage, keyed by tool call id. */
+    const byId = new Map();
+    const flushStreamingIntoById = () => {
+        for (const call of streaming.values()) {
+            if (call.id)
+                byId.set(call.id, call);
+        }
+        streaming.clear();
+    };
+    const renderToolMessage = (message) => {
+        const id = typeof message.tool_call_id === 'string' ? message.tool_call_id : '';
+        const tracked = id ? byId.get(id) : undefined;
+        if (id)
+            byId.delete(id);
+        const name = tracked?.name || (typeof message.name === 'string' ? message.name : '') || '';
+        const result = typeof message.content === 'string' ? message.content : JSON.stringify(message.content);
+        const isError = message.status === 'error';
+        // Colour only when configured AND stdout is a real terminal — piped output stays clean
+        // monochrome (unlike consoleUtils' blanket dim, this block is asserted non-TTY-clean).
+        const colour = getUseColour() && !!stdout.isTTY;
+        const statusGlyph = isError
+            ? colour
+                ? '\x1b[31m✗\x1b[0m'
+                : '✗'
+            : colour
+                ? '\x1b[32m✓\x1b[0m'
+                : '✓';
+        const summary = summariseToolCall(name, tracked?.argsText);
+        const summaryText = colour ? `\x1b[2m${summary}\x1b[0m` : summary;
+        const head = `${statusGlyph} ${getToolGlyph(name)} ${summaryText}`;
+        const preview = buildToolPreviewLines({
+            name,
+            argsText: tracked?.argsText,
+            result,
+            isError,
+            // Shell-shaped results stream their child output live through the channel's default
+            // sink on this surface — suppress the duplicated body, keep the status tail.
+            liveOutputAlreadyShown: parseCommandOutputResult(result) !== null,
+        });
+        const body = preview.map((line) => INDENT + renderToolLineAnsi(line, colour));
+        // Leading newline mirrors the historical notice framing (the model text stream may have
+        // left the cursor mid-line).
+        emit(['', head, ...body].join('\n'));
+    };
+    return {
+        observe(chunk) {
+            // Order matters: AIMessageChunk extends AIMessage, so test the chunk shape first
+            // (mirrors processEventStream).
+            if (AIMessageChunk.isInstance(chunk)) {
+                const c = chunk;
+                const deltas = c.tool_call_chunks ?? [];
+                if (deltas.length > 0) {
+                    for (const delta of deltas) {
+                        const index = typeof delta.index === 'number' ? delta.index : 0;
+                        const entry = streaming.get(index) ?? { name: '', argsText: '' };
+                        if (delta.id)
+                            entry.id = delta.id;
+                        if (delta.name)
+                            entry.name = entry.name || delta.name;
+                        if (delta.args)
+                            entry.argsText += delta.args;
+                        streaming.set(index, entry);
+                    }
+                }
+                else {
+                    // Some providers surface COMPLETE tool_calls on a chunk instead of deltas.
+                    for (const tc of c.tool_calls ?? []) {
+                        if (tc.id) {
+                            byId.set(tc.id, {
+                                id: tc.id,
+                                name: tc.name,
+                                argsText: JSON.stringify(tc.args ?? {}),
+                            });
+                        }
+                    }
+                }
+                return;
+            }
+            if (AIMessage.isInstance(chunk)) {
+                // A non-chunk AIMessage (resumed/checkpoint-replayed runs) carries final tool_calls.
+                const m = chunk;
+                for (const tc of m.tool_calls ?? []) {
+                    if (tc.id) {
+                        byId.set(tc.id, { id: tc.id, name: tc.name, argsText: JSON.stringify(tc.args ?? {}) });
+                    }
+                }
+                return;
+            }
+            if (chunk instanceof ToolMessage) {
+                // The round is over: park any streamed calls under their ids (chunk indexes restart
+                // next round), then render the arrived result. Fail-soft — rendering must never break
+                // the run.
+                try {
+                    flushStreamingIntoById();
+                    renderToolMessage(chunk);
+                }
+                catch {
+                    /* indication is best-effort; the model-facing stream is untouched */
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=plainToolIndication.js.map

package/dist/core/plainToolIndication.js.map

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

package/dist/core/runStats.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * GS2-16 — pure, fail-soft helpers that harvest per-run analytics (token usage + invoked tool
+ * names) from LangChain messages, so the opt-in history recorder can populate `gth insights`
+ * with real numbers instead of zeros.
+ *
+ * The extraction is deliberately structural and defensive (duck-typed reads guarded by a
+ * try/catch) rather than `instanceof`-based: the same accumulator serves both the non-streaming
+ * `invoke` path (a full `messages[]` from graph state) and the streaming paths (individual
+ * message chunks / `ToolMessage`s as they arrive), across providers whose message shapes vary.
+ * Nothing here may throw into a run — a missing/odd field just means that datum is skipped.
+ */
+import type { GthRunStats } from '#src/core/types.js';
+/** Mutable tally behind {@link finalizeRunStats}; see {@link createRunStatsAccumulator}. */
+export interface RunStatsAccumulator {
+    /** Running sum of input/prompt tokens. */
+    input: number;
+    /** Running sum of output/completion tokens. */
+    output: number;
+    /** Whether ANY message reported `usage_metadata` — gates whether tokens are recorded at all. */
+    sawUsage: boolean;
+    /** Deduplicated set of invoked tool names. */
+    tools: Set<string>;
+}
+/** A fresh, empty accumulator. */
+export declare function createRunStatsAccumulator(): RunStatsAccumulator;
+/**
+ * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
+ * shape is swallowed so a run is never affected. Harvests, when present:
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`), and
+ * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured.
+ */
+export declare function accumulateMessage(acc: RunStatsAccumulator, message: unknown): void;
+/** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */
+export declare function finalizeRunStats(acc: RunStatsAccumulator): GthRunStats;
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export declare function extractRunStats(messages: unknown): GthRunStats;

package/dist/core/runStats.js

@@ -0,0 +1,73 @@
+/** A fresh, empty accumulator. */
+export function createRunStatsAccumulator() {
+    return { input: 0, output: 0, sawUsage: false, tools: new Set() };
+}
+/**
+ * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
+ * shape is swallowed so a run is never affected. Harvests, when present:
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`), and
+ * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured.
+ */
+export function accumulateMessage(acc, message) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const m = message;
+        if (!m || typeof m !== 'object')
+            return;
+        const usage = m.usage_metadata;
+        if (usage && typeof usage === 'object') {
+            acc.sawUsage = true;
+            if (typeof usage.input_tokens === 'number' && Number.isFinite(usage.input_tokens)) {
+                acc.input += usage.input_tokens;
+            }
+            if (typeof usage.output_tokens === 'number' && Number.isFinite(usage.output_tokens)) {
+                acc.output += usage.output_tokens;
+            }
+        }
+        // Requested tool calls (AIMessage / AIMessageChunk). Continuation chunks in a streamed
+        // tool call carry an empty name, so guard on a non-empty string; the Set dedupes repeats.
+        const toolCalls = m.tool_calls;
+        if (Array.isArray(toolCalls)) {
+            for (const tc of toolCalls) {
+                const name = tc?.name;
+                if (typeof name === 'string' && name.length > 0)
+                    acc.tools.add(name);
+            }
+        }
+        // Executed tool result (ToolMessage). Its `.name` is the tool that produced the result.
+        const type = typeof m.getType === 'function' ? m.getType() : m._getType?.();
+        if (type === 'tool' && typeof m.name === 'string' && m.name.length > 0) {
+            acc.tools.add(m.name);
+        }
+    }
+    catch {
+        /* fail-soft: never let stats capture affect a run */
+    }
+}
+/** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */
+export function finalizeRunStats(acc) {
+    return {
+        tokensInput: acc.sawUsage ? acc.input : undefined,
+        tokensOutput: acc.sawUsage ? acc.output : undefined,
+        tools: [...acc.tools],
+    };
+}
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export function extractRunStats(messages) {
+    const acc = createRunStatsAccumulator();
+    try {
+        if (Array.isArray(messages)) {
+            for (const m of messages)
+                accumulateMessage(acc, m);
+        }
+    }
+    catch {
+        /* fail-soft */
+    }
+    return finalizeRunStats(acc);
+}
+//# sourceMappingURL=runStats.js.map

package/dist/core/runStats.js.map

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

package/dist/core/shell/ShellCommandFailedError.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * body so a softening middleware can hand the model the exact observation it saw before — the
+ * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
+ *
+ * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
+ * `agent → core` dependency direction:
+ *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
+ *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ *
+ * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
+ * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export declare class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    readonly output: string;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    readonly exitCode: number | null;
+    /** The exact command string that was executed. */
+    readonly command: string;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    readonly toolName: string;
+    constructor(params: {
+        output: string;
+        exitCode: number | null;
+        command: string;
+        toolName: string;
+    });
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export declare function isShellCommandFailedError(e: unknown): e is ShellCommandFailedError;

package/dist/core/shell/ShellCommandFailedError.js

@@ -0,0 +1,68 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * body so a softening middleware can hand the model the exact observation it saw before — the
+ * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
+ *
+ * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
+ * `agent → core` dependency direction:
+ *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
+ *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ *
+ * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
+ * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    output;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    exitCode;
+    /** The exact command string that was executed. */
+    command;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    toolName;
+    constructor(params) {
+        // Use the full body as the Error message so any generic logger/handler still surfaces the
+        // real command output rather than an opaque wrapper string.
+        super(params.output);
+        this.name = 'ShellCommandFailedError';
+        this.output = params.output;
+        this.exitCode = params.exitCode;
+        this.command = params.command;
+        this.toolName = params.toolName;
+    }
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export function isShellCommandFailedError(e) {
+    if (e instanceof ShellCommandFailedError)
+        return true;
+    return (typeof e === 'object' &&
+        e !== null &&
+        e.name === 'ShellCommandFailedError' &&
+        typeof e.output === 'string' &&
+        typeof e.command === 'string' &&
+        typeof e.toolName === 'string');
+}
+//# sourceMappingURL=ShellCommandFailedError.js.map

package/dist/core/shell/ShellCommandFailedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellCommandFailedError.js","sourceRoot":"","sources":["../../../src/core/shell/ShellCommandFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,iGAAiG;IACxF,MAAM,CAAS;IACxB,oGAAoG;IAC3F,QAAQ,CAAgB;IACjC,kDAAkD;IACzC,OAAO,CAAS;IACzB,4FAA4F;IACnF,QAAQ,CAAS;IAE1B,YAAY,MAKX;QACC,0FAA0F;QAC1F,4DAA4D;QAC5D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,CAAU;IAClD,IAAI,CAAC,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,yBAAyB;QAC5D,OAAQ,CAA0B,CAAC,MAAM,KAAK,QAAQ;QACtD,OAAQ,CAA2B,CAAC,OAAO,KAAK,QAAQ;QACxD,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/core/shell/allowlist.d.ts

@@ -0,0 +1,75 @@
+import type { ToolApprovalScope } from '#src/core/types.js';
+/**
+ * Approval persistence scopes, widest-lived last. Alias of the canonical
+ * {@link ToolApprovalScope} so the allow-list engine and the decision vocabulary stay in sync.
+ */
+export type ApprovalScope = ToolApprovalScope;
+/**
+ * Decide whether a candidate argv contains a flag that *widens* the approved operation.
+ *
+ * Rule implemented (documented for the coordinator):
+ *  - Re-derive the meaningful prefix from the candidate's actual argv.
+ *  - Inspect every token of the candidate that is a flag (starts with `-`).
+ *  - If any flag token — normalized by stripping a trailing `=value` and lowercasing —
+ *    is in {@link WIDENING_FLAGS}, the command is considered a widening of the approved
+ *    operation and the match is REFUSED (returns true).
+ *
+ * This is purposely a deny-list of operation-changing flags rather than an allow-list of
+ * benign flags: benign flag variants (`-b`, `--oneline`, `-la`) are exactly what we WANT
+ * to keep auto-approving, while the handful of "run-an-arbitrary-program / redirect-the-
+ * transport" flags are what an injected approval must never silently enable.
+ */
+export declare function hasWideningFlag(argv: string[]): boolean;
+/**
+ * A holder of approved prefixes with set semantics. Used for both the in-memory session
+ * store and the loaded persisted store. Pure data + membership; persistence is layered on
+ * top by {@link PersistedAllowlist}.
+ */
+export declare class AllowlistStore {
+    private readonly prefixes;
+    constructor(initial?: Iterable<string>);
+    has(prefix: string): boolean;
+    add(prefix: string): void;
+    list(): string[];
+}
+/**
+ * The persisted (`always`) allow-list, backed by a JSON file. The path is injected (the
+ * runner resolves it via fileUtils → `.gsloth/.gsloth-settings/shell-allowlist.json`) so
+ * tests can point it at a temp dir. Loads lazily/defensively: a missing or malformed file
+ * yields an empty store rather than throwing (fail-open on READ is safe — an empty
+ * allow-list just means "prompt"; it never auto-approves anything).
+ */
+export declare class PersistedAllowlist {
+    private readonly store;
+    private readonly filePath;
+    constructor(filePath: string);
+    private static load;
+    has(prefix: string): boolean;
+    list(): string[];
+    /** Add a prefix and persist the whole set to disk. */
+    add(prefix: string): void;
+    private persist;
+}
+/**
+ * Read-only view over the stores consulted for an auto-approval check. The runner passes
+ * its per-instance session store and (optionally) the persisted store.
+ */
+export interface ApprovalStores {
+    session: Pick<AllowlistStore, 'has'>;
+    always?: Pick<PersistedAllowlist, 'has'>;
+}
+/**
+ * Decide whether `command` is already approved by the given stores — the gate the runner
+ * consults BEFORE prompting the human.
+ *
+ * Returns true ONLY when ALL of the following hold:
+ *  1. {@link classifyCommand} returns a non-null classification (so composition /
+ *     substitution / redirection commands can never match — anti-injection layer 1);
+ *  2. the classified prefix is present in the session OR persisted (`always`) store; AND
+ *  3. the safe-bin re-validation passes: the candidate's actual argv contains no
+ *     operation-widening flag (anti-injection layer 2 — see {@link hasWideningFlag}).
+ *
+ * Anything else (unclassifiable, unknown prefix, or a widening flag) → false → the human
+ * is prompted. Fail-closed by construction.
+ */
+export declare function matchesApproval(command: string, stores: ApprovalStores): boolean;