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

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;

package/dist/core/shell/arity.js

@@ -0,0 +1,313 @@
+/**
+ * @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 *`.
+ */
+/**
+ * Arity table: command-prefix string → number of leading tokens (binary + subcommands,
+ * flags excluded) that define the "human-understandable command". Longest matching
+ * prefix wins. Ported subset of opencode's table — git/npm/pnpm/yarn/docker/kubectl/
+ * cargo/go/etc. Binaries absent here default to arity 0 (just the binary), see
+ * {@link arityFor}.
+ *
+ * Rule (from opencode): flags never count as tokens; only subcommands do. Include a
+ * longer prefix only when its arity differs from what the shorter prefix implies.
+ */
+const ARITY = {
+    // Single-token utilities (arity 1 = just the binary; here for completeness/clarity).
+    cat: 1,
+    cd: 1,
+    chmod: 1,
+    chown: 1,
+    cp: 1,
+    echo: 1,
+    env: 1,
+    export: 1,
+    grep: 1,
+    kill: 1,
+    killall: 1,
+    ln: 1,
+    ls: 1,
+    mkdir: 1,
+    mv: 1,
+    ps: 1,
+    pwd: 1,
+    rm: 1,
+    rmdir: 1,
+    sleep: 1,
+    source: 1,
+    tail: 1,
+    head: 1,
+    touch: 1,
+    unset: 1,
+    which: 1,
+    find: 1,
+    // Cloud / infra CLIs.
+    aws: 3,
+    az: 3,
+    bazel: 2,
+    brew: 2,
+    bun: 2,
+    'bun run': 3,
+    'bun x': 3,
+    cargo: 2,
+    'cargo add': 3,
+    'cargo run': 3,
+    cdk: 2,
+    cf: 2,
+    cmake: 2,
+    composer: 2,
+    consul: 2,
+    'consul kv': 3,
+    crictl: 2,
+    deno: 2,
+    'deno task': 3,
+    doctl: 3,
+    docker: 2,
+    'docker builder': 3,
+    'docker compose': 3,
+    'docker container': 3,
+    'docker image': 3,
+    'docker network': 3,
+    'docker volume': 3,
+    eksctl: 2,
+    'eksctl create': 3,
+    firebase: 2,
+    flyctl: 2,
+    gcloud: 3,
+    gh: 3,
+    git: 2,
+    'git config': 3,
+    'git remote': 3,
+    'git stash': 3,
+    go: 2,
+    gradle: 2,
+    helm: 2,
+    heroku: 2,
+    hugo: 2,
+    ip: 2,
+    'ip addr': 3,
+    'ip link': 3,
+    'ip netns': 3,
+    'ip route': 3,
+    kind: 2,
+    'kind create': 3,
+    kubectl: 2,
+    'kubectl kustomize': 3,
+    'kubectl rollout': 3,
+    kustomize: 2,
+    make: 2,
+    mc: 2,
+    'mc admin': 3,
+    minikube: 2,
+    mongosh: 2,
+    mysql: 2,
+    mvn: 2,
+    ng: 2,
+    npm: 2,
+    'npm exec': 3,
+    'npm init': 3,
+    'npm run': 3,
+    'npm view': 3,
+    npx: 2,
+    nvm: 2,
+    nx: 2,
+    openssl: 2,
+    'openssl req': 3,
+    'openssl x509': 3,
+    pip: 2,
+    pipenv: 2,
+    pnpm: 2,
+    'pnpm dlx': 3,
+    'pnpm exec': 3,
+    'pnpm run': 3,
+    poetry: 2,
+    podman: 2,
+    'podman container': 3,
+    'podman image': 3,
+    psql: 2,
+    pulumi: 2,
+    'pulumi stack': 3,
+    pyenv: 2,
+    python: 2,
+    python3: 2,
+    rake: 2,
+    rbenv: 2,
+    'redis-cli': 2,
+    rustup: 2,
+    serverless: 2,
+    sfdx: 3,
+    skaffold: 2,
+    sls: 2,
+    sst: 2,
+    swift: 2,
+    systemctl: 2,
+    terraform: 2,
+    'terraform workspace': 3,
+    tmux: 2,
+    turbo: 2,
+    ufw: 2,
+    vault: 2,
+    'vault auth': 3,
+    'vault kv': 3,
+    vercel: 2,
+    volta: 2,
+    wp: 2,
+    yarn: 2,
+    'yarn dlx': 3,
+    'yarn run': 3,
+};
+/**
+ * Tokens / sequences whose presence means the command composes or redirects in a way that
+ * could change what actually runs — so it must NOT be classifiable for auto-match. Checked
+ * against the NORMALIZED command (see normalize.ts) which has already collapsed obfuscation.
+ *
+ * Note: `&&`/`||`/`|` are covered by the bare `&`/`|` character scan; listed conceptually.
+ */
+function hasUnsafeComposition(normalized) {
+    // Newlines are folded by normalizeCommand, but guard anyway in case a raw string is passed.
+    if (/[\n\r]/.test(normalized))
+        return true;
+    // Shell control / separator operators and background.
+    if (/[;|&]/.test(normalized))
+        return true;
+    // Command substitution: $(...) or `...`.
+    if (/\$\(/.test(normalized))
+        return true;
+    if (/`/.test(normalized))
+        return true;
+    // Variable/arith expansion that could inject: ${...} and $((...)).
+    if (/\$\{/.test(normalized))
+        return true;
+    // Process substitution: <(...) or >(...).
+    if (/[<>]\(/.test(normalized))
+        return true;
+    // Redirections (any < or > not already caught as process substitution): >, >>, <, 2>, &>.
+    if (/[<>]/.test(normalized))
+        return true;
+    return false;
+}
+/**
+ * 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 function tokenize(command) {
+    const tokens = [];
+    let current = '';
+    let inToken = false;
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            inToken = true;
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (inToken) {
+                tokens.push(current);
+                current = '';
+                inToken = false;
+            }
+            continue;
+        }
+        current += ch;
+        inToken = true;
+    }
+    if (quote)
+        return null; // unbalanced quote
+    if (inToken)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * 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 function meaningfulPrefixTokens(argv) {
+    // Drop leading flags before the binary cannot happen (binary is first), but a binary
+    // can be followed by flags interleaved with subcommands (e.g. `git -C . checkout`).
+    // Build the flag-free token sequence first, preserving order.
+    const nonFlag = argv.filter((t) => !t.startsWith('-'));
+    if (nonFlag.length === 0)
+        return [];
+    // Longest matching prefix in the arity table wins.
+    for (let len = nonFlag.length; len > 0; len--) {
+        const candidate = nonFlag.slice(0, len).join(' ');
+        const arity = ARITY[candidate];
+        if (arity !== undefined) {
+            // arity counts meaningful tokens from the start of the non-flag sequence.
+            return nonFlag.slice(0, Math.min(arity, nonFlag.length));
+        }
+    }
+    // Not in the table → arity 0 means "just the binary".
+    return nonFlag.slice(0, 1);
+}
+/**
+ * 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 function classifyCommand(command, normalize) {
+    const normalized = normalize(command);
+    if (!normalized)
+        return null;
+    // FAIL-CLOSED on any composition/redirection/substitution. This is the anti-injection
+    // guarantee: such commands never auto-match an allow-list entry.
+    if (hasUnsafeComposition(normalized))
+        return null;
+    const argv = tokenize(normalized);
+    if (!argv || argv.length === 0)
+        return null;
+    const prefixTokens = meaningfulPrefixTokens(argv);
+    if (prefixTokens.length === 0)
+        return null;
+    const prefix = prefixTokens.join(' ');
+    return { prefix, pattern: `${prefix} *` };
+}
+//# sourceMappingURL=arity.js.map

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

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