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

package/dist/core/GthAgentRunner.d.ts

@@ -1,6 +1,35 @@
-import { GthConfig } from '#src/config.js';
+import { type AllowlistCounts, type ApprovalRung, GthConfig, type McpAnnotationTrustChange, type McpAnnotationTrustView, type ResolvedApprovals, type ToolAnnotationHint } from '#src/config.js';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
-import { AgentResolvers, AgentStreamEvent, GthAgentFactory, GthAgentInterface, GthCommand, Message, StatusUpdateCallback, ToolApprovalCallback } from '#src/core/types.js';
+import { AgentResolvers, AgentStreamEvent, type AttackHaltCallback, GthAgentFactory, GthAgentInterface, GthCommand, GthRunStats, Message, StatusUpdateCallback, ToolApprovalCallback } from '#src/core/types.js';
+import { type ApprovalGrant } from '#src/core/approvals/grants.js';
+import { type ApprovalDecisionCapture } from '#src/core/shell/approvalCapture.js';
+/**
+ * GS2-81 — the page carrying WHICH commands honor `agent.backend`, pointed at rather than
+ * enumerated in the notice itself.
+ *
+ * The list belongs in exactly one place. A copy of it inside a runtime string is a second source of
+ * truth with nothing pinning it: the first draft of this notice already disagreed with the docs
+ * table written in the same commit (it omitted `workflow` agent steps), and no test could tell,
+ * because a sentence is not a claim a test can check. The docs table is checkable, and
+ * `agentBackendScope.spec.ts` pins that this URL's anchor still resolves to a real heading in it.
+ *
+ * **A GitHub blob URL, matching the other user-facing runtime doc links in this repo** (the
+ * approvals-protection pointer in `config/shell-policy.ts` and the 2.0 migration pointer in
+ * `config/schema.ts`) — a running CLI's user has no checkout for a relative path to resolve in.
+ */
+export declare const AGENT_BACKEND_SCOPE_DOCS_URL = "https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/configuration/profiles.md#which-commands-honour-it";
+/** Options for {@link GthAgentRunner#init} that qualify the run without changing how it behaves. */
+export interface GthAgentRunnerInitOptions {
+    /**
+     * GS2-81 — the CLI verb this run belongs to, for messages only, when `command` is deliberately
+     * `undefined`. It is a SEPARATE input from `command` because `command` is not a label: it selects
+     * the mode prompt (`readModePrompt`), the per-command approvals posture (`resolveApprovals`) and
+     * the command-specific filesystem config, so a helper agent that must run on the chat prompt —
+     * the `gth pr` change-requirements discovery agent — cannot borrow it to say which verb it serves.
+     * Nothing but the wording of a notice reads this.
+     */
+    owningCommand?: GthCommand;
+}
 /**
  * Agent simplifies interaction with LLM and reduces it to calling a few methods
  * {@link GthAgentRunner#init} and {@link GthAgentRunner#processMessages}.
@@ -19,36 +48,96 @@ export declare class GthAgentRunner {
      * for non-interactive entrypoints (a scripted `exec` run with no TTY to prompt on).
      */
     private toolApprovalCallback;
+    /**
+     * [[TUI-C68]] §6.1 — consumer hook invoked when the rater rates a command an `attack`, so an
+     * interactive surface can show the red banner before the run ends. Set via
+     * {@link setAttackHaltCallback}; **when unset the runner halts immediately**, which is the
+     * behaviour every surface had before a banner existed. A surface that forgets to wire it
+     * therefore keeps the halt rather than losing it.
+     */
+    private attackHaltCallback;
     /** The command the runner was initialized for; selects which `devTools` config applies. */
     private command;
     /**
-     * EXT-12 — runtime, session-scoped yolo flag toggled by the `/yolo` slash command. Distinct
-     * from the static `devTools.shellYolo` config flag (which omits the tool from `interruptOn` at
-     * agent-build time and cannot be changed mid-session). Because the tool stays gated (in
-     * `interruptOn`), this flag is consulted at the TOP of {@link decideToolApproval}: when ON, a
-     * gated `run_shell_command` is auto-approved WITHOUT prompting (yolo behaviour) for the rest of
-     * this runner's life. Never persisted; defaults OFF. It does NOT disable the hardline floor —
-     * catastrophic commands are still refused at exec time in `GthDevToolkit.executeCommand`.
+     * GS2-16 — snapshot of the last turn's analytics (token usage + invoked tools), captured from
+     * the agent at {@link cleanup} time. Needed because {@link runSingleShot} reads stats AFTER it
+     * has already called `cleanup()` (which nulls the agent); interactive callers read live via
+     * {@link getRunStats} before cleanup. Defaults to an empty tally.
      */
-    private sessionYolo;
+    private lastRunStats;
     /**
-     * EXT-9 Tier-2 session allow-list — approved command prefixes that auto-approve for the
-     * life of THIS runner instance. Instance-scoped (not module-global) so concurrent
-     * sessions (ACP / AG-UI multi-session) cannot stomp each other's approvals.
+     * CFG-27 — the runtime, session-scoped approvals posture, seeded at {@link init} from
+     * {@link resolveApprovals} and thereafter switchable for the session by `/approvals <rung>`.
+     * **This field, not the interrupt wiring, is where the rung lives.** The backends wire the
+     * interrupt rung-independently, so every tool any rung could gate arrives at the top of
+     * {@link decideToolApproval} and is judged against the rung recorded here — which is what makes
+     * `/approvals manual` take effect mid-session, and what keeps a config that pre-selects
+     * `bypass` switchable back. Never persisted.
+     *
+     * It does NOT disable the hardline floor — catastrophic commands are still refused at exec time
+     * in `GthDevToolkit.executeCommand` under every rung.
      */
