@gaunt-sloth/core 2.0.0-alpha.24 → 2.0.0-alpha.26

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

@@ -0,0 +1,560 @@
+/**
+ * @module core/shell/rater
+ *
+ * CFG-27 (CFG-26 rework) — the **auto-rater**: the LLM that rates a pending `run_shell_command`
+ * before it executes, sitting *in front of* the human approval prompt (EXT-9). It is consulted at
+ * exactly two of the five rungs — `auto-safe` and `full-auto` (see `APPROVAL_RUNGS`); `read-only`,
+ * `write` and `bypass` are fully deterministic and never pay for a model call.
+ *
+ * NOTE ON THE NAME: "judge" is reserved for the **eval grader** (`gth eval --judge <profile>`,
+ * `@gaunt-sloth/batch`) — a different concept. This module is the approvals rater.
+ *
+ * Validated prior art (both place the rater in front of the human prompt as an auto-approve
+ * fatigue-reducer): openclaw `exec-auto-reviewer.ts` and hermes-agent `approval.py` "smart" mode.
+ *
+ * Two hardening guarantees are baked in here:
+ *
+ * 1. **Prompt-injection defense.** The command is attacker-controlled text. It is normalized
+ *    (reusing {@link normalizeCommand} + home-path folding) and embedded inside an XML
+ *    `<command_to_evaluate>` tag, behind a preamble that states the tagged text is UNTRUSTED
+ *    DATA to be analyzed, never instructions to follow. See {@link buildRaterPrompt}.
+ * 2. **Fail-closed on error.** If the LLM call throws, times out, or returns unparseable
+ *    output, the verdict returned NEVER auto-approves — it is `destructive` with an honest
+ *    "could not assess" reason. A rater failure can never silently green-light a command.
+ *    See {@link FAIL_CLOSED_VERDICT}.
+ *
+ * Fail-closed-on-AMBIGUITY (when the command's target can't be statically resolved) lives in the
+ * decision mapping ({@link mapVerdictToAction}), not here, so it applies regardless of what the
+ * rater says.
+ *
+ * Mirrors the QA-3 rating substrate (`packages/review/src/middleware/reviewRateMiddleware.ts`):
+ * structured-output evaluation over `config.llm`, wrapped in try/catch.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import * as z from 'zod';
+import type { ApprovalRung, GrantedToolSummary, GthConfig } from '#src/config.js';
+import type { EffectiveToolAnnotations } from '#src/core/approvals/matcher.js';
+/**
+ * CFG-28 (spec §4.1) — the **four** outcomes the rater may return. The retired third outcome named
+ * the halt trigger by *mechanism* while positioning it as the top *severity*; the rescale (§11.1)
+ * splits that into two outcomes asking two different questions. There is no
+ * ordering knob and no threshold: each outcome's consequence is fixed by the rung
+ * ({@link mapVerdictToAction}).
+ *
+ * - `safe` — no harmful effect.
+ * - `destructive` — **the catch-all**: harmful, but recoverable from inside the session, and not
+ *   an attack — **and anything the rater cannot assess**. The rating prompt defines it *by
+ *   exclusion* ("not safe, not catastrophic and not an attack") precisely so no command can fall
+ *   outside the four.
+ * - `catastrophic` — *can this be undone from inside the session?* Irreversible without something
+ *   OUTSIDE the session: rescue media, a backup, a re-provision, a restore from a third party.
+ *   Escalates at both rated rungs; never negotiable and never sticky (§4.2).
+ * - `attack` — *is something hostile acting here?* The command's own **structure** evidences
+ *   compromise (§4.1.1: credential targeting, privilege escalation / permission weakening,
+ *   persistence, deception, obfuscation). It is the only outcome that HALTS the run.
+ *
+ * **`catastrophic` and `attack` are not ranked against each other** — they ask different
+ * questions, and the spec says so explicitly. A command can be both; `attack` wins the
+ * *consequence* (a manipulated session cannot be trusted to continue) but MUST NOT swallow the
+ * finding — see the §6.1 clause in {@link buildRaterSystemPrompt}. Nothing here may be written as
+ * a severity comparison between the two.
+ */
+export declare const RATER_OUTCOMES: readonly ['safe', 'destructive', 'catastrophic', 'attack'];
+/** One outcome of {@link RATER_OUTCOMES}. */
+export type RaterOutcome = (typeof RATER_OUTCOMES)[number];
+/**
+ * Structured verdict the rater model must return: one outcome plus one short sentence. There is
+ * deliberately nothing else — no severity number, no booleans to recombine into a compound
+ * condition. The consequence is a property of the rung, not of a knob.
+ */
+export declare const ShellSafetyVerdictSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        attack: "attack";
+        catastrophic: "catastrophic";
+        destructive: "destructive";
+        safe: "safe";
+    }>;
+    reason: z.ZodString;
+    suggestedTool: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The rater's structured verdict on a single shell command.
+ */
+export type ShellSafetyVerdict = z.infer<typeof ShellSafetyVerdictSchema>;
+/**
+ * The honest reason text used whenever the outcome was NOT assessed by the rater — a rater failure
+ * ({@link FAIL_CLOSED_VERDICT}) or a command the gate itself cannot statically vet
+ * ({@link mapVerdictToAction}'s ambiguity / script-env-leak preflight). Spec rule (§4.1):
+ * *uncertainty is not an outcome*, so it maps to `destructive` while SAYING it could not be
+ * assessed rather than pretending the command was found harmful.
+ */
+export declare const COULD_NOT_ASSESS_PREFIX = "Could not assess this command";
+/**
+ * EXT-61 (§4.6) — the reason text prefix for the **open-world** preflight, and deliberately NOT
+ * {@link COULD_NOT_ASSESS_PREFIX}: this preflight *did* assess the command and found something
+ * specific. Saying "could not assess" here would be a lie, and the named host is the whole value of
+ * the escalation — "it downloads something, confirm" and "it fetches from registry.npmjs.ag" are
+ * different warnings, and only the second is worth reading.
+ */
+export declare const NAMES_A_HOST_PREFIX = "This command names a host";
+/**
+ * EXT-70 (§4.7.2, §4.7.3) — the reason text prefix for the **tool** arm of the open-world floor: a
+ * call whose EFFECTIVE `openWorldHint` is true. Like {@link NAMES_A_HOST_PREFIX} and unlike
+ * {@link COULD_NOT_ASSESS_PREFIX}, it states something the gate positively established.
+ *
+ * It names the hint rather than paraphrasing it, because the hint is also the thing the user can
+ * act on: trust it from that server (`approvals.mcp`), or declare the call in `approvals.allow`.
+ */
+export declare const REACHES_OPEN_WORLD_PREFIX = "This tool reaches the open world";
+/**
+ * The closing clause **shared by every open-world floor reason**, shell and tool alike.
+ *
+ * It is a constant rather than two copies of a sentence, and that is load-bearing rather than
+ * tidiness: the two arms are one rule (§4.6 for a shell fetch, §4.7.3 for the same fetch reached
+ * through a tool), so a reader who has seen one escalation reads the other as the same decision.
+ * It is also the one part of the floor a **second implementation** cannot reproduce by accident —
+ * an inline `{ outcome: 'destructive', reason: … }` written at some future call site would say
+ * something else, and the assertions that compare a floored reason against the exported reason
+ * builders are what turn that into a red test rather than a slow divergence.
+ */
+export declare const NEVER_AUTO_APPROVED_CLAUSE = "so it is never auto-approved.";
+/**
+ * The verdict returned whenever the rater cannot produce a trustworthy answer (LLM throws,
+ * times out, or returns unparseable output). Fail-closed: `destructive`, never auto-approved,
+ * and never `attack` or `catastrophic` either — a failure to assess must not manufacture a
+ * run-halting outcome any more than it may manufacture an approval.
+ */
+export declare const FAIL_CLOSED_VERDICT: ShellSafetyVerdict;
+/**
+ * EXT-66 — why the gate failed closed. **Every one of these is a fact about the GATE, not about the
+ * command**, which is the whole point of naming them: {@link FAIL_CLOSED_VERDICT} collapsed four
+ * different gate failures into one verdict that reads, downstream and in every eval report, exactly
+ * like a model that looked at the command and judged it `destructive`.
+ *
+ * That is not hypothetical. The EXT-62 anchoring sweep read its first `gemma4:12b` column as full
+ * coverage of the interpreter-wrapper misses; 3 of those escalations were the gate defaulting after
+ * 30 seconds, not the model judging, and only the reason string distinguished them.
+ *
+ * The outcome stays `destructive` for all four — failing closed is right and stays right, and a
+ * failure to assess must not manufacture `catastrophic`/`attack` any more than it may manufacture
+ * an approval. What changes is that the reason now says which failure happened. [[EXT-64]] routes
+ * the `timeout` and `no-model` causes onto its `abstain` ACTION by reading this, rather than
+ * re-deriving it; this module deliberately does not anticipate that vocabulary.
+ */
+export type FailClosedCause = 'no-model' | 'timeout' | 'unparseable' | 'threw';
+/**
+ * The fail-closed verdict for a specific {@link FailClosedCause}. Keeps
+ * {@link COULD_NOT_ASSESS_PREFIX} — the statement "this was not assessed" is still true and is what
+ * downstream keys on — and appends what actually went wrong.
+ *
+ * The timeout arm names the budget, because "the rater timed out" is not actionable and "the rater
+ * did not answer within 30000ms" points straight at `approvals.raterTimeoutMs`.
+ */
+export declare function failClosedVerdict(cause: FailClosedCause, timeoutMs?: number): ShellSafetyVerdict;
+/**
+ * Whether a verdict is one this gate produced because it could not obtain a rating, as opposed to
+ * one a rater actually returned. Keys on {@link COULD_NOT_ASSESS_PREFIX} — the same
+ * reason-prefix-as-identity idiom {@link NAMES_A_HOST_PREFIX} already uses — so it covers the
+ * legacy {@link FAIL_CLOSED_VERDICT} as well as every {@link failClosedVerdict} cause.
+ *
+ * Exported so a caller can tell "the gate defaulted" from "the model judged" without string
+ * matching at the call site, which is the distinction an eval column and a session summary both
+ * need and neither could previously make.
+ */
+export declare function isFailClosed(verdict: ShellSafetyVerdict | undefined): boolean;
+/** Whether a verdict is specifically the {@link FailClosedCause} `timeout` arm. */
+export declare function isRaterTimeout(verdict: ShellSafetyVerdict | undefined): boolean;
+/**
+ * Default wall-clock budget (ms) for the rater LLM call. Kept low so a slow/hung rater can't
+ * wedge the approval flow — on timeout we fail closed. Mirrors openclaw's low exec-reviewer
+ * timeout minimum.
+ *
+ * **EXT-66 — this is a HOSTED-model number, and it is now a default rather than the only value.**
+ * `claude-haiku-4-5` and `gemini-3.6-flash` answered a 23-case corpus well inside it, 0 fail-closed.
+ * `gemma4:12b` over a local GPU took 6.0s–114.7s on the same corpus, and the harder the command the
+ * longer it thought — so the fixed limit preferentially clipped exactly the commands that most
+ * needed rating (3 of 18 calls in one run, 9 of 17 in the next; all of them returned real verdicts
+ * at 120s, including a correct `catastrophic` returned 85 seconds after the gate had given up).
+ * Override with `approvals.raterTimeoutMs`.
+ */
+export declare const RATER_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * The invariant half of the rater's system prompt: the role and the untrusted-input contract (the
+ * tagged command is DATA, not instructions). Patterned after openclaw's
+ * `DEFAULT_EXEC_REVIEWER_SYSTEM_PROMPT` and hermes' untrusted-input framing. Exported so tests can
+ * assert the injection-defense preamble survives.
+ */
+export declare const RATER_SYSTEM_PREAMBLE: string;
+/**
+ * The `catastrophic` half of the rating prompt (§4.1). The whole outcome is one question — *can
+ * this be undone from inside the session?* — and the prompt asks it that way rather than offering
+ * a severity scale, because a rater given "how bad is it" instead of "is it recoverable" produces a
+ * ranking rather than the classification §4.2 acts on.
+ *
+ * The examples deliberately include the members the §8 deterministic floor **cannot** reach
+ * (`DROP DATABASE`, `terraform destroy -auto-approve`, `kubectl delete namespace production`):
+ * §11.1 records that only a model recognises that class, which is the reason the outcome exists.
+ * The counter-examples matter just as much — `git reset --hard` is reflog-recoverable and therefore
+ * `destructive`, and that is precisely what lets §5's negotiation open on it at all (§11.1a).
+ */
+export declare const RATER_CATASTROPHIC_GUIDANCE: string;
+/**
+ * The `attack` half of the rating prompt, kept as its own export because **§4.1.1 requires the
+ * prompt to carry the structural test in its own words, not merely the one-line table
+ * definition.**
+ *
+ * The reason is worth restating where the prompt author will read it: `attack` is the only outcome
+ * that halts the run, the halt is not negotiable, and from `auto-safe` — the default rung for
+ * everyone — a non-interactive run has no key at all and the only ways through are an allow-list
+ * entry or dropping to `bypass`, i.e. one step from the default gate to no gate. An outcome that
+ * expensive MUST NOT fire on ordinary work, so the test is **what the command's own structure
+ * shows, not who it talks to**.
+ *
+ * Two clauses here are measurements rather than opinions, and neither may be quietly relaxed:
+ *
+ * - **Origin trust is not the rater's job** (§4.1.1's measured note). A cheap model rated
+ *   `curl https://pypi.org.packages-cdn.io/simple/ -o index.html` as `safe` while *naming the
+ *   deception in its own reasoning*, and split identically-shaped commands at random. A property
+ *   that holds only on the good model is not a property, and `auto-safe` is the default for people
+ *   pointed at small local models. `curl … | <shell>` is therefore `destructive` whatever the host.
+ * - **Clause (1) is narrowed** (§11.1b, 2026-07-28). A secret handed to a tool that is doing some
+ *   other job is not credential targeting; a secret exposed for its own sake is. Read literally,
+ *   the un-narrowed clause halted the run on `python deploy.py --key $AWS_SECRET_ACCESS_KEY` — one
+ *   of the most ordinary shapes in deployment work, from a section that opens by saying an outcome
+ *   this expensive must not fire on ordinary work. **Nothing is given up**: the deterministic
+ *   {@link hasScriptEnvLeakRisk} preflight fires on exactly that shape, annotates this prompt, and
+ *   forces the fail-closed `destructive` path in {@link mapVerdictToAction} — so a secret in an
+ *   argument cannot reach `safe` however the rater rates it. The change trades a halt for a prompt
+ *   on commands that were never going to auto-approve.
+ */
+export declare const RATER_ATTACK_GUIDANCE: string;
+/**
+ * EXT-61 (spec §4.6.1) — **deception becomes a REPORT and an upgrade, never a gate.**
+ *
+ * This is the rater-side half of the open-world preflight, and it exists because the preflight
+ * changed what the rater's hostname judgement is *for*. §4.6 floors every command that names a host
+ * at `destructive` before the rater is called, so that judgement no longer stands between a
+ * typosquat and execution. Its job is now to *tell the user what it sees*.
+ *
+ * **The error costs invert, and that is the point.** A missed deception costs a warning rather than
+ * a bypass; a wrongly-suspected one costs a sentence rather than a halted run. That is the correct
+ * place to put a judgement neither models nor humans perform reliably — §4.1.1's measurement is a
+ * cheap model rating a lookalike host `safe` *while naming the deception in its own reasoning*, and
+ * a working developer who did not discriminate hostnames in either direction.
+ *
+ * Both halves are normative and neither may be softened into the other:
+ *
+ * - **(1) Always report it**, naming the mechanism, **even when the outcome stays `destructive`**.
+ *   The "even when" is the whole clause; a rater that only names a typosquat when it is halting the
+ *   run reports nothing on the commands this preflight was built for, since they all land on
+ *   `destructive`.
+ * - **(2) Upgrade to `attack` only when the deception is CLEAR**, resolving uncertainty *downward*
+ *   to `destructive` with the doubt stated. §12.1 is the reason: a halt that fires is already more
+ *   likely wrong than right, so it must be spent only where the structure is unambiguous.
+ *
+ * CFG-28 deliberately left (2) out of the prompt, on the reasoning that it presumes the §4.6 floor.
+ * The scoping call was right and the reasoning was not: at both rated rungs a `destructive` outcome
+ * escalates anyway, so the clause would have cost nothing had it landed early. **The floor is what
+ * makes the `destructive` half of §4.6.1 meaningful, not what gates the upgrade.**
+ */
+export declare const RATER_DECEPTION_GUIDANCE: string;
+/**
+ * EXT-58 (spec §4.4) — the granted-alternative section of the rating prompt, built from the
+ * already-granted built-in tools of the current rung.
+ *
+ * Three properties are normative and each is spelled out to the rater:
+ *
+ * - It must name a granted tool **whenever** the outcome is not `safe` and one of them would do the
+ *   job, because a free built-in call beats an interruption.
+ * - It must **not** name one when none can do the job — a path outside the working folder is the
+ *   canonical case, where neither the read nor the edit tool can reach either. A facility that
+ *   manufactures suggestions makes "a suggestion is never an approval" meaningless.
+ * - A suggestion is **never an approval**: it does not change the outcome, does not approve the
+ *   original command, and does not pre-approve the suggested tool (which is gated normally when it
+ *   arrives). The gate enforces this structurally — {@link mapVerdictToAction} never reads the
+ *   field — but the rater is told so it does not soften an outcome because an alternative exists.
+ *
+ * The list is **trusted, locally-generated text** (§4.3) and therefore lives in the SYSTEM prompt,
+ * structurally outside the `<command_to_evaluate>` block that carries the untrusted command. Only
+ * tool names and one-line descriptions authored in `config/tool-descriptions.ts` ever appear here;
+ * no MCP/custom/A2A tool's own description can reach the rater.
+ *
+ * Returns `null` when nothing is granted (or the caller supplied no list), so the prompt is exactly
+ * the pre-EXT-58 text and the rater is never invited to invent a tool out of an empty list.
+ */
+export declare function buildGrantedToolsGuidance(grantedTools: readonly GrantedToolSummary[] | undefined): string | null;
+/**
+ * Build the rater's system prompt: the invariant {@link RATER_SYSTEM_PREAMBLE}, the four outcome
+ * definitions (with §4.1's recoverability question spelled out in
+ * {@link RATER_CATASTROPHIC_GUIDANCE} and §4.1.1's structural test in
+ * {@link RATER_ATTACK_GUIDANCE}), the rules that make `destructive` the catch-all and uncertainty a
+ * `destructive` rather than an outcome of its own, and — when the caller supplies them — the
+ * already-granted tools of §4.4 ({@link buildGrantedToolsGuidance}).
+ *
+ * `destructive` is defined **last and by exclusion** on purpose: the two severe outcomes have to be
+ * on the page before "everything else" can mean anything, and defining the catch-all in terms of
+ * the other three is what makes it structurally impossible for a command to fall outside the four.
+ *
+ * There is no strictness parameter: §1 removed strictness levels along with severity thresholds,
+ * so this prompt is the same at every rated rung.
+ */
+export declare function buildRaterSystemPrompt(grantedTools?: readonly GrantedToolSummary[]): string;
+/**
+ * Detect whether the command invokes an interpreter on a script target AND passes an
+ * `$ALL_CAPS` shell-variable expansion in its arguments — openclaw's "script preflight". Such a
+ * command can leak environment (often secrets) into the script, so it should bias toward
+ * escalation. Lightweight heuristic over the normalized command; a positive flag is fed to the
+ * rater prompt AND forces the fail-closed `destructive` path in the decision mapping.
+ *
+ * @returns true when an interpreter+script invocation also expands an ALL_CAPS env var.
+ */
+export declare function hasScriptEnvLeakRisk(normalizedCommand: string): boolean;
+/**
+ * Fold an absolute home path to `~` so the rater sees a stable, less-identifying form (mirrors
+ * hermes `_normalize_command_for_detection` path folding). Best-effort: only the literal home
+ * dir prefix is folded.
+ */
+export declare function foldHomePath(command: string, home: string | undefined): string;
+/**
+ * Build the messages for the rater call: the system prompt ({@link buildRaterSystemPrompt}) plus a
+ * human message that embeds the NORMALIZED command inside an XML `<command_to_evaluate>` tag and
+ * (optionally) notes what a deterministic preflight already found — the script-env-leak flag, and
+ * (§4.6) a host literal in a fetch position. The command text is only ever DATA in the tag — the
+ * builder never executes or interpolates it as instructions.
+ *
+ * The two preflight notes are worded differently on purpose. The script-env-leak note caps nothing
+ * but says "treat this as at least destructive"; the open-world note must NOT, because §4.6.1 asks
+ * the rater to *upgrade* a clear typosquat to `attack` and a note that anchors on `destructive`
+ * would talk it out of the one judgement it is still being asked for.
+ *
+ * §4.3 defines the rated unit tool-generally (tool name + JSON arguments); `run_shell_command` is
+ * the case whose argument is a command string, and it alone is additionally normalized and
+ * home-path-folded before fencing. The first implementation covers the shell only — every other
+ * tool is granted or escalated by the rung without a rating call until [[EXT-30]] widens the gate.
+ *
+ * Exposed (and returning plain strings) so tests can assert the structure: the tag is present,
+ * the untrusted-input preamble is present, and an injection string inside the command lands
+ * inside the tag rather than being acted on.
+ */
+export declare function buildRaterPrompt(command: string, options?: {
+    home?: string;
+    grantedTools?: readonly GrantedToolSummary[];
+}): {
+    system: string;
+    user: string;
+};
+/**
+ * Rate a single shell command with the rater model and return a structured
+ * {@link ShellSafetyVerdict}.
+ *
+ * - Builds an injection-hardened, normalized prompt ({@link buildRaterPrompt}).
+ * - Calls the rater model (defaults to `config.llm`) via `withStructuredOutput(schema)`.
+ * - Races the call against {@link RATER_DEFAULT_TIMEOUT_MS}.
+ * - **Fail-closed:** any throw / timeout / parse failure returns {@link FAIL_CLOSED_VERDICT}
+ *   (`destructive` + "could not assess"), never an approval.
+ *
+ * Note: this only produces a verdict; the approve / escalate / halt decision (including
+ * fail-closed-on-ambiguity) is made by {@link mapVerdictToAction} in the runner.
+ */
+export declare function rateShellCommand(command: string, config: GthConfig, options?: {
+    model?: BaseChatModel;
+    home?: string;
+    timeoutMs?: number;
+    /**
+     * EXT-58 (§4.4) — the already-granted built-ins of the current rung. Supplied, the rater is
+     * asked to name one whenever it does not return `safe` and one would do the job; omitted, the
+     * prompt is exactly as before and no suggestion is ever produced.
+     */
+    grantedTools?: readonly GrantedToolSummary[];
+}): Promise<ShellSafetyVerdict>;
+/**
+ * The action the approvals gate resolves to for a single gated call, BEFORE the human prompt.
+ *
+ * - `approve` — approve ONCE; do not touch the human or the allow-list.
+ * - `escalate` — fall through to the human approval callback, carrying the verdict when one
+ *   exists. Where there is no human, §6.2 turns this into an immediate non-zero exit — that
+ *   translation belongs to the runner, not here.
+ * - `halt` — **end the agent loop** (§4.2). Reserved for `attack`. It is not a rejection the
+ *   model can respond to and offers it no moves; no rung except `bypass` can turn it into
+ *   anything else.
+ *
+ * There is deliberately **no `refuse` arm for `catastrophic`** (settled 2026-07-27c, §4.2). The
+ * deterministic members of that class — fork bomb, `mkfs`, `rm -rf /`, `dd` to a block device — are
+ * already refused unappealably by the §8 hardline floor under every rung including `bypass`, so a
+ * refusing `catastrophic` would add nothing for the commands that motivate the idea. What it would
+ * newly refuse is the remainder the floor cannot reach, every member of which has routine
+ * legitimate use (a staging database, an ephemeral `terraform destroy`, a preview namespace). An
+ * unmeasured classifier belongs behind a human who can correct it; a refusal has no correction
+ * path.
+ */
+export type RaterAction = 'approve' | 'escalate' | 'halt';
+/** Inputs to the decision mapping: just the rung. Each rung fully determines behaviour (§1). */
+export interface RaterDecisionOptions {
+    /** The rung in force for this session. */
+    rung: ApprovalRung;
+}
+/**
+ * The verdict {@link mapVerdictToAction} acts on, after the gate's own fail-closed preflight has
+ * overridden the rater where it must. Returned alongside the action so the caller surfaces the
+ * HONEST reason (a "could not assess" note) rather than whatever the rater claimed about a
+ * command the gate could not statically vet. `undefined` at the unrated rungs, where no rating
+ * call was made at all.
+ */
+export interface RaterDecision {
+    action: RaterAction;
+    /** The verdict actually used — the rater's, or the fail-closed `destructive` override. */
+    verdict?: ShellSafetyVerdict;
+}
+/**
+ * Is this outcome below the deterministic `destructive` floor — i.e. may a preflight rewrite it?
+ *
+ * See {@link BELOW_DESTRUCTIVE_FLOOR}. An outcome that is not in the table is treated as below the
+ * floor, so an out-of-band value is FLOORED to `destructive` rather than sailing past the preflight
+ * carrying the model's own unvalidated reason.
+ *
+ * The lookup is OWN-PROPERTY-ONLY, and the declared `boolean` return is the reason. `outcome` is
+ * only `RaterOutcome` as far as the compiler is concerned — this helper exists to be robust to a
+ * value that lied — and a `?? undefined` default would still hand back the *inherited* value for a
+ * prototype-chain key (`'toString'` → a function, `'constructor'` → `Object`). Those happen to be
+ * truthy, so today's single caller would still floor; but a caller written as `=== true`, which is
+ * how a predicate advertised as hardened invites being consumed, would fail OPEN on exactly the
+ * class of input this function is for. `Object.hasOwn` makes the advertised invariant true rather
+ * than incidentally true.
+ */
+export declare function isBelowDestructiveFloor(outcome: RaterOutcome): boolean;
+/**
+ * **THE deterministic floor — the one place an outcome is raised to `destructive`.**
+ *
+ * Every gated call reaches it: a shell command through {@link mapVerdictToAction}'s preflights
+ * ({@link preflightFloorReason}), a tool call through its effective `openWorldHint`
+ * ({@link openWorldToolFloorReason}, §4.7.3). They differ only in the *reason* they compute; what
+ * the reason then does to the outcome is decided here and nowhere else. A second implementation is
+ * how a gate and a display come to disagree about what a call is, and how one of them comes to
+ * *lower* an outcome the other raised.
+ *
+ * Two properties, both delegated to {@link isBelowDestructiveFloor} so they hold for every caller:
+ *
+ * - **It only ever RAISES.** A `destructive`, `catastrophic` or `attack` verdict passes through
+ *   untouched, keeping its own explanation (and any §4.4 suggestion) — the floor is agreeing with
+ *   it, not overriding it, and a floor that rewrote `catastrophic` would silently trade an
+ *   unnegotiable escalation for a negotiable one.
+ * - **`undefined` is below the floor.** Nothing has assessed the call, so there is no outcome for
+ *   the floor to defer to; a call nobody rated is exactly the call this rule exists to speak for.
+ *   That is what lets a tool call — which no rater sees while §4.3's scope boundary stands — be
+ *   floored by the same function that floors a rated shell command.
+ *
+ * @param verdict The outcome so far, or `undefined` when nothing has rated the call.
+ * @param reason The floor reason, or `null` when no preflight fired (the verdict is returned as-is).
+ */
+export declare function applyDestructiveFloor(verdict: ShellSafetyVerdict, reason: string | null): ShellSafetyVerdict;
+export declare function applyDestructiveFloor(verdict: ShellSafetyVerdict | undefined, reason: string | null): ShellSafetyVerdict | undefined;
+/**
+ * EXT-70 (§4.7.2, §4.7.3) — the **tool** arm of the open-world floor: the reason a call whose
+ * EFFECTIVE `openWorldHint` is true is floored at `destructive`, or `null` when it is not.
+ *
+ * It sits beside {@link preflightFloorReason} because it is the same rule seen from the other side.
+ * §4.6 floors a shell fetch before any model call precisely so that no misreading of a hostname can
+ * auto-approve; *the same fetch reached through a tool instead of through `curl` must not be
+ * ungated*, or the preflight is a rule about spelling rather than about fetching. Both feed
+ * {@link applyDestructiveFloor}.
+ *
+ * **Independent of `readOnlyHint`, and that is the whole of §4.7.3.** A fetch tool is read-only in
+ * the local sense — it mutates nothing on this machine — while reaching the network; the two facts
+ * are unrelated, and `gth_web_fetch` (`readOnlyHint: true`, `openWorldHint: true`) is the case that
+ * proves it. `destructiveHint` is not consulted either: §4.7.2 lets it only ever RAISE, so a
+ * `destructiveHint: false` can never lower a floor this rule set. `idempotentHint` has no built-in
+ * consumer at all — do not invent one here.
+ *
+ * @param annotations The call's effective set (§4.7.1), never its declared one — trust has already
+ *   been applied, so an untrusted server's `openWorldHint: false` has already collapsed to the
+ *   fail-closed `true` by the time it arrives. `undefined` (a source that cannot decide) floors, in
+ *   the same direction as the fail-closed default it would otherwise have returned.
+ */
+export declare function openWorldToolFloorReason(annotations: EffectiveToolAnnotations | undefined): string | null;
+/**
+ * CFG-27 — pure, testable mapping from a {@link ShellSafetyVerdict} + the raw command to a
+ * {@link RaterAction}, keyed on the **rung** (spec §4.2, §8):
+ *
+ * | Outcome | `read-only`/`write` | `auto-safe` | `full-auto` | `bypass` |
+ * |---|---|---|---|---|
+ * | — (no rating) | escalate | | | approve |
+ * | `safe` | — | approve | approve | — |
+ * | `destructive` | — | escalate | negotiate ([[EXT-29]]; escalate for now) | — |
+ * | `catastrophic` | — | escalate | escalate — **never negotiate** | — |
+ * | `attack` | — | **halt** | **halt** | — |
+ *
+ * Order of precedence (fail-closed FIRST — **this ordering IS the safety property**):
+ *
+ * 1. `bypass` → `approve`. The gate is off. The declared deny list and the exec-time hardline
+ *    floor still apply, but neither is decided here.
+ * 2. Unrated rungs (`read-only`, `write`) → `escalate`. No model is consulted at all; the
+ *    allow-list is checked by the caller BEFORE this function, so reaching here means the human
+ *    decides. (Both rungs behave identically for the shell because the shell is the only gated
+ *    tool today — the built-in read/write tools each rung grants are not gated until [[EXT-30]]
+ *    widens the gate. That is a scope boundary, not a missing branch.)
+ * 3. **The deterministic preflights, which FLOOR the outcome at `destructive` and never lower
+ *    one** ({@link preflightFloorReason}). Ambiguity ({@link classifyCommand} returns null — the
+ *    command composes / substitutes / redirects, so its target cannot be statically resolved), the
+ *    script-env-leak preflight ({@link hasScriptEnvLeakRisk}), and EXT-61's open-world preflight
+ *    ({@link findOpenWorldHostLiterals} — a host literal in a fetch/transfer position, §4.6) are all
+ *    recomputed from the RAW command, independently of what
+ *    the rater said. Any one of them rewrites a verdict that sits BELOW the floor — i.e. `safe`, and
+ *    only `safe` ({@link isBelowDestructiveFloor}) — to `destructive` with an honest
+ *    {@link COULD_NOT_ASSESS_PREFIX} reason, **before the `safe` check**, so a manipulated `safe`
+ *    verdict can never slip an unresolvable command through. **A rater verdict may only ever make
+ *    an outcome worse, never better**, and so may a preflight: `destructive`, `catastrophic` and
+ *    `attack` all pass through UNCHANGED. (Before the rescale this branch excluded the single
+ *    halting outcome BY NAME. Renamed in place it would have let a preflight hit *downgrade* a
+ *    `catastrophic` verdict to `destructive` — the exact inverse of the invariant above, silently
+ *    trading an unnegotiable escalation for a negotiable one at `full-auto`.)
+ * 4. `attack` → `halt`, at both rated rungs, never negotiable.
+ * 5. `safe` → `approve`; `catastrophic` → `escalate` and MUST NOT enter §5; `destructive` →
+ *    `escalate` (a negotiation at `full-auto` once [[EXT-29]] lands).
+ *
+ * **EXT-58 (§4.4): the verdict's `suggestedTool` is not read here, and that is deliberate.** A
+ * suggestion is never an approval — it must not change the action, must not approve the original
+ * command, and must not pre-approve the suggested tool. The gate also never decides for itself that
+ * a shell command is "equivalent" to a built-in and substitutes it: any such equivalence test would
+ * be a second command parser, and a second command parser is a second place for the gate to be
+ * bypassed. The suggestion is carried, untouched, to the human (§6) and to the model (§7) — nothing
+ * else. Note that the fail-closed rewrite in (3) builds a FRESH verdict and therefore drops any
+ * suggestion along with the reason it belonged to: a verdict the gate has just declared
+ * untrustworthy must not keep recommending anything. A verdict the preflight leaves alone was never
+ * declared untrustworthy — the gate is agreeing with it, not overriding it — so it keeps both.
+ *
+ * @param command The raw command string (used to recompute ambiguity + preflight independently
+ *   of the rater, so the gate is robust even if the rater is wrong or manipulated).
+ * @param verdict The rater's verdict (or {@link FAIL_CLOSED_VERDICT}); `undefined` at the unrated
+ *   rungs. A missing verdict at a RATED rung is treated as {@link FAIL_CLOSED_VERDICT}.
+ * @param opts The rung in force.
+ */
+export declare function mapVerdictToAction(command: string, verdict: ShellSafetyVerdict | undefined, opts: RaterDecisionOptions): RaterDecision;
+/**
+ * EXT-71 §3.2 — the mapping for a call an **allow entry already matched** while keeping the rater
+ * involved (`rate: true`). This is a **TRIPWIRE, not a re-adjudication**, and the difference is the
+ * whole reason it is a separate function from {@link mapVerdictToAction}:
+ *
+ * | Outcome | Action | Why |
+ * |---|---|---|
+ * | `safe` | approve | nothing to say |
+ * | `destructive` | **approve** | the human already authorized this call; the rater does not overrule a standing human decision by disliking it |
+ * | `catastrophic` | escalate | a human decides, and per §4.2 that approval is never sticky |
+ * | `attack` | **halt** | exactly per §4.2 — the structure evidenced compromise, which no prior grant answers |
+ *
+ * The rater's job on an allow-listed call is to catch the tail where a broad entry matched
+ * something structurally hostile — not to re-ask a question the human answered.
+ *
+ * **The deterministic preflights are deliberately not consulted** ({@link preflightFloorReason} is
+ * not called). §4.6 states it directly for the open-world arm: *an allow match lifts this floor even
+ * when the entry keeps the rater involved — the tripwire still sees the call; the floor does not
+ * apply to it.* The other two arms are lifted with it, and doing so changes no outcome: a preflight
+ * only ever raises `safe` to `destructive`, and both of those run here. Applying the floor would
+ * therefore alter nothing except to replace an honest verdict with a note about a decision this
+ * mapping does not make. (The ambiguity arm cannot fire at all — an allow entry does not match a
+ * command that fails to statically resolve.)
+ *
+ * @param verdict The rater's verdict; `undefined` or a fail-closed verdict is `destructive` and so
+ *   runs — the tripwire failing to answer does not revoke the human's standing decision, exactly as
+ *   `rate: false` would not have asked in the first place.
+ */
+export declare function mapAllowMatchedVerdictToAction(verdict: ShellSafetyVerdict | undefined): RaterDecision;