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

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

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

package/dist/core/shell/approvalCapture.js

@@ -0,0 +1,108 @@
+/**
+ * How many gated decisions one session keeps. A ring buffer for the same reason the debug-log one
+ * is: each record carries a full rating prompt (a few KB), and a long `auto` session makes a lot of
+ * them. The newest are the ones a bug report is about, so the oldest are evicted.
+ */
+export const APPROVAL_CAPTURE_MAX = 50;
+/**
+ * The per-session log of gated decisions.
+ *
+ * **Instance-scoped, on the runner, and never a module singleton** — the same reason
+ * `ShellNegotiationState` and the grant stores are: a concurrent ACP / AG-UI session must not
+ * inherit another session's approvals history, and a dump taken in one must not describe the other.
+ */
+export class ApprovalCaptureLog {
+    records = [];
+    /**
+     * Open a record for a gated call and return it LIVE, already in the buffer.
+     *
+     * The caller mutates the returned object as the decision is made. See the module docblock for why
+     * the push happens here rather than at the end: a halt throws out of the decision, and a record
+     * assembled at the end would be lost on exactly the calls most worth keeping.
+     */
+    begin(record) {
+        this.records.push(record);
+        if (this.records.length > APPROVAL_CAPTURE_MAX)
+            this.records.shift();
+        return record;
+    }
+    /**
+     * The records so far, oldest first. A copy of the ARRAY: the records themselves are handed over
+     * live, because a decision still in flight is one the archive should show as it stands rather
+     * than not at all.
+     */
+    snapshot() {
+        return [...this.records];
+    }
+    /** Drop everything — the TUI's `/clear` rotates the thread. */
+    clear() {
+        this.records = [];
+    }
+}
+/**
+ * A short, KEY-FREE label for the rater model: its id and its provider type, and nothing else.
+ *
+ * Deliberately not a param dump. A live `BaseChatModel` carries an `apiKey` and a client instance,
+ * and this string goes into an archive people attach to bug reports — so it reads a fixed handful of
+ * scalar fields through guards, exactly as `debugDump`'s own live-model descriptor does, rather than
+ * serialising anything of the instance.
+ */
+export function raterModelLabel(model) {
+    if (!model || typeof model !== 'object')
+        return undefined;
+    const m = model;
+    let type;
+    try {
+        type = typeof m._llmType === 'function' ? m._llmType() : undefined;
+    }
+    catch {
+        type = undefined;
+    }
+    const id = [m.model, m.modelName, m.modelId].find((value) => typeof value === 'string');
+    if (id && type)
+        return `${type}/${id}`;
+    return id ?? type;
+}
+/**
+ * Describe the §5.1 context a rating is about to be made with — **as it was handed to the prompt
+ * builder**, so the record and the prompt cannot come to describe two different ratings.
+ *
+ * The note is the legibility half of the acceptance: an empty user-messages window means one thing
+ * at round 1 (by design) and something else entirely at round 3, and a reader of the archive has no
+ * way to tell them apart from a `[]`.
+ */
+export function describeRaterNegotiation(negotiation) {
+    const priorRounds = [...(negotiation?.priorRounds ?? [])];
+    const userMessages = [...(negotiation?.userMessages ?? [])];
+    const roundOne = priorRounds.length === 0;
+    const populated = userMessages.length > 0;
+    return {
+        round: priorRounds.length + 1,
+        roundOne,
+        contextSupplied: negotiation !== undefined,
+        ...(negotiation?.justification !== undefined
+            ? { justification: negotiation.justification }
+            : {}),
+        priorRounds,
+        userMessages,
+        userMessagesPopulated: populated,
+        userMessagesNote: userMessagesNote(negotiation !== undefined, roundOne, populated),
+    };
+}
+/** The sentence {@link describeRaterNegotiation} puts on the window, for a reader with no spec. */
+function userMessagesNote(contextSupplied, roundOne, populated) {
+    if (!contextSupplied) {
+        return ('No negotiation context was supplied for this rating (the rung does not negotiate, or this ' +
+            'was the allow-list tripwire), so the rater saw the command alone. An empty window here is ' +
+            'not a defect.');
+    }
+    if (roundOne) {
+        return ('Round 1: spec §5.1 admits no justification, no transcript and no user messages, so the ' +
+            'rater saw the command alone. An empty window here is BY DESIGN, not a defect.');
+    }
+    return populated
+        ? "Round 2 or later: the user's own recent messages WERE in the rater's view for this rating."
+        : 'Round 2 or later, and the window is still empty — the conversation had no non-blank user ' +
+            'message to admit. This one IS worth looking at.';
+}
+//# sourceMappingURL=approvalCapture.js.map

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

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

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