-    private readonly sessionAllowlist;
+    private sessionApprovals;
     /**
-     * EXT-9 Tier-2 persisted (`always`) allow-list, loaded lazily on first use from
-     * `.gsloth/.gsloth-settings/shell-allowlist.json`. Null until the shell tool is gated
-     * and the allow-list is enabled; null also when persistence is disabled by config.
+     * CFG-26 — the model the AI rater rates with, when `approvals.rater.profile` names an identity
+     * profile. Resolved ONCE at {@link init} (never mid-turn) and handed to `rateShellCommand`;
+     * `undefined` means no profile is configured and the rater uses the session model.
      */
-    private persistedAllowlist;
-    private persistedAllowlistLoaded;
+    private raterModel;
+    /**
+     * EXT-66 — how many rating calls this session gave up on. Counted so the notice can say "3 times
+     * this session" rather than repeating an identical line, and so a silent drift toward
+     * escalate-everything has a number attached to it.
+     */
+    private raterTimeouts;
+    /**
+     * EXT-71 §3.1/§6 — what the escalation menu granted at run time, for the life of THIS runner
+     * instance: {@link ApprovalEntry} objects, never prefixes, and never anything from config (the
+     * declared lists are read-only input consulted straight from the posture). Instance-scoped so
+     * concurrent sessions (ACP / AG-UI multi-session) cannot stomp each other's approvals.
+     */
+    private readonly sessionGrants;
+    /**
+     * CFG-27 §3 — what the escalation menu's *always reject* choice adds at run time, in the same
+     * grammar ([[TUI-C26]] wires that writer; the store speaks it already). The entries DECLARED in
+     * `approvals.deny` are not here — they are read-only config input, matched from the posture — and
+     * both are handed to the same matcher, so a runtime refusal and a declared one are one list.
+     */
+    private denyGrants;
+    /**
+     * The persisted (`always`) grant store, loaded lazily on first use from
+     * `.gsloth/.gsloth-settings/shell-allowlist.json`. Null until a gated call actually needs it, and
+     * null when the file cannot be loaded at all (in which case `always` grants degrade to session).
+     */
+    private persistedGrants;
+    private persistedGrantsLoaded;
+    /**
+     * [[EXT-29]] §5 — the state of the agent↔rater negotiation at `auto`: the transcript, §5.3's
+     * consecutive-rejection counter and the reachability bound. Instance-scoped for the same reason
+     * the grant stores are — a concurrent ACP / AG-UI session must not inherit another's argument.
+     */
+    private readonly negotiation;
+    /**
+     * [[TUI-C27]] — the diagnostic record of every gated decision this session made, for
+     * `/debug-dump`. Instance-scoped for the same reason the negotiation and the grant stores are: a
+     * concurrent ACP / AG-UI session must not inherit another's approvals history, and a dump taken
+     * in one must not describe the other.
+     */
+    private readonly approvalCaptures;
+    /**
+     * GS2-81 — whether the caller supplied a backend factory. When it did NOT, this runner is
+     * hard-wired to the lean default below, so a config asking for `agent.backend: 'deep'` cannot be
+     * honored no matter what it says. Recorded here (rather than inferred later) because by then the
+     * fallback has already collapsed both cases into one function.
+     */
+    private readonly backendFactorySupplied;
     /**
      * @param agentFactory Produces the {@link GthAgentInterface} the runner drives.
      *   Defaults to the lean {@link GthLangChainAgent} (core). `@gaunt-sloth/agent`
      *   passes a factory returning a deep `GthDeepAgent` so the same runner can drive a
      *   `createDeepAgent` graph without core depending on deepagents.
+     *   **Omitting it opts the caller out of `agent.backend`** — see {@link init}, which says so out
+     *   loud rather than letting the key be dropped in silence.
      */
     constructor(statusUpdate: StatusUpdateCallback, resolvers?: AgentResolvers, agentFactory?: GthAgentFactory);
     /**
@@ -58,20 +147,156 @@ export declare class GthAgentRunner {
      */
     setToolApprovalCallback(callback: ToolApprovalCallback | null): void;
     /**
-     * EXT-12 — flip the runtime, session-scoped yolo flag (the `/yolo` slash command). When ON,
-     * gated `run_shell_command` calls auto-approve without prompting for the rest of this session;
-     * the hardline floor still applies at exec time. Returns the NEW state so the caller can render
-     * a notice. Session-scoped only — nothing is written to config.
+     * [[TUI-C68]] §6.1 — register the handler that shows the **attack banner**, the one way a human
+     * gets past an `attack` verdict. Pass `null` to clear.
+     *
+     * Separate from {@link setToolApprovalCallback} because it is a separate question with an
+     * inverted default: an absent approval callback means *this session has nobody to ask*, and an
+     * absent one here means *end the run*. Wiring it is what an interactive surface opts into; every
+     * other surface keeps the halt (see {@link attackHaltCallback}).
+     */
+    setAttackHaltCallback(callback: AttackHaltCallback | null): void;
+    /**
+     * §6.1 — **the single seam between an `attack` verdict and the end of the run.** Both rating
+     * paths — the §3.2 allow-match tripwire and the ordinary rater decision — go through here, so the
+     * banner cannot be present on one and missing on the other, which is the shape of bug that leaves
+     * a halt answerable in some sessions and not others with nothing on screen to tell them apart.
+     *
+     * It returns a decision for the one answer that grants and throws for everything else:
+     *
+     * - **no callback → throw**, immediately and unchanged. §6.2's rule is that a run with nobody to
+     *   ask never blocks and never times out into a grant; the way that is guaranteed is that waiting
+     *   is something only a wired surface can cause.
+     * - **`run-anyway` → approve, scope `once`.** Exactly one command runs. `once` is not a default
+     *   restated: it is what keeps §6.1's three "never"s true. Returning here is also returning from
+     *   *before* the block that records a sticky grant, so no allow-list entry and no session grant
+     *   can be written on this path — the next identical call is rated again and reaches this banner
+     *   again. Nothing here touches the rung, and nothing disables the rater, the escalation or the
+     *   halt for anything else.
+     * - **anything else → throw.** `stop`, and equally a value a surface invents or forgets to
+     *   return: the grant is one exact answer and everything else is a refusal.
+     */
+    private haltOrRunAnyway;
+    /**
+     * CFG-27 — switch the session-scoped rung (`/approvals <rung>`). Idempotent; returns the NEW
+     * rung so the caller can render a notice. Session-scoped only — nothing is written to config,
+     * and the declared allow/deny lists are unaffected (they are config input, not session state).
      */
