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

package/dist/config/shell-policy.js

@@ -0,0 +1,750 @@
+/**
+ * @packageDocumentation
+ * Shell / dev-tools policy: the {@link GthDevToolsConfig} type plus all the resolvers
+ * that interpret it (shell enablement, timeouts, output budget, per-command dev-tools
+ * selection), and — since CFG-27 — the {@link ApprovalsConfig} value and its resolver
+ * {@link resolveApprovals} (the five-rung ladder, the rater's identity profile, and the declared
+ * allow/deny lists).
+ *
+ * CFG-18 — the dev/shell tools are now configured through the unified {@link GthConfig.builtInTools}
+ * registry (`string[] | Record<string, boolean | BuiltInToolConfig>`), NOT the removed per-command
+ * `commands.<mode>.devTools` key. {@link GthDevToolsConfig} is therefore no longer an on-disk shape:
+ * it is the internal, resolved view that {@link getEffectiveDevToolsConfig} builds from the effective
+ * `builtInTools` registry, and that {@link GthDevToolkit} + the shell accessors below consume. This
+ * keeps the toolkit/accessor surface stable while the single config surface is `builtInTools`.
+ */
+import { StatusLevel } from '#src/core/types.js';
+import { isAccessClassGrantedAtRung } from '#src/config/tool-descriptions.js';
+/**
+ * The fixed dev-command tools: each maps a `command` string (from its {@link BuiltInToolConfig})
+ * to a run_* tool emitted by {@link GthDevToolkit}.
+ */
+export const DEV_COMMAND_TOOL_NAMES = [
+    'run_tests',
+    'run_lint',
+    'run_build',
+    'run_single_test',
+];
+/** The opt-in general-purpose shell tool name. */
+export const SHELL_TOOL_NAME = 'run_shell_command';
+/**
+ * All dev/shell tool names carried in the {@link GthConfig.builtInTools} registry. These are emitted
+ * by {@link GthDevToolkit} via the dev-tools bucket, NOT loaded as plain built-in tools — so
+ * `getBuiltInTools` skips them (a `run_shell_command` entry in `builtInTools` is legitimate, not an
+ * "unknown built-in tool").
+ */
+export const DEV_TOOL_NAMES = [...DEV_COMMAND_TOOL_NAMES, SHELL_TOOL_NAME];
+/**
+ * Normalize the widened {@link BuiltInToolsSetting} to a plain lookup keyed by tool name. The array
+ * form maps each name to `true`; the object form passes through unchanged; absent → `{}`.
+ */
+export function normalizeBuiltInTools(builtInTools) {
+    if (!builtInTools)
+        return {};
+    if (Array.isArray(builtInTools)) {
+        const out = {};
+        for (const name of builtInTools)
+            out[name] = true;
+        return out;
+    }
+    return builtInTools;
+}
+/**
+ * Whether a plain built-in tool's registry entry is enabled: a bare `true`, or an object entry that
+ * is not `{ enabled: false }` (configuring a tool enables it). A bare `false` force-disables it.
+ * Dev/shell tools ({@link DEV_TOOL_NAMES}) are NOT resolved through this — they go through
+ * {@link getEffectiveDevToolsConfig} / {@link isShellToolEnabled}.
+ */
+export function isBuiltInToolEntryEnabled(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    return value.enabled !== false;
+}
+/**
+ * Default per-command shell timeout (ms) when {@link GthDevToolsConfig.shell}
+ * does not specify one. ~120s suits typical build/test/git steps without
+ * hanging the agent forever on a stuck command.
+ */
+export const SHELL_DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Default byte budget for shell output captured into the ToolMessage returned to
+ * the model (head + tail window). ~100KB keeps a noisy log from blowing the
+ * context window; the full output is spilled to a temp file when this is exceeded.
+ */
+export const SHELL_DEFAULT_MAX_OUTPUT_BYTES = 100_000;
+/**
+ * Normalize the {@link GthDevToolsConfig.shell} opt-in (bare boolean or
+ * `{ enabled }`) to a plain boolean. Centralized so the toolkit (tool emission)
+ * and the deep agent (interrupt wiring) agree on what "shell enabled" means.
+ *
+ * EXT-12 / CFG-18 — default-resolution is `enabled ?? default`. An EXPLICIT `enabled` always wins
+ * (a bare boolean, or the object form's `enabled`), so `shell: false` / `{ enabled: false }` remains
+ * a hard escape hatch that fully disables the tool. When `enabled` is ABSENT — whether `shell` is
+ * undefined OR an object that omits `enabled` (e.g. `{ timeout: 300000 }`, i.e. a
+ * `{ "run_shell_command": { "timeout": 300000 } }` registry entry) — the per-mode default applies:
+ * ON in `code` mode (still gated — the per-command approval interrupt is wired separately and is NOT
+ * bypassed by this), OFF everywhere else (`exec`, `ask --write`, …). This is the CFG-18 change from
+ * the old `enabled === true` object semantics: configuring the shell no longer silently turns it off.
+ * The default is `code`-mode only because `code` is the interactive agentic-coding surface where a
+ * TTY can answer the approval prompt; the absent-config default never implies yolo.
+ *
+ * @param command The active command, so the absent-config default can be scoped to `code`.
+ *   Omit (or pass a non-`code` command) to keep the historical OFF-by-default behaviour.
+ */
+export function isShellToolEnabled(devTools, command) {
+    const shell = devTools?.shell;
+    if (typeof shell === 'boolean')
+        return shell;
+    // Object form: `enabled ?? default` — an object without `enabled` still defaults ON in `code`.
+    if (shell && typeof shell === 'object')
+        return shell.enabled ?? command === 'code';
+    // Absent/undefined shell: ON by default for `code` mode (gated), OFF elsewhere.
+    return command === 'code';
+}
+/**
+ * Resolve the per-command shell timeout (ms) from config, falling back to
+ * {@link SHELL_DEFAULT_TIMEOUT_MS}. Only the object form can override it; a bare
+ * `shell: true` uses the default. Non-positive / non-finite values are ignored.
+ */
+export function getShellTimeoutMs(devTools) {
+    const shell = devTools?.shell;
+    if (shell && typeof shell === 'object' && typeof shell.timeout === 'number') {
+        if (Number.isFinite(shell.timeout) && shell.timeout > 0)
+            return shell.timeout;
+    }
+    return SHELL_DEFAULT_TIMEOUT_MS;
+}
+/**
+ * Resolve the captured-output byte budget from config, falling back to
+ * {@link SHELL_DEFAULT_MAX_OUTPUT_BYTES}. Only the object form can override it.
+ * Non-positive / non-finite values are ignored.
+ */
+export function getShellMaxOutputBytes(devTools) {
+    const shell = devTools?.shell;
+    if (shell && typeof shell === 'object' && typeof shell.maxOutputBytes === 'number') {
+        if (Number.isFinite(shell.maxOutputBytes) && shell.maxOutputBytes > 0) {
+            return shell.maxOutputBytes;
+        }
+    }
+    return SHELL_DEFAULT_MAX_OUTPUT_BYTES;
+}
+/**
+ * Build the internal, resolved {@link GthDevToolsConfig} from a normalized `builtInTools` registry:
+ * the fixed dev-command tools read their `command` string, and `run_shell_command` maps to the
+ * `shell` view the accessors below consume (CFG-26: the approval knobs are no longer here — they
+ * live in the top-level `approvals` block, resolved by {@link resolveApprovals}). Returns `undefined` when the registry
+ * carries no dev/shell entry at all, so callers treat it exactly like an unset `devTools` (the
+ * `code`-mode shell default still applies downstream via {@link isShellToolEnabled}).
+ */
+function devToolsConfigFromRegistry(registry) {
+    const resolved = {};
+    let hasAny = false;
+    for (const name of DEV_COMMAND_TOOL_NAMES) {
+        const entry = registry[name];
+        const cmd = entry && typeof entry === 'object' ? entry.command : undefined;
+        if (typeof cmd === 'string' && cmd.length > 0) {
+            resolved[name] = cmd;
+            hasAny = true;
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(registry, SHELL_TOOL_NAME)) {
+        const entry = registry[SHELL_TOOL_NAME];
+        if (typeof entry === 'boolean') {
+            resolved.shell = entry;
+        }
+        else if (entry && typeof entry === 'object') {
+            resolved.shell = {
+                enabled: entry.enabled,
+                timeout: entry.timeout,
+                maxOutputBytes: entry.maxOutputBytes,
+            };
+        }
+        hasAny = true;
+    }
+    return hasAny ? resolved : undefined;
+}
+/**
+ * Resolve the {@link GthDevToolsConfig} that applies to the active command from the unified
+ * {@link GthConfig.builtInTools} registry (CFG-18 — replaces the removed per-command `devTools`).
+ * Mirrors the per-command selection used by `builtInToolsConfig.getDefaultTools`: `exec` →
+ * `commands.exec`, `ask --write` → `commands.ask`, `code` → `commands.code`; `undefined` elsewhere
+ * (the dev/shell tools are inert there). The effective registry for the scope is the per-command
+ * `builtInTools` if set, else the root `builtInTools` — matching `getEffectiveConfig`'s replace
+ * merge. Shared in core so the runner's allow-list/judge gates stay in lockstep with where the
+ * shell tool is actually emitted.
+ */
+export function getEffectiveDevToolsConfig(config, command) {
+    if (!config)
+        return undefined;
+    const askWrite = command === 'ask' && config.askWriteMode === true;
+    const cmdConfig = command === 'exec'
+        ? config.commands?.exec
+        : askWrite
+            ? config.commands?.ask
+            : command === 'code'
+                ? config.commands?.code
+                : undefined;
+    // Only the do-the-job commands (code/exec/ask --write) carry dev/shell tools.
+    if (command !== 'exec' && command !== 'code' && !askWrite)
+        return undefined;
+    const effective = cmdConfig?.builtInTools ?? config.builtInTools;
+    return devToolsConfigFromRegistry(normalizeBuiltInTools(effective));
+}
+/* -------------------------------------------------------------------------------------------- *
+ * CFG-27 — the `approvals` ladder: one ordered set of five rungs, plus the declared lists.
+ * -------------------------------------------------------------------------------------------- */
+/**
+ * CFG-27 (spec §1, §2) — **the ladder**. There is ONE approvals setting and it is a single ordered
+ * ladder; each rung fully determines behaviour. There are no severity thresholds, no strictness
+ * levels and no independent rater on/off switch.
+ *
+ * | # | Rung | Rater | LLM cost |
+ * |---|---|---|---|
+ * | 1 | `manual` | no | none |
+ * | 2 | `write` | no | none |
+ * | 3 | `assisted` | yes | 1 call per gated call |
+ * | 4 | `auto` | yes | 1–2 calls per gated call |
+ * | 5 | `bypass` | no | none |
+ *
+ * Rungs 1, 2 and 5 are fully deterministic: no model is consulted, so behaviour is reproducible
+ * and costs nothing.
+ *
+ * **CFG-39 — four postures plus one modifier, not five peers.** `write` is not a rung on a trust
+ * ladder: it is the same posture as `manual` with a different auto-granted set. The four postures
+ * a user chooses between are {@link APPROVAL_POSTURES} (`manual` → `assisted` → `auto`, plus
+ * `bypass`), and that ordering is legible in the names themselves. `write` remains fully settable
+ * — via `/approvals write` and via config — and simply does not occupy a row in quick access.
+ * This constant keeps ALL FIVE members: it is the type's domain, the set
+ * {@link resolveInterruptToolNames} unions over, and what makes `write` settable at all.
+ *
+ * **`bypass` is NOT a higher-autonomy rung than `auto`** (§2.5). Both let the agent act
+ * without asking; `bypass` is the same autonomy with the checks removed. The ordering below is the
+ * order the rungs are *offered* in, and must never be presented as though `auto` were an
+ * incomplete `bypass`.
+ *
+ * Identifiers are lower-case single words (§9.1) because the same token must work as a config
+ * value, a slash-command argument and a CLI flag — a space breaks the last two. Display names are
+ * capitalised; see {@link APPROVAL_RUNG_LABELS}.
+ */
+export const APPROVAL_RUNGS = ['manual', 'write', 'assisted', 'auto', 'bypass'];
+/**
+ * §9.1 rule / §10 rule 4 — the display spelling of each rung, with spaces. An identifier and a
+ * label do not have to match and only one of them has to survive a shell, so user-facing prose
+ * uses these and never the kebab-case identifiers.
+ */
+export const APPROVAL_RUNG_LABELS = {
+    manual: 'Manual',
+    write: 'Write',
+    assisted: 'Assisted',
+    auto: 'Auto',
+    bypass: 'Bypass',
+};
+/**
+ * CFG-39 — **the four postures**, in the order they are offered: the rows `/approvals` presents
+ * when it asks the user to choose one.
+ *
+ * `write` is deliberately absent, and its absence is the whole point of the reframe. It is not a
+ * rung on a trust ladder — it is `manual`'s posture with a different auto-granted set, so listing
+ * it as a fifth peer is what made a four-point ladder read as five indistinguishable ones. It stays
+ * fully settable via `/approvals write` and via config; it simply leaves quick access.
+ *
+ * **This is a presentation list, never a policy one.** Every predicate, every `Record<ApprovalRung,
+ * …>` and the interrupt set are built from {@link APPROVAL_RUNGS}, which keeps all five. Using this
+ * constant to decide behaviour would silently un-settle `write`.
+ */
+export const APPROVAL_POSTURES = [
+    'manual',
+    'assisted',
+    'auto',
+    'bypass',
+];
+/**
+ * CFG-39 — the one-line note that `write` exists, shown as picker CHROME beside the `manual` row.
+ *
+ * It lives here rather than appended to {@link APPROVAL_RUNG_DESCRIPTIONS}`.manual` on purpose: the
+ * descriptions are one surface's copy shared by six, so a sentence about quick-access mechanics
+ * would follow the mode into the status display and the tool-description layer, where it means
+ * nothing.
+ */
+export const APPROVAL_WRITE_MODIFIER_HINT = 'Manual also has a Write variant that may edit files in your working folder without asking: ' +
+    'set it with /approvals write.';
+/**
+ * §10 — what each mode is **for**, in at most two sentences, shown wherever a mode is chosen or
+ * displayed.
+ *
+ * **The first sentence is load-bearing and must stand alone.** The `/approvals` picker, the text
+ * fallback and the usage hint all render one line per mode through `firstSentence`, so sentence
+ * one has to answer "what is this mode for" on its own and sentence two carries the qualification.
+ * Keep it short enough to read as a menu row.
+ *
+ * **Say what the mode is for, not only what it permits.** A description that lists permissions
+ * invites the category error these modes actually suffer: Manual reads as "the safe one", so it
+ * gets picked for a long unattended run — where the deciding is done by a human, and a human is the
+ * fastest-degrading decider in the system. Manual and Write are bounded-volume tools and their copy
+ * says so.
+ *
+ * The wording is constrained by four normative rules (state what the mode PERMITS, state the
+ * allow-list carve-out, never claim safety this system cannot deliver, use the display spelling)
+ * plus §8.1 — the hardline floor is real but is NEVER advertised, so descriptions cite only
+ * protections the user can inspect and extend, i.e. the deny list. Five further constraints bind
+ * every edit here:
+ *
+ * 1. **No description may imply containment.** The gate protects against accidents, not intent, and
+ *    a working-folder claim collapses the moment the agent has a shell — `write_file` refuses a
+ *    path that `touch` then writes. The narrow true form (the built-in file *tools* are confined)
+ *    is stated once, on `write`, alongside the fact that the shell is not confined that way.
+ * 2. **Claims are scoped to the session the user is in.** These strings render on terminal surfaces
+ *    only; a sentence whose subject is "Gaunt Sloth" and whose claim is that it always asks would
+ *    be false over the AG-UI and ACP servers, which never drain an approval interrupt ([[EXT-94]]).
+ * 3. **`assisted` MUST keep the sentence saying files are still rewritten and deleted without
+ *    asking** — it sounds safer than it is, and that clause is the correction.
+ * 4. **A qualification may not live in the second sentence alone.** The picker, the text fallback
+ *    and the usage hint all render `firstSentence` and nothing else, so the opener is the whole
+ *    message on the three surfaces a user reads while *choosing* a mode. An opener that sells a
+ *    behavioural difference the product does not have is not rescued by a sentence two those
+ *    surfaces never print — check a wording by rendering it, not by reading the constant.
+ * 5. **`auto` is the mode a reader most wants to hear is quiet, and it is not.** It settles some
+ *    risky commands with the rater instead of interrupting — that difference is real and may be
+ *    stated — but the copy MUST also say that a bounded exchange ends at the user, and MUST NOT
+ *    promise the user watches it happen. The rounds reach a person at the escalation, all of them
+ *    at once, and nothing renders them before that ([[TUI-C26]]), so a sentence implying a live
+ *    commentary would be describing a screen that does not exist.
+ *
+ * Everything these two sentences cannot hold lives at {@link APPROVAL_PROTECTION_DOCS_URL}, which
+ * the surfaces print beside the copy rather than each description repeating it.
+ */
+export const APPROVAL_RUNG_DESCRIPTIONS = {
+    manual: 'For a handful of commands you want to read yourself — not a mode to leave running. In this ' +
+        'session Gaunt Sloth reads and lists files in your working folder on its own; everything ' +
+        'else — shell, file changes, MCP and custom tools — comes to you, until you tell it to always ' +
+        'allow a command.',
+    write: 'Manual, for work that is mostly editing, and like Manual a bounded stretch: the built-in ' +
+        'file tools run free inside your working folder. The shell is not confined that way, so shell ' +
+        'commands, MCP calls and custom tools still come to you, until you tell it to always allow a ' +
+        'command.',
+    assisted: 'For everyday work: safe commands run, anything riskier comes to you — usually with a line ' +
+        'explaining what it does. Gaunt Sloth can still rewrite and delete files in your working ' +
+        'folder without asking — "safe" means each action is checked for reaching outside that folder ' +
+        'or harming your system, not that nothing changes.',
+    auto: 'For work you want to keep moving: Auto sends a risky command back to the agent to fix or ' +
+        'justify a few times, then stops and asks you. It is not safe — Gaunt Sloth will change and ' +
+        'delete things, your deny list still applies, and when it does ask, you are shown the whole ' +
+        'argument that led there.',
+    bypass: 'No gate, for a throwaway environment you would not mind losing. Whatever Gaunt Sloth decides ' +
+        'to run, runs — nothing is rated and nothing is asked; only the refusals in your config’s ' +
+        'deny list still apply.',
+};
+/**
+ * The page that carries what these modes do and do NOT protect you from — the reasoning the
+ * two-sentence descriptions deliberately do not hold.
+ *
+ * **A GitHub blob URL, matching the one other user-facing runtime doc link in this package** (the
+ * 2.0 migration pointer in `config/schema.ts`). The docs site publishes the same page at
+ * `https://gauntsloth.app/docs/guides/what-approvals-protect-you-from/`; move this constant there
+ * once that path serves the page, and nothing else changes.
+ */
+export const APPROVAL_PROTECTION_DOCS_URL = 'https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/guides/what-approvals-protect-you-from.md';
+/**
+ * The docs pointer as the surfaces print it: **label and URL as two separate lines**, never one
+ * joined string. Every notice surface takes `lines: string[]` and renders one line each, so a bare
+ * URL on its own line is the only form that survives a narrow pane without the break landing
+ * mid-path — and it is what lets a terminal that linkifies URLs pick the whole thing up.
+ *
+ * It lives beside the descriptions rather than inside them for {@link APPROVAL_WRITE_MODIFIER_HINT}'s
+ * reason: one line about where to read more, repeated into all five descriptions, would follow each
+ * mode into the tool-description layer and the status display, where it is noise.
+ */
+export const APPROVAL_PROTECTION_DOCS_LINES = [
+    'What these modes do and do not protect you from:',
+    APPROVAL_PROTECTION_DOCS_URL,
+];
+/** Narrowing type guard for a raw string that may name a rung. */
+export function isApprovalRung(value) {
+    return typeof value === 'string' && APPROVAL_RUNGS.includes(value);
+}
+/** The rungs at which every gated call is rated by the model (§2.3, §2.4). */
+export function isRatedRung(rung) {
+    return rung === 'assisted' || rung === 'auto';
+}
+/**
+ * [[EXT-29]] (§5) — the rung at which a `destructive` rating opens a **negotiation** with the rater
+ * instead of going to the human: the agent may revise the command or justify it, the rater re-rates
+ * with the exchange in view, and only a spent bound reaches a person.
+ *
+ * **This is the one predicate that separates `auto` from `assisted`, and it is deliberately ONE.**
+ * Three places have to agree about it — the decision mapping
+ * ({@link import('../core/shell/rater.js').mapVerdictToAction}, which returns `reject` here and
+ * `escalate` at `assisted`), the rating prompt (§5.2's wording rules are addressed to the agent, so
+ * they are turned on by this and not by whether a transcript happens to exist yet), and the runner
+ * that counts the rounds. Two of them agreeing and the third not is exactly how the two rated rungs
+ * would drift back into being the same posture with different names.
+ *
+ * Written as a `=== 'auto'` test rather than as "rated but not assisted" so that a sixth rung has to
+ * be classified deliberately rather than inheriting a negotiation by omission.
+ */
+export function isNegotiatingRung(rung) {
+    return rung === 'auto';
+}
+/**
+ * The rungs that decide a gated call **without a model** — `manual` and `write` (§2.1, §2.2).
+ * Everything they do not auto-grant goes to the human, so these are the two rungs a user picks in
+ * order to read and approve every tool call themselves.
+ *
+ * The complement of {@link isRatedRung} plus `bypass`; written out rather than negated so that a
+ * sixth rung would have to be classified deliberately instead of defaulting into this set.
+ */
+export function isDeterministicRung(rung) {
+    return rung === 'manual' || rung === 'write';
+}
+/**
+ * **The one rule: does `rung` gate this tool — i.e. must this call be decided rather than simply
+ * run?** Everything else in this area is a projection of this predicate over a set of names.
+ *
+ * - The shell is gated whenever the shell gate is on, at EVERY rung (`bypass` included, so §2.5's
+ *   deny list can still fire — see the `bypass` arm of `GthAgentRunner.decideToolApproval`).
+ * - At the two **deterministic** rungs, a tool is gated when the rung's own grant does not cover its
+ *   access class ({@link isAccessClassGrantedAtRung}). At `manual` that leaves only the built-in
+ *   READ tools free; at `write`, the built-in read and write tools. The write built-ins, the shell,
+ *   deepagents' `execute`, MCP tools and custom/agent-authored tools all escalate to the human.
+ * - At `assisted`, `auto` and `bypass` nothing but the shell is gated. **That split is
+ *   deliberate and load-bearing, not tidiness.** At a rated rung a gated non-shell call reaches the
+ *   `subject.kind !== 'shell'` arm of `GthAgentRunner.decideToolApproval`, which floors it at
+ *   `destructive` and sends it to the human *with no rating call*, because §4.3 keeps the rater on
+ *   the shell until [[EXT-30]]. Gating there would silently turn every MCP call at `assisted` into
+ *   a human prompt — a UX change belonging to EXT-30, not to the two rungs whose published
+ *   descriptions this predicate makes true.
+ *
+ * `gateShell` only ever WIDENS the result. At a deterministic rung the shell is gated by its own
+ * (absent) access class if it is bound at all, so `gateShell: false` does not exempt it — an
+ * exemption keyed to one tool NAME is the defect class this predicate exists to remove. In practice
+ * a disabled shell tool is never bound, so the two agree.
+ *
+ * **This takes no bound toolset**, which is what lets `GthAgentRunner` ask it about a single
+ * arriving call: the runner sees the names the graph registered, and on the deep backend that list
+ * omits tools deepagents registers itself. A decision that consulted a bound list would grant
+ * `execute` at `manual` purely because the runner could not see it.
+ */
+export function isToolGatedAtRung(options) {
+    const { toolName, rung, gateShell } = options;
+    if (gateShell && toolName === SHELL_TOOL_NAME)
+        return true;
+    if (!isDeterministicRung(rung))
+        return false;
+    return !isAccessClassGrantedAtRung(toolName, rung);
+}
+/**
+ * **The LIVE gated set: which bound tools the rung in force actually gates.** What a decision is
+ * measured against — the tool descriptions the model reads (§4.5) and the rater's granted-tools
+ * summary (§4.4) are both built from this, so neither can tell the model a tool is free while the
+ * gate escalates it.
+ *
+ * **It is NOT what the backends wire into the interrupt.** That is
+ * {@link resolveInterruptToolNames}, and the two are different sets on purpose: the interrupt is
+ * installed once, at agent init, while `/approvals <rung>` moves the rung underneath it for the rest
+ * of the session. A set that carried the rung would be frozen at the rung the session started on —
+ * and since the default is `assisted`, typing `/approvals manual` would leave exactly the write
+ * tools this design escalates ungated. So the interrupt is wired rung-independently and
+ * `GthAgentRunner.decideToolApproval` consults {@link isToolGatedAtRung} against the LIVE rung.
+ *
+ * **Derived from the bound toolset, never a hand-written list.** A static list of built-ins would
+ * leave MCP, custom and agent-authored tools out — the exact tools with no access class and so the
+ * exact tools the deterministic rungs must escalate. `boundToolNames` must therefore be the FINAL
+ * toolset the graph is handed, including tools the graph builder registers itself (deepagents'
+ * filesystem tools, `execute`, `task` and `write_todos` never appear in the array gsloth passes it).
+ *
+ * Order is stable: the shell first, then bound order. Duplicates are collapsed, so a caller may pass
+ * overlapping name sources without deduplicating first.
+ */
+export function resolveGatedToolNames(options) {
+    const { rung, gateShell, boundToolNames } = options;
+    return collectToolNames(gateShell, boundToolNames, (name) => isToolGatedAtRung({ toolName: name, rung, gateShell }));
+}
+/**
+ * **Which commands have something that ANSWERS an approval interrupt.**
+ *
+ * `GthAgentRunner` is the one component that drains a suspended graph
+ * (`resolveToolInterrupts` → `decideToolApproval`) and the one that holds the session rung, so every
+ * command it drives answers approvals and can move the rung under a running session.
+ *
+ * **The AG-UI server (`api`) does not.** It drives the agent directly — `agent.init` +
+ * `streamWithEvents` — and its resume path serves its own frontend-tool `interrupt()` stubs, not
+ * approvals. An approval interrupt raised there suspends the graph with nobody to resume it: the
+ * tool never runs, the client is never asked, and the turn simply ends with that tool call
+ * unanswered. Measured, not inferred.
+ *
+ * So a command that answers nothing must be handed **no approval interrupt beyond what the shell
+ * gate itself requires** — see the `interruptTools` wiring in both backends. In particular it must
+ * NOT be handed the LIVE set for its configured rung: that set is non-empty at `manual` and
+ * `write`, so it carries exactly the same trap, and `commands.api.approvals` (plus a root-level
+ * `approvals`, which applies to every command) puts an ordinary config on those rungs.
+ *
+ * **Total over {@link GthCommand} on purpose.** An eighth command has to be classified here before
+ * it compiles, rather than defaulting silently into "answers approvals". The property is really
+ * about the DRIVER and not about the command — a second server built under an existing command that
+ * drives the agent without `GthAgentRunner` would inherit the trap with this record fully populated
+ * — so the shape that cannot rot at all is for the constructing surface to declare it at its own
+ * call site.
+ *
+ * Approvals for the AG-UI surface are [[EXT-30]]'s to build; until then this keeps a rung the server
+ * cannot serve from silently swallowing the tool calls it was asked to make.
+ */
+const COMMAND_ANSWERS_APPROVALS = {
+    ask: true,
+    chat: true,
+    code: true,
+    exec: true,
+    pr: true,
+    review: true,
+    /** The AG-UI server: it drives the agent itself and drains nothing. */
+    api: false,
+};
+/**
+ * {@link COMMAND_ANSWERS_APPROVALS} as a predicate. An unset command is a session driven by
+ * `GthAgentRunner` (nothing else leaves it unset), so it answers approvals.
+ *
+ * **`?? true` is the fail-safe default, not defensive noise.** The lookup yields `undefined` for a
+ * value outside {@link GthCommand}, and `undefined` is falsy — which would tell the caller to
+ * install NO approval interrupt, the one direction this predicate must never fail in. TypeScript
+ * makes that unreachable from inside this repo, but the function is re-exported from the public
+ * `@gaunt-sloth/core/config.js` barrel, so an untyped consumer can reach it. The coalesce restores
+ * runtime totality without weakening the compile-time totality the record already gives.
+ */
+export function commandAnswersApprovals(command) {
+    return command === undefined ? true : (COMMAND_ANSWERS_APPROVALS[command] ?? true);
+}
+/**
+ * **The interrupt set: which tool names the backends wire into the approval interrupt.** Every bound
+ * tool that ANY rung could gate — the union of {@link resolveGatedToolNames} over
+ * {@link APPROVAL_RUNGS}, which in practice is the shell plus every bound tool that is not a
+ * built-in READ tool.
+ *
+ * One derivation for both backends, for the same reason {@link resolveShellApprovalGate} is one: the
+ * lean backend installs `humanInTheLoopMiddleware` directly and the deep backend installs the very
+ * same middleware through deepagents' `interruptOn`, and a set computed twice is a set that drifts.
+ *
+ * **Deliberately rung-independent.** The interrupt is installed once, when the agent is built, and
+ * `/approvals <rung>` then moves the rung for the rest of the session without rebuilding it. Only a
+ * set that covers every rung can survive that: the interrupt fires and
+ * `GthAgentRunner.decideToolApproval` decides on the rung in force, which is where the rung has
+ * always been read. **Wiring wider does not gate wider** — a call the live rung does not gate is
+ * approved there with no rating call and no prompt, so `assisted`, `auto` and `bypass` behave
+ * exactly as they do when the interrupt holds the shell alone.
+ *
+ * **Only for a command that answers approvals** ({@link commandAnswersApprovals}). A surface that
+ * drains nothing gets the shell-gate set instead, because a rung-independent set there parks tool
+ * calls nobody can reach.
+ */
+export function resolveInterruptToolNames(options) {
+    const { gateShell, boundToolNames } = options;
+    return collectToolNames(gateShell, boundToolNames, (name) => APPROVAL_RUNGS.some((rung) => isToolGatedAtRung({ toolName: name, rung, gateShell })));
+}
+/**
+ * Shared body of the two resolvers above: the shell first (when gated), then the bound names the
+ * caller's predicate selects, in bound order, deduplicated, with nameless entries dropped.
+ */
+function collectToolNames(gateShell, boundToolNames, include) {
+    const names = [];
+    const seen = new Set();
+    const add = (name) => {
+        if (typeof name !== 'string' || name.length === 0 || seen.has(name))
+            return;
+        seen.add(name);
+        names.push(name);
+    };
+    if (gateShell)
+        add(SHELL_TOOL_NAME);
+    for (const name of boundToolNames) {
+        if (typeof name === 'string' && name.length > 0 && include(name))
+            add(name);
+    }
+    return names;
+}
+/**
+ * §4.7 — the four MCP `ToolAnnotations` hint names, and the whole vocabulary. It is the same list
+ * on both sides of the design: what a `hint` pattern may name ({@link ApprovalHintPattern}) and what
+ * a user may believe from a server ({@link McpServerApprovalsConfig.trustAnnotations}).
+ *
+ * **The schema twin `HINT_ANNOTATION_KEYS` in `config/schema.ts` is a deliberate duplicate, and the
+ * reason is layering, not oversight.** Neither file may import the other. `schema.ts` states in its
+ * own header that it must stay pure and cwd/fs-independent because it feeds `z.toJSONSchema()`, and
+ * importing this module would pull `core/types.js` and the whole runtime policy surface into it;
+ * importing `schema.ts` here would in turn pull zod into every module that only wanted a policy
+ * type. So the vocabulary is written once per layer on purpose — do not "simplify" it by making one
+ * import the other.
+ *
+ * What keeps the two honest instead is the equality assertion in `mcpApprovalsBlock.spec.ts`, which
+ * fails the moment they drift. Drift matters in one direction especially: a name the config accepts
+ * but the derivation never reads fails silently, and it fails toward trusting. Change one list,
+ * change the other.
+ */
+export const TOOL_ANNOTATION_HINTS = [
+    'readOnlyHint',
+    'destructiveHint',
+    'idempotentHint',
+    'openWorldHint',
+];
+/**
+ * §1.1 — **the default rung is `assisted`, everywhere.** It is the default in every interactive
+ * context, it does NOT vary with the configured model, and there is no separate non-interactive
+ * default. What changes without a human is what an escalation *does* (§6.2: an immediate non-zero
+ * exit, never an approval), not which rung the session starts on. A context-dependent default
+ * would reintroduce exactly the hidden branching this ladder exists to remove.
+ */
+export const DEFAULT_APPROVAL_RUNG = 'assisted';
+/** Normalize the scalar/object union to the object form. The scalar is sugar for `{ mode }`. */
+function toApprovalsObject(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === 'string')
+        return { mode: raw };
+    return raw;
+}
+/**
+ * CFG-27 — resolve the effective {@link ResolvedApprovals} for the active command.
+ *
+ * There is no defaults *matrix*: §1.1 makes `assisted` the default in every context, so this
+ * resolver neither detects nor accepts a "context". Precedence is the only thing it decides, and
+ * §9.1 splits it in two:
+ *
+ * - **The scalars — `mode`, `rater`, `raterTimeoutMs` — are replaced** when the per-command value
+ *   states them and **inherited from the root when it does not**. So the scalar sugar
+ *   `"code": { "approvals": "bypass" }` is exactly `{ mode: 'bypass' }` merged over the root: it
+ *   sets the rung and nothing else.
+ * - **`deny` and `escalate` never replace: they CONCATENATE across every scope.** A
+ *   command-specific `deny` *adds to* the root's. Removing an inherited prohibition for one command
+ *   is deliberately not expressible.
+ * - **`allow` is REPLACED when the per-command value states its own, and inherited when it does
+ *   not.** A per-command scope may therefore narrow what runs unprompted, and may never widen what
+ *   is prohibited.
+ * - **`mcp` (EXT-70 §4.7) follows `allow`, not the restrictive lists**: replaced when the
+ *   per-command value states it, inherited when it does not. Believing a hint is a PERMISSIVE act
+ *   in both directions — it can make an `allow` hint entry fire and can make a `deny` hint entry
+ *   stop firing — so it merges the way the permissive list does, and a per-command scope can
+ *   narrow the session's trust (`"mcp": {}` believes nothing) but never inherits half of it by
+ *   accident. Deep-merging the two scopes' `servers` maps was rejected for the same reason: it
+ *   would leave a deliberately distrustful per-command block silently carrying the root's trust.
+ *
+ * **The two halves differ because the costs differ (§3.1), not for tidiness.** A missed allow entry
+ * escalates and a missed deny entry falls through to the rater — neither is an execution — while a
+ * too-broad allow entry *runs, unrated and unprompted*. Concatenating the restrictive lists fails
+ * toward a prompt; concatenating the permissive one fails toward an execution, and would leave a
+ * deliberately restrictive per-command rung with no way to shed the root's standing grants. Do not
+ * "regularize" these three into one policy: the direction each list fails in is the whole design.
+ *
+ * On the restrictive side the pressure runs the other way (§11.1f). Were the per-command value to
+ * replace the root wholesale, the friendliest spelling of "stop asking me about `code`" would also
+ * delete every `deny` entry — at the one rung where the deny list and the §8 floor are the only
+ * checks left. A prohibition a nested config key can quietly delete is not a hardline.
+ *
+ * Concatenation order cannot change any outcome (`resolveApprovalRules` consults every deny entry
+ * before any escalate entry and every escalate entry before any allow entry), so root-first is a
+ * convention for readability — matching `GthAgentRunner.approvalRuleLists`, where the declared
+ * entries precede the runtime grants — and never a precedence.
+ *
+ * Defaults are applied HERE, at the read site, rather than in `DEFAULT_CONFIG` — so the
+ * effective-config snapshot the `/config` panel renders never churns (à la GS2-34
+ * `injectModelContext` / GS2-63 `output.header`).
+ *
+ * This is the per-command half. The cross-LAYER half (a project config's lists adding to a global
+ * config's rather than replacing them) is the additive-array policy in `config/loader.ts`; both are
+ * needed, since either alone still loses a list silently.
+ *
+ * @param command The active command; selects the per-command block.
+ */
+export function resolveApprovals(config, command) {
+    const root = toApprovalsObject(config?.approvals);
+    const perCommand = toApprovalsObject(command
+        ? config?.commands?.[command]
+            ?.approvals
+        : undefined);
+    return {
+        rung: perCommand?.mode ?? root?.mode ?? DEFAULT_APPROVAL_RUNG,
+        rater: perCommand?.rater ?? root?.rater,
+        // `??`, so an EXPLICIT empty list is honoured: `allow: []` on a command states "nothing is
+        // pre-trusted here" and must not read as "said nothing, inherit the root's".
+        allow: perCommand?.allow ?? root?.allow ?? [],
+        deny: [...(root?.deny ?? []), ...(perCommand?.deny ?? [])],
+        escalate: [...(root?.escalate ?? []), ...(perCommand?.escalate ?? [])],
+        raterTimeoutMs: perCommand?.raterTimeoutMs ?? root?.raterTimeoutMs,
+        // `??`, so an EXPLICIT empty block is honoured exactly as an explicit empty `allow` is: it
+        // states "believe nothing external here" and must not read as "said nothing, inherit the root".
+        mcp: perCommand?.mcp ?? root?.mcp,
+    };
+}
+/**
+ * EXT-52 — the ONE shell approval-gate policy both agent backends resolve
+ * (`GthLangChainAgent` = lean/default, `GthDeepAgent` = deep). It decides whether the opt-in
+ * `run_shell_command` tool is gated behind the per-command approval interrupt, and which status
+ * notice (if any) the backend should surface. The backends differ only in HOW they install the
+ * interrupt; the policy and its user-facing copy live here so the two can never drift (and so a
+ * later rename of this config surface has one place to change).
+ *
+ * CFG-27 — **the tool is gated whenever it is enabled, at every rung including `bypass`.** CFG-26
+ * used to leave it UNGATED under `bypass` outside interactive `code`, which the ladder cannot
+ * afford: §2.5 makes the declared **deny list the one check `bypass` keeps**, and a deny entry can
+ * only fire if the call reaches `GthAgentRunner.decideToolApproval` — an ungated call never does.
+ * Gating unconditionally also keeps the rung switchable mid-session (`/approvals <rung>`), since a
+ * tool wired without the interrupt cannot be re-gated without rebuilding the agent.
+ *
+ * What each rung then does is decided in `decideToolApproval`, not here:
+ *   • `bypass` — deny list, then approve without prompting or rating.
+ *   • `manual`/`write` — deny list, allow-list, else escalate to the human.
+ *   • `assisted`/`auto` — deny list, allow-list, then the rater.
+ *
+ * **This decides the SHELL's gating only, and it is not the whole gated set.** With the shell tool
+ * disabled — or on a non-dev-tools command (chat/api/…) — nothing about the shell is gated and
+ * nothing is announced, but at `manual` and `write` {@link resolveGatedToolNames} still gates
+ * every bound tool the rung does not auto-grant, so an MCP call in a plain `chat` session is
+ * escalated there. Read `gateShell` as "does the shell need the interrupt", never as "is the
+ * interrupt needed at all".
+ *
+ * Shell enablement itself is resolved through {@link getEffectiveDevToolsConfig} +
+ * {@link isShellToolEnabled}, so the gate stays in lockstep with where `GthDevToolkit` actually
+ * emits the tool; the posture comes from {@link resolveApprovals}, so this and the runner can
+ * never disagree about which rung is in force.
+ */
+export function resolveShellApprovalGate(config, command) {
+    const devTools = getEffectiveDevToolsConfig(config, command);
+    const gateShell = isShellToolEnabled(devTools, command);
+    if (!gateShell)
+        return { gateShell };
+    const { rung } = resolveApprovals(config, command);
+    if (rung === 'bypass') {
+        return {
+            gateShell,
+            notice: {
+                level: StatusLevel.WARNING,
+                message: 'Shell tool (run_shell_command): commands run without asking and without rating ' +
+                    '(approvals: bypass). Only your deny list still applies — type /approvals assisted to ' +
+                    'rate commands again.',
+            },
+        };
+    }
+    if (isRatedRung(rung)) {
+        // **Both rated modes get the SAME tail, because it is true of both and it is all this line
+        // promises**: nothing the rater does not clear simply runs. They reach it differently — at
+        // `assisted` an unsafe-looking command goes to the human, at `auto` ([[EXT-29]] §5) it is
+        // refused back to the agent first and reaches the human when a bound is spent — and at `auto`
+        // both halves happen within one session, so a per-mode tail could only pick one of them. This
+        // is the startup notice a user meets while working out what their config does; the mode's own
+        // description ({@link APPROVAL_RUNG_DESCRIPTIONS}) is where the difference is stated.
+        return {
+            gateShell,
+            notice: {
+                level: StatusLevel.INFO,
+                message: `Shell tool (run_shell_command) rated by the auto-rater (approvals: ${rung}); ` +
+                    'anything it does not rate safe is still refused or escalated to you.',
+            },
+        };
+    }
+    return {
+        gateShell,
+        notice: {
+            level: StatusLevel.INFO,
+            message: `Shell tool (run_shell_command) enabled with per-command approval (approvals: ${rung}).`,
+        },
+    };
+}
+//# sourceMappingURL=shell-policy.js.map