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

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

@@ -0,0 +1,935 @@
+/**
+ * @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 — `assisted` and `auto` (see `APPROVAL_RUNGS`); `manual`,
+ * `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}. §5.1's
+ *    negotiation context ([[EXT-29]]) is admitted on exactly those terms — the justification, the
+ *    prior rounds and the last user messages are each fenced in the user message, and
+ *    {@link RATER_NEGOTIATION_GUIDANCE} extends the untrusted-data contract to their tags. Nothing
+ *    else from the conversation is admitted at any round: no tool output, no file contents, no
+ *    fetched pages (§4.3).
+ * 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}.
+ *
+ * A command whose target the gate cannot statically resolve is RATED like any other ([[EXT-81]]),
+ * carrying a neutral note about the shape the parser saw ({@link buildParserPreflightNote}). It is
+ * not an action, not a floor, and not a reason to skip the call.
+ *
+ * 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';
+import { type RaterCallCapture } from '#src/core/shell/approvalCapture.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.
+ *
+ * **The schema is written plainly, as the verdict the rater's CALLERS want.** `suggestedTool` is a
+ * plain `.optional()` and the parsed verdict's `suggestedTool` is `string | undefined`. What a
+ * strict `json_schema` provider has to be sent instead — the key required and its type nullable —
+ * and the `null` that then comes back are entirely the business of
+ * {@link structuredOutputBoundary}, which {@link rateShellCommand} runs both halves of the call
+ * through. Nothing about the wire belongs in this object; putting it here is what made the schema we
+ * send contradict the schema we validate with.
+ */
+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. `suggestedTool` is `string | undefined`
+ * and never `null` — the boundary the rating call goes through collapses a `null` to the key being
+ * absent before any consumer sees it, so "no suggestion" has exactly one spelling.
+ */
+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 the 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, which is what lets a
+ * caller tell the gate defaulting from the model judging ({@link isFailClosed}).
+ */
+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 `assisted` — 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 `assisted` 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-29]] (spec §5.1) — how to WEIGH the negotiation context, added to the SYSTEM prompt for
+ * exactly the ratings that carry one ({@link buildNegotiationContextBlock}).
+ *
+ * **It is conditional on the CONTEXT, and that is the design rather than an optimisation.** Round 1
+ * is deliberately context-free (§5.1): there is no justification to weigh and no transcript to
+ * reason from, so a prompt explaining how a justification may lower an outcome has nothing to
+ * govern and everything to prime. Tying it to the block means the two can never disagree — the
+ * rules about weighing the extra context appear exactly when the extra context does.
+ *
+ * **§5.2's wording rules are NOT here, and the split is the point.** They are scoped by *whether
+ * the rejection is addressed to the agent at all* — which is what `auto` means — not by whether a
+ * transcript happens to exist yet; see {@link RATER_NEGOTIABLE_REJECTION_GUIDANCE}.
+ *
+ * Three rules are normative and none may be softened into another:
+ *
+ * - **A justification may only ever LOWER a rating** — *lower* meaning **less severe**. It may move
+ *   `destructive` to `safe`; it may never move `safe` to `destructive`. That is the permissive
+ *   direction on purpose: a negotiation the justification cannot win is not a negotiation.
+ * - **A stated intent that does not match what the command does is grounds for REJECTION, not for a
+ *   discount.** This is the counterweight to the rule above and is not optional — the justification
+ *   is the one place in the whole design where attacker-influenceable text can *reduce* an outcome.
+ * - **`attack` and `catastrophic` are exempt from the entire mechanism** (§4.2). No justification,
+ *   no revision and no accumulated context moves either.
+ *
+ * The opening clause extends {@link RATER_SYSTEM_PREAMBLE}'s untrusted-data contract to the new
+ * tags. The preamble names `<command_to_evaluate>` alone and cannot be edited without breaking
+ * round-1 byte-identity, so the tags this block introduces are declared untrusted *here*, in the
+ * same prompt that introduces them.
+ */
+export declare const RATER_NEGOTIATION_CONTEXT_GUIDANCE: string;
+/**
+ * [[EXT-29]] (spec §5.2) — **how a rejection must be WORDED, added whenever the rejection will be
+ * read by the agent** rather than by a person.
+ *
+ * **This is scoped by MODE, not by round, and the distinction is the whole of §5.2.** §5.1 governs
+ * what *context* a rating is allowed to see, and round 1 sees the command alone; §5.2 governs how a
+ * rejection is *written*, and a rejection is written the same way in every round of a negotiation
+ * — including the first, which is the round §5.6's escalation example requires to name the fix
+ * (*"Name the commits to drop, or use `--soft`"*). What decides whether these rules apply at all is
+ * whether the rejection is *addressed to the agent*: at `auto` it is, at `assisted` a `destructive`
+ * outcome goes to the human instead, so *"MUST invite a response"* would be addressed to nobody.
+ *
+ * Turning it on therefore keys on {@link import('#src/config.js').isNegotiatingRung} and NOT on
+ * whether a negotiation block exists. The two are independent by construction: a cleared transcript
+ * (§5.3) produces a round-1 *context* that is still a round of a negotiation.
+ *
+ * It sits LAST in the system prompt, after {@link buildGrantedToolsGuidance}, because §5.2's list of
+ * things a rejection may name ends with *a granted built-in that does the job* — a clause that reads
+ * as an instruction only once that list is already on the page.
+ *
+ * The two named anti-patterns are stated as failures rather than merely left out: a bare *"Rejected.
+ * This is destructive."* leaves the agent nothing to act on, and a rejection that restates the danger
+ * and asks the agent to explain itself invites another justification rather than a better command.
+ */
+export declare const RATER_NEGOTIABLE_REJECTION_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 the rating criteria are the same at every rated rung. Two blocks are appended on top of them,
+ * and they key on **two independent things** ([[EXT-29]]):
+ *
+ * - `hasNegotiationContext` appends {@link RATER_NEGOTIATION_CONTEXT_GUIDANCE} — the rules for
+ *   weighing a justification and a transcript, which have nothing to govern until one exists.
+ * - `negotiable` appends {@link RATER_NEGOTIABLE_REJECTION_GUIDANCE} — §5.2's rules for wording a
+ *   rejection that the *agent* will read, which apply at every round of a negotiation including the
+ *   first.
+ *
+ * **They are two parameters and not one because they are two questions.** Tying §5.2 to the context
+ * would silence it in exactly the two rounds §5.6 requires it in: round 1, and the round right after
+ * a §5.3 reset — both of which are round-1 *contexts* inside a live negotiation. Both blocks only
+ * ever APPEND, so a negotiated system prompt still has the plain one as its prefix.
+ *
+ * @param grantedTools §4.4's already-granted built-ins, or nothing.
+ * @param options `hasNegotiationContext` — whether this rating carries a §5.1 context; callers
+ *   should not decide it for themselves, since {@link buildRaterPrompt} derives it from the one
+ *   thing that decides it, namely whether {@link buildNegotiationContextBlock} produced a block.
+ *   `negotiable` — whether a rejection will be handed back to the agent (§5.2), i.e. the rung
+ *   negotiates ({@link import('#src/config.js').isNegotiatingRung}).
+ */
+export declare function buildRaterSystemPrompt(grantedTools?: readonly GrantedToolSummary[], options?: {
+    hasNegotiationContext?: boolean;
+    negotiable?: boolean;
+}): 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;
+/**
+ * [[EXT-29]] (spec §5.1) — one COMPLETED round of a negotiation, as the next round's rater sees it.
+ *
+ * It carries exactly what §5.1's third bullet admits and nothing else: the command the agent
+ * proposed, the justification it attached (when it attached one), and **the rater's own outcome and
+ * explanation** for that round — *"the rater reasons from its earlier positions rather than
+ * re-deriving them."*
+ *
+ * **The rater's half is two flat fields rather than an embedded {@link ShellSafetyVerdict}**, and
+ * that is deliberate. A verdict also carries §4.4's `suggestedTool`, which is advice about the
+ * rating that produced it and not part of the history §5.1 admits; a renderer handed a three-field
+ * object that renders two of them is a silent drop waiting to be read as a bug. Flat fields mean the
+ * builder renders everything it is given, and the type states the admitted set by construction.
+ *
+ * `command` is the RAW command as the agent proposed it. The builder normalizes and home-folds it
+ * with the same functions the live command goes through, so the transcript shows a past round in the
+ * form that round was actually rated in, then renders it on one line — see
+ * {@link buildNegotiationContextBlock}.
+ */
+export interface RaterNegotiationRound {
+    /**
+     * The command the agent proposed in that round, RAW. The builder normalizes, home-folds and
+     * one-lines it; a caller that pre-processes it is doing the work twice and differently.
+     */
+    command: string;
+    /** The justification the agent attached to it, if any. Omitted when it argued nothing. */
+    justification?: string;
+    /** The rater's own outcome for that round. */
+    outcome: RaterOutcome;
+    /** The rater's own one-sentence explanation for that round. */
+    reason: string;
+}
+/**
+ * [[EXT-29]] (spec §5.1) — the additional context a rating from **round 2 onward** carries. Absent,
+ * or present but carrying nothing, means a round-1 rating: the command alone, byte-for-byte the
+ * prompt this module built before the negotiation existed.
+ *
+ * "Carrying nothing" is defined so a caller never has to choose a spelling: `undefined`, `{}`, an
+ * empty or whitespace-only `justification`, and empty arrays are all the same round-1 context. §5.3
+ * clears the transcript with the counter, so the state the runner holds after a reset is exactly
+ * this, whichever way it spells it.
+ *
+ * Nothing here is bounded by the caller: the last-5 rule and the 1000-character truncation are
+ * applied by {@link buildNegotiationContextBlock}, so a caller that hands over an entire
+ * conversation still cannot put a pasted log into the rater's context.
+ */
+export interface RaterNegotiationContext {
+    /** The main model's justification for **this** command. Untrusted; fenced like the command. */
+    justification?: string;
+    /**
+     * The conversation's user messages, oldest first. Only the last {@link NEGOTIATION_MAX_USER_MESSAGES}
+     * are admitted and each is truncated — hand over as many as are to hand.
+     */
+    userMessages?: readonly string[];
+    /** The negotiation so far, oldest round first. */
+    priorRounds?: readonly RaterNegotiationRound[];
+}
+/**
+ * Neutralise any sequence that would CLOSE the fence `tag`, so untrusted text cannot escape it.
+ *
+ * A fenced block is only a boundary if the fenced text cannot write the boundary itself. Untrusted
+ * content containing its own closing tag ends the fence early and everything after it reads as our
+ * own prose — and inside `<negotiation_so_far>` that is not merely confusing but *persuasive*: the
+ * block quotes the rater's own previous positions back to it, and {@link RATER_NEGOTIATION_GUIDANCE}
+ * tells it to reason from those positions. A forged prior `safe` therefore argues for approval in
+ * the rater's own voice.
+ *
+ * The replacement carries no angle brackets at all (a marker that spelled the tag out would be the
+ * very sequence being removed) and says what happened, because a rater that can see text was
+ * tampered with has been told something useful about the command it is rating.
+ *
+ * **Matching is deliberately loose, and the looseness is the mechanism.** The reader is a language
+ * model, not a parser, so a matcher that is stricter than the reader is not a filter — it is a list
+ * of spellings the attacker gets to choose from. Four kinds of slack are closed: case, the
+ * whitespace an XML parser would ignore (`</ justification >`), the compatibility glyphs NFKC folds
+ * (a fullwidth solidus is a solidus to a reader), and any invisible spliced into the tag
+ * ({@link INVISIBLE_FORMAT_CHARS}).
+ *
+ * **That is four kinds of slack, not all of them**, and the difference is worth keeping in view: the
+ * invisibles are covered by an enumeration of Unicode properties, so this is as tolerant as those
+ * properties are and no more. {@link INVISIBLE_FORMAT_CHARS} states that residual; a character
+ * measured to render as blank and walk through belongs in that class, not in a second matcher here.
+ *
+ * Self-reconstruction is impossible by construction: the replacement contains no angle bracket and
+ * no slash, so no arrangement of neutralised text can rebuild a closing tag.
+ *
+ * Parameterised by tag because it guards every fence in the rating prompt — the three §5.1 ones and
+ * `<command_to_evaluate>` — rather than each growing a mechanism that escapes differently. Exported
+ * so a test can drive the matcher directly.
+ *
+ * **THE RESIDUAL IS WIDER THAN A HOMOGLYPH LIST — measured, and do not size it from this comment.**
+ * This matcher catches the tag spelled essentially exactly. Four classes walk through, and the first
+ * needs no Unicode at all:
+ *
+ * 1. **Pure ASCII near-misses** — `</tag foo>` (a trailing attribute), `<//tag>`, `</tag/>`, and a
+ *    plain space inside the name. Note the asymmetry that makes the last one easy to miss: a
+ *    ZERO-WIDTH space between two letters of the name IS neutralised by the strip below, while an
+ *    ordinary space in the identical position is not.
+ * 2. **Solidus homoglyphs** — NFKC folds the fullwidth solidus (U+FF0F) but not the fraction slash
+ *    (U+2044), the division slash (U+2215) or the big solidus (U+29F8).
+ * 3. **Bracket homoglyphs** — U+2039, U+27E8, U+3008, U+2329, U+276C.
+ * 4. **Tag-name homoglyphs** — Cyrillic and Greek lookalikes inside the tag name.
+ *
+ * **The ASCII class is the serious one.** The reader this function defends against is a language
+ * model, and `</tag foo>` reads as a closing tag to a model more readily than any homoglyph does —
+ * it is what a closing tag with an attribute looks like in the XML-shaped prompt it sits in.
+ *
+ * **Nothing mechanical is fooled by any of it:** none produces the literal `</tag>`, so no boundary
+ * count is wrong and no test that counts fences can see it. That is precisely why it is written here.
+ *
+ * **Left open for SCOPE, not because it is mild** — the matcher guards all four fences, so widening
+ * it lands on every one at once. That decision, and the shape it should take (a tolerant matcher
+ * reaches class 1; a confusable skeleton answers 2-4), is [[EXT-111]].
+ */
+export declare function neutralizeClosingTag(text: string, tag: string): string;
+/**
+ * [[EXT-29]] (spec §5.1) — the negotiation context block appended to the rater's USER message, or
+ * `null` when there is no negotiation (a round-1 rating).
+ *
+ * **Everything here is attacker-influenceable and every part of it is fenced**, exactly as
+ * `<command_to_evaluate>` is: the justification is written by a main model that reads untrusted
+ * input, the user messages arrive through a channel an attacker can reach, and the prior rounds
+ * carry both. The system prompt's {@link RATER_NEGOTIATION_GUIDANCE} declares these tags untrusted
+ * and is emitted with this block for that reason. Only the rater's own past outcomes and our own
+ * headings are ours, and they are the block's structure rather than its contents.
+ *
+ * **The fences here are enforced, not merely drawn.** Two things could otherwise write the block's
+ * own structure from inside it, and both are neutralised at the point of rendering: a closing tag
+ * ({@link neutralizeClosingTag}) and a newline in any one-line slot ({@link oneLine}). The amplifier
+ * that makes this worth more than tidiness is what the block IS — it quotes the rater's previous
+ * outcomes back to it under guidance telling it to reason from them, so a forged prior `safe` argues
+ * for approval in the rater's own voice.
+ *
+ * **The order inside the block narrows outward from the command being rated**: the justification is
+ * about THIS command, the transcript is the exchange that produced it, and the user messages are the
+ * mandate around the whole thing. It also keeps the agent's argument for the pending command out of
+ * the final position, which is the one a model weighs hardest.
+ *
+ * **Prior commands are normalized here**, by the same function the live command goes through, so a
+ * past round appears in the form it was actually rated in. **Home-folding applies to every value the
+ * block renders** — the justification and the user messages as much as the commands — because
+ * {@link foldHomePath} exists to keep the identifying form out of the prompt, and a prose field is
+ * where an absolute home path is most likely to appear, not least.
+ *
+ * Bounds are applied here rather than trusted from the caller: at most
+ * {@link NEGOTIATION_MAX_USER_MESSAGES} messages (the LAST that many), each truncated to
+ * {@link NEGOTIATION_USER_MESSAGE_MAX_CHARS}. Blank entries are dropped before the last-5 window is
+ * taken, so a run of empty messages cannot spend the budget that carries the mandate — and "blank"
+ * counts the characters {@link INVISIBLE_FORMAT_CHARS} names as nothing ({@link isBlank}), so a
+ * value carrying only those cannot render a block that a plain rating would not have.
+ *
+ * @param negotiation The §5.1 context, or nothing.
+ * @param home The home directory to fold — the caller's own `home`, so the block folds exactly as
+ *   the live command does.
+ * @returns The block, or `null` when nothing would be rendered. `null` is the single signal that
+ *   this is a round-1 rating: {@link buildRaterPrompt} uses it for both halves of the prompt, so the
+ *   guidance and the context can never appear without each other.
+ */
+export declare function buildNegotiationContextBlock(negotiation: RaterNegotiationContext | undefined, home?: string): string | null;
+/**
+ * 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,
+ * (§4.6) a host literal in a fetch position, and ([[EXT-81]]) the shape our own parser could not
+ * resolve. The command text is only ever DATA in the tag — the builder never executes or
+ * interpolates it as instructions, and the notes are our own trusted text beside it. That
+ * separation is ENFORCED rather than merely drawn: the command cannot close its own fence
+ * ({@link neutralizeClosingTag}), so no part of it can render where our notes render.
+ *
+ * The four preflight notes are worded differently on purpose, and the differences are the design:
+ *
+ * - The **script-env-leak** note caps nothing but says "treat this as at least destructive".
+ * - The **open-world floor** 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. It may say the command is never auto-approved, because a
+ *   floor really did fire on it.
+ * - The **parser** note ({@link buildParserPreflightNote}) is a third register again: those two
+ *   describe findings that ARE hazards and are entitled to a floor, while this one reports that our
+ *   parser could not read the command, which establishes nothing about it. So it states a mechanism
+ *   and asks a question, carries no verdict and no severity, and — unlike the open-world note —
+ *   never says the command has already been floored, because for these families none has.
+ * - The **composed open-world** note ({@link buildComposedOpenWorldNote}) shares that third register
+ *   and must not borrow the floor note's wording, for the reason the floor note is entitled to it:
+ *   no floor fired here. It names the DATA FLOW across the parts rather than restating the hostname,
+ *   which is already in the command text — see that function for the measurement behind that
+ *   distinction.
+ *
+ * **Order matters here and is the order of a reader's attention**: the two hazard notes come first
+ * because each names something positively established, then the parser note, then its open-world
+ * elaboration — general shape of what could not be resolved, then the specific flow inside it. Then,
+ * last, [[EXT-29]]'s negotiation context ({@link buildNegotiationContextBlock}) — the notes describe
+ * THIS command, the negotiation is the history around it.
+ *
+ * **Round 1 is the prompt this function built before the negotiation existed, character for
+ * character.** No negotiation, or one carrying nothing, adds no block and no guidance; a negotiated
+ * round only ever APPENDS to both halves. §5.3 clears the transcript with the counter, so the rating
+ * after a reset is a round-1 rating by construction rather than by the caller remembering to make
+ * one.
+ *
+ * §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[];
+    /**
+     * [[EXT-29]] (§5.1) — the negotiation so far, from round 2 onward. Absent or empty builds
+     * exactly the round-1 prompt this function built before the negotiation existed, character for
+     * character, which is what makes §5.6's *"a cleared transcript means a round-1 context"* a
+     * property of this function rather than a discipline the caller has to keep.
+     */
+    negotiation?: RaterNegotiationContext;
+    /**
+     * [[EXT-29]] (§5.2) — whether a rejection will be handed back to the AGENT rather than to a
+     * person, i.e. the rung negotiates ({@link import('#src/config.js').isNegotiatingRung}).
+     *
+     * **Independent of `negotiation` on purpose.** §5.1 decides what the rating may SEE; this
+     * decides how a rejection must be WRITTEN, and the two diverge in exactly the round §5.6 cares
+     * most about — round 1 of a negotiation, and the round right after a §5.3 reset, where the
+     * context is empty and the rejection is still addressed to the agent.
+     *
+     * It changes the SYSTEM prompt only. The user message is a function of the command and the
+     * context alone, so a negotiation's round 1 has a byte-identical user prompt to an
+     * `assisted` rating of the same command.
+     */
+    negotiable?: boolean;
+}): {
+    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[];
+    /**
+     * [[EXT-29]] (§5.1) — the negotiation so far, for a rating from round 2 onward. Passed straight
+     * to {@link buildRaterPrompt}; absent or empty, this call is a round-1 rating and the prompt,
+     * the verdict and every decision made from it are exactly what they were before.
+     */
+    negotiation?: RaterNegotiationContext;
+    /**
+     * [[EXT-29]] (§5.2) — whether a rejection is addressed to the agent (the rung negotiates).
+     * Passed straight to {@link buildRaterPrompt}; see the option there for why it is independent
+     * of `negotiation`.
+     */
+    negotiable?: boolean;
+    /**
+     * [[TUI-C27]] — the sink for the diagnostic record of THIS call, handed over **at the send
+     * site**, carrying the prompt strings that are about to be sent.
+     *
+     * It is called once, BEFORE the model is invoked, with a record this function then fills in as
+     * the answer arrives. Two properties follow, and both are the point:
+     *
+     * - **The prompt is captured, never re-rendered.** The caller receives the very strings passed
+     *   to `invoke`, so nothing downstream can rebuild a prompt that disagrees with the one that
+     *   was actually sent — the one thing a diagnostic archive must never do.
+     * - **A rater that never answers still leaves a record of what it was asked.** The record is in
+     *   the caller's hands before the call is made, so a hang, a timeout or a throw cannot take the
+     *   question with it.
+     *
+     * Omitted (the eval target, and every caller that wants no diagnostics) costs nothing: no
+     * record is built.
+     */
+    onCapture?: (capture: RaterCallCapture) => void;
+    /** [[TUI-C27]] — `approvals.rater`, recorded on the capture so a dump names WHO rated. */
+    raterProfile?: string;
+}): 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.
+ * - `reject` — [[EXT-29]] (§5): hand the rater's explanation back to the **agent** as the refused
+ *   call's tool result (§7), opening a round of the negotiation. Returned for `destructive` at
+ *   `auto` and nowhere else.
+ *
+ * **`reject` says the outcome is negotiable, NOT that the negotiation may continue.** This mapping
+ * is keyed on the rung and knows nothing about how many rounds have been spent; §5.3's consecutive
+ * cap and the reachability bound live with the state they count, in the runner, which turns a
+ * `reject` into an escalation once either is spent. Putting the counters in here would make a pure
+ * rung-keyed table depend on session history, and would give the eval target
+ * (`@gaunt-sloth/batch`'s `raterTarget`) an action that varies with something it does not model.
+ *
+ * **[[EXT-81]] retired the fourth arm, `abstain`.** A command whose target the gate could not
+ * statically resolve used to skip the rating call entirely and return that action instead. Under
+ * §6.1's rule — *deterministic checks fire only where we are confident something is a threat; where
+ * we cannot tell, the model decides* — a parser reporting that it could not resolve a string is not
+ * a detection, so it no longer earns an action of its own. What it earns is a neutral note in the
+ * rating prompt ({@link buildParserPreflightNote}) and a real rating, which is also what restores
+ * the ceiling: `catastrophic` and `attack` were UNREACHABLE for that whole class while nobody rated
+ * it, so `pwd && rm -rf ~` could only ever be floored at `destructive`.
+ *
+ * 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' | 'reject';
+/** 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;
+/** Which of the two deterministic preflights fired. See {@link preflightFloorFinding}. */
+export type PreflightFloorKind = 'script-env-leak' | 'open-world';
+/** A preflight finding: which arm fired, and the reason it floors the command with. */
+export interface PreflightFloorFinding {
+    kind: PreflightFloorKind;
+    reason: string;
+}
+/**
+ * [[TUI-C27]] — the same finding {@link preflightFloorReason} returns, with the ARM NAMED.
+ *
+ * The reason alone is what the decision needs; a diagnostic archive needs to say *which* stage
+ * decided, and "an environment variable was expanded into a script" and "a host literal sat in a
+ * fetch position" are two different findings a reader must be able to tell apart without matching
+ * prose prefixes. `preflightFloorReason` delegates here rather than the two existing side by side:
+ * a second copy of this ordering is how a gate and a dump come to disagree about what floored a
+ * command.
+ */
+export declare function preflightFloorFinding(command: string): PreflightFloorFinding | 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 | `manual`/`write` | `assisted` | `auto` | `bypass` |
+ * |---|---|---|---|---|
+ * | — (no rating) | escalate | | | approve |
+ * | `safe` | — | approve | approve | — |
+ * | `destructive` | — | escalate | **reject** — §5's negotiation ([[EXT-29]]) | — |
+ * | `catastrophic` | — | escalate | escalate — **never negotiate** | — |
+ * | `attack` | — | **halt** | **halt** | — |
+ *
+ * **[[EXT-81]] — there is no longer a row cutting across that column.** A command whose target the
+ * gate cannot statically resolve used to return `abstain` here, before the `safe` check and after
+ * the two severe outcomes. It is now rated like any other command, carrying a neutral note about
+ * the shape the parser saw ({@link buildParserPreflightNote}), and this table is the whole mapping
+ * again. The table gained nothing it did not have: what it LOST is a branch that made
+ * `catastrophic` and `attack` unreachable for every composed, substituting or redirecting command.
+ *
+ * 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 (`manual`, `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. (The two rungs behave identically here, and that is not a missing branch: what
+ *    separates them is which tools they auto-grant, decided once in `resolveGatedToolNames` when the
+ *    gated set is built. A call that reaches this function is already one the rung did not grant,
+ *    and the shell — this function's only subject — is granted by neither.)
+ * 3. **The deterministic preflight FINDINGS, which FLOOR the outcome at `destructive` and never
+ *    lower one** ({@link preflightFloorReason}): 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). Both
+ *    are recomputed from the RAW command, independently of what the rater said. Either rewrites a
+ *    verdict that sits BELOW the floor — i.e. `safe`, and only `safe`
+ *    ({@link isBelowDestructiveFloor}) — to `destructive` with an honest reason, **before the `safe`
+ *    check**, so a manipulated `safe` verdict can never slip one of them 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 `auto`.)
+ * 4. `attack` → `halt`, at both rated rungs, never negotiable.
+ * 5. `catastrophic` → `escalate`, and MUST NOT enter §5's negotiation.
+ * 6. `safe` → `approve`; `destructive` → `escalate` at `assisted`, `reject` at `auto` (§5's
+ *    negotiation, [[EXT-29]]).
+ *
+ * **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 script-env-leak arm is 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.
+ *
+ * @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;