-    toggleSessionYolo(): boolean;
-    /** EXT-12 — current state of the runtime session-scoped yolo flag (see {@link toggleSessionYolo}). */
-    isSessionYolo(): boolean;
+    setSessionApprovalRung(rung: ApprovalRung): ApprovalRung;
+    /** CFG-27 — the session's current approvals posture (rung + rater profile + declared lists). */
+    getSessionApprovals(): ResolvedApprovals;
+    /**
+     * [[TUI-C27]] — every gated decision this session made, oldest first, for the `/debug-dump`
+     * archive.
+     *
+     * Threaded by each surface into `writeDebugDump`, exactly as `agent.lastModelRequest` is: the
+     * writer redacts it with the same pass it applies to every other artifact, and a surface that
+     * does not thread it simply omits the file.
+     */
+    getApprovalCaptures(): ApprovalDecisionCapture[];
+    /**
+     * CFG-26 — the allow-list sizes for the `/approvals` display: how many command prefixes the
+     * human has trusted this session, and how many are persisted in the project file.
+     *
+     * READ-ONLY BY CONSTRUCTION: it reports the persisted count only when the store has ALREADY
+     * been loaded (or persistence is on and it can be read), and never through a path that would
+     * CREATE the store as a side effect of showing a display — a status command must not mutate
+     * session state. `always: undefined` therefore means "not loaded / persistence off", which the
+     * caller renders as `—` rather than a misleading `0`.
+     */
+    getAllowlistCounts(): AllowlistCounts;
+    /**
+     * CFG-27 — the session's deny entries for display: the declared `approvals.deny` entries
+     * (rendered one line each) followed by whatever the escalation menu's *always reject* added at
+     * run time. Both refuse a call, so both are shown.
+     */
+    getDenylist(): string[];
+    /**
+     * §3/§4.7.4 — **the grants themselves**, for an approvals view that shows *what* was granted,
+     * *when*, and *under which effective annotations*. The counterpart of {@link getAllowlistCounts},
+     * which answers only how many.
+     *
+     * The declared config lists are deliberately NOT here. They are something a human wrote and
+     * reviewed, they carry no `grantedAt` and no scope, and `getAllowlistCounts` already counts them
+     * alongside these; mixing them in would present a config line as something the session granted.
+     *
+     * **Read-only in both senses.** It never loads the persisted store — same rule as
+     * {@link getAllowlistCounts}: a display must not create the store in order to show it, so a
+     * session that has not yet needed the file lists its session grants alone. And every grant is
+     * **deep-copied on the way out**, because the stores hand back their live records: the copy on the
+     * way in is what makes a snapshot private to its grant, and handing the same object to a renderer
+     * would put what the gate matches against one property assignment away from any consumer.
+     */
+    getGrants(): ApprovalGrant[];
+    /**
+     * §4.7.1 — **which of each server's annotation hints this session believes**, for display.
+     *
+     * Every key either side names is listed: a configured `mcpServers` key with no policy of its own
+     * (which resolves through `defaults`), and a policy key naming a server the config does not have
+     * (which is what a typo looks like). Resolution is {@link trustedAnnotationHints}, the same
+     * function the gate derives effective annotations through, so the display cannot claim a
+     * relationship the gate does not act on.
+     */
+    getMcpAnnotationTrust(): McpAnnotationTrustView;
+    /**
+     * §4.7.1 — **believe, or stop believing, specific hints from one server**, for the life of this
+     * session. The runtime half of `approvals.mcp.servers.<key>.trustAnnotations` (§9), so a user can
+     * do from the TUI what they can do in config.
+     *
+     * **Per hint, never per server.** `hints` names the hints this call moves and leaves every other
+     * hint of that server's exactly as it was, because believing a server's `readOnlyHint` while
+     * disbelieving its `openWorldHint` is a coherent position and the common one. A "trust this
+     * server" flag is the design §4.7.1 rejects.
+     *
+     * **The previous set is what was IN FORCE, resolved through `defaults`.** A server not named
+     * under `servers` inherits `defaults`, and naming it makes it state its relationship in full (§9)
+     * — so seeding from the empty set would mean that believing one more hint silently withdrew every
+     * hint `defaults` had granted, which is a weakening the user did not ask for and would invalidate
+     * their grants.
+     *
+     * **Session-scoped only.** Nothing is written to config: the declared block is read-only input
+     * (§9.1), exactly as the rung is.
+     *
+     * A trusted external annotation still never grants more than the same annotation grants one of
+     * our own built-ins — that holds in `core/approvals/annotations.ts` by construction, and this
+     * changes only which hints are read.
+     */
+    setMcpAnnotationTrust(server: string, hints: readonly ToolAnnotationHint[], believe: boolean): McpAnnotationTrustChange;
+    /**
+     * §4.7.4 — which of this server's saved approvals the trust now in force weakens, for the notice
+     * that reports a trust change. **It predicts; it never removes.** The removal stays where Task
+     * 4 put it — at the call being decided — because that is the only moment the tool's declaration
+     * can be read for certain; here a server that is merely offline declares nothing and would read
+     * as having weakened everything.
+     *
+     * It compares through the same two functions the gate does: the effective-annotation source built
+     * from the posture as it stands *after* the change, and `annotationWeakenings`. A second
+     * comparison written for the display is how a warning comes to describe a rule the gate does not
+     * have.
+     */
+    private grantsWeakenedByCurrentTrust;
     /**
      * Init is split into a separate method. This may create a number of connections,
      * and we'd better have an instance by that moment, for the case things will go wrong,
      * so we can wrap init into try-catch and then call {@link #cleanup} within finally.
      */
