@gaunt-sloth/core 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/config/shell-policy.js

@@ -1,3 +1,19 @@
+/**
+ * @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';
 /**
  * The fixed dev-command tools: each maps a `command` string (from its {@link BuiltInToolConfig})
  * to a run_* tool emitted by {@link GthDevToolkit}.
@@ -113,66 +129,11 @@ export function getShellMaxOutputBytes(devTools) {
     }
     return SHELL_DEFAULT_MAX_OUTPUT_BYTES;
 }
-/**
- * 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.
- */
-export function isShellAllowlistEnabled(devTools) {
-    const shell = devTools?.shell;
-    if (shell && typeof shell === 'object' && shell.allowlist === false)
-        return false;
-    return true;
-}
-/**
- * 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`).
- */
-export function isShellAllowlistPersisted(devTools) {
-    const shell = devTools?.shell;
-    if (shell && typeof shell === 'object' && shell.persistAllowlist === false)
-        return false;
-    return true;
-}
-/**
- * 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.
- */
-export function isShellJudgeEnabled(devTools) {
-    const shell = devTools?.shell;
-    if (!shell || typeof shell !== 'object')
-        return false;
-    const judge = shell.judge;
-    if (typeof judge === 'boolean')
-        return judge;
-    if (judge && typeof judge === 'object')
-        return judge.enabled === true;
-    return false;
-}
-/**
- * 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}.
- */
-export function getShellJudgeSettings(devTools) {
-    const enabled = isShellJudgeEnabled(devTools);
-    const shell = devTools?.shell;
-    const judge = shell && typeof shell === 'object' && shell.judge && typeof shell.judge === 'object'
-        ? shell.judge
-        : undefined;
-    return {
-        enabled,
-        autoApproveLow: judge?.autoApproveLow ?? true,
-        blockHigh: judge?.blockHigh ?? false,
-        model: judge?.model,
-    };
-}
 /**
  * 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` (+ `shellYolo`) view the accessors below consume. Returns `undefined` when the registry
+ * `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}).
  */
@@ -197,12 +158,7 @@ function devToolsConfigFromRegistry(registry) {
                 enabled: entry.enabled,
                 timeout: entry.timeout,
                 maxOutputBytes: entry.maxOutputBytes,
-                allowlist: entry.allowlist,
-                persistAllowlist: entry.persistAllowlist,
-                judge: entry.judge,
             };
-            if (entry.yolo !== undefined)
-                resolved.shellYolo = entry.yolo;
         }
         hasAny = true;
     }
