@gaunt-sloth/core 2.0.0-alpha.1 → 2.0.0-alpha.10

package/dist/core/debugCapture.d.ts

@@ -0,0 +1,59 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * The non-message parts of a `wrapModelCall` request that also shape a turn: the tool
+ * definitions, the system prompt, and the model params. Captured alongside the message
+ * history so the `/debug` panel can show the full picture of what was sent to the model.
+ *
+ * SECURITY: these are assembled from an explicit allowlist at the capture site
+ * (see {@link extractDebugRequestExtras}); the raw model instance (which can carry an
+ * `apiKey`) is never passed through here.
+ */
+export interface DebugRequestExtras {
+    /** The composed system prompt string sent to the model for this call. */
+    systemPrompt?: string;
+    /** The tool definitions made available for this call (name + description + JSON schema). */
+    tools?: DebugToolDef[];
+    /** Scalar model params (model id, temperature, …) — a key-free allowlist. */
+    modelParams?: Record<string, unknown>;
+    /** The tool-choice configuration for this call, if any. */
+    toolChoice?: unknown;
+}
+/** A single tool's debug-renderable definition. */
+export interface DebugToolDef {
+    name: string;
+    description?: string;
+    /** The tool's JSON-schema parameters, when resolvable. */
+    schema?: unknown;
+}
+/**
+ * Debug-capture sink for the TUI's `/debug` panel.
+ *
+ * A {@link DebugCapture} is an OPT-IN callback the TUI sets on a live agent after `init`
+ * (on the shared {@link import('#src/core/GthAbstractAgent.js').GthAbstractAgent} base, so
+ * both the lean and deep backends support it). When present, the agent's `wrapModelCall`
+ * middleware reports, per model call:
+ *
+ * - `request` — `request.messages: BaseMessage[]`, the real history sent to the model at
+ *   call time (post-summarization / post-middleware), plus the {@link DebugRequestExtras}
+ *   (tools, system prompt, model params) that also shape the turn. This is exactly what the
+ *   model saw.
+ * - `response` — the resolved `AIMessage` returned by the handler, captured as a whole
+ *   (resolved message, not per-chunk frames; keeps the streaming core untouched).
+ *
+ * The sink is read lazily inside the middleware (per call), so when no TUI debug panel is
+ * attached the middleware is a transparent pass-through and the normal path pays nothing.
+ */
+export interface DebugCapture {
+    /** The full message history sent to the model for this call, plus the request extras. */
+    onRequest?(messages: BaseMessage[], extras?: DebugRequestExtras): void;
+    /** The resolved model response for this call (an `AIMessage`). */
+    onResponse?(response: unknown): void;
+}
+/**
+ * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
+ * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
+ * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * Shared by both the lean ({@link import('#src/core/GthLangChainAgent.js').GthLangChainAgent})
+ * and deep backends so the panel behaves identically on either.
+ */
+export declare function extractDebugRequestExtras(request: unknown): DebugRequestExtras | undefined;

package/dist/core/debugCapture.js