-    init(command: GthCommand | undefined, configIn: GthConfig, checkpointSaver?: BaseCheckpointSaver | undefined): Promise<void>;
+    init(command: GthCommand | undefined, configIn: GthConfig, checkpointSaver?: BaseCheckpointSaver | undefined, options?: GthAgentRunnerInitOptions): Promise<void>;
+    /**
+     * GS2-81 — `agent.backend` is a COMMAND-SCOPED key, and this is where a command opts out of it.
+     *
+     * A caller that hands the runner no factory gets the lean {@link GthLangChainAgent}, whatever the
+     * config asked for: `agent.backend: 'deep'` is then accepted by the schema, resolved into the
+     * config, and dropped on the floor. `gth review` and `gth pr` are in exactly that position — the
+     * review module builds its runner without one, and `@gaunt-sloth/review` does not depend on
+     * `@gaunt-sloth/agent`, so the deep backend is out of its reach — as is the `gth pr` change-
+     * requirements discovery agent.
+     *
+     * The check lives HERE, on the `agentFactory ?? lean` fallback itself, rather than in a list of
+     * verbs that cannot honor the key: a list is a second source of truth that goes stale the first
+     * time someone adds a command, whereas anything that reaches this fallback is by construction a
+     * run the key cannot reach. `lean` and the unset default need no warning — that IS what runs.
+     */
+    private warnIfBackendCannotBeHonored;
     /**
      * processMessages deals with both streaming and non-streaming approaches.
      */
