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

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;

package/dist/core/shell/allowlist.js

@@ -0,0 +1,187 @@
+/**
+ * @module core/shell/allowlist
+ *
+ * EXT-9 Tier-2: the persisted + session-scoped allow-list engine for the opt-in
+ * `run_shell_command` tool. Once a human approves a command at `session` or `always`
+ * scope, future commands with the same classified prefix ({@link classifyCommand}) are
+ * auto-approved without re-prompting — the ergonomics improvement mature agents
+ * (opencode/openclaw/hermes) ship.
+ *
+ * SECURITY — a naive "remember the prefix" allow-list is an injection vector. Two layers
+ * guard it:
+ *  1. **Classification fail-closed** (arity.ts): any command with shell composition,
+ *     substitution, or redirection returns `null` and can NEVER match, so
+ *     `git checkout x; rm -rf /` does not ride an approved `git checkout *`.
+ *  2. **Safe-bin anti-widening re-validation** (here, after opencode/openclaw): a stored
+ *     approval is matched ONLY if the candidate command's first non-flag operand region
+ *     does not introduce a flag that *widens or redirects* the approved operation. The
+ *     exact rule is documented on {@link matchesApproval} / {@link hasWideningFlag}.
+ *
+ * No module-global mutable state: the session store is a per-instance class so concurrent
+ * sessions (ACP / AG-UI multi-session) cannot stomp each other. The persisted (`always`)
+ * store is a small JSON file the runner loads once per instance.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { classifyCommand, tokenize } from '#src/core/shell/arity.js';
+import { normalizeCommand } from '#src/core/shell/normalize.js';
+const PERSISTED_VERSION = 1;
+/**
+ * Flags that, if present in a candidate command but not implied by the approved prefix,
+ * could change the *operation* the human approved (point it at a different transport,
+ * exec a hook, follow an attacker-controlled URL). Approving `git clone` must not
+ * green-light `git clone --upload-pack=evil`. This list is intentionally conservative:
+ * it is the openclaw "safe-bin" idea reduced to a deny-set of operation-changing flags
+ * that commonly appear in shell-injection / supply-chain abuse.
+ *
+ * Matched against the flag token with any `=value` stripped, case-insensitively.
+ */
+const WIDENING_FLAGS = new Set([
+    // git: remote command / hook overrides.
+    '--upload-pack',
+    '--receive-pack',
+    '--exec',
+    '-u', // git clone -u <upload-pack>
+    '--config', // git -c is the short form; --config can inject core.sshCommand etc.
+    '-c', // git -c core.sshCommand='...' — arbitrary command execution
+    // generic "run this program" escape hatches across tools.
+    '--exec-path',
+    '-exec', // find -exec <cmd>
+    '--use-askpass',
+    '--ssh-command',
+    // package managers: lifecycle-script / arbitrary-script toggles.
+    '--unsafe-perm',
+    '--ignore-scripts=false',
+    '--allow-scripts',
+    // curl/wget style follow/exec (in case a bare binary is approved).
+    '-o', // write to arbitrary path
+    '--output',
+    '-T', // upload
+    '--upload-file',
+]);
+/**
+ * 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 function hasWideningFlag(argv) {
+    for (const tok of argv) {
+        if (!tok.startsWith('-'))
+            continue;
+        const bare = tok.split('=', 1)[0].toLowerCase();
+        if (WIDENING_FLAGS.has(bare))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 class AllowlistStore {
+    prefixes;
+    constructor(initial = []) {
+        this.prefixes = new Set(initial);
+    }
+    has(prefix) {
+        return this.prefixes.has(prefix);
+    }
+    add(prefix) {
+        this.prefixes.add(prefix);
+    }
+    list() {
+        return [...this.prefixes];
+    }
+}
+/**
+ * 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 class PersistedAllowlist {
+    store;
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.store = new AllowlistStore(PersistedAllowlist.load(filePath));
+    }
+    static load(filePath) {
+        try {
+            if (!existsSync(filePath))
+                return [];
+            const raw = readFileSync(filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || !Array.isArray(parsed.prefixes))
+                return [];
+            return parsed.prefixes.filter((p) => typeof p === 'string');
+        }
+        catch {
+            // Corrupt/unreadable file → behave as empty (fail-closed on auto-approval).
+            return [];
+        }
+    }
+    has(prefix) {
+        return this.store.has(prefix);
+    }
+    list() {
+        return this.store.list();
+    }
+    /** Add a prefix and persist the whole set to disk. */
+    add(prefix) {
+        if (this.store.has(prefix))
+            return;
+        this.store.add(prefix);
+        this.persist();
+    }
+    persist() {
+        const file = {
+            version: PERSISTED_VERSION,
+            prefixes: this.store.list().sort(),
+        };
+        writeFileSync(this.filePath, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    }
+}
+/**
+ * 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 function matchesApproval(command, stores) {
+    const classification = classifyCommand(command, normalizeCommand);
+    if (!classification)
+        return false; // layer 1: composition/redirection/substitution.
+    const approved = stores.session.has(classification.prefix) ||
+        (stores.always?.has(classification.prefix) ?? false);
+    if (!approved)
+        return false;
+    // Layer 2: re-derive argv from the normalized command and refuse if an operation-
+    // widening flag is present that the human's prefix-level approval never implied.
+    const argv = tokenize(normalizeCommand(command));
+    if (!argv)
+        return false; // unbalanced quoting → fail-closed.
+    if (hasWideningFlag(argv))
+        return false;
+    return true;
+}
+//# sourceMappingURL=allowlist.js.map

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

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

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

@@ -0,0 +1,75 @@
+/**
+ * @module core/shell/arity
+ *
+ * EXT-9 Tier-2 ergonomics: classify a shell command into a stable, human-readable
+ * **prefix** (binary + N meaningful subcommands) so an approval the human grants once
+ * (`git checkout main`) can be remembered as a pattern (`git checkout *`) and matched
+ * against later flag-variants (`git checkout -b foo bar`) WITHOUT re-prompting.
+ *
+ * The arity table (which tokens past the binary are "meaningful subcommands" rather
+ * than operands/flags) is a port of a subset of opencode's ~160-command table
+ * (`opencode/packages/opencode/src/permission/arity.ts`). Binaries not in the table
+ * default to arity 0 = just the binary.
+ *
+ * SECURITY — this is the anti-injection core. {@link classifyCommand} returns `null`
+ * (fail-closed) whenever the command contains shell composition that could change the
+ * target of the operation: separators (`;`, `&&`, `||`, `|`, `&`), newlines, command
+ * substitution (`$(...)`, backticks), process substitution (`<(...)`/`>(...)`), or
+ * redirections. Such commands NEVER auto-match an allow-list entry — they always go to
+ * fresh human approval. This is what stops `git checkout x; rm -rf /` from matching an
+ * approved `git checkout *`.
+ */
+/**
+ * Result of classifying a command for allow-list matching.
+ */
+export interface CommandClassification {
+    /**
+     * The meaningful command prefix — binary plus subcommands per the arity table, with
+     * flags removed. This is the allow-list KEY: two commands with the same prefix are the
+     * "same operation" for approval purposes (`git checkout main` and `git checkout -b x`
+     * both → `git checkout`).
+     */
+    prefix: string;
+    /**
+     * Human-facing display pattern, e.g. `git checkout *` (or `ls *`). The trailing `*`
+     * signals "any args/flags". A prefix that already consumed the whole command (no extra
+     * operands) still gets ` *` for a consistent, honest "future args allowed" affordance.
+     */
+    pattern: string;
+}
+/**
+ * Tokenize a shell command into argv, honoring single and double quotes. Quotes group
+ * (and are stripped from) a token; backslash-escaping inside double quotes is collapsed
+ * by the prior normalize step, so this tokenizer treats a residual `\` literally.
+ *
+ * This is a deliberately small tokenizer used ONLY for prefix detection — never for
+ * execution. The original command string is what runs.
+ *
+ * Returns `null` if quoting is unbalanced (an open quote with no close), which is itself
+ * a reason to refuse classification (ambiguous parse → fail-closed).
+ */
+export declare function tokenize(command: string): string[] | null;
+/**
+ * Look up the arity (number of leading meaningful tokens) for an argv, using the
+ * longest-matching-prefix rule against {@link ARITY}. Flag tokens (starting with `-`) are
+ * dropped when forming the candidate prefixes so boolean flags like `git --no-pager
+ * checkout` still resolve `git checkout`. Unknown binaries default to arity 0 → just the
+ * binary.
+ *
+ * LIMITATION (intentional, fail-closed): we do NOT maintain a per-flag arity table, so an
+ * arg-taking flag leaves its operand in the non-flag stream (e.g. `git -C . checkout` →
+ * `git .`). That simply fails to match an approved `git checkout` and re-prompts — safe, by
+ * design — rather than risking a mis-classification that mis-approves.
+ *
+ * Returns the list of meaningful tokens (binary + subcommands), flag tokens excluded.
+ */
+export declare function meaningfulPrefixTokens(argv: string[]): string[];
+/**
+ * Classify a command into a stable allow-list prefix + display pattern, or `null` when it
+ * cannot be safely classified for matching (composition/redirection/substitution present,
+ * empty, or unbalanced quotes).
+ *
+ * @param command Raw command string as the model proposed it.
+ * @param normalize Normalizer to apply for the detection form (inject normalizeCommand).
+ */
+export declare function classifyCommand(command: string, normalize: (cmd: string) => string): CommandClassification | null;