@gaunt-sloth/core 2.0.0-alpha.23 → 2.0.0-alpha.25

package/dist/config/shell-policy.d.ts

@@ -1,8 +1,10 @@
 /**
  * @packageDocumentation
  * Shell / dev-tools policy: the {@link GthDevToolsConfig} type plus all the resolvers
- * that interpret it (shell enablement, timeouts, output budget, allow-list, the EXT-10
- * LLM-as-judge gate, and per-command dev-tools selection).
+ * 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
@@ -11,8 +13,8 @@
  * `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 type { GthCommand } from '#src/core/types.js';
-import type { GthConfig, LLMConfig } from '#src/config/types.js';
+import { type GthCommand, StatusLevel } from '#src/core/types.js';
+import type { GthConfig } from '#src/config/types.js';
 /**
  * CFG-18 — the per-tool config object carried as a value in the {@link GthConfig.builtInTools}
  * registry (the object form's values, alongside a bare boolean that enables/force-disables a tool).
@@ -20,12 +22,16 @@ import type { GthConfig, LLMConfig } from '#src/config/types.js';
  * discriminated union so the registry can carry every tool's shape:
  * - the fixed dev-command tools (`run_tests`/`run_lint`/`run_build`/`run_single_test`) read
  *   {@link command} — the shell command to run; its presence enables the tool;
- * - `run_shell_command` reads the EXT-9/10/12 knobs ({@link enabled}/{@link timeout}/
- *   {@link maxOutputBytes}/{@link allowlist}/{@link persistAllowlist}/{@link judge}/{@link yolo} —
- *   `yolo` is the folded former `shellYolo`);
+ * - `run_shell_command` reads the EXT-9/12 execution knobs ({@link enabled}/{@link timeout}/
+ *   {@link maxOutputBytes});
  * - `gth_grep` reads {@link fileSet} (GS2-51) — which corpus to search;
  * - a plain built-in tool (`gth_checklist`, `gth_web_fetch`, …) reads {@link enabled} (or is
  *   toggled with a bare boolean in the registry).
+ *
+ * CFG-26 — the APPROVAL knobs (`allowlist`, `persistAllowlist`, `judge`, `yolo`) are gone from
+ * here and live in the top-level {@link ApprovalsConfig}. They were fields of the object shared by
+ * EVERY built-in tool, so `gth_grep: { yolo: true }` used to validate; approvals are a property of
+ * the session, not of one tool's registry entry.
  */
 export interface BuiltInToolConfig {
     /**
@@ -41,23 +47,6 @@ export interface BuiltInToolConfig {
     timeout?: number;
     /** `run_shell_command`: captured-output byte budget. See {@link SHELL_DEFAULT_MAX_OUTPUT_BYTES}. */
     maxOutputBytes?: number;
-    /** `run_shell_command`: EXT-9 Tier-2 scoped allow-list master switch (default `true`). */
-    allowlist?: boolean;
-    /** `run_shell_command`: persist `always`-scoped approvals to the project file (default `true`). */
-    persistAllowlist?: boolean;
-    /** `run_shell_command`: EXT-10 LLM-as-judge safety gate (default OFF). */
-    judge?: boolean | {
-        enabled?: boolean;
-        autoApproveLow?: boolean;
-        blockHigh?: boolean;
-        model?: LLMConfig;
-    };
-    /**
-     * `run_shell_command`: opt out of the per-command approval prompt — the explicit "yolo" bypass
-     * (folded former top-level `shellYolo`). Dangerous by design; off by default. Example:
-     * `{ "run_shell_command": { "yolo": true } }`.
-     */
-    yolo?: boolean;
     /**
      * `gth_grep` (GS2-51): which corpus the content-search tool scans, applied consistently to BOTH
      * execution engines (native ripgrep and the in-process JS fallback):
@@ -87,7 +76,7 @@ export interface BuiltInToolConfig {
  * { "builtInTools": {
  *     "gth_checklist": true,
  *     "gth_web_fetch": true,
- *     "run_shell_command": { "timeout": 300000, "judge": { "enabled": true } }
+ *     "run_shell_command": { "timeout": 300000 }
  * } }
  * ```
  * Turn the (code-mode default-on) shell OFF: `{ "builtInTools": { "run_shell_command": false } }`.
@@ -156,17 +145,16 @@ export interface GthDevToolsConfig {
      * lacks (it can read/write files but not run commands).
      *
      * EXT-12 — default: ON in `code` mode, OFF elsewhere. When this is ABSENT/undefined,
-     * `code` mode emits the tool (still GATED behind the per-command approval prompt — the
-     * absent-config default NEVER implies yolo); `exec` / `ask --write` keep it OFF. An
-     * EXPLICIT value always wins: `shell: false` (or `{ enabled: false }`) is a hard escape
-     * hatch that fully disables it even in `code`. Accepts a bare boolean or an
-     * `{ enabled }` object for symmetry with future per-tool options.
+     * `code` mode emits the tool (still GATED behind the approval gate — the absent-config
+     * default NEVER implies bypass); `exec` / `ask --write` keep it OFF. An EXPLICIT value
+     * always wins: `shell: false` (or `{ enabled: false }`) is a hard escape hatch that fully
+     * disables it even in `code`. Accepts a bare boolean or an `{ enabled }` object.
      *
-     * Because the model chooses the command, every invocation is gated behind a
-     * per-command human confirmation dialog (LangChain `humanInTheLoopMiddleware`,
-     * wired via deepagents' `interruptOn`) UNLESS {@link shellYolo} bypasses it.
-     * The confirmation — not string-filtering — is the guardrail, so the command
-     * is passed through verbatim (pipes / `$` / `;` are all legitimate).
+     * Because the model chooses the command, every invocation is gated behind the CFG-26
+     * approvals gate (LangChain `humanInTheLoopMiddleware`, wired via deepagents' `interruptOn`)
+     * UNLESS `approvals.mode: "bypass"` turns the gate off. The gate — not string-filtering — is
+     * the guardrail, so the command is passed through verbatim (pipes / `$` / `;` are all
+     * legitimate).
      *
      * The object form also tunes the EXT-9 Tier-1 hardening applied to every run
      * (these have safe defaults so bare `shell: true` is already hardened):
@@ -179,63 +167,21 @@ export interface GthDevToolsConfig {
      *
      * A hardcoded hardline blocklist of catastrophic commands (rm -rf /, mkfs, dd
      * to a block device, fork bomb, shutdown/reboot, …) is refused even under
-     * {@link shellYolo}; that floor is not configurable.
+     * `approvals.mode: "bypass"`; that floor is not configurable.
      *
      * On-disk (CFG-18) these live on the `run_shell_command` entry of `builtInTools`, e.g.
      * `{ "builtInTools": { "run_shell_command": true } }` or
      * `{ "builtInTools": { "run_shell_command": { "timeout": 300000, "maxOutputBytes": 200000 } } }`.
      *
-     * The object form additionally accepts EXT-9 Tier-2 allow-list knobs:
-     * - `allowlist`: master switch for the scoped approval allow-list (session +
-     *   persisted `always`). Default `true` — once a command is approved at `session`/
-     *   `always` scope, flag-variants of the same classified operation auto-approve
-     *   without re-prompting. Set `false` to require fresh approval for every command.
-     * - `persistAllowlist`: whether `always`-scoped approvals are written to the project
-     *   allow-list file (`.gsloth/.gsloth-settings/shell-allowlist.json`). Default `true`.
-     *   When `false`, an `always` decision behaves like `session` (in-memory only).
-     *
-     * The object form also accepts the EXT-10 LLM-as-judge safety gate (default OFF):
-     * - `judge`: an opt-in, tiered auto-approve pre-filter that vets each `run_shell_command`
-     *   with a lightweight judge model BEFORE the human prompt. It auto-approves clearly-safe
-     *   commands (fatigue reducer), escalates the rest to the existing human prompt, and may
-     *   reject clearly-catastrophic ones. Default OFF because it costs one LLM call per command.
-     *   Accepts a bare boolean (`judge: true` → defaults: auto-approve low, escalate medium/high,
-     *   judge model = `config.llm`) or an object:
-     *     - `enabled`: turn the gate on.
-     *     - `autoApproveLow`: auto-approve `low`-risk, statically-resolvable commands. Default true.
-     *     - `blockHigh`: reject clearly-catastrophic (`high` + destructive) verdicts WITHOUT
-     *       prompting. Default false (conservative; EXT-9's hardline floor already refuses truly
-     *       catastrophic commands at exec time).
-     *     - `model`: an optional separate (e.g. cheaper) judge model config. Defaults to `config.llm`.
-     *   Hardening (always on when the judge runs): the command is normalized + XML-tagged as
-     *   UNTRUSTED input in the judge prompt; a judge throw/timeout/parse-failure fails CLOSED
-     *   (escalate, never auto-approve); commands whose target can't be statically resolved
-     *   (shell composition / substitution / redirection) and interpreter+script invocations that
-     *   leak ALL_CAPS env vars are NEVER auto-approved.
+     * CFG-26 — the approval knobs that used to live here (`allowlist`, `persistAllowlist`,
+     * `judge`, `yolo`) moved to the top-level `approvals` block ({@link ApprovalsConfig}); read
+     * them through {@link resolveApprovals}, never from this object.
      */
     shell?: boolean | {
         enabled?: boolean;
         timeout?: number;
         maxOutputBytes?: number;
-        allowlist?: boolean;
-        persistAllowlist?: boolean;
-        judge?: boolean | {
-            enabled?: boolean;
-            autoApproveLow?: boolean;
-            blockHigh?: boolean;
-            model?: LLMConfig;
-        };
     };
-    /**
-     * Opt-out of the per-command confirmation dialog for {@link shell}
-     * (`run_shell_command`) — the explicit "yolo" bypass. When `true` AND `shell`
-     * is enabled, the shell tool runs without any approval interrupt: the model's
-     * commands execute immediately. Dangerous by design; off by default.
-     *
-     * On-disk (CFG-18) this is the `yolo` knob of the `run_shell_command` entry, e.g.
-     * `{ "builtInTools": { "run_shell_command": { "yolo": true } } }`.
-     */
-    shellYolo?: boolean;
 }
 /**
  * Default per-command shell timeout (ms) when {@link GthDevToolsConfig.shell}
@@ -282,50 +228,454 @@ export declare function getShellTimeoutMs(devTools: GthDevToolsConfig | undefine
  */
 export declare function getShellMaxOutputBytes(devTools: GthDevToolsConfig | undefined): number;
 /**
- * Whether the EXT-9 Tier-2 scoped allow-list is active. Default `true`; only the object
- * form's `allowlist: false` disables it (a bare `shell: true` keeps it on). When off, the
- * runner prompts for every `run_shell_command` regardless of prior approvals.
+ * 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 declare function getEffectiveDevToolsConfig(config: Pick<GthConfig, 'commands' | 'builtInTools' | 'askWriteMode'> | undefined, command: GthCommand | undefined): GthDevToolsConfig | undefined;
+/**
+ * CFG-27 (spec §1, §2) — **the ladder**. There is ONE approvals setting and it is a single ordered
+ * ladder of five rungs; 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 | `read-only` | no | none |
+ * | 2 | `write` | no | none |
+ * | 3 | `auto-safe` | yes | 1 call per gated call |
+ * | 4 | `full-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.
+ *
+ * **`bypass` is NOT a higher-autonomy rung than `full-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 `full-auto` were an
+ * incomplete `bypass`.
+ *
+ * Identifiers are kebab-case (§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 keep their
+ * spaces; see {@link APPROVAL_RUNG_LABELS}.
+ */
+export declare const APPROVAL_RUNGS: readonly ['read-only', 'write', 'auto-safe', 'full-auto', 'bypass'];
+/** One rung of {@link APPROVAL_RUNGS}. */
+export type ApprovalRung = (typeof APPROVAL_RUNGS)[number];
+/**
+ * §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 declare const APPROVAL_RUNG_LABELS: Record<ApprovalRung, string>;
+/**
+ * §10 — the one sentence shown wherever a rung is chosen or displayed. **Copied verbatim from the
+ * specification**; the wording is constrained by four normative rules there (state what the rung
+ * 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 — descriptions
+ * cite only protections the user can inspect and extend, i.e. the deny list). Do not "improve"
+ * these: `auto-safe` in particular MUST keep the sentence saying files are still rewritten and
+ * deleted without asking.
+ *
+ * The only departure from the source text is that §10's markdown emphasis markers (`**not**` in
+ * *Full auto*) are dropped, since these strings are rendered as plain terminal copy.
+ */
+export declare const APPROVAL_RUNG_DESCRIPTIONS: Record<ApprovalRung, string>;
+/** Narrowing type guard for a raw string that may name a rung. */
+export declare function isApprovalRung(value: unknown): value is ApprovalRung;
+/** The rungs at which every gated call is rated by the model (§2.3, §2.4). */
+export declare function isRatedRung(rung: ApprovalRung): boolean;
+/**
+ * EXT-71 §3.1 — the **subject** axis of a rule entry, and only that. The schema twin is
+ * `APPROVAL_ENTRY_TYPES` in `config/schema.ts`. What holds the two together is
+ * `approvalEntrySchema.spec.ts`, where a list of `ApprovalEntry`-typed literals is parsed by that
+ * schema: a value either side stops accepting fails there. That is a weaker pin than a direct
+ * equality assertion — it catches a narrowing, not a widening on one side alone.
  */