@@ -91,44 +316,315 @@ export declare class GthAgentRunner {
      * streamed across all resume turns (empty when nothing was resumed).
      *
      * No-ops (returns '') when the agent does not support interrupts (`getPendingToolInterrupts`/
-     * `streamResume` absent), so the lean agent and non-HITL configs are unaffected.
+     * `streamResume` absent) — that is the only exemption. As of EXT-52 BOTH backends gate
+     * `run_shell_command` and expose the interrupt surface, so the lean (default) agent is now
+     * exactly the agent this loop serves; only an agent implementation without those methods
+     * (e.g. a test double) skips it.
      */
     private resolveToolInterrupts;
     /**
-     * Decide a single pending tool call (EXT-9 Tier-2). For the opt-in `run_shell_command`,
-     * consult the scoped allow-list FIRST: if the command's classified prefix is already
-     * approved (session or persisted `always`) and survives the safe-bin anti-widening
-     * re-validation, auto-approve SILENTLY (no human prompt). Otherwise fall through to the
-     * human callback; when the human grants `session`/`always` scope, record the command's
-     * classified prefix into the matching store so future flag-variants stop re-prompting.
+     * EXT-71 §3.1/§3.2, EXT-70 §4.7.5 — the subject a pending tool call presents to the rule matcher.
+     *
+     * A gated `run_shell_command` is a **shell** subject and nothing else: it is matched by `shell`
+     * entries, against the command. It is deliberately NOT also offered as a `tool` subject named
+     * `run_shell_command`, which would create a second allow path to every shell command carrying a
+     * different §3.2 `rate` default and a match that never saw the command it was approving.
      *
-     * When no human callback is wired (non-TTY exec run) and nothing is allow-listed, reject —
-     * never auto-approve. Non-shell tools (or any tool when the allow-list is disabled) skip the
-     * allow-list and go straight to the human callback / default-reject, preserving prior behaviour.
+     * **Everything else splits by provenance**, which is the distinction §4.7.1 rests on: `tool` is
+     * the TRUSTED provenance, read verbatim, so an MCP tool arriving as one would be asking the
+     * trusted path for a third party's annotations — a gate any server can opt itself out of. Every
+     * MCP-namespaced name therefore becomes an `mcpTool` subject carrying the user's own `mcpServers`
+     * key, and one whose server cannot be resolved stays an `mcpTool` subject under an unnameable
+     * server rather than falling back to `tool` (see `approvalSubjectForToolName`).
+     *
+     * **The host (§4.7.4)** is attached here, so the one subject the whole decision runs on carries
+     * it: the rule matcher treats a `host` on an entry as an additional exact-match condition, and a
+     * grant the menu writes records it. A call naming no single host has none, which fails toward a
+     * prompt at both sites.
+     *
+     * Widening which tools the gate actually suspends on is still [[EXT-30]]; this decides what a
+     * suspended call *is* whenever one arrives.
+     *
+     * @param hosts Every distinct host the call's arguments name ({@link toolCallHosts}).
+     */
+    private approvalSubjectFor;
+    /**
+     * §4.7.5 — the user's own `mcpServers` keys, the only identity a server has here. Own enumerable
+     * keys via `Object.keys`, so nothing inherited can pose as a configured server.
+     */
+    private configuredMcpServerKeys;
+    /**
+     * EXT-70 §4.7.1 — the source a `hint` entry reads a call's EFFECTIVE annotations through, built
+     * from the session's `approvals.mcp` block and the two declared-annotation lookups.
+     *
+     * Built per decision rather than cached at {@link init}, for two reasons that both bite: the
+     * agent registers its tools *inside* `agent.init()`, so an init-time snapshot would be empty; and
+     * a re-init re-resolves the tool list, which for MCP may hand back different declarations.
+     *
+     * The two lookups are deliberately different in kind. `builtIn` reads OUR OWN authored table and
+     * never the bound tool list — the bound list contains every server's tools, and a `builtIn`
+     * lookup over it would read a third party's declaration through the trusted-verbatim path.
+     * `mcp` reads what the servers declared, keyed by the registered tool name so the server key is
+     * never split apart and re-joined differently.
+     */
+    private effectiveToolAnnotationSource;
+    /**
+     * Decide a single pending tool call. Spec order — **deny → bypass → escalate → allow → rater →
+     * human prompt**, with the hardline floor at exec time regardless. The two adjacencies that carry
+     * the design are that deny comes BEFORE `bypass` and escalate comes AFTER it:
+     *
+     * 1. **deny** (§3) — a declared entry or a runtime *always reject* grant is refused with no
+     *    prompt and no rating call. It is consulted FIRST, and it is the one
+     *    check that **still applies under `bypass`**: choosing `bypass` says *"stop asking me"*, not
+     *    *"forget what I told you never to do"*. A deny entry MAY match a compound command, because a
+     *    prohibition that catches something unresolvable errs in the direction that costs nothing.
+     * 2. **`bypass`** — the gate is off for this session; approve at scope `once`.
+     * 3. **escalate** (§3.2) — a declared entry always asks the human, whatever the rung would have
+     *    done, **including outranking the automatic grants of `manual` and `write`** and any allow
+     *    entry that also matched. It goes straight to the human with **no rating call**, and it never
+     *    enters the `auto` negotiation. It is **inert at `bypass`**, which is why it sits below
+     *    the rung check: the rung chosen for this session wins, and a stop that must survive `bypass`
+     *    is a deny entry and only that.
+     * 4. **allow** (§3, §3.2) — a declared entry or a grant the human made at an earlier prompt this
+     *    session (or persisted), matched against the whole normalized command and only when that
+     *    command statically resolves. An allow match settles the human's part: no prompt. Whether the rater
+     *    still reviews the call is the entry's own `rate` (§3.2) — honored at the rater rungs and
+     *    inert at the deterministic ones, so no entry can smuggle a model call into `manual` or
+     *    `write` — and a rated allow match is a TRIPWIRE, not a re-adjudication
+     *    ({@link mapAllowMatchedVerdictToAction}).
+     * 5. **auto-rater** (`assisted` / `auto` only) — `safe` approves, `destructive` and
+     *    `catastrophic` escalate, and `attack` HALTS the run ({@link AttackHaltError}). The other
+     *    three rungs consult no model at all. A command whose target the gate cannot statically
+     *    resolve is rated **exactly like any other** ([[EXT-81]]), with a neutral note in the rating
+     *    prompt naming the shape the parser saw. It used to skip the call and be refused straight
+     *    back to the model instead; §6.1's rule is that a deterministic layer fires only where it is
+     *    confident something is a threat, and a parser reporting it could not read a string has
+     *    detected nothing. At those same two rungs a **tool**
+     *    call is instead floored deterministically by §4.7.3's open-world rule
+     *    ({@link openWorldToolFloorReason} into {@link applyDestructiveFloor} — the one floor the
+     *    shell path also reaches): a call whose effective `openWorldHint` is true is `destructive`,
+     *    whatever its `readOnlyHint` says.
+     * 6. **human prompt** — the approval callback; when the human grants `session`/`always` scope,
+     *    **that command** is recorded as an `exact` entry (§3.1/§6 — the menu never widens), so the
+     *    same command stops re-prompting and a longer variant of it still asks.
+     *
+     * §6.2 — where no human can answer (CI, a one-shot run, a server), an escalation is **not** a
+     * rejection handed back to the model: it is an immediate non-zero exit
+     * ({@link NonInteractiveEscalationError}) carrying the command, the rating and its reason. No
+     * prompt, no waiting, and never a timeout into approval. Declaring commands in `approvals.allow`
+     * is the supported way to make a pipeline pass.
      *
      * Hardline catastrophic commands remain refused at exec time regardless of any approval here
      * (defense in depth in `GthDevToolkit.executeCommand`), so an allow-listed `rm -rf /` still
      * cannot run.
+     *
+     * **Step 0 is the rung.** The backends wire the interrupt over every tool ANY rung could gate,
+     * because the graph is built once and `/approvals <rung>` moves the rung under it for the rest of
+     * the session. So a call arriving here has not yet been judged against the rung in force: this is
+     * where that happens, on `sessionApprovals.rung`, which a mid-session switch has already updated.
+     * A call the live rung does not gate is approved on the spot — no rule matching, no rating, no
+     * prompt — which is what keeps `assisted`, `auto` and `bypass` behaving exactly as they did
+     * when the interrupt held the shell alone. It sits ABOVE the deny check for the same reason: an
+     * ungated call never reached this method at all before, so a deny entry could not fire on one, and
+     * a security fix for two rungs is not the place to change that. (The shell is gated at every rung
+     * whenever the shell gate is on, so §2.5's rule that the deny list survives `bypass` is untouched.)
      */
     private decideToolApproval;
