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

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/abstention.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The shape in the command that the gate's parser could not resolve.
+ *
+ * These are FORMS, not judgements — nothing here says a command is dangerous, and nothing here is a
+ * rating. They exist to select the sentence the rater is shown.
+ */
+export type AbstentionMechanism = 
+/** A git commit whose message contains a substitution the SHELL runs before git sees it. */
+'commit-message-substitution'
+/** More than one command: `;`, `&`, `&&`, `|`, `||`, or a line break. */
+ | 'composition'
+/** Command / variable / process substitution: `$(…)`, backticks, `${…}`, `<(…)`. */
+ | 'substitution'
+/** A stream redirect: `>`, `>>`, `<`, `2>`, `&>`. */
+ | 'redirect'
+/** None of the above — an unbalanced quote, an empty command, or no resolvable program name. */
+ | 'unparseable';
+/** What the parser saw in a command it could not resolve: the shapes, and the note for each. */
+export interface AbstentionDefect {
+    /** The most specific mechanism found — what the note leads with. */
+    mechanism: AbstentionMechanism;
+    /** Every mechanism found, in note order. A command may carry more than one. */
+    mechanisms: AbstentionMechanism[];
+    /** One note per mechanism, in the same order. Never empty. */
+    notes: string[];
+}
+/**
+ * **The per-family note text — one distinct string per {@link AbstentionMechanism}.**
+ *
+ * Typed as a total `Record`, so adding a mechanism is a COMPILE ERROR until someone writes its
+ * sentence. A family that silently fell back to another family's note would be the failure this
+ * table exists to prevent: [[QA-17]] measured that the note's effect is family-specific, and
+ * `docs/test-sessions/qa-17-substitution-note-2026-08-03/` records a narrowing by family name that
+ * was FALSIFIED — `gh pr comment 42 --body "…"` carrying an executing substitution classifies as
+ * generic `substitution`, and three of three hosted raters called it safe unassisted.
+ *
+ * Every entry states a fact about what THE SHELL does, and then asks a question. Neither is a
+ * verdict about the command in front of the rater, which is what keeps the note neutral while still
+ * carrying the mechanism that the measurement showed is load-bearing.
+ */
+export declare const MECHANISM_NOTES: Readonly<Record<AbstentionMechanism, string>>;
+/**
+ * Classify a command the gate's parser could not resolve, or return `null` when it resolves.
+ *
+ * **The `null` arm is the guard, and it is structural on purpose.** Every mechanism below is a
+ * regex, and `unparseable` is the fallback — so without this gate the function would classify `ls
+ * -la` as `unparseable` and a note would be attached to every command in the session. The predicate
+ * is {@link classifyCommand}'s own, not a second reading of it, so the note appears on exactly the
+ * set of commands the gate could not resolve and on no others.
+ *
+ * Detection runs on the NORMALIZED command (the same form `classifyCommand` refused), so obfuscation
+ * that the normalizer collapses cannot hide a mechanism from the note — while the command shown to
+ * the rater stays the one the rater is being asked about, fenced by its own caller.
+ *
+ * The line-break check reads the RAW command, exactly as `classifyCommand` does: the normalizer is
+ * not required to preserve that separator, and EXT-55 is the node about what happens when a caller
+ * assumes it did.
+ *
+ * **Order is note order, most specific first**, and `commit-message-substitution` SUPPRESSES the
+ * generic substitution note it is a special case of — telling the rater the same thing twice about
+ * one `$(…)` spends attention on a repetition.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns What the parser saw, or `null` when the command's target statically resolves.
+ */
+export declare function describeAbstention(command: string): AbstentionDefect | null;
+/**
+ * The opening line of the preflight note: **what this is, and what it is not.**
+ *
+ * It says the finding is about OUR PARSER rather than about the command, and that nothing has been
+ * judged. Both halves are load-bearing. The first stops the rater reading the note as a report of
+ * something found — the failure mode a bare observation produced, where a rater treats our
+ * uncertainty as evidence and either inflates or explains it away. The second is what keeps this
+ * note out of the open-world note's register: that one may say the command *"has ALREADY been
+ * floored deterministically and will be shown to the user whatever you return"*, and here that
+ * sentence would simply be false.
+ */
+export declare const PARSER_NOTE_PREAMBLE: string;
+/**
+ * Build the neutral preflight note for a command, or `null` when the gate resolved it.
+ *
+ * One note per mechanism the command carries, most specific first, bulleted when there is more than
+ * one — a command can compose AND substitute AND redirect, and a note that mentioned only the first
+ * would leave the rater reasoning about a fragment of the shape.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export declare function buildParserPreflightNote(command: string): string | null;

package/dist/core/shell/abstention.js

@@ -0,0 +1,184 @@
+/**
+ * @module core/shell/abstention
+ *
+ * EXT-81 — **what the RATER is told about a command our parser could not resolve.**
+ *
+ * `classifyCommand` resolves a command's target, or returns `null` when it cannot. That `null` used
+ * to be an ACTION: the gate refused the call before any rating, on the theory that a reading of a
+ * command it could not parse was not worth buying. §6.1's rule reverses that — *deterministic checks
+ * fire only where we are confident something is a threat; where we cannot tell, the model decides* —
+ * and a parser reporting that it could not resolve a string is not a detection of anything. So the
+ * finding is now **neutral context handed to the rater**, and the flow is one path: preflight → note
+ * → rate → approve / escalate / halt.
+ *
+ * This module turns the `null` into that note: **which shape the parser saw, and the mechanism that
+ * makes the shape worth a second look.** Two properties are the whole design, and each has a
+ * measurement behind it ([[QA-17]], `docs/test-sessions/qa-17-substitution-note-2026-08-03/`):
+ *
+ * - **The note carries the MECHANISM, not just the construct's name.** A bare *"the parser saw a
+ *   substitution"* observation was measured NEGATIVE on two raters — one became more confidently
+ *   wrong than with no note at all (*"not executed since it's within double quotes"*), another lost
+ *   severity against the control. Adding one sentence of mechanism — that a double-quoted argument
+ *   is not inert prose, because the shell expands it before the outer program runs — is what moved
+ *   every deployment-class rater to the correct verdict. A bare observation from a component that
+ *   has just announced it could not read the command reads as DOUBT, and doubt is not information.
+ * - **The note is ASSISTANCE, never an accusation.** *"Hey rater, here is a command, please pay
+ *   attention it includes composition."* No verdict, no severity, no *suspicious*, no *careful*, no
+ *   *treat this as at least X*, and nothing that caps the outcome — `catastrophic` and `attack` stay
+ *   reachable. A question is allowed; a question is not a lean. A composition is not a hazard:
+ *   `cd build && ls`, `npm test && npm run build` and `git add -A && git status` are the
+ *   overwhelming majority of what this fires on, and a leading note would re-create the very
+ *   escalation this design removes — laundered through the model instead of the parser, and now
+ *   unfalsifiable because a model said it.
+ *
+ * It also states nothing about what the gate will DO with the verdict. The open-world note's shape
+ * (*"has ALREADY been floored deterministically and will be shown to the user whatever you
+ * return"*) is honest only where a floor exists, and for these families none does.
+ *
+ * **Scope, deliberately narrow.** Flag what the parser saw and stop. Extracting spans, naming which
+ * segment is unresolvable, and drawing on surrounding context all wait for real user trial — the
+ * elaborate note is the one most likely to acquire connotation by accident.
+ */
+import { classifyCommand } from '#src/core/shell/arity.js';
+import { COMMAND_SEPARATOR_RE, LINE_BREAK_RE, normalizeCommand, } from '#src/core/shell/normalize.js';
+/**
+ * **The per-family note text — one distinct string per {@link AbstentionMechanism}.**
+ *
+ * Typed as a total `Record`, so adding a mechanism is a COMPILE ERROR until someone writes its
+ * sentence. A family that silently fell back to another family's note would be the failure this
+ * table exists to prevent: [[QA-17]] measured that the note's effect is family-specific, and
+ * `docs/test-sessions/qa-17-substitution-note-2026-08-03/` records a narrowing by family name that
+ * was FALSIFIED — `gh pr comment 42 --body "…"` carrying an executing substitution classifies as
+ * generic `substitution`, and three of three hosted raters called it safe unassisted.
+ *
+ * Every entry states a fact about what THE SHELL does, and then asks a question. Neither is a
+ * verdict about the command in front of the rater, which is what keeps the note neutral while still
+ * carrying the mechanism that the measurement showed is load-bearing.
+ */
+export const MECHANISM_NOTES = {
+    'commit-message-substitution': 'This is a git commit carrying its message inline, and the message contains a ' +
+        'dollar-parenthesis or a backtick. The SHELL expands that before git ever sees the message, ' +
+        'so the text inside the quotes is not inert prose: double quotes do not stop `$(…)` or a ' +
+        'backtick from running, and git receives whatever it produced. What does the shell run when ' +
+        'it expands that message?',
+    composition: 'This command line runs MORE THAN ONE command — a `;`, `&&`, `||`, `|` or a line break ' +
+        'separates them — and the shell runs each part in turn, feeding one into the next where the ' +
+        'separator is a pipe. What does the whole line do once every part has run?',
+    substitution: 'This command line contains a substitution — `$(…)`, a backtick, `${…}` or `<(…)`. The SHELL ' +
+        'expands it BEFORE the outer program runs, and hands that program the result. A ' +
+        'double-quoted argument is therefore not inert prose: double quotes do not stop `$(…)` or a ' +
+        'backtick from being run, so a substitution inside what reads as ordinary text is still ' +
+        'executed. What does the shell run when it expands this one?',
+    redirect: 'This command line redirects a stream — `>`, `>>`, `<`, `2>` or `&>`. The shell attaches a ' +
+        'file to the program before the program starts, so its output lands in that file rather than ' +
+        'on the terminal, and a `>` truncates the file it names first. Which file is being read or ' +
+        'written here?',
+    unparseable: 'The gate could not tokenize this command line at all — most often an unbalanced quote, or no ' +
+        'program name it could identify. So we cannot tell you which program this runs; what is ' +
+        'quoted above is exactly the text that would be handed to the shell. What does it do?',
+};
+/** Process substitution `<(…)` / `>(…)`, which is a SUBSTITUTION and must not also read as a redirect. */
+const PROCESS_SUBSTITUTION_RE = /[<>]\(/g;
+/**
+ * Does this look like a `git commit` carrying an inline message?
+ *
+ * Deliberately a heuristic and not a parser: the command has already defeated the gate's tokenizer,
+ * so there is nothing precise left to parse. It is safe to be approximate here because a wrong
+ * answer costs at most a less specific note — the rating is bought either way.
+ */
+const GIT_COMMIT_RE = /\bgit\b[^\n]*\bcommit\b/i;
+const INLINE_MESSAGE_FLAG_RE = /(^|\s)(-m\b|--message\b|-\w*m\b)/;
+/** Command substitution `$(…)` or a backtick — the two the shell EXECUTES. */
+const EXECUTING_SUBSTITUTION_RE = /\$\(|`/;
+/** Every substitution/expansion form, including the non-executing ones. */
+const ANY_SUBSTITUTION_RE = /\$\(|`|\$\{|[<>]\(/;
+/**
+ * Classify a command the gate's parser could not resolve, or return `null` when it resolves.
+ *
+ * **The `null` arm is the guard, and it is structural on purpose.** Every mechanism below is a
+ * regex, and `unparseable` is the fallback — so without this gate the function would classify `ls
+ * -la` as `unparseable` and a note would be attached to every command in the session. The predicate
+ * is {@link classifyCommand}'s own, not a second reading of it, so the note appears on exactly the
+ * set of commands the gate could not resolve and on no others.
+ *
+ * Detection runs on the NORMALIZED command (the same form `classifyCommand` refused), so obfuscation
+ * that the normalizer collapses cannot hide a mechanism from the note — while the command shown to
+ * the rater stays the one the rater is being asked about, fenced by its own caller.
+ *
+ * The line-break check reads the RAW command, exactly as `classifyCommand` does: the normalizer is
+ * not required to preserve that separator, and EXT-55 is the node about what happens when a caller
+ * assumes it did.
+ *
+ * **Order is note order, most specific first**, and `commit-message-substitution` SUPPRESSES the
+ * generic substitution note it is a special case of — telling the rater the same thing twice about
+ * one `$(…)` spends attention on a repetition.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns What the parser saw, or `null` when the command's target statically resolves.
+ */
+export function describeAbstention(command) {
+    if (classifyCommand(command, normalizeCommand) !== null)
+        return null;
+    const normalized = normalizeCommand(command);
+    const composes = COMMAND_SEPARATOR_RE.test(normalized) || LINE_BREAK_RE.test(command.trim());
+    const substitutes = ANY_SUBSTITUTION_RE.test(normalized);
+    const commitSubstitution = GIT_COMMIT_RE.test(normalized) &&
+        INLINE_MESSAGE_FLAG_RE.test(normalized) &&
+        EXECUTING_SUBSTITUTION_RE.test(normalized);
+    // A redirect is any `<`/`>` that is NOT the opening of a process substitution — that form is
+    // already reported as a substitution, and reporting it twice would describe one piece of syntax
+    // with two different mechanisms.
+    const redirects = /[<>]/.test(normalized.replace(PROCESS_SUBSTITUTION_RE, ''));
+    const mechanisms = [];
+    if (commitSubstitution)
+        mechanisms.push('commit-message-substitution');
+    if (composes)
+        mechanisms.push('composition');
+    if (substitutes && !commitSubstitution)
+        mechanisms.push('substitution');
+    if (redirects)
+        mechanisms.push('redirect');
+    // The fallback for the causes that are not a shape at all — an unbalanced quote, an empty
+    // command, a command with no resolvable program name — so a note is never empty.
+    if (mechanisms.length === 0)
+        mechanisms.push('unparseable');
+    return {
+        mechanism: mechanisms[0],
+        mechanisms,
+        notes: mechanisms.map((mechanism) => MECHANISM_NOTES[mechanism]),
+    };
+}
+/**
+ * The opening line of the preflight note: **what this is, and what it is not.**
+ *
+ * It says the finding is about OUR PARSER rather than about the command, and that nothing has been
+ * judged. Both halves are load-bearing. The first stops the rater reading the note as a report of
+ * something found — the failure mode a bare observation produced, where a rater treats our
+ * uncertainty as evidence and either inflates or explains it away. The second is what keeps this
+ * note out of the open-world note's register: that one may say the command *"has ALREADY been
+ * floored deterministically and will be shown to the user whatever you return"*, and here that
+ * sentence would simply be false.
+ */
+export const PARSER_NOTE_PREAMBLE = 'PREFLIGHT NOTE: our command parser could not resolve what this command line runs, so here is ' +
+    'what it did see. This is a fact about OUR PARSER and not a finding about the command — nothing ' +
+    'has been judged, nothing has been floored, and none of this is a verdict or a severity. Rate ' +
+    'the command on its own merits.';
+/**
+ * Build the neutral preflight note for a command, or `null` when the gate resolved it.
+ *
+ * One note per mechanism the command carries, most specific first, bulleted when there is more than
+ * one — a command can compose AND substitute AND redirect, and a note that mentioned only the first
+ * would leave the rater reasoning about a fragment of the shape.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export function buildParserPreflightNote(command) {
+    const defect = describeAbstention(command);
+    if (defect === null)
+        return null;
+    const body = defect.notes.length === 1
+        ? defect.notes[0]
+        : defect.notes.map((note) => `- ${note}`).join('\n');
+    return `${PARSER_NOTE_PREAMBLE}\n${body}`;
+}
+//# sourceMappingURL=abstention.js.map

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

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

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

@@ -0,0 +1,271 @@
+/**
+ * @module core/shell/approvalCapture
+ *
+ * [[TUI-C27]] — **what the approvals gate DID, recorded while it was doing it**, for the
+ * `/debug-dump` archive.
+ *
+ * ## The two gaps this exists to close
+ *
+ * 1. **An approval used to leave no trace at all.** A rejection is legible in a dump only as a
+ *    byproduct of the negotiation — the protocol has to hand the reason back to the agent, so it
+ *    lands in the transcript. An approval relays nothing to anyone: the tool simply runs. So the
+ *    archive was at its most detailed about the decisions that STOPPED something and silent about
+ *    the one decision that let something happen, which is exactly backwards for an incident review.
+ *    Everything here is written on both branches.
+ * 2. **Every field anyone had was a rater OUTPUT; its INPUT was never recorded.** Rung, outcome,
+ *    reason, which preflight, whether the floor fired — all of them describe what the rater
+ *    *answered*, and none records what it was *shown*. The question that actually failed in the
+ *    field — *"were the user's messages in view on round 2?"* — needs the input of an approving
+ *    round, the one combination the dump had neither half of.
+ *
+ * ## The one rule that shapes the whole module: CAPTURE, NEVER RE-RENDER
+ *
+ * {@link RaterCallCapture.prompt} holds the exact `{system, user}` strings handed to the model, taken
+ * inside `rateShellCommand` at the send site — not rebuilt afterwards from the state that produced
+ * them. A dump that can disagree with what actually happened is worse than no dump: it invites a
+ * confident wrong conclusion from the only evidence there is, which is the failure mode this node
+ * was filed over. The same rule is why {@link RaterCallCapture.rawResponse} keeps the model's answer
+ * *before* it is mapped to an outcome — a malformed or surprising answer stays visible rather than
+ * being smoothed into a verdict.
+ *
+ * ## The records are pushed EARLY and mutated in place, deliberately
+ *
+ * {@link ApprovalCaptureLog.begin} appends the record the moment a gated call arrives, and the gate
+ * fills fields in as they are decided. The alternative — assemble the whole record, push it at the
+ * end — loses exactly the events worth keeping: an `attack` verdict throws `AttackHaltError` out of
+ * the decision, so a run that halted would carry no record of the rating that halted it. Pushing
+ * first makes survival a property of the structure rather than of someone remembering to write the
+ * record before each `throw`.
+ *
+ * ## Redaction
+ *
+ * Nothing is redacted here. The archive writer routes this artifact through the SAME
+ * [[GS2-47]]/[[GS2-54]] pass as `transcript.json` and `model-messages.json`
+ * (`renderStructured` → `redactText`, over the literal secret values `collectSecretValues`
+ * harvested from env + config). Redacting twice, in two places, is how two policies come to exist.
+ */
+import type { ApprovalRung } from '#src/config.js';
+import type { ToolApprovalScope } from '#src/core/types.js';
+import type { AbstentionDefect } from '#src/core/shell/abstention.js';
+import type { NegotiationCounters } from '#src/core/shell/negotiation.js';
+import type { FailClosedCause, PreflightFloorKind, RaterNegotiationContext, RaterNegotiationRound, ShellSafetyVerdict } from '#src/core/shell/rater.js';
+/**
+ * How many gated decisions one session keeps. A ring buffer for the same reason the debug-log one
+ * is: each record carries a full rating prompt (a few KB), and a long `auto` session makes a lot of
+ * them. The newest are the ones a bug report is about, so the oldest are evicted.
+ */
+export declare const APPROVAL_CAPTURE_MAX = 50;
+/**
+ * **Which layer of the gate decided this call.** The diagnostic value of the whole record is
+ * precisely here: a bug report that says "escalated" does not distinguish a rater verdict from a
+ * floor match from a timeout from a deny-list hit, and those need four different answers.
+ *
+ * The names follow the numbered steps of `GthAgentRunner.decideToolApprovalInner`:
+ *
+ * - `not-gated` — the rung in force does not gate this tool at all.
+ * - `deny-list` — a declared `approvals.deny` entry, or an *always reject* the human chose earlier.
+ * - `bypass` — the gate is off for the session.
+ * - `hardline-floor` — §8's deterministic floor matched, before any rating or prompt.
+ * - `escalate-entry` — a declared `approvals.escalate` entry; a human answers, with no rating call.
+ * - `allow-list` — an allow entry settled it with no rating (`rate: false`, or an unrated rung).
+ * - `allow-tripwire` — an allow entry that kept the rater involved (§3.2's `rate: true`).
+ * - `rater` — the ordinary rating path.
+ * - `tool-open-world-floor` — §4.7.3's floor on a non-shell call whose effective `openWorldHint`
+ *   is true. No rater sees it while §4.3's scope boundary stands.
+ * - `unrated-rung` — nothing but the rung itself: `manual` and `write` consult no model, so a call
+ *   no rule claimed goes to the human on the rung's say-so. It is its own value rather than an
+ *   absent one, because "the rung requires a person" is an answer and a blank field reads as the
+ *   recorder having failed.
+ */
+export type ApprovalDecidingStage = 'not-gated' | 'deny-list' | 'bypass' | 'hardline-floor' | 'escalate-entry' | 'allow-list' | 'allow-tripwire' | 'rater' | 'tool-open-world-floor' | 'unrated-rung';
+/**
+ * What became of the call, as the agent experienced it. `error` is its own value rather than an
+ * absence: a decision that threw something other than a halt is a fact about the gate, and a record
+ * left with no action at all would read as one that never finished being written.
+ */
+export type ApprovalCaptureAction = 'approve' | 'reject' | 'escalate' | 'halt' | 'error';
+/** How an escalation ended once it reached (or failed to reach) a person. */
+export type ApprovalHumanAnswer = 'approve' | 'reject' | 'no-human';
+/**
+ * §5.1's negotiation context **as it was handed to the prompt builder**, plus the one distinction a
+ * reader of the archive keeps needing and could never make.
+ *
+ * **`userMessagesPopulated` is the field the node exists for.** Round 1 is context-free *by design*
+ * (§5.1: *"round 1 sees the command alone"*), so an empty window is not a bug — and a reader with no
+ * access to the source cannot know that. {@link userMessagesNote} states which case this is in
+ * words, so the answer to *"were the user's messages in view on round N?"* is one field and one
+ * sentence rather than a source-reading exercise across three files.
+ */
+export interface RaterNegotiationCapture {
+    /** 1-based index of this rating within the current negotiation. */
+    round: number;
+    /** Whether this rating was a round-1 (context-free) rating. */
+    roundOne: boolean;
+    /** Whether a §5.1 context was supplied at all (it is not, at a rung that does not negotiate). */
+    contextSupplied: boolean;
+    /** The justification admitted into THIS rating. Withheld at round 1 by `contextFor`, by design. */
+    justification?: string;
+    /** `<negotiation_so_far>` as handed over: the completed rounds, oldest first. */
+    priorRounds: RaterNegotiationRound[];
+    /** `<user_messages>` as handed over, oldest first, before the builder's last-5 + truncation. */
+    userMessages: string[];
+    /** Whether that window carried anything. THE distinction this facility turns on. */
+    userMessagesPopulated: boolean;
+    /** Why the window looks the way it does, in words, for a reader who has never seen the spec. */
+    userMessagesNote: string;
+}
+/**
+ * One rating call: what the rater was SHOWN and what it ANSWERED, captured at the send site.
+ *
+ * Every field is filled by `rateShellCommand` itself. `prompt` is set before the call and the rest
+ * as the answer arrives, so a rater that never answers still leaves a record of what it was asked.
+ */
+export interface RaterCallCapture {
+    /** ISO timestamp of the moment the call was sent. */
+    at: string;
+    /** Wall-clock ms the call took, once it has returned (or timed out). */
+    durationMs?: number;
+    /** The rater model's own label — an id and a provider type, never the instance. */
+    model?: string;
+    /** `approvals.rater` — the identity profile the rater model came from, when one is configured. */
+    profile?: string;
+    /** The budget this call was raced against ([[EXT-66]]). */
+    timeoutMs: number;
+    /** §5.2 — whether a rejection would be handed back to the AGENT rather than to a person. */
+    negotiable: boolean;
+    /** **The exact strings sent.** Captured, never re-rendered. */
+    prompt: {
+        system: string;
+        user: string;
+    };
+    /** What the negotiation looked like at the moment of this call. */
+    negotiation: RaterNegotiationCapture;
+    /** The model's answer BEFORE it is parsed or mapped, so a malformed one stays visible. */
+    rawResponse?: unknown;
+    /** The verdict this call resolved to, including a fail-closed one. */
+    verdict?: ShellSafetyVerdict;
+    /** Set when the verdict is the gate failing closed rather than the model judging ([[EXT-66]]). */
+    failClosed?: FailClosedCause;
+}
+/** A declared entry or runtime grant that decided the call, rendered as the user would read it. */
+export interface ApprovalRuleMatchCapture {
+    action: 'allow' | 'deny' | 'escalate';
+    /** The entry in the words the menu and the notices use (`describeApprovalEntry`). */
+    entry: string;
+    /** §3.2 — whether an allow entry kept the rater involved as a tripwire. */
+    rate?: boolean;
+}
+/**
+ * §8's deterministic floor, when it matched.
+ *
+ * **This block NAMES THE MATCHED PATTERN, and that is a decision taken rather than an oversight.**
+ * §8.1 says the floor is never advertised, and [[CFG-31]] binds user-facing rung copy to that rule.
+ * The resolution taken for [[TUI-C27]] is that §8.1 governs **rung descriptions and promotional
+ * copy** — text that invites a user to feel safe — and not a diagnostic archive a user opens about
+ * their own session. "A floor matched" without saying which one leaves nobody able to act on it;
+ * the refusal the *user* sees ({@link import('./hardline.js').buildHardlineRefusal}) is unchanged
+ * and still names only the description.
+ */
+export interface HardlineFloorCapture {
+    /** The human-readable description, as the refusal message carries it. */
+    description: string;
+    /** The matched pattern's source, or the stable token of the non-pattern arm. */
+    pattern: string;
+}
+/** A deterministic preflight finding, and whether it actually rewrote the rater's outcome. */
+export interface PreflightFloorCapture {
+    kind: PreflightFloorKind;
+    reason: string;
+    /**
+     * Whether the floor changed the outcome. A preflight only ever RAISES, and only `safe` sits below
+     * the floor — so a finding on a `destructive` verdict is the floor AGREEING with the rater, not
+     * overriding it, and reporting those two the same way would misattribute the decision.
+     */
+    rewroteRating: boolean;
+}
+/** One gated tool call, from arrival to outcome. */
+export interface ApprovalDecisionCapture {
+    /** ISO timestamp of the moment the call arrived at the gate. */
+    at: string;
+    /** The tool that was called. */
+    tool: string;
+    /** The command, for a `run_shell_command` call whose argument was a readable string. */
+    command?: string;
+    /** The rung in force for THIS decision (`/approvals <rung>` moves it mid-session). */
+    rung: ApprovalRung;
+    /** The stage that decided. `undefined` only if the decision threw before reaching one. */
+    stage?: ApprovalDecidingStage;
+    /** What became of the call. Always set by the time the decision returns or throws. */
+    action?: ApprovalCaptureAction;
+    /** The scope an approval was granted at, when one was. */
+    scope?: ToolApprovalScope;
+    /** Whether a person was actually asked, and what they said. */
+    humanAnswer?: ApprovalHumanAnswer;
+    /** §8's floor, when it matched. */
+    hardline?: HardlineFloorCapture;
+    /** The declared entry or runtime grant that decided the call, when one did. */
+    ruleMatch?: ApprovalRuleMatchCapture;
+    /** The deterministic preflight finding on this command, when there was one. */
+    preflight?: PreflightFloorCapture;
+    /**
+     * [[EXT-81]] — whether the gate's own parser could not statically resolve the command, so the
+     * rating carried a neutral note about the shape it saw.
+     *
+     * **This is what remains of "was the call an ABSTAIN".** `abstain` was an ACTION of its own until
+     * [[EXT-81]] retired it: a parser reporting that it could not read a string has detected nothing,
+     * so it no longer earns an action, and the command is now rated like any other. The observable
+     * that survived is this shape report, and the budget position that used to accompany it is
+     * {@link budget}.
+     */
+    parserUnresolved?: AbstentionDefect;
+    /** Where this call sat in §5.3's consecutive bound and the reachability bound, on arrival. */
+    budget: NegotiationCounters;
+    /** The rating, when one was made. Absent for every stage that decided without a model. */
+    rating?: RaterCallCapture;
+    /** The error that ended the decision, when one did. */
+    error?: string;
+}
+/**
+ * The per-session log of gated decisions.
+ *
+ * **Instance-scoped, on the runner, and never a module singleton** — the same reason
+ * `ShellNegotiationState` and the grant stores are: a concurrent ACP / AG-UI session must not
+ * inherit another session's approvals history, and a dump taken in one must not describe the other.
+ */
+export declare class ApprovalCaptureLog {
+    private records;
+    /**
+     * Open a record for a gated call and return it LIVE, already in the buffer.
+     *
+     * The caller mutates the returned object as the decision is made. See the module docblock for why
+     * the push happens here rather than at the end: a halt throws out of the decision, and a record
+     * assembled at the end would be lost on exactly the calls most worth keeping.
+     */
+    begin(record: ApprovalDecisionCapture): ApprovalDecisionCapture;
+    /**
+     * The records so far, oldest first. A copy of the ARRAY: the records themselves are handed over
+     * live, because a decision still in flight is one the archive should show as it stands rather
+     * than not at all.
+     */
+    snapshot(): ApprovalDecisionCapture[];
+    /** Drop everything — the TUI's `/clear` rotates the thread. */
+    clear(): void;
+}
+/**
+ * A short, KEY-FREE label for the rater model: its id and its provider type, and nothing else.
+ *
+ * Deliberately not a param dump. A live `BaseChatModel` carries an `apiKey` and a client instance,
+ * and this string goes into an archive people attach to bug reports — so it reads a fixed handful of
+ * scalar fields through guards, exactly as `debugDump`'s own live-model descriptor does, rather than
+ * serialising anything of the instance.
+ */
+export declare function raterModelLabel(model: unknown): string | undefined;
+/**
+ * Describe the §5.1 context a rating is about to be made with — **as it was handed to the prompt
+ * builder**, so the record and the prompt cannot come to describe two different ratings.
+ *
+ * The note is the legibility half of the acceptance: an empty user-messages window means one thing
+ * at round 1 (by design) and something else entirely at round 3, and a reader of the archive has no
+ * way to tell them apart from a `[]`.
+ */
+export declare function describeRaterNegotiation(negotiation: RaterNegotiationContext | undefined): RaterNegotiationCapture;