-export declare function isShellAllowlistEnabled(devTools: GthDevToolsConfig | undefined): boolean;
+export type ApprovalEntryType = 'shell' | 'tool' | 'mcpTool';
+/** EXT-71 §3.1 — the **comparison** axis of a rule entry, and only that. */
+export type ApprovalMatcher = 'exact' | 'glob' | 'regexp' | 'hint';
 /**
- * Whether `always`-scoped approvals are persisted to the project allow-list file. Default
- * `true`; only the object form's `persistAllowlist: false` disables persistence (an
- * `always` decision then behaves as `session`).
+ * §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 declare function isShellAllowlistPersisted(devTools: GthDevToolsConfig | undefined): boolean;
+export declare const TOOL_ANNOTATION_HINTS: readonly ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'];
+/** One of {@link TOOL_ANNOTATION_HINTS}. */
+export type ToolAnnotationHint = (typeof TOOL_ANNOTATION_HINTS)[number];
 /**
- * Resolved settings for the EXT-10 LLM-as-judge safety gate.
+ * EXT-71 §3.1 — a `hint` pattern: the four MCP `ToolAnnotations` booleans, each mapped to the
+ * value it must EFFECTIVELY hold (§4.7.1). All named hints must match (AND within the entry);
+ * hints not named are unconstrained; `false` is the spelling of negation. At least one must be
+ * named — an empty object is a config error, never a match-everything.
  */