@@ -235,4 +191,259 @@ export function getEffectiveDevToolsConfig(config, command) {
     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 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 const APPROVAL_RUNGS = ['read-only', 'write', 'auto-safe', 'full-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 = {
+    'read-only': 'Read only',
+    write: 'Write',
+    'auto-safe': 'Auto safe',
+    'full-auto': 'Full auto',
+    bypass: 'Bypass',
+};
+/**
+ * §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 const APPROVAL_RUNG_DESCRIPTIONS = {
+    'read-only': 'Gaunt Sloth may automatically read and list files in the current working folder. It asks ' +
+        'for approval for anything else, until you tell it to always allow a command.',
+    write: 'Gaunt Sloth may automatically read, edit, create and delete files in the current working ' +
+        'folder. It asks for approval for anything else, until you tell it to always allow a command.',
+    'auto-safe': 'Same as write, plus the auto-rater rates everything else and automatically approves what it ' +
+        'rates as safe; anything questionable comes to you. 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.',
+    'full-auto': 'The auto-rater steers Gaunt Sloth: it decides for itself and does not stop to ask you. This ' +
+        'is safer than bypass — the auto-rater still stops the run on a command that reads your keys ' +
+        'or passwords, weakens permissions, installs itself to run again later, or hides what it ' +
+        'does; it brings anything it cannot undo to you rather than deciding alone; and your deny ' +
+        'list still applies — but it is not safe. Gaunt Sloth will change and delete things. Use it ' +
+        'where the consequences are recoverable, and put real gates (deployment approvals, ' +
+        'two-factor, branch protection) on anything that is not.',
+    bypass: 'No gate. Gaunt Sloth runs whatever it decides to run, without asking and without rating. ' +
+        'Only the refusals configured in the deny list in your config still apply.',
+};
+/** 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 === 'auto-safe' || rung === 'full-auto';
+}
+/**
+ * §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 `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 const DEFAULT_APPROVAL_RUNG = 'auto-safe';
+/** 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 `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 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.
+ *   • `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 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 auto-safe to ' +
+                    'rate commands again.',
+            },
+        };
+    }
+    if (isRatedRung(rung)) {
+        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 ' +
+                    (rung === 'auto-safe' ? 'escalated to you.' : 'refused or escalated.'),
+            },
+        };
+    }
+    return {
+        gateShell,
+        notice: {
+            level: StatusLevel.INFO,
+            message: `Shell tool (run_shell_command) enabled with per-command approval (approvals: ${rung}).`,
+        },
+    };
+}
 //# sourceMappingURL=shell-policy.js.map

package/dist/config/shell-policy.js.map

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

package/dist/config/tool-descriptions.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @packageDocumentation
+ * EXT-58 — **rung-aware tool descriptions** (`docs/gaunt-sloth-2.0/approvals-and-rater-spec.md`
+ * §4.5) and the table of built-in tools the rater may offer as a granted alternative (§4.4).
+ *
+ * §4.5 is the *prevention* half of the approvals design. Shell commands are gated; built-in tools
+ * at or below the current rung are not, so a model that reaches for the shell to do something a
+ * granted built-in already does converts a free action into an interruption. A model chooses a
+ * tool by reading that tool's description, so the approvals posture is stated **there** — not as a
+ * global preference in the system prompt, which sits far from the decision and can drift out of
+ * step with the gate.
+ *
+ * Two properties are load-bearing and are why this module exists at all:
+ *
+ * 1. **A tool that is auto-approved gets NO suffix.** The absence of the sentence is what marks it
+ *    free. Appending "this tool is already approved" would be the opposite of the design.
+ * 2. **The suffix is derived from the rung in force AND from the set of tools the gate actually
+ *    gates.** "A description that disagrees with what the gate will actually do is worse than no
+ *    description at all" (§4.5), so {@link isGrantedAtRung} takes the gated set as a parameter and
+ *    both backends pass the SAME set they wire into the approval interrupt. The two can therefore
+ *    not drift: widening the gate ([[EXT-30]]) widens the descriptions in the same breath.
+ *
+ * **Scope boundary, per §4.3:** *"The first implementation and the measurement corpus cover the
+ * shell only. Every other tool is granted or escalated by the rung without a rating call until
+ * EXT-30 widens the gate."* Today `run_shell_command` is the only tool either backend wires into
+ * the approval interrupt, so it is the only tool that can ever require approval — every other tool
+ * is **granted**, and a granted tool gets no suffix. The rung-vs-access-class rule below
+ * (read tools granted from `read-only` up, write tools from `write` up) is implemented in full and
+ * unit-tested against an injected wider gated set, so EXT-30 inherits it rather than re-deriving
+ * it; it simply has no observable effect while the gated set is the shell alone.
+ */
+import type { ApprovalRung } from '#src/config/shell-policy.js';
+/**
+ * §4.5's table, **verbatim**. The wordings are normative copy the model reads; do not paraphrase,
+ * re-punctuate or "improve" them.
+ *
+ * - `read-only` and `write` share one sentence: at both rungs a non-granted call goes to the human,
+ *   so the user's approval is a certainty, not a possibility.
+ * - `auto-safe` softens `will` to `MAY`: the rater approves what it rates safe, so only some calls
+ *   reach the user.
+ * - `full-auto` gets its **own** wording because the consequence differs — the user is not asked
+ *   there, so promising the user's approval would be false. What can happen is a refusal by the
+ *   rater.
+ * - `bypass` appends nothing to anything: no gate, so no sentence could be true.
+ */
+export declare const RUNG_TOOL_DESCRIPTION_SUFFIXES: Readonly<Record<ApprovalRung, string | null>>;
+/**
+ * The access class of a built-in tool, in the sense §2 grants them: `read` = reading and listing
+ * files within the working folder; `write` = creating, editing, moving and deleting files within
+ * the working folder. A tool that does neither (the shell, a network fetch, an MCP call) has no
+ * class and is granted by no rung but `bypass`.
+ */
+export type BuiltInToolAccess = 'read' | 'write';
+/**
+ * Access class per built-in tool name. Covers BOTH backends' names: gsloth's own
+ * `GthFileSystemToolkit` (lean) and deepagents' filesystem tools (`ls`/`glob`/`grep`, deep) — the
+ * two sets overlap on `read_file`/`write_file`/`edit_file`, which is exactly why one flat table
+ * keyed by name serves both.
+ *
+ * Deliberately absent: `run_shell_command`, the fixed dev-command tools, `gth_web_fetch`,
+ * `gth_checklist`, `gth_status_update`, `show_a2ui_surface`, MCP/custom/A2A tools. None of them is
+ * "reading or writing files in the working folder", so none is granted by a rung's access class.
+ * (They are still *granted today* — the gate does not gate them — which {@link isGrantedAtRung}
+ * decides on the gated set, not on this table.)
+ */
+export declare const BUILT_IN_TOOL_ACCESS: Readonly<Record<string, BuiltInToolAccess>>;
+/** A built-in tool the rater may offer as an already-granted alternative (§4.4). */
+export interface GrantedToolSummary {
+    /** The registered tool name, exactly as the model sees it. */
+    name: string;
+    /** One line, authored here — locally-generated trusted text (§4.3), never a tool's own blurb. */
+    description: string;
+}
+/**
+ * §4.3/§4.4 — the one-line descriptions handed to the rater with the granted tools' names.
+ *
+ * **Authored here on purpose.** §4.3 admits this list as *"trusted, locally-generated text, not
+ * part of the fenced block"*, so it may not be assembled from tool `description` fields at large:
+ * an MCP server's tool description is attacker-influenceable text, and placing it outside the
+ * fenced block would open an injection channel straight past the rater's untrusted-input preamble.
+ * Only tools named in THIS table are ever offered, so an MCP, custom or A2A tool can never
+ * contribute text to the rater prompt.
+ *
+ * Restricted to tools that could plausibly stand in for a shell command — the file tools, content
+ * search, and the fixed dev-command tools (whose command is human-authored config, so suggesting
+ * `run_tests` over `npm test` is exactly the trade this section exists to make). `gth_checklist`,
+ * `gth_status_update` and `show_a2ui_surface` are omitted: they substitute for nothing a model
+ * would otherwise shell out for, and a suggestion list is only useful while it is short.
+ *
+ * **`gth_web_fetch` is deliberately NOT here**, though it is ungated at every rung. §4.5's
+ * justification for disclosing the posture at all is that the granted tools are "by construction,
+ * the constrained ones confined to the working folder" — a network fetch is not. Offering it would
+ * let a refused `curl`/`wget` come back as a suggestion whose §7 clause tells the model, verbatim,
+ * that the alternative "will not interrupt the user": a refused egress turned into a free one,
+ * through the rater rather than through the gate. An `attack` halts before any message reaches the
+ * model, but a merely `destructive` fetch would not. Same reasoning excludes MCP and custom tools,
+ * which additionally supply text we did not author.
+ */
+export declare const BUILT_IN_TOOL_SUMMARIES: Readonly<Record<string, string>>;
+/** The sentence §4.5 appends at this rung, or `null` when the rung appends nothing (`bypass`). */
+export declare function getRungToolDescriptionSuffix(rung: ApprovalRung): string | null;
+/**
+ * Is `toolName` auto-approved (granted, free, no prompt and no rating) at `rung`?
+ *
+ * @param toolName The registered tool name.
+ * @param rung The rung in force for the session.
+ * @param gatedTools The names the gate actually wires into the approval interrupt. **This is the
+ *   parameter that keeps the descriptions honest**: a tool the gate does not gate cannot require
+ *   approval, whatever a rung's table row says about tool classes, so it is granted. Both backends
+ *   pass the same set they hand to `interruptOn` / `humanInTheLoopMiddleware`.
+ *
+ * Order:
+ * 1. `bypass` grants everything (§2.5) — the gate is off.
+ * 2. A tool the gate does not gate is granted at every rung (§4.3's scope boundary).
+ * 3. A gated tool is granted only where the rung's own grant covers its access class: read tools
+ *    from `read-only` up (§2.1), write tools from `write` up (§2.2, and §2.3/§2.4 which grant
+ *    "everything `write` grants"). A gated tool with no access class — the shell, a network call,
+ *    an MCP tool — is granted at no rung but `bypass`.
+ */
+export declare function isGrantedAtRung(toolName: string, rung: ApprovalRung, gatedTools: readonly string[]): boolean;
+/**
+ * Remove a previously-appended §4.5 suffix (any rung's), returning the tool's own description.
+ *
+ * Makes {@link applyRungAwareToolDescriptions} idempotent and re-appliable at a different rung —
+ * which matters because a resolver may hand back the SAME tool instance on a re-init (an MCP
+ * client caches its tool objects), and a second pass would otherwise stack sentences.
+ */
+export declare function stripRungToolDescriptionSuffix(description: string): string;
+/** The minimal shape {@link applyRungAwareToolDescriptions} needs; keeps this module langchain-free. */
+export interface DescribableTool {
+    name?: string;
+    description?: string;
+}
+/**
+ * §4.5 — at tool-registration time, append the rung's sentence to the description of every tool
+ * that is NOT auto-approved at that rung, and leave every granted tool's description untouched.
+ *
+ * Mutates in place (and returns the same array): the tools are about to be handed to
+ * `createAgent`/`createDeepAgent`, and the array is freshly resolved per init. Idempotent — any
+ * previously-appended suffix is stripped first, so re-registration at a different rung replaces
+ * the sentence rather than stacking one.
+ *
+ * A tool with no name is left alone (provider-native "magic object" tools carry no name and cannot
+ * be classified); a tool with an empty description gets the suffix as its whole description rather
+ * than a leading space.
+ */
+export declare function applyRungAwareToolDescriptions<T extends DescribableTool>(tools: T[], options: {
+    rung: ApprovalRung;
+    gatedTools: readonly string[];
+}): T[];
+/**
+ * §4.3/§4.4 — the names and one-line descriptions of the built-in tools already granted at `rung`,
+ * for the rater prompt.
+ *
+ * Filtered three ways, each of which matters:
+ * - to tools **actually registered** in this session (a suggestion naming a tool the model does not
+ *   have is worse than no suggestion);
+ * - to tools in {@link BUILT_IN_TOOL_SUMMARIES}, so only locally-authored text ever reaches the
+ *   rater prompt (never an MCP/custom tool's own description);
+ * - to tools **granted at the rung** — suggesting a tool that would itself need approval defeats
+ *   the point.
+ *
+ * Order follows the registration order so the prompt is stable across runs.
+ */
+export declare function describeGrantedBuiltInTools(registeredToolNames: readonly string[], rung: ApprovalRung, gatedTools: readonly string[]): GrantedToolSummary[];