-    /** Whether the EXT-10 LLM-as-judge safety gate is enabled for the active command's config. */
-    private isShellJudgeOn;
-    /** Whether the EXT-9 Tier-2 allow-list is enabled for the active command's devTools config. */
-    private isShellAllowlistOn;
     /**
-     * Lazily load (once per instance) the persisted `always` allow-list, unless persistence is
-     * disabled by config. Returns null when persistence is off so `always` grants behave as
-     * `session` (in-memory only).
+     * [[TUI-C27]] — {@link decideToolApprovalInner} with the record closed off on EVERY exit.
+     *
+     * The final action is written here rather than at each of the decision's many returns, because
+     * "what became of the call" is one fact with one source: what this method returns or throws. A
+     * per-return assignment is a list that a new branch joins without noticing, and the branch that
+     * would be forgotten is the one that ends the run.
      */
-    private getPersistedAllowlist;
-    /** Check the command against the session + persisted stores (with anti-widening re-validation). */
-    private isApprovedByAllowlist;
+    private recordedDecision;
+    /** The decision itself; {@link decideToolApproval} wraps it with §5.3's reset. */
+    private decideToolApprovalInner;
     /**
-     * Record a human-granted approval at the given scope. `once` persists nothing. `session`
-     * adds the classified prefix to the in-memory store. `always` additionally persists it (or
-     * falls back to session-only when persistence is disabled).
+     * [[TUI-C27]] — attribute the deciding stage and hand the decision straight back.
+     *
+     * A one-liner so a stage can be recorded ON the `return` that carries it rather than on the line
+     * above: two statements let an early return be added between them, and the record would then name
+     * a stage that did not decide.
+     */
+    private stage;
+    /**
+     * One rating call, with EXT-66's timeout reporting attached. Extracted so the §3.2 tripwire (a
+     * rated allow match) and the ordinary rater path cannot drift apart in WHAT they hand the rater —
+     * only in what they do with the answer.
+     */
+    private rateCommand;
+    /**
+     * EXT-58 (§4.3/§4.4) — the built-in tools already granted at the session's CURRENT rung, as
+     * names plus one-line locally-authored descriptions, for the rater prompt.
+     *
+     * Two filters make this safe to place outside the rater's fenced untrusted block:
+     * - the names come from what the agent actually registered
+     *   ({@link GthAgentInterface.getRegisteredToolNames}), so the rater can only ever offer a tool
+     *   this session has;
+     * - the descriptions come from core's own `BUILT_IN_TOOL_SUMMARIES` table, so no MCP, custom or
+     *   A2A tool's own (attacker-influenceable) description can reach the prompt.
+     *
+     * Empty when the agent does not expose its tools — the rater then gets no list and, per the
+     * prompt, offers nothing.
+     */
+    private getGrantedBuiltInTools;
+    /**
+     * §3/§3.3 — the three rule lists this session decides by: the DECLARED entries from config
+     * (read-only input) concatenated with the runtime grants the escalation menu made. One set of
+     * lists, handed to the one comparison engine; the concatenation cannot change any outcome
+     * because `resolveApprovalRules` consults every deny entry before any escalate entry and every
+     * escalate entry before any allow entry.
+     *
+     * The persisted store is loaded here rather than at {@link init} — lazily, once per instance, and
+     * NEVER at `bypass`, where the allow list is moot and a session that has switched the gate off
+     * should not be reading or rewriting the project's grant file.
+     */
+    private approvalRuleLists;
+    /**
+     * Lazily load (once per instance) the persisted `always` grant store.
+     *
+     * CFG-27 removed the `persistAllowlist` switch: §3 makes persistence a per-decision choice in
+     * the escalation menu (`approve` forgets, `always approve` persists), and a global "never
+     * persist" setting would only duplicate a keystroke. Returns null when the store cannot be
+     * loaded at all, in which case `always` grants degrade to `session` (in-memory only).
+     *
+     * The v1→v2 migration notice is routed to `statusUpdate` from here, which is the only place that
+     * knows how to reach the user.
+     */
+    private getPersistedGrants;
+    /**
+     * §3.1/§4.7.4/§6 — **the grant a sticky choice would write for this call**, or `undefined` when
+     * none is on offer. The one place that question is answered, so the menu's *this is what will be
+     * stored* line (§6) and the store can never disagree.
+     *
+     * - **A shell call** records the command itself as an `exact` entry (§3.1) — never a prefix,
+     *   never a pattern. One that does not statically resolve (composition, substitution,
+     *   redirection) is not on offer: no allow entry of any matcher matches such a command, so the
+     *   entry would be inert, and an inert entry sitting in a list §3 requires to be inspectable
+     *   tells the user something is in force when nothing is.
+     * - **A tool call** records identity — the tool, its server, and the host where the call carries
+     *   one (§4.7.4, {@link toolGrantEntry}) — never arguments, which would produce a grant that
+     *   never matches twice. A call naming no host records the tool alone, which is §6's own example
+     *   (*always approve `mcp__jira__create_issue`*, where no host is involved); what keeps that from
+     *   being unbounded is §3.2's default that a tool entry is still `rate: true`, so the rater goes
+     *   on seeing every call's full arguments.
+     *
+     * Four cases have **no grant on offer at all**, each fail-closed:
+     *
+     * 1. **`bypass`** — the gate is off for this session and nothing is remembered from it.
+     * 2. **`run_shell_command` arriving as a tool subject.** That is what a shell call with no
+     *    readable `command` argument presents as, and it names no host, so without this it would take
+     *    the tool-only arm and write a `{"type":"tool","pattern":"run_shell_command"}` grant that
+     *    auto-approves every future call whose command cannot even be read. This exclusion is what
+     *    stops that, not a side effect of anything else, and it must survive [[EXT-30]] widening the
+     *    gate.
+     * 3. **A call naming more than one distinct host.** The grammar has no entry for it. `host` is a
+     *    single optional string on every tool arm of `approvalEntrySchema`, and every arm is a
+     *    `z.strictObject`, so recording the *set* is not a policy this code may choose — a `hosts`
+     *    array is an unrecognized-key error, and writing one would be a §3.1 grammar change. Of the
+     *    two entries that would parse, the host-bound one displays a bound the grant does not have,
+     *    which §6 forbids (the menu shows exactly what will be stored). And a grammar that did record
+     *    the set, matching only when all of it recurred, would fail §4.7.4's opening test anyway: a
+     *    tool whose host set varies per call would get a grant that never matches a second time — not
+     *    a narrower grant, the useless one §4.7.4 rejects by name.
+     *
+     *    **What this arm does not claim.** It is not a narrowing. A hostless entry imposes no host
+     *    condition at all (`resolveApprovalRules`), so the tool-only grant that any host-less call to
+     *    the same tool produces already auto-approves a multi-host one. Refusing here withholds a
+     *    grant; it does not close a hole, and the reason to keep it is the grammar above rather than
+     *    any breadth it prevents. Asserted, so this cannot drift back into a claim the system does not
+     *    support.
+     * 4. **An MCP call whose server could not be resolved** ({@link toolGrantEntry} returns `null`) —
+     *    a call nobody can attribute is not one anything can remember.
+     */
+    private stickyGrantFor;
+    /**
+     * [[TUI-C26]] §6 — **the entry the escalation menu's *always reject* choice would record**, or
+     * `undefined` when the grammar cannot hold one. The deny mirror of {@link stickyGrantFor}, and a
+     * separate function rather than a flag on it, because the two answer different questions.
+     *
+     * **Nearly every reason an allow entry is withheld does not apply here.** §3 has one rule for
+     * this and it runs the other way — *undecidable is a non-match on the allow side and a match on
+     * the deny side* — so:
+     *
+     * - **A command that does not statically resolve gets an entry.** `stickyGrantFor` refuses one
+     *   because no allow entry of any matcher would ever match it, making the entry inert; a deny
+     *   entry for the same command is matched against the whole normalized command *and* every
+     *   segment a shell would run, so it is the opposite of inert.
+     * - **A `catastrophic` verdict changes nothing.** §4.2 withdraws the sticky grants there; it says
+     *   nothing about refusals, and refusing more is never the direction that needs withdrawing.
+     * - **`bypass` changes nothing either**, and that is a positive statement rather than a gap. Deny
+     *   is resolved at step (1) of {@link decideToolApprovalInner}, *before* the `bypass` return, so
+     *   a recorded refusal is in force at every rung — which is why this does not copy the allow
+     *   side's `bypass` guard.
+     * - **A call naming several hosts gets the host-less entry.** On the allow side that would show a
+     *   bound the grant does not have; here the entry covers every host of that tool, which is
+     *   broader than the call and safe in the direction breadth is safe. The menu shows exactly that
+     *   entry, so the breadth is on screen rather than inferred.
+     * - **`run_shell_command` arriving as a TOOL subject gets a tool entry** — a shell call whose
+     *   `command` argument cannot even be read. On the allow side that entry would auto-approve every
+     *   future unreadable shell call, which is why it is excluded there; as a refusal it stops the
+     *   shell tool for the session, and the dialog says so in the words the entry is written in.
+     *
+     * The one genuine exclusion is an **MCP call whose server could not be attributed**
+     * ({@link toolGrantEntry} returns `null`): the grammar's `server` cannot be the empty string, so
+     * the entry would be dropped by its own validator and the human would be told a refusal had been
+     * recorded when none was. A shell command that normalizes to nothing is excluded for the same
+     * reason — an empty `pattern` is not a legal entry.
+     */
+    private denyEntryFor;
+    /**
+     * §6 — record the menu's *always reject* choice, for the life of this runner instance.
+     *
+     * It lands in the same store `approvals.deny` entries are matched from ({@link approvalRuleLists}
+     * concatenates the two), so a refusal the human made at the prompt and one they wrote in their
+     * config are one list to the matcher and one list to `/approvals`.
+     *
+     * **Session-lifetime, and there is nothing else to choose.** There is no persisted deny file;
+     * whether there should be is a question about a file users live with, not about this prompt. What
+     * the surfaces must not do is say otherwise — a confirmation promising a persistence that did not
+     * happen is §6's *offered and then refused* with the evidence hidden.
+     */
+    private recordDenial;
+    /**
+     * §3.1/§6 — record a human-granted approval at the given scope. `once` remembers nothing.
+     * `session` adds the entry to the in-memory store; `always` additionally persists it (falling
+     * back to session-only when the file cannot be written).
+     *
+     * What is recorded was decided by {@link stickyGrantFor} and shown to the human before they
+     * answered; this only stamps it with when and at what scope.
      */
     private recordApproval;