-export interface ShellJudgeSettings {
-    /** Whether the judge gate runs at all. */
-    enabled: boolean;
-    /** Auto-approve `low`-risk, statically-resolvable commands (the fatigue reducer). */
-    autoApproveLow: boolean;
-    /** Reject clearly-catastrophic (`high` + destructive) verdicts without prompting. */
-    blockHigh: boolean;
-    /** Optional separate judge model config; when absent the runner uses `config.llm`. */
-    model?: LLMConfig;
+export interface ApprovalHintPattern {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** Fields every rule entry may carry, whatever its subject. */
+interface ApprovalEntryCommon {
+    /**
+     * §3.2 — whether the rater still reviews a call this entry matched, honored at the rater rungs
+     * and inert at the deterministic ones. Valid on EVERY type. Absent takes the §3.2 default: an
+     * entry skips the rater only to the extent that it recorded what the rater would have seen, so
+     * `shell` + `exact` defaults to `false` and everything else to `true`.
+     */
+    rate?: boolean;
+}
+/** §3.1 — a `shell` entry: a command, compared against the normalized command string. */
+export interface ShellApprovalEntry extends ApprovalEntryCommon {
+    type: 'shell';
+    /** `hint` is absent on purpose — a command carries no tool annotations. */
+    matcher: 'exact' | 'glob' | 'regexp';
+    pattern: string;
+}
+/** §3.1 — a `tool` entry: a built-in or custom in-process tool, compared against the tool name. */
+export interface ToolApprovalEntry extends ApprovalEntryCommon {
+    type: 'tool';
+    matcher: ApprovalMatcher;
+    pattern: string | ApprovalHintPattern;
+    /** §4.7.4 — optional exact-match bound on the call's host. Tool subjects only. */
+    host?: string;
+}
+/** §3.1 — an `mcpTool` entry: one server's tool. */
+export interface McpToolApprovalEntry extends ApprovalEntryCommon {
+    type: 'mcpTool';
+    matcher: ApprovalMatcher;
+    pattern: string | ApprovalHintPattern;
+    /**
+     * §4.7.5 — **required**, and the user's own key in `mcpServers`: the only identity a server has
+     * that is stable, unique and user-authored. The literal `*` means every server, which is why a
+     * configured server may not be named `*`.
+     */
+    server: string;
+    /** §4.7.4 — optional exact-match bound on the call's host. */
+    host?: string;
 }
 /**
- * Whether the EXT-10 LLM-as-judge safety gate is enabled for the given dev-tools config.
- * Default OFF (only the object form's `judge` truthy enables it), mirroring
- * {@link isShellToolEnabled}. A bare `shell: true` keeps the judge OFF — it costs an LLM call
- * per command and must be opted into explicitly.
+ * EXT-71 §3.1 — **one entry** in `allow`, `deny` or `escalate`. All three lists take the same
+ * shape; the list an entry sits in decides only what a match DOES (deny over escalate over allow).
+ *
+ * `type`, `matcher` and `pattern` are always required — no field is inferred and no entry reads
+ * two ways. The runtime validator is `approvalEntrySchema` in `config/schema.ts`, which is
+ * stricter than TypeScript can be: it rejects unknown fields, an empty or unknown-key `hint`
+ * pattern, and a `regexp` that does not compile or is over the length cap.
  */
-export declare function isShellJudgeEnabled(devTools: GthDevToolsConfig | undefined): boolean;
+export type ApprovalEntry = ShellApprovalEntry | ToolApprovalEntry | McpToolApprovalEntry;
 /**
- * Resolve the EXT-10 judge gate settings from a dev-tools config, applying safe defaults
- * (auto-approve low, do NOT block high). `enabled` reflects {@link isShellJudgeEnabled}.
+ * EXT-70 §4.7.1/§9 — the approvals relationship with ONE MCP server, keyed by the user's own
+ * `mcpServers` config key (§4.7.5 — the only identity a server has that is stable, unique and
+ * user-authored; nothing a server declares about itself ever participates).
+ *
+ * `trustAnnotations` names the hints that are BELIEVED from that server. It is a list rather than a
+ * boolean because trusting `readOnlyHint` while distrusting `openWorldHint` is a coherent position
+ * and the common one, and because a single "trusted server" flag throws that distinction away for
+ * nothing. **Absent or empty means what the default means: nothing external is believed** — every
+ * hint of that server's collapses to the MCP fail-closed default, so its declarations cannot
+ * perturb any rule.
  */
-export declare function getShellJudgeSettings(devTools: GthDevToolsConfig | undefined): ShellJudgeSettings;
+export interface McpServerApprovalsConfig {
+    /** §4.7.1 — the hints believed from this server. Absent or empty trusts nothing. */
+    trustAnnotations?: ToolAnnotationHint[];
+}
 /**
- * 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.
+ * EXT-70 §4.7/§9 — the `approvals.mcp` block: the per-server relationship, keyed by the user's own
+ * `mcpServers` config key.
+ *
+ * **`defaults` applies to servers NOT named under `servers`** — §9's own gloss. A server that names
+ * itself states its own relationship in full, so `{"jira": {}}` trusts nothing however permissive
+ * `defaults` is: trust by omission is exactly the failure §4.7.1 exists to prevent, and the fail-
+ * closed direction is the one a silent config edit must fall in.
+ *
+ * A key here is **not** validated against `mcpServers`. A user may write the policy before adding
+ * the server, and coupling the two would make config ORDER matter.
+ *
+ * This block cannot live inside `mcpServers`, which is modelled permissively because it carries
+ * runtime objects.
  */
-export declare function getEffectiveDevToolsConfig(config: Pick<GthConfig, 'commands' | 'builtInTools' | 'askWriteMode'> | undefined, command: GthCommand | undefined): GthDevToolsConfig | undefined;
+export interface McpApprovalsConfig {
+    /** The relationship with every server not named under {@link servers}. */
+    defaults?: McpServerApprovalsConfig;
+    /** Per-server relationships, keyed by the user's own `mcpServers` config key (§4.7.5). */
+    servers?: Record<string, McpServerApprovalsConfig>;
+}
+/**
+ * On-disk `approvals` object form (root or per command). The **scalar form is exactly sugar for
+ * `{ mode: <value> }`** (§9.1) — the union exists so the extras have a home when they are needed,
+ * not so there are two ways to say the same thing.
+ */
+export interface ApprovalsObjectConfig {
+    /** The rung. Absent = {@link DEFAULT_APPROVAL_RUNG}. */
+    mode?: ApprovalRung;
+    /**
+     * §9.1 — the identity profile the rater runs under, as a **bare name** (strict resolution,
+     * GS2-62: a name that does not resolve is a hard config error, never a silent fallback).
+     * Omitted = the main model. It is the only rater knob; nesting a one-field object is what this
+     * design removed.
+     */
+    rater?: string;
+    /** §3 — declared allow-list: what the human has trusted. Read-only input. */
+    allow?: ApprovalEntry[];
+    /** §3 — declared deny-list: what never runs. Read-only input; applies under `bypass` too. */
+    deny?: ApprovalEntry[];
+    /**
+     * §3/§3.2 — declared escalate list: a match always asks the human, whatever the rung would have
+     * done, and with no rating call. Read-only input; inert under `bypass` (§2.5).
+     */
+    escalate?: ApprovalEntry[];
+    /**
+     * EXT-66 — wall-clock budget (ms) for ONE rating call. Absent = {@link RATER_DEFAULT_TIMEOUT_MS}
+     * (30s), which is a hosted-model number: a local rater is knowably slower, and when it runs out
+     * of time the gate escalates, so an unreachable timeout turns the permissive rung into one that
+     * asks about everything while every layer reports success.
+     */
+    raterTimeoutMs?: number;
+    /**
+     * EXT-70 §4.7/§9 — the per-server MCP relationship. Read through
+     * `createEffectiveToolAnnotationSource` (`core/approvals/annotations.ts`), which is the ONE place
+     * an effective annotation set is derived; nothing else re-reads this block.
+     */
+    mcp?: McpApprovalsConfig;
+}
+/** On-disk `approvals` value: the rung on its own, or the object when the extras are needed. */
+export type ApprovalsConfig = ApprovalRung | ApprovalsObjectConfig;
+/**
+ * The fully-defaulted approvals posture for one command. `allow`/`deny`/`escalate` are the
+ * **declared** lists straight from config — read-only input that the runner merges with the
+ * runtime stores the escalation menu writes, and that is never written back to config (§9.1).
+ */
+export interface ResolvedApprovals {
+    /** The rung in force. */
+    rung: ApprovalRung;
+    /** Identity profile the rater runs under, or `undefined` for the session model. */
+    rater?: string;
+    /** Declared allow-list entries (§3.1). Empty when none are declared. */
+    allow: ApprovalEntry[];
+    /** Declared deny-list entries (§3.1). Empty when none are declared. */
+    deny: ApprovalEntry[];
+    /** Declared escalate-list entries (§3.1). Empty when none are declared. */
+    escalate: ApprovalEntry[];
+    /**
+     * EXT-66 — wall-clock budget (ms) for one rating call, or `undefined` to let the rater apply
+     * `RATER_DEFAULT_TIMEOUT_MS`. Left `undefined` rather than defaulted here so the effective-config
+     * snapshot does not churn, exactly as `rater` is.
+     */
+    raterTimeoutMs?: number;
+    /**
+     * EXT-70 §4.7 — the declared per-server MCP relationship, or `undefined` when no scope states
+     * one (which reads the same as an empty block: nothing external is believed). Left `undefined`
+     * rather than defaulted here for the same reason `rater` is — so the effective-config snapshot
+     * does not churn.
+     */
+    mcp?: McpApprovalsConfig;
+}
+/**
+ * CFG-26 — how many command prefixes the allow-list holds, for the `/approvals` display.
+ * `always: undefined` means the persisted store has not been loaded — rendered `—` rather than a
+ * misleading `0`, since a display must never create the store.
+ */
+export interface AllowlistCounts {
+    session: number;
+    always: number | undefined;
+}
+/**
+ * EXT-70 §4.7.1 — what one server's annotations are believed on, for display.
+ *
+ * `configured` says whether {@link server} is a key under `mcpServers` in the loaded config. It is
+ * an advisory rather than a validity test: §9 deliberately does NOT check `approvals.mcp` keys
+ * against `mcpServers`, so a user may write the policy before adding the server and config ORDER
+ * never matters. What it buys interactively is that a mistyped key — which trusts nothing while
+ * reading as though it did — can be pointed out rather than swallowed.
+ */
+export interface McpServerAnnotationTrust {
+    /** §4.7.5 — the user's own `mcpServers` config key. */
+    server: string;
+    /** The hints believed from this server, resolved through `defaults` where it is not named. */
+    trusted: ToolAnnotationHint[];
+    /** Whether this key names a server in the loaded config's `mcpServers`. */
+    configured: boolean;
+}
+/** EXT-70 §4.7.1 — the whole believed-annotation picture, for the `/approvals` display. */
+export interface McpAnnotationTrustView {
+    /** §9 — the hints believed from servers NOT named under `servers`. */
+    defaults: ToolAnnotationHint[];
+    /** Per-server, for every key either the config names or the policy does. */
+    servers: McpServerAnnotationTrust[];
+}
+/**
+ * EXT-70 §4.7.1/§4.7.4 — the outcome of believing (or ceasing to believe) hints from one server,
+ * so the surface that asked can report exactly what landed and what it costs.
+ *
+ * **`weakening` is the field that keeps the human un-surprised.** Withdrawing trust pushes a hint
+ * back to its fail-closed default, which for three of the four is a *weakening*, so the saved
+ * approvals made for that server while the hint was believed will be invalidated (§4.7.4) at the
+ * next call to that tool. That has to be said where the user withdraws trust, not only in the
+ * notice that arrives later.
+ */
+export interface McpAnnotationTrustChange extends McpServerAnnotationTrust {
+    /** Hints this change started believing (absent from the previous set). */
+    added: ToolAnnotationHint[];
+    /** Hints this change stopped believing (present in the previous set). */
+    removed: ToolAnnotationHint[];
+    /**
+     * §4.7.4 — the subset of {@link removed} whose withdrawal can weaken an effective set, and
+     * therefore invalidate a grant. Empty on a grant of trust, which can never weaken: every
+     * weakening move ends at the fail-closed default, and believing a hint only ever moves away
+     * from it.
+     */
+    weakening: ToolAnnotationHint[];
+    /**
+     * §4.7.4 — the saved approvals for this server that the *resulting* trust actually weakens, each
+     * rendered by `describeApprovalEntry`. They are the ones that will be withdrawn, with the §4.7.4
+     * notice, at the next call to that tool.
+     *
+     * **A prediction, never a deletion.** Invalidation stays scoped to the call being decided, because
+     * a sweep would read every held grant against a source that can only answer for the tools
+     * registered right now — a server that happened to be offline would read as having weakened
+     * everything it ever declared, and the grants would go. Listing them is safe where deleting them
+     * is not.
+     *
+     * **It over-reports in two distinct ways, and both are the same trade.** The comparison is each
+     * grant's recorded snapshot against the set in force *now*, not the set before this change against
+     * the set after it. So (1) a server that is offline when trust moves declares nothing, resolves to
+     * the fail-closed constant, and every grant it holds is named; and (2) a grant already weakened
+     * for some other reason — an earlier withdrawal, a `tools/list` that took a hint back — is named
+     * under whichever withdrawal happens to run next, including one that moved nothing relevant to it.
+     * A named grant is therefore one that the trust now in force weakens, which is what the user needs
+     * to know; it is not a claim that *this* withdrawal is what weakened it. Reading it as the latter
+     * is how a test comes to assert causation the field never promised.
+     *
+     * Empty is likewise not "nothing is at risk" but "nothing this session can see is": with
+     * {@link weakening} non-empty the rule still holds for any grant made while those hints were
+     * believed, which is what the notice says in that case. Counted read-only, like
+     * {@link AllowlistCounts}: the persisted store is consulted only when it is already loaded.
+     */
+    invalidates: string[];
+}
+/**
+ * §1.1 — **the default rung is `auto-safe`, 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 declare const DEFAULT_APPROVAL_RUNG: ApprovalRung;
+/**
+ * CFG-27 — resolve the effective {@link ResolvedApprovals} for the active command.
+ *
+ * There is no defaults *matrix*: §1.1 makes `auto-safe` 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 declare function resolveApprovals(config: Pick<GthConfig, 'commands' | 'approvals'> | undefined, command: GthCommand | undefined): ResolvedApprovals;
+/** A status notice a backend should surface after resolving the shell approval gate. */
+export interface ShellApprovalGateNotice {
+    /** Severity to pass to the agent's `statusUpdate` callback. */
+    level: StatusLevel;
+    /** The user-facing message. */
+    message: string;
+}
+/** The resolved shell approval-gate policy: whether to gate, and what to tell the user. */
+export interface ShellApprovalGateDecision {
+    /**
+     * Whether `run_shell_command` must be wired behind the per-command approval interrupt
+     * (langchain's `humanInTheLoopMiddleware` — installed directly on the lean backend, via
+     * deepagents' `interruptOn` on the deep one).
+     */
+    gateShell: boolean;
+    /** The notice to surface, when this configuration warrants one. */
+    notice?: ShellApprovalGateNotice;
+}
+/**
+ * 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.
+ *   • `read-only`/`write` — deny list, allow-list, else escalate to the human.
+ *   • `auto-safe`/`full-auto` — deny list, allow-list, then the rater.
+ *   • With the shell tool disabled — or on a non-dev-tools command (chat/api/…) — nothing is gated
+ *     and nothing is announced.
+ *
+ * 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 declare function resolveShellApprovalGate(config: Pick<GthConfig, 'commands' | 'builtInTools' | 'askWriteMode' | 'approvals'> | undefined, command: GthCommand | undefined): ShellApprovalGateDecision;
+export {};