@@ -26,9 +26,8 @@
  */
 /**
  * Base class for the two run-ending approvals outcomes, so a caller that wants to present them as
- * an ending rather than a crash can catch both with one `instanceof`. Nothing does that today —
- * every surface currently shows the message as-is, which is already the whole explanation — and
- * [[TUI-C26]] is the node that will catch it to render the §6.1 banner.
+ * an ending rather than a crash can catch both with one `instanceof`. Every surface shows the
+ * message as-is, which is already the whole explanation.
  */
 export declare abstract class ApprovalStopError extends Error {
     /** The command that ended the run. */
@@ -40,9 +39,11 @@ export declare abstract class ApprovalStopError extends Error {
  * credential targeting, privilege escalation, persistence, deception, obfuscation). Ends the agent
  * loop; the model is told nothing and offered nothing.
  *
- * [[TUI-C26]] will present this interactively as the §6.1 red banner — any key stops, typing
- * `run anyway` runs this one command — BEFORE the throw; until then the run simply ends with this
- * message, which is what a non-interactive session gets either way (§6.2).
+ * **This is what reaches a surface that cannot ask.** An interactive surface is offered §6.1's red
+ * banner first — `GthAgentRunner.setAttackHaltCallback`, where typing `run anyway` runs this one
+ * command and everything else stops the run — and this error is thrown when no banner is wired, or
+ * when the banner is answered with anything but that phrase. A non-interactive session wires
+ * nothing and so gets this message directly (§6.2).
  *
  * The recovery this message names is deliberately the **allow-list**, not `bypass`. §4.2 makes
  * `approvals.allow` the supported way to run such a command unattended (it is consulted before the
@@ -71,5 +72,13 @@ export declare class NonInteractiveEscalationError extends ApprovalStopError {
      * `escalate` outranks a match on `allow`.
      */
     readonly escalatedBy: string | undefined;
-    constructor(command: string, outcome?: string, reason?: string, escalatedBy?: string);
+    /**
+     * [[EXT-29]] §6 — the §5 negotiation that preceded this escalation, rendered, when there was one.
+     *
+     * §6.2's message is the ONLY thing a person sees on this path — there is no prompt to attach a
+     * transcript to — so an unattended run that ended after three rejections would otherwise report
+     * the last command and give no hint that the agent had already been told twice what to fix.
+     */
+    readonly negotiation: string | undefined;
+    constructor(command: string, outcome?: string, reason?: string, escalatedBy?: string, negotiation?: string);
 }

package/dist/core/shell/approvalStop.js

@@ -26,9 +26,8 @@
  */
 /**
  * Base class for the two run-ending approvals outcomes, so a caller that wants to present them as
- * an ending rather than a crash can catch both with one `instanceof`. Nothing does that today —
- * every surface currently shows the message as-is, which is already the whole explanation — and
- * [[TUI-C26]] is the node that will catch it to render the §6.1 banner.
+ * an ending rather than a crash can catch both with one `instanceof`. Every surface shows the
+ * message as-is, which is already the whole explanation.
  */
 export class ApprovalStopError extends Error {
     /** The command that ended the run. */
@@ -46,9 +45,11 @@ export class ApprovalStopError extends Error {
  * credential targeting, privilege escalation, persistence, deception, obfuscation). Ends the agent
  * loop; the model is told nothing and offered nothing.
  *
- * [[TUI-C26]] will present this interactively as the §6.1 red banner — any key stops, typing
- * `run anyway` runs this one command — BEFORE the throw; until then the run simply ends with this
- * message, which is what a non-interactive session gets either way (§6.2).
+ * **This is what reaches a surface that cannot ask.** An interactive surface is offered §6.1's red
+ * banner first — `GthAgentRunner.setAttackHaltCallback`, where typing `run anyway` runs this one
+ * command and everything else stops the run — and this error is thrown when no banner is wired, or
+ * when the banner is answered with anything but that phrase. A non-interactive session wires
+ * nothing and so gets this message directly (§6.2).
  *
  * The recovery this message names is deliberately the **allow-list**, not `bypass`. §4.2 makes
  * `approvals.allow` the supported way to run such a command unattended (it is consulted before the
@@ -86,11 +87,20 @@ export class NonInteractiveEscalationError extends ApprovalStopError {
      * `escalate` outranks a match on `allow`.
      */
     escalatedBy;
-    constructor(command, outcome, reason, escalatedBy) {
+    /**
+     * [[EXT-29]] §6 — the §5 negotiation that preceded this escalation, rendered, when there was one.
+     *
+     * §6.2's message is the ONLY thing a person sees on this path — there is no prompt to attach a
+     * transcript to — so an unattended run that ended after three rejections would otherwise report
+     * the last command and give no hint that the agent had already been told twice what to fix.
+     */
+    negotiation;
+    constructor(command, outcome, reason, escalatedBy, negotiation) {
         super(`Approval required, but this session has no one to ask.\n` +
             `  Command: ${command}\n` +
             (outcome ? `  Rating: ${outcome}\n` : '') +
             (reason ? `  Reason: ${reason}\n` : '') +
+            (negotiation ? `${negotiation}\n` : '') +
             (escalatedBy
                 ? `  Matched approvals.escalate: ${escalatedBy}\n` +
                     `An escalate entry always asks a human, whatever the rung would have done, so no ` +
@@ -103,6 +113,7 @@ export class NonInteractiveEscalationError extends ApprovalStopError {
         this.outcome = outcome;
         this.reason = reason;
         this.escalatedBy = escalatedBy;
+        this.negotiation = negotiation;
     }
 }
 //# sourceMappingURL=approvalStop.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"approvalStop.js","sourceRoot":"","sources":["../../../src/core/shell/approvalStop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,KAAK;IACnD,sCAAsC;IAC7B,OAAO,CAAS;IAEzB,YAAsB,OAAe,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,+FAA+F;QAC/F,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IACpD,sEAAsE;IAC7D,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CACH,mFAAmF;YACjF,cAAc,OAAO,IAAI;YACzB,aAAa,MAAM,IAAI;YACvB,wFAAwF;YACxF,oFAAoF;YACpF,yFAAyF;YACzF,wDAAwD,EAC1D,OAAO,CACR,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,6BAA8B,SAAQ,iBAAiB;IAClE,gFAAgF;IACvE,OAAO,CAAqB;IACrC,sDAAsD;IAC7C,MAAM,CAAqB;IACpC;;;;;OAKG;IACM,WAAW,CAAqB;IAEzC,YAAY,OAAe,EAAE,OAAgB,EAAE,MAAe,EAAE,WAAoB;QAClF,KAAK,CACH,0DAA0D;YACxD,cAAc,OAAO,IAAI;YACzB,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,CAAC,WAAW;gBACV,CAAC,CAAC,iCAAiC,WAAW,IAAI;oBAChD,kFAAkF;oBAClF,oFAAoF;oBACpF,wBAAwB;gBAC1B,CAAC,CAAC,sFAAsF;oBACtF,+EAA+E;oBAC/E,kFAAkF;oBAClF,YAAY,CAAC,EACnB,OAAO,CACR,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF"}
+{"version":3,"file":"approvalStop.js","sourceRoot":"","sources":["../../../src/core/shell/approvalStop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,KAAK;IACnD,sCAAsC;IAC7B,OAAO,CAAS;IAEzB,YAAsB,OAAe,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,+FAA+F;QAC/F,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IACpD,sEAAsE;IAC7D,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CACH,mFAAmF;YACjF,cAAc,OAAO,IAAI;YACzB,aAAa,MAAM,IAAI;YACvB,wFAAwF;YACxF,oFAAoF;YACpF,yFAAyF;YACzF,wDAAwD,EAC1D,OAAO,CACR,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,6BAA8B,SAAQ,iBAAiB;IAClE,gFAAgF;IACvE,OAAO,CAAqB;IACrC,sDAAsD;IAC7C,MAAM,CAAqB;IACpC;;;;;OAKG;IACM,WAAW,CAAqB;IAEzC;;;;;;OAMG;IACM,WAAW,CAAqB;IAEzC,YACE,OAAe,EACf,OAAgB,EAChB,MAAe,EACf,WAAoB,EACpB,WAAoB;QAEpB,KAAK,CACH,0DAA0D;YACxD,cAAc,OAAO,IAAI;YACzB,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,CAAC,WAAW;gBACV,CAAC,CAAC,iCAAiC,WAAW,IAAI;oBAChD,kFAAkF;oBAClF,oFAAoF;oBACpF,wBAAwB;gBAC1B,CAAC,CAAC,sFAAsF;oBACtF,+EAA+E;oBAC/E,kFAAkF;oBAClF,YAAY,CAAC,EACnB,OAAO,CACR,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF"}

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

@@ -0,0 +1,141 @@
+/**
+ * @module core/shell/escalationSeverity
+ *
+ * [[TUI-C26]] (spec §6) — **how severe the escalation is, said in words.**
+ *
+ * Every escalation used to look identical: the same yellow line, the same
+ * `⚠ Auto-rater (<outcome>):`, on both surfaces. So `npm install lodash` and a typosquatted
+ * `curl | bash` produced the same dialog, and a dialog that looks the same for everything trains
+ * the reader to answer it the same way — which costs more than having no dialog at all.
+ *
+ * ## Why the words carry it, not the colour
+ *
+ * Colour is not reliably available. `NO_COLOR` is set on plenty of machines, output gets piped, a
+ * monochrome or high-contrast terminal renders every tone identically, and a reader may simply not
+ * be looking at hue. So each outcome carries **three** independent signals — a glyph, a tone and a
+ * sentence — and the sentence is the one that always arrives. A change that makes two outcomes read
+ * the same in words has removed the signal even if the colours still differ.
+ *
+ * **What the sentence says is the consequence, not the severity word again.** `catastrophic` is
+ * defined by needing something from *outside* the session to undo (rescue media, a backup, a
+ * re-provision), and that — not the adjective — is what a person can act on.
+ *
+ * ## The map is total, and `attack` is in it
+ *
+ * A `Record<RaterOutcome, …>` rather than a lookup with a default: an outcome added to
+ * {@link RATER_OUTCOMES} must be given words here, and cannot silently inherit another outcome's.
+ *
+ * `attack` is present for that totality and **not because the approval prompt renders it**. An
+ * `attack` verdict halts the run (`AttackHaltError`) on both rating paths, so it never reaches an
+ * approval dialog: it is answered at [[TUI-C68]]'s §6.1 banner, whose copy is
+ * {@link attackBannerCopy} — here, beside the heading it reuses, so the two cannot come to describe
+ * one verdict two ways.
+ *
+ * `attack` shares the `danger` tone and glyph with `catastrophic` deliberately: the two are not
+ * ranked against each other (they answer different questions — *can this be undone?* versus *is
+ * something hostile acting here?*), so distinguishing them by loudness would assert an ordering the
+ * rater's own schema refuses. They are distinguished where it matters, in what they say.
+ */
+import type { RaterOutcome } from '#src/core/shell/rater.js';
+/**
+ * How loud a surface should be about an outcome. A surface maps this to its own vocabulary — Ink
+ * colours on the TUI, the `display*` channel on the readline prompt — so neither has to hold its
+ * own opinion about which outcome is worse than which.
+ */
+export type EscalationTone = 'notice' | 'warn' | 'danger';
+/** Everything a surface needs to render one outcome, so no surface invents its own wording. */
+export interface RaterOutcomeDisplay {
+    /**
+     * The heading a surface paints above the rater's reason, glyph and sentence included.
+     *
+     * It keeps the `Auto-rater (<outcome>):` opening the dialog has always had — that is the
+     * attribution, and the reason underneath it is the rater's, not the gate's — and adds the
+     * consequence after it.
+     */
+    heading: string;
+    /** The tone the heading and the framed reason are painted in. */
+    tone: EscalationTone;
+}
+/**
+ * The label above the framed reason.
+ *
+ * The heading now carries a sentence of the gate's own, so without this the model-authored prose
+ * beneath it could be read as a continuation of what the gate said. §6 wants the opposite: the
+ * reason is the rater's, quoted, and it is framed exactly like the command for the same reason.
+ */
+export declare const RATER_REASON_LABEL = "    the rater's own words:";
+/** How to render {@link RaterOutcome} on an approval dialog. */
+export declare function describeRaterOutcome(outcome: RaterOutcome): RaterOutcomeDisplay;
+/**
+ * [[TUI-C68]] §6.1 — **the phrase that runs an `attack`-rated command anyway.** The only string on
+ * the banner that is not a refusal.
+ *
+ * A typed phrase rather than a key, because an irreversible decision must not be reachable by the
+ * muscle memory built answering routine prompts. A key merely *disjoint from today's menu* stops
+ * being disjoint the moment someone binds one; a phrase is immune to any future binding. `run`
+ * alone was considered and rejected as the leading token of half of what anyone types into a
+ * terminal.
+ *
+ * The label is never `bypass`: that is a rung (§2.5) and a far broader thing — it turns off the
+ * rater, the escalation and the halt together, for every command, for the whole run — and a user
+ * must never read this banner as switching to it.
+ */
+export declare const RUN_ANYWAY_PHRASE = "run anyway";
+/**
+ * §6.1 — does what the human typed grant this one command?
+ *
+ * **The whole matching rule, in one place both surfaces call**, so what the banner *says* is
+ * answerable and what a surface *accepts* cannot drift. Trimmed, lower-cased, compared whole:
+ * `RUN ANYWAY` and a phrase with surrounding spaces grant; `run`, `runanyway`, `run anyway please`
+ * and the phrase with a doubled inner space do not. No prefix, no initial, no `y`, no alias.
+ *
+ * **Everything that is not the phrase is a refusal, and that is the property the banner rests on.**
+ * An approval prompt grants only on an offered key and treats every other keystroke as a rejection;
+ * a text buffer inverts that by accumulating keystrokes instead of rejecting them, and a matcher
+ * this narrow is what puts it back — the buffer may hold anything at all, and only one value of it
+ * runs the command.
+ *
+ * Deliberately NOT whitespace-normalising the middle: a rule that repairs what the user typed is a
+ * rule that grants on something they did not type, and retyping a phrase costs nothing next to
+ * running this command by accident.
+ */
+export declare function grantsRunAnyway(typed: string): boolean;
+/**
+ * §6.1 — the banner's own words, shared so no surface invents its own.
+ *
+ * It carries what every surface must say and nothing about how any one of them is driven: the
+ * readline prompt reads a line in cooked mode and has no `q` or `Esc` to bind, so a keyboard line
+ * here would be false on one of the two surfaces. A surface adds its own keys beside these.
+ */
+export interface AttackBannerCopy {
+    /** The banner's title row — what happened, above everything else. */
+    title: string;
+    /** The `attack` heading from {@link describeRaterOutcome}, glyph and consequence included. */
+    heading: string;
+    /**
+     * **The irreversibility line, and it is UNCONDITIONAL** — on every attack banner, whatever the
+     * rating said, and not only where the command was also rated `catastrophic`.
+     *
+     * The banner is rare by construction (§4.1.1 forbids `attack` firing on ordinary work), so the
+     * line cannot become noise; and a static string cannot fail the way a model's explanation can. It
+     * is the last thing between a human and an action nothing else will stop.
+     */
+    irreversible: string;
+    /** What each control does, in the phrase's own words. */
+    controls: readonly string[];
+    /** The label a surface puts in front of the buffer the human types into. */
+    prompt: string;
+    /**
+     * What a surface says once the phrase has been accepted.
+     *
+     * It states the scope of what was just granted, because that is the half a user cannot observe:
+     * the command running is visible, and *only this one running* is not. Shared so neither surface
+     * can promise a persistence the runner does not perform.
+     */
+    granted: string;
+}
+/**
+ * §6.1 — the banner copy. A function rather than an exported object so one surface cannot mutate
+ * the strings another is about to paint.
+ */
+export declare function attackBannerCopy(): AttackBannerCopy;