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

package/dist/config/tool-descriptions.js

@@ -0,0 +1,229 @@
+/**
+ * §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 const RUNG_TOOL_DESCRIPTION_SUFFIXES = {
+    'read-only': "Calling this tool will require the user's approval. Only use it when the result cannot be " +
+        'achieved with the other provided tools.',
+    write: "Calling this tool will require the user's approval. Only use it when the result cannot be " +
+        'achieved with the other provided tools.',
+    'auto-safe': "Calling this tool MAY require the user's approval if it does not look safe. Only use it when " +
+        'it is impossible to achieve the result with the other provided tools.',
+    'full-auto': 'Calling this tool MAY be refused by the auto-rater if it does not look safe. Only use it ' +
+        'when it is impossible to achieve the result with the other provided tools.',
+    bypass: null,
+};
+/** The distinct suffix strings, for {@link stripRungToolDescriptionSuffix}'s idempotency check. */
+const ALL_SUFFIXES = Array.from(new Set(Object.values(RUNG_TOOL_DESCRIPTION_SUFFIXES).filter((s) => s !== null)));
+/**
+ * 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 const BUILT_IN_TOOL_ACCESS = {
+    // gsloth GthFileSystemToolkit (lean backend)
+    read_file: 'read',
+    read_multiple_files: 'read',
+    gth_read_binary: 'read',
+    list_directory: 'read',
+    list_directory_with_sizes: 'read',
+    directory_tree: 'read',
+    search_files: 'read',
+    get_file_info: 'read',
+    list_allowed_directories: 'read',
+    write_file: 'write',
+    edit_file: 'write',
+    create_directory: 'write',
+    move_file: 'write',
+    delete_file: 'write',
+    delete_directory: 'write',
+    // deepagents filesystem tools (deep backend) not already named above
+    ls: 'read',
+    glob: 'read',
+    grep: 'read',
+    // gsloth built-ins that read file contents in the working folder
+    gth_grep: 'read',
+};
+/**
+ * §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 const BUILT_IN_TOOL_SUMMARIES = {
+    read_file: 'Read one file in the working folder.',
+    read_multiple_files: 'Read several files in the working folder in one call.',
+    gth_read_binary: 'Read an image or other binary file in the working folder.',
+    list_directory: 'List the entries of a directory in the working folder.',
+    list_directory_with_sizes: 'List a directory in the working folder with entry sizes.',
+    directory_tree: 'Show a recursive tree of a directory in the working folder.',
+    search_files: 'Find files in the working folder by name pattern.',
+    get_file_info: 'Show size, timestamps and type of a file in the working folder.',
+    list_allowed_directories: 'List the directories the file tools are allowed to touch.',
+    write_file: 'Create or overwrite a file in the working folder.',
+    edit_file: 'Apply a targeted edit to a file in the working folder.',
+    create_directory: 'Create a directory in the working folder.',
+    move_file: 'Move or rename a file in the working folder.',
+    delete_file: 'Delete a file in the working folder.',
+    delete_directory: 'Delete a directory in the working folder.',
+    ls: 'List the entries of a directory in the working folder.',
+    glob: 'Find files in the working folder by glob pattern.',
+    grep: 'Search file contents in the working folder by regular expression.',
+    gth_grep: 'Search file contents in the working folder by regular expression.',
+    run_tests: "Run the project's configured test command.",
+    run_single_test: "Run one test file with the project's configured test command.",
+    run_lint: "Run the project's configured lint command.",
+    run_build: "Run the project's configured build command.",
+};
+/** The sentence §4.5 appends at this rung, or `null` when the rung appends nothing (`bypass`). */
+export function getRungToolDescriptionSuffix(rung) {
+    return RUNG_TOOL_DESCRIPTION_SUFFIXES[rung] ?? 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 function isGrantedAtRung(toolName, rung, gatedTools) {
+    if (rung === 'bypass')
+        return true;
+    if (!gatedTools.includes(toolName))
+        return true;
+    const access = BUILT_IN_TOOL_ACCESS[toolName];
+    if (access === 'read')
+        return true;
+    if (access === 'write')
+        return rung !== 'read-only';
+    return false;
+}
+/**
+ * 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 function stripRungToolDescriptionSuffix(description) {
+    let result = description;
+    // Loop: a description that was appended to twice by an older build still ends up clean.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const suffix of ALL_SUFFIXES) {
+            if (result.endsWith(suffix)) {
+                result = result.slice(0, -suffix.length).replace(/\s+$/, '');
+                changed = true;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * §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 function applyRungAwareToolDescriptions(tools, options) {
+    const suffix = getRungToolDescriptionSuffix(options.rung);
+    for (const tool of tools) {
+        if (!tool || typeof tool.name !== 'string' || tool.name.length === 0)
+            continue;
+        if (typeof tool.description !== 'string')
+            continue;
+        const base = stripRungToolDescriptionSuffix(tool.description);
+        // A granted tool carries NO sentence — its absence is what marks it free (§4.5).
+        if (suffix === null || isGrantedAtRung(tool.name, options.rung, options.gatedTools)) {
+            tool.description = base;
+            continue;
+        }
+        tool.description = base.length > 0 ? `${base} ${suffix}` : suffix;
+    }
+    return tools;
+}
+/**
+ * §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 function describeGrantedBuiltInTools(registeredToolNames, rung, gatedTools) {
+    const seen = new Set();
+    const summaries = [];
+    for (const name of registeredToolNames) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const description = BUILT_IN_TOOL_SUMMARIES[name];
+        if (!description)
+            continue;
+        if (!isGrantedAtRung(name, rung, gatedTools))
+            continue;
+        summaries.push({ name, description });
+    }
+    return summaries;
+}
+//# sourceMappingURL=tool-descriptions.js.map

package/dist/config/tool-descriptions.js.map

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

package/dist/config/types.d.ts

@@ -7,7 +7,7 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
 import type { StatusLevel } from '#src/core/types.js';
-import type { BuiltInToolsSetting } from '#src/config/shell-policy.js';
+import type { ApprovalsConfig, BuiltInToolsSetting } from '#src/config/shell-policy.js';
 /**
  * GS2-43 — the seven configurable prompt segments. Each maps to a prompt file with a
  * well-known default name (`.gsloth.backstory.md`, `.gsloth.guidelines.md`,
@@ -59,6 +59,12 @@ export type PromptsConfig = Partial<Record<PromptSegmentName, PromptSegmentSetti
 export interface CommandToolingConfig {
     filesystem?: string[] | 'all' | 'read' | 'none';
     builtInTools?: BuiltInToolsSetting;
+    /**
+     * §9.1 — per-command approvals posture. It overrides only the fields it NAMES: `mode`,
+     * `rater`, `raterTimeoutMs` and `allow` replace the root's, while `deny` and `escalate`
+     * concatenate with it. See {@link GthConfig.approvals}.
+     */
+    approvals?: ApprovalsConfig;
     customTools?: CustomToolsConfig | false;
     /** See {@link GthConfig.allowedTools}. */
     allowedTools?: string[];
@@ -187,6 +193,22 @@ export interface GthConfig {
      * a per-command value replaces the top-level one.
      */
     builtInTools?: BuiltInToolsSetting;
+    /**
+     * CFG-27 — the tool-approval **ladder**: one of the five rungs (`read-only` · `write` ·
+     * `auto-safe` · `full-auto` · `bypass`), written either as the bare rung name or as an object
+     * carrying the rater's identity profile and the declared allow/deny lists. Each rung fully
+     * determines behaviour — there are no severity thresholds, no strictness levels and no
+     * independent rater switch.
+     *
+     * Settable at the root or per command (`commands.<command>.approvals`). §9.1 — a per-command
+     * value overrides only the fields it NAMES. `mode`, `rater` and `raterTimeoutMs` replace the
+     * root's; `deny` and `escalate` CONCATENATE across every scope, so a per-command rung can never
+     * discard the root's prohibitions; `allow` is REPLACED when the command states its own and
+     * inherited when it does not, so a scope may narrow what runs unprompted and may never widen
+     * what is prohibited (§3.1: a too-broad allow entry runs unrated, a missed deny entry does not).
+     * Absent = `auto-safe`, resolved by `resolveApprovals`.
+     */
+    approvals?: ApprovalsConfig;
     tools?: StructuredToolInterface[] | BaseToolkit[] | ServerTool[];
     /**
      * Restrict the agent to this allow-list of tool names, applied after every tool source
@@ -262,6 +284,13 @@ export interface GthConfig {
      * Use colour in output
      */
     useColour: boolean;
+    /**
+     * Enable terminal mouse reporting in the Ink TUI, making its affordances clickable.
+     * On by default in an interactive terminal. While it is on the terminal's own text selection
+     * needs a modifier (Shift, or Option in some macOS terminals) — set this to `false`, or set
+     * `GTH_NO_MOUSE`, to get unmodified selection back.
+     */
+    useMouse: boolean;
     /**
      * Stream session log instead of writing it when inference streaming is complete.
      * (only works when {@link streamOutput} is true)
@@ -351,6 +380,12 @@ export interface GthConfig {
         api?: {
             filesystem?: string[] | 'all' | 'read' | 'none';
             builtInTools?: BuiltInToolsSetting;
+            /**
+             * §9.1 — per-command approvals posture. It overrides only the fields it NAMES: `mode`,
+             * `rater`, `raterTimeoutMs` and `allow` replace the root's, while `deny` and `escalate`
+             * concatenate with it. See {@link GthConfig.approvals}.
+             */
+            approvals?: ApprovalsConfig;
             port?: number;
             cors?: {
                 allowOrigin?: string;

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAqoBA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAwqBA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}

package/dist/config.d.ts

@@ -15,12 +15,15 @@
  * - `config/defaults.ts` — {@link DEFAULT_CONFIG}.
  * - `config/loader.ts` — discovery + the layered load/merge pipeline.
  * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator.
+ * - `config/tool-descriptions.ts` — EXT-58: the rung-aware tool-description suffixes (§4.5) and
+ *   the granted-built-in table the rater's alternative suggestion draws on (§4.4).
  *
  * Every name that was previously exported from `config.ts` is re-exported here, so the
  * public import path `@gaunt-sloth/core/config.js` (and `#src/config.js`) is unchanged.
  */
 export * from '#src/config/types.js';
 export * from '#src/config/shell-policy.js';
+export * from '#src/config/tool-descriptions.js';
 export * from '#src/config/defaults.js';
 export * from '#src/config/loader.js';
 export * from '#src/config/profiles.js';

package/dist/config.js

@@ -15,12 +15,15 @@
  * - `config/defaults.ts` — {@link DEFAULT_CONFIG}.
  * - `config/loader.ts` — discovery + the layered load/merge pipeline.
  * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator.
+ * - `config/tool-descriptions.ts` — EXT-58: the rung-aware tool-description suffixes (§4.5) and
+ *   the granted-built-in table the rater's alternative suggestion draws on (§4.4).
  *
  * Every name that was previously exported from `config.ts` is re-exported here, so the
  * public import path `@gaunt-sloth/core/config.js` (and `#src/config.js`) is unchanged.
  */
 export * from '#src/config/types.js';
 export * from '#src/config/shell-policy.js';
+export * from '#src/config/tool-descriptions.js';
 export * from '#src/config/defaults.js';
 export * from '#src/config/loader.js';
 export * from '#src/config/profiles.js';

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC"}

package/dist/core/GthAbstractAgent.d.ts

@@ -1,5 +1,6 @@
-import { GthConfig, ServerTool } from '#src/config.js';
+import { GthConfig, ServerTool, type ApprovalRung, type DescribableTool } from '#src/config.js';
 import { AgentResolvers, AgentStreamEvent, GthAgentInterface, GthCommand, GthCompiledGraph, GthRunStats, Message, PendingToolInterrupt, StatusUpdateCallback } from '#src/core/types.js';
+import type { DeclaredToolAnnotations } from '#src/core/approvals/annotations.js';
 import type { DebugCapture, DebugRequestExtras, LastModelRequest } from '#src/core/debugCapture.js';
 import { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
 import { RunnableConfig } from '@langchain/core/runnables';
@@ -75,6 +76,22 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     private runStatsAcc;
+    /**
+     * EXT-58 — the names of the tools registered with the graph at the last {@link init}, recorded by
+     * {@link registerApprovalsAwareTools}. Read by `GthAgentRunner` to build the rater's
+     * granted-built-in list (§4.4), so a suggestion can only ever name a tool the model actually has.
+     */
+    private registeredToolNames;
+    /**
+     * EXT-70 §4.7.1 — what the connected MCP servers DECLARED about their own tools, captured from
+     * the same registration hook as {@link registeredToolNames} and keyed by the registered tool
+     * name. Read by `GthAgentRunner` as the `mcp` half of a `DeclaredToolAnnotationLookup`.
+     *
+     * It is a record of claims, never of decisions: no trust is applied here (that is
+     * `createEffectiveToolAnnotationSource`'s only job), and an absent tool yields the fail-closed
+     * defaults rather than "declared nothing".
+     */
+    private declaredMcpToolAnnotations;
     constructor(statusUpdate: StatusUpdateCallback, resolvers?: AgentResolvers);
     /**
      * GS2-63 — emit one line of the technical run-header preamble (the Workdir/Model/Tools/Middleware
@@ -85,6 +102,47 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * output, warnings and errors keep using {@link statusUpdate} directly.
      */
     protected headerStatus(message: string): void;
+    /**
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their final tool
+     * array, just before handing it to the graph builder. It does two things:
+     *
+     * 1. Appends the rung's approval sentence to every tool that is **not** auto-approved at that
+     *    rung, and leaves every granted tool's description untouched (the absence of the sentence is
+     *    what marks a tool free). See {@link applyRungAwareToolDescriptions}.
+     * 2. Records the registered tool names for {@link getRegisteredToolNames}, which feeds the
+     *    rater's granted-alternative list (§4.4).
+     * 3. EXT-70 §4.7.1 — records what the MCP servers declared about their own tools, for
+     *    {@link getDeclaredMcpToolAnnotations}. This is the ONE place a `tools/list` annotation
+     *    enters the approvals stack, and it enters as a claim: nothing here decides whether it is
+     *    believed.
+     *
+     * `gatedTools` MUST be the same set the caller wires into the approval interrupt
+     * (`humanInTheLoopMiddleware`'s `interruptOn` on lean, deepagents' `interruptOn` on deep). That
+     * shared parameter is what makes it impossible for a description to promise an approval the gate
+     * will not ask for — §4.5's "a description that disagrees with what the gate will actually do is
+     * worse than no description at all".
+     *
+     * `additionalToolNames` covers tools the graph builder registers itself and that therefore never
+     * appear in `tools` — deepagents' own filesystem tools on the deep backend. Their descriptions
+     * are deepagents', not ours, so they cannot be suffixed here; they are recorded only so the
+     * rater's suggestion list reflects what the deep model actually has.
+     */
+    protected registerApprovalsAwareTools<T extends DescribableTool>(tools: T[], options: {
+        rung: ApprovalRung;
+        gatedTools: readonly string[];
+        additionalToolNames?: readonly string[];
+    }): T[];
+    /**
+     * EXT-58 — the tool names registered with the graph at the last {@link init} (empty before it).
+     * The runner intersects these with the built-in summaries table to build the rater's
+     * granted-alternative list, so the rater can never name a tool this session does not have.
+     */
+    getRegisteredToolNames(): string[];
+    /**
+     * EXT-70 §4.7.1 — what the MCP servers declared for their tools at the last {@link init}, keyed
+     * by registered tool name (empty before it, and on a session with no MCP servers).
+     */
+    getDeclaredMcpToolAnnotations(): ReadonlyMap<string, DeclaredToolAnnotations>;
     /**
      * GS2-16 — clear the per-run analytics tally so the next turn starts from zero. The runner
      * calls this at each turn boundary because it (and this agent) are reused across turns in an

package/dist/core/GthAbstractAgent.js

@@ -1,5 +1,7 @@
+import { applyRungAwareToolDescriptions, } from '#src/config.js';
 import { StatusLevel, } from '#src/core/types.js';
 import { accumulateMessage, createRunStatsAccumulator, finalizeRunStats, } from '#src/core/runStats.js';
+import { collectDeclaredMcpToolAnnotations } from '#src/core/approvals/toolAnnotationSources.js';
 import { createPlainToolIndication } from '#src/core/plainToolIndication.js';
 import { debugLog, debugLogError, debugLogObject } from '#src/utils/debugUtils.js';
 import { ProgressIndicator } from '#src/utils/ProgressIndicator.js';
@@ -205,6 +207,22 @@ export class GthAbstractAgent {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     runStatsAcc = createRunStatsAccumulator();
+    /**
+     * EXT-58 — the names of the tools registered with the graph at the last {@link init}, recorded by
+     * {@link registerApprovalsAwareTools}. Read by `GthAgentRunner` to build the rater's
+     * granted-built-in list (§4.4), so a suggestion can only ever name a tool the model actually has.
+     */
+    registeredToolNames = [];
+    /**
+     * EXT-70 §4.7.1 — what the connected MCP servers DECLARED about their own tools, captured from
+     * the same registration hook as {@link registeredToolNames} and keyed by the registered tool
+     * name. Read by `GthAgentRunner` as the `mcp` half of a `DeclaredToolAnnotationLookup`.
+     *
+     * It is a record of claims, never of decisions: no trust is applied here (that is
+     * `createEffectiveToolAnnotationSource`'s only job), and an absent tool yields the fail-closed
+     * defaults rather than "declared nothing".
+     */
+    declaredMcpToolAnnotations = new Map();
     constructor(statusUpdate, resolvers) {
         this.statusUpdate = (level, message) => {
             statusUpdate(level, message);
@@ -224,6 +242,60 @@ export class GthAbstractAgent {
             return;
         this.statusUpdate(StatusLevel.INFO, message);
     }
+    /**
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their final tool
+     * array, just before handing it to the graph builder. It does two things:
+     *
+     * 1. Appends the rung's approval sentence to every tool that is **not** auto-approved at that
+     *    rung, and leaves every granted tool's description untouched (the absence of the sentence is
+     *    what marks a tool free). See {@link applyRungAwareToolDescriptions}.
+     * 2. Records the registered tool names for {@link getRegisteredToolNames}, which feeds the
+     *    rater's granted-alternative list (§4.4).
+     * 3. EXT-70 §4.7.1 — records what the MCP servers declared about their own tools, for
+     *    {@link getDeclaredMcpToolAnnotations}. This is the ONE place a `tools/list` annotation
+     *    enters the approvals stack, and it enters as a claim: nothing here decides whether it is
+     *    believed.
+     *
+     * `gatedTools` MUST be the same set the caller wires into the approval interrupt
+     * (`humanInTheLoopMiddleware`'s `interruptOn` on lean, deepagents' `interruptOn` on deep). That
+     * shared parameter is what makes it impossible for a description to promise an approval the gate
+     * will not ask for — §4.5's "a description that disagrees with what the gate will actually do is
+     * worse than no description at all".
+     *
+     * `additionalToolNames` covers tools the graph builder registers itself and that therefore never
+     * appear in `tools` — deepagents' own filesystem tools on the deep backend. Their descriptions
+     * are deepagents', not ours, so they cannot be suffixed here; they are recorded only so the
+     * rater's suggestion list reflects what the deep model actually has.
+     */
+    registerApprovalsAwareTools(tools, options) {
+        applyRungAwareToolDescriptions(tools, {
+            rung: options.rung,
+            gatedTools: options.gatedTools,
+        });
+        const names = tools
+            .map((tool) => tool?.name)
+            .filter((name) => typeof name === 'string' && name.length > 0);
+        this.registeredToolNames = [...names, ...(options.additionalToolNames ?? [])];
+        // `additionalToolNames` are deliberately NOT consulted: they are names the graph builder
+        // registers itself, with no tool object and therefore no declaration to read.
+        this.declaredMcpToolAnnotations = collectDeclaredMcpToolAnnotations(tools);
+        return tools;
+    }
+    /**
+     * EXT-58 — the tool names registered with the graph at the last {@link init} (empty before it).
+     * The runner intersects these with the built-in summaries table to build the rater's
+     * granted-alternative list, so the rater can never name a tool this session does not have.
+     */
+    getRegisteredToolNames() {
+        return [...this.registeredToolNames];
+    }
+    /**
+     * EXT-70 §4.7.1 — what the MCP servers declared for their tools at the last {@link init}, keyed
+     * by registered tool name (empty before it, and on a session with no MCP servers).
+     */
+    getDeclaredMcpToolAnnotations() {
+        return this.declaredMcpToolAnnotations;
+    }
     /**
      * GS2-16 — clear the per-run analytics tally so the next turn starts from zero. The runner
      * calls this at each turn boundary because it (and this agent) are reused across turns in an