@@ -0,0 +1,101 @@
+/**
+ * Scalar model-param fields worth surfacing in the `/debug` panel. Deliberately an
+ * allowlist (NOT a whole-object dump) so no credential field (`apiKey`, `accessToken`, …)
+ * can ever leak into the rendered debug view.
+ *
+ * `streaming` is intentionally NOT here: it is the model instance's static flag, which is
+ * usually `false` even when the turn streams — the GthAgentRunner decides streaming by calling
+ * `.stream()` vs `.invoke()`, not by this property — so surfacing it just misleads.
+ */
+const DEBUG_MODEL_PARAM_KEYS = [
+    'model',
+    'modelName',
+    'modelId',
+    'deploymentName',
+    'temperature',
+    'topP',
+    'topK',
+    'maxTokens',
+    'maxOutputTokens',
+    'maxReasoningTokens',
+    'reasoningEffort',
+    'thinkingBudget',
+    'stop',
+    'provider',
+];
+/** Pull the key-free scalar model params from the (provider-specific) model instance. */
+function extractModelParams(model) {
+    if (!model || typeof model !== 'object')
+        return undefined;
+    const src = model;
+    const out = {};
+    for (const key of DEBUG_MODEL_PARAM_KEYS) {
+        const value = src[key];
+        if (value === undefined || value === null)
+            continue;
+        // Only scalars / scalar arrays — never nested objects that could carry credentials.
+        if (typeof value === 'object' && !Array.isArray(value))
+            continue;
+        out[key] = value;
+    }
+    // `model` / `modelName` / `modelId` are langchain aliases for the same value; collapse the
+    // duplicates so the panel shows the model id once instead of two identical lines.
+    if (typeof out.model !== 'string' && typeof out.modelName === 'string') {
+        out.model = out.modelName;
+    }
+    if (out.modelName === out.model)
+        delete out.modelName;
+    if (out.modelId === out.model)
+        delete out.modelId;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Best-effort tool definition (name + description + schema) for the debug view. */
+function extractToolDefs(tools) {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return undefined;
+    const defs = [];
+    for (const tool of tools) {
+        if (!tool || typeof tool !== 'object')
+            continue;
+        const t = tool;
+        const name = typeof t.name === 'string' ? t.name : undefined;
+        if (!name)
+            continue;
+        const description = typeof t.description === 'string' ? t.description : undefined;
+        // LangChain StructuredTools expose a Zod/JSON `schema`; some carry it on `lc_kwargs`.
+        const schema = t.schema ?? undefined;
+        defs.push({ name, description, schema });
+    }
+    return defs.length > 0 ? defs : undefined;
+}
+/**
+ * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
+ * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
+ * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * Shared by both the lean ({@link import('#src/core/GthLangChainAgent.js').GthLangChainAgent})
+ * and deep backends so the panel behaves identically on either.
+ */
+export function extractDebugRequestExtras(request) {
+    if (!request || typeof request !== 'object')
+        return undefined;
+    const req = request;
+    const systemMessage = req.systemMessage;
+    const systemPrompt = typeof req.systemPrompt === 'string' && req.systemPrompt
+        ? req.systemPrompt
+        : typeof systemMessage?.content === 'string'
+            ? systemMessage.content
+            : undefined;
+    const extras = {
+        systemPrompt,
+        tools: extractToolDefs(req.tools),
+        modelParams: extractModelParams(req.model),
+        toolChoice: req.toolChoice,
+    };
+    // Return undefined when nothing useful was captured so the renderer can show a clear empty state.
+    const hasAny = extras.systemPrompt !== undefined ||
+        extras.tools !== undefined ||
+        extras.modelParams !== undefined ||
+        extras.toolChoice !== undefined;
+    return hasAny ? extras : undefined;
+}
+//# sourceMappingURL=debugCapture.js.map

package/dist/core/debugCapture.js.map

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

package/dist/core/gthLeanAgentFactory.d.ts

@@ -0,0 +1,9 @@
+import type { GthAgentFactory } from '#src/core/types.js';
+/**
+ * The lean backend factory — a {@link GthAgentFactory} that produces a plain
+ * {@link GthLangChainAgent} (no deepagents graph). This is identical to the built-in
+ * default {@link GthAgentRunner} constructs when no factory is passed; exporting it lets
+ * `@gaunt-sloth/agent`'s {@link resolveAgentFactory} pick lean vs deep from config without
+ * duplicating the constructor call.
+ */
+export declare const gthLeanAgentFactory: GthAgentFactory;

package/dist/core/gthLeanAgentFactory.js

@@ -0,0 +1,10 @@
+import { GthLangChainAgent } from '#src/core/GthLangChainAgent.js';
+/**
+ * The lean backend factory — a {@link GthAgentFactory} that produces a plain
+ * {@link GthLangChainAgent} (no deepagents graph). This is identical to the built-in
+ * default {@link GthAgentRunner} constructs when no factory is passed; exporting it lets
+ * `@gaunt-sloth/agent`'s {@link resolveAgentFactory} pick lean vs deep from config without
+ * duplicating the constructor call.
+ */
+export const gthLeanAgentFactory = (statusUpdate, resolvers) => new GthLangChainAgent(statusUpdate, resolvers);
+//# sourceMappingURL=gthLeanAgentFactory.js.map

package/dist/core/gthLeanAgentFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gthLeanAgentFactory.js","sourceRoot":"","sources":["../../src/core/gthLeanAgentFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAoB,CAAC,YAAY,EAAE,SAAS,EAAE,EAAE,CAC9E,IAAI,iBAAiB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC"}

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;