+    /**
+     * §4.7.4 — **drop a tool grant the tool has since weakened out from under, with a notice naming
+     * the tool, the server and the hint that moved.**
+     *
+     * The human approved a tool *as annotated*; a tool that re-annotates itself into a more dangerous
+     * shape is a different proposition wearing the same name, so the grant is invalidated and the next
+     * call prompts again. Only a **trusted** server can produce a weakening — an untrusted server's
+     * effective set is the constant fail-closed default (§4.7.1) and cannot move — which is exactly
+     * where it matters, since the trusted server is the one whose rug-pull would otherwise ride an
+     * existing grant.
+     *
+     * **Scoped to the call being decided, never a sweep of the store.** A sweep would read every held
+     * grant against a source that can only answer for the tools registered right now, so a server that
+     * happened to be offline would read as having weakened everything it ever declared — and the
+     * grants would be deleted for it.
+     *
+     * **The scope is every grant that could auto-approve THIS call, which is at most two.** A grant
+     * with no `host` imposes no host condition, so it matches a call that carries one; looking up only
+     * the entry this call would grant (`host` included) would miss the tool-only grant that is about
+     * to auto-approve it, and the weakening would ride straight through — the exact failure §4.7.4
+     * exists to stop. The host-bound entry of a DIFFERENT host is deliberately not a candidate: it
+     * does not match this call either, so this call's annotations say nothing about it.
+     *
+     * **Only allow-side grants.** A weakening makes a tool more dangerous, so dropping an *always
+     * reject* over one would be the unsafe direction: the reason to withdraw an approval is the reason
+     * to keep a refusal.
+     */
+    private invalidateWeakenedGrants;
     /**
      * Event-stream counterpart to {@link processMessages}: drives the agent's typed
      * {@link AgentStreamEvent} path using the runner's own thread-bound `runConfig`, so a
@@ -144,7 +640,7 @@ export declare class GthAgentRunner {
      * leaves the graph suspended on a `humanInTheLoopMiddleware` interrupt rather than
      * completing. This is the event-stream counterpart to the readline path's
      * {@link resolveToolInterrupts}: it drains any pending interrupts through
-     * {@link decideToolApproval} (allow-list → judge → bridged human prompt), resumes via
+     * {@link decideToolApproval} (bypass → allow-list → rater → bridged human prompt), resumes via
      * `streamWithEventsResume({ decisions })`, and loops until the graph completes with no
      * pending interrupts — so the executed command's output renders into the TUI. Without
      * this the TUI silently finalized an empty turn (approval gate was dead code on the
@@ -156,18 +652,36 @@ export declare class GthAgentRunner {
      * resolve any tool-approval interrupts it suspended on, yielding the resumed run's typed
      * {@link AgentStreamEvent}s so the renderer (the Ink TUI) shows the executed command's
      * output. Each pending tool call is consulted via {@link decideToolApproval} — the SAME
-     * three-layer gate the readline path uses (allow-list auto-approve → EXT-10 judge →
+     * gate the readline path uses (bypass → allow-list approve → CFG-26 AI rater →
      * bridged human callback, defaulting to REJECT when no handler is wired) — and the
      * collected decisions are sent back via `streamWithEventsResume` as a LangChain HITL
      * resume (`{ decisions }`). Because a resumed run can suspend again on the next gated
      * tool call, this loops until the graph completes with no pending interrupts.
      *
      * No-ops (yields nothing) when the agent does not support interrupts
-     * (`getPendingToolInterrupts`/`streamWithEventsResume` absent), so the lean agent and
-     * non-HITL configs are unaffected. Aborts (`signal`) propagate through the resumed stream.
+     * (`getPendingToolInterrupts`/`streamWithEventsResume` absent) — that is the only exemption.
+     * As of EXT-52 BOTH backends gate `run_shell_command` and expose the interrupt surface, so the
+     * lean (default) agent is now exactly the agent this loop serves; only an agent implementation
+     * without those methods (e.g. a test double) skips it. Aborts (`signal`) propagate through the
+     * resumed stream.
      */
     private resolveToolInterruptsWithEvents;
     getAgent(): GthAgentInterface | null;
+    /**
+     * GS2-16 — reset the current turn's analytics tally on both the live agent and the runner's
+     * cached snapshot, so a new turn starts clean. Fail-soft (an agent without stats support is a
+     * no-op). Called at the top of each `processMessages` / `processMessagesWithEvents`.
+     */
+    private resetRunStats;
+    /** GS2-16 — read the live agent's run stats (fail-soft; empty tally if unavailable). */
+    private captureRunStats;
+    /**
+     * GS2-16 — the analytics harvested from the just-finished turn (token usage + invoked tools),
+     * to thread into the opt-in history recorder. Reads live from the agent when one is present,
+     * otherwise the snapshot captured at {@link cleanup} (the single-shot path reads post-cleanup).
+     * Never throws.
+     */
+    getRunStats(): GthRunStats;
     /**
      * Rotate the thread the runner drives by minting a fresh `runConfig` (new `thread_id`),
      * so subsequent turns start from an empty checkpointer thread rather than retrieving the