@gaunt-sloth/core 2.0.0-alpha.29 → 2.0.0-alpha.30

package/dist/core/shell/normalize.js

@@ -2,11 +2,11 @@
  * @module core/shell/normalize
  *
  * Command-string normalization shared by the shell hardening layer. The hardline
- * blocklist (in `@gaunt-sloth/agent` `tools/shell/hardline`) and the EXT-9 Tier-2
+ * blocklist (`core/shell/hardline`) and the EXT-9 Tier-2
  * allow-list classifier ({@link ./arity.js}) both match against the *normalized* form so
  * trivial obfuscation (ANSI escapes, fullwidth glyphs, backslash splits, padded
- * whitespace) cannot smuggle a command past the guard. Canonical home is core so both the
- * core runner (allow-list) and the agent toolkit (hardline) import a single implementation.
+ * whitespace) cannot smuggle a command past the guard. Canonical home is core so every
+ * consumer — the allow-list, the hardline floor, the approvals gate — imports one implementation.
  *
  * Patterned after hermes-agent `tools/approval.py:_normalize_command_for_detection`.
  */
@@ -32,8 +32,8 @@ const LINE_BREAK_RUN = /\s*\n\s*/g;
  * every character at which the shell stops one command and starts the next: `;`, `&` (hence
  * `&&`), `|` (hence `||`), and a LINE BREAK. Both consumers of the normalized form build their
  * patterns from it — the allow-list classifier's fail-closed check
- * ({@link import('./arity.js').classifyCommand}) and the agent hardline blocklist's pattern
- * terminators (`@gaunt-sloth/agent` `tools/shell/hardline`) — so the two layers can never again
+ * ({@link import('./arity.js').classifyCommand}) and the hardline blocklist's pattern
+ * terminators (`core/shell/hardline`) — so the two layers can never again
  * disagree about what a separator is.
  *
  * The layers disagreed before EXT-55: `;`/`&&`/`|` made a command ambiguous (fail-closed) but a

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

@@ -3,7 +3,7 @@
  *
  * 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`,
+ * 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>`,
@@ -17,7 +17,12 @@
  * 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}.
+ *    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.
@@ -34,6 +39,7 @@ 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)
@@ -212,7 +218,7 @@ export declare const RATER_CATASTROPHIC_GUIDANCE: string;
  * 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
+ * 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
@@ -223,7 +229,7 @@ export declare const RATER_CATASTROPHIC_GUIDANCE: string;
  * - **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
+ *   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,
@@ -266,6 +272,62 @@ export declare const RATER_ATTACK_GUIDANCE: string;
  * 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.
@@ -304,9 +366,31 @@ export declare function buildGrantedToolsGuidance(grantedTools: readonly Granted
  * 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.
+ * 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[]): string;
+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
@@ -323,13 +407,174 @@ export declare function hasScriptEnvLeakRisk(normalizedCommand: string): boolean
  * 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.
+ * 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:
  *
@@ -351,7 +596,15 @@ export declare function foldHomePath(command: string, home: string | undefined):
  *
  * **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.
+ * 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
@@ -365,6 +618,27 @@ export declare function foldHomePath(command: string, home: string | undefined):
 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;
@@ -392,6 +666,38 @@ export declare function rateShellCommand(command: string, config: GthConfig, opt
      * 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.
@@ -403,6 +709,16 @@ export declare function rateShellCommand(command: string, config: GthConfig, opt
  * - `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
@@ -422,7 +738,7 @@ export declare function rateShellCommand(command: string, config: GthConfig, opt
  * unmeasured classifier belongs behind a human who can correct it; a refusal has no correction
  * path.
  */
-export type RaterAction = 'approve' | 'escalate' | 'halt';
+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. */
@@ -506,15 +822,33 @@ export declare function applyDestructiveFloor(verdict: ShellSafetyVerdict | unde
  *   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 | `read-only`/`write` | `auto-safe` | `full-auto` | `bypass` |
+ * | Outcome | `manual`/`write` | `assisted` | `auto` | `bypass` |
  * |---|---|---|---|---|
  * | — (no rating) | escalate | | | approve |
  * | `safe` | — | approve | approve | — |
- * | `destructive` | — | escalate | negotiate ([[EXT-29]]; escalate for now) | — |
+ * | `destructive` | — | escalate | **reject** — §5's negotiation ([[EXT-29]]) | — |
  * | `catastrophic` | — | escalate | escalate — **never negotiate** | — |
  * | `attack` | — | **halt** | **halt** | — |
  *
@@ -529,11 +863,12 @@ export declare function openWorldToolFloorReason(annotations: EffectiveToolAnnot
  *
  * 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
+ * 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. (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.)
+ *    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
@@ -546,11 +881,11 @@ export declare function openWorldToolFloorReason(annotations: EffectiveToolAnnot
  *    `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`.)
+ *    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` (a negotiation at `full-auto` once [[EXT-29]]
- *    lands).
+ * 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