@gaunt-sloth/core 2.0.0-alpha.23 → 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,47 @@
 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`,
+ * `.gsloth.system.md`, `.gsloth.chat.md`, `.gsloth.code.md`, `.gsloth.exec.md`,
+ * `.gsloth.review.md`) and can be retargeted / disabled / composed via
+ * {@link GthConfig.prompts}.
+ */
+export type PromptSegmentName = 'backstory' | 'guidelines' | 'system' | 'chat' | 'code' | 'exec' | 'review';
+/**
+ * GS2-43 — configuration for one prompt segment.
+ */
+export interface PromptSegmentConfig {
+    /**
+     * File to read for this segment. Resolved like every prompt file: the config dir
+     * (`.gsloth/.gsloth-settings[/<profile>]/`) first, then relative to the project root.
+     */
+    path?: string;
+    /**
+     * `false` drops the segment entirely — even its bundled default. Default `true`.
+     */
+    enabled?: boolean;
+    /**
+     * `'replace'` (default): the {@link path} file replaces the built-in segment content.
+     * `'append'`: the file content is appended after the built-in content.
+     */
+    mode?: 'replace' | 'append';
+}
+/**
+ * GS2-43 — one segment's setting: a `string` path (shorthand for `{ path }`) or a
+ * {@link PromptSegmentConfig} object.
+ */
+export type PromptSegmentSetting = string | PromptSegmentConfig;
+/**
+ * GS2-43 — the unified `prompts` config object. Replaces the removed flat
+ * `projectGuidelines` / `projectReviewInstructions` keys and makes all seven prompt
+ * segments retargetable through config. Sibling keys are trivially addable (GS2-44 will
+ * add `agents` for AGENTS.md auto-discovery), so keep segment names and future siblings
+ * in this one flat namespace.
+ */
+export type PromptsConfig = Partial<Record<PromptSegmentName, PromptSegmentSetting>>;
 /**
  * Shared per-command tooling configuration (the knobs every actionable command carries).
  * Reused across the per-command types in {@link GthConfig.commands} and by
@@ -19,11 +59,38 @@ import type { BuiltInToolsSetting } from '#src/config/shell-policy.js';
 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[];
     binaryFormats?: false | BinaryFormatConfig[];
 }
+/**
+ * GS2-33 — one profile-backed subagent declaration. When the parent agent spawns this subagent
+ * (the deepagents `task` tool), the CHILD resolves the named config {@link profile} through the
+ * GS2-1 cascade, so it runs under THAT profile's model + tools + prompt (e.g. a cheap flash-lite
+ * profile for recall/search subagents while the parent runs on a strong model).
+ *
+ * The `profile` is a named profile block created by `gth config profile create <name>` — a
+ * `.gsloth/.gsloth-settings/<name>/` config dir, the same discovery convention `--profile` /
+ * `--identity-profile` resolve.
+ */
+export interface SubagentProfileSpec {
+    /** Identifier the model selects this subagent by (the task-tool subagent name). */
+    name: string;
+    /** Description shown to the model when it chooses a subagent. Defaults to a profile note. */
+    description?: string;
+    /**
+     * Named config profile whose model + tools + prompt the CHILD resolves. Threaded through the
+     * subagent-spawn config resolution as {@link CommandLineConfigOverrides.identityProfile}.
+     */
+    profile: string;
+}
 /**
  * This is a processed Gaunt Sloth config ready to be passed down into components.
  *
@@ -80,11 +147,12 @@ export interface GthConfig {
      */
     requirementSource: string;
     /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
+     * GS2-43 — the unified prompt-segment config (see {@link PromptsConfig}). Each of the seven
+     * segments (`backstory | guidelines | system | chat | code | exec | review`) accepts a string
+     * path (e.g. `"guidelines": "AGENTS.md"`) or an object (`{ path?, enabled?, mode? }`). When a
+     * segment is omitted its default-named file / bundled default applies unchanged.
      */
-    projectGuidelines: string;
+    prompts?: PromptsConfig;
     /**
      * Separate identity profile.
      * May include separate identity, guidelines and command protocol,
@@ -108,7 +176,6 @@ export interface GthConfig {
         locale?: string;
         timezone?: string;
     };
-    projectReviewInstructions: string;
     /**
      * If true, only use user-provided system prompts. Do not fall back to the
      * bundled `.gsloth.*.md` prompt files shipped with the installation.
@@ -126,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
@@ -201,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)
@@ -290,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;
@@ -374,6 +470,27 @@ export interface GthConfig {
     output?: {
         header?: boolean;
     };
+    /**
+     * EXT-36 — the tool-loop guard: a repeated-identical-`(tool, args)` / no-progress detector that
+     * runs as a lean-backend `beforeModel` middleware, the orthogonal sibling of GS2-36's
+     * consecutive-tool-ERROR budget. It catches the case GS2-36 leaves open — a model re-issuing the
+     * SAME call verbatim, whether it keeps erroring or keeps "succeeding" with the same result.
+     *
+     * - `false` disables it entirely.
+     * - `true` / omitted → WARN on, HALT off, default threshold ({@link DEFAULT_TOOL_LOOP_THRESHOLD}).
+     * - object → per-field: `warn` (default ON) injects a control-flow-free nudge at the threshold;
+     *   `halt` (default OFF, opt-in) ends the run cleanly (`jumpTo:'end'`, never a throw) at the
+     *   threshold; `threshold` is the number of consecutive identical calls that trip it.
+     *
+     * WARN is provably harmless (no routing effect, one nudge per signature per streak). The WARN-on
+     * default is applied at the read site (not in {@link DEFAULT_CONFIG}) to avoid churning the
+     * effective-config snapshot.
+     */
+    toolLoopGuard?: boolean | {
+        warn?: boolean;
+        halt?: boolean;
+        threshold?: number;
+    };
     /**
      * BATCH-19 — custom `gth eval` reporters, keyed by the NAME they are selected under
      * (`gth eval … --reporter <name>`). Each value is a MODULE PATH, resolved relative to the project
@@ -384,6 +501,15 @@ export interface GthConfig {
      * it is the user's own config, which already executes arbitrary JS.
      */
     reporters?: Record<string, string>;
+    /**
+     * GS2-33 — profile-backed subagents. Each entry names a subagent and the {@link
+     * SubagentProfileSpec.profile named config profile} the CHILD resolves when the parent spawns it,
+     * so a subagent can run under a different model/tools/prompt than the parent (a cheap profile for
+     * recall/search while the parent runs on a strong model). Honored by the deep (deepagents) backend
+     * — its `task` tool gains one selectable subagent per entry; the lean backend's own subagent
+     * primitive lands in GS2-25.
+     */
+    subagents?: SubagentProfileSpec[];
 }
 /**
  * `gth pr` command configuration.
@@ -417,6 +543,13 @@ export type ConsoleLevelInput = StatusLevel | keyof typeof StatusLevel | Lowerca
 export interface RawGthConfig extends Omit<GthConfig, 'llm' | 'consoleLevel'> {
     llm: LLMConfig;
     consoleLevel?: ConsoleLevelInput;
+    /**
+     * GS2-41 — profile composition. When set on a NAMED profile config, this profile inherits from
+     * the named base profile: the base resolves first, then this profile's fields merge on top
+     * (last-wins). Raw-config-only — resolved and consumed at load time (`resolveConfigExtends`), so
+     * it never appears on the resolved {@link GthConfig}.
+     */
+    extends?: string;
 }
 export type BinaryFormatType = 'image' | 'file' | 'audio' | 'video' | 'binary';
 export interface BinaryFormatConfig {

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAiiBA,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,11 +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,16 @@
  * - `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';
 //# sourceMappingURL=config.js.map

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"}
+{"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,11 +1,13 @@
-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 { DebugCapture } from '#src/core/debugCapture.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';
 import { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
 import { IterableReadableStream } from '@langchain/core/utils/stream';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { type RefusalInfo } from '#src/core/refusal.js';
 /**
  * TUI-C29 — return a chunk fit for `concat`-aggregation with OpenRouter's raw response stripped.
  *
@@ -51,6 +53,22 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * server / non-TUI callers simply never set it, so those contracts are unchanged.
      */
     debugCapture: DebugCapture | undefined;
+    /**
+     * GS2-56 — the ALWAYS-ON snapshot of the most recent model request (extras + the as-sent,
+     * post-summarization messages), populated UNCONDITIONALLY at each backend's `wrapModelCall` feed
+     * site — NOT gated on {@link debugCapture} being attached. This is what lets `/debug-dump` render
+     * the full model input even when the TUI `/debug` panel was never opened and on non-TUI surfaces
+     * (the sink only ever fed the live `/debug` panel). O(1): a single overwritten reference retaining
+     * only the LAST call — no accumulation, so the "pay nothing until you need it" intent is kept.
+     */
+    lastModelRequest: LastModelRequest | undefined;
+    /**
+     * GS2-56 — stash the last model request (the as-sent messages + {@link DebugRequestExtras}).
+     * Called unconditionally from each backend's capture middleware, independent of the debug sink,
+     * so the snapshot is available to `/debug-dump` on every surface. Overwrites (retains only the
+     * most recent call). Callers already guard the invocation; kept trivial so it can never throw.
+     */
+    protected setLastModelRequest(messages: BaseMessage[], extras?: DebugRequestExtras): void;
     /**
      * GS2-16 — per-run analytics tally (token usage + invoked tool names) folded from the messages
      * flowing through {@link invoke} / the streaming paths. Reset at each turn boundary via
@@ -58,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
@@ -68,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
@@ -90,6 +165,14 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * part that differs between the lean and deep agents.
      */
     abstract init(command: GthCommand | undefined, configIn: GthConfig, checkpointer?: BaseCheckpointSaver | undefined): Promise<void>;
+    /**
+     * EXT-37 — surface a detected content-policy refusal: emit the clear, user-facing explanation at
+     * WARNING level (an empty-content refusal streams nothing, so without this the console shows
+     * nothing) and return the same message so it becomes the turn's terminal answer. Shared by the
+     * non-streaming {@link invoke} and streaming {@link streamFromInput} paths so both render a
+     * refusal identically. A refusal is a *successful* (if declined) response — never a retry.
+     */
+    protected surfaceRefusal(info: RefusalInfo): string;
     /**
      * Invoke LLM with a message and runnable config.
      * For streaming use {@link #stream} method, streaming is preferred if model API supports it.