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

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

@@ -14,33 +14,49 @@
  *
  * 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
+ * 2. **The suffix is derived from the rung in force AND from the set of tools that rung 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.
+ *    description at all" (§4.5), so {@link isGrantedAtRung} takes the LIVE gated set as a parameter
+ *    and both backends pass the SAME `resolveGatedToolNames` result. The two can therefore not
+ *    drift: widening what a rung gates ([[EXT-30]]) widens the descriptions in the same breath.
+ *    That set is narrower than the rung-independent one wired into the interrupt
+ *    (`resolveInterruptToolNames`), because a call the live rung does not gate is approved on
+ *    arrival and so is genuinely free.
+ *
+ * **Scope, per §4.3.** The *rater* covers the shell only: every other gated tool goes to the human
+ * without a rating call until [[EXT-30]] widens the rater. The *gate* is wider than the rater. At
+ * the two deterministic rungs (`manual`, `write`) both backends gate every bound tool the rung's
+ * access class does not auto-grant — the write built-ins, the shell, MCP tools (whatever their
+ * `readOnlyHint` says) and custom tools — so at those rungs a non-granted call always reaches the
+ * human. At `assisted`, `auto` and `bypass` the gated set is the shell alone.
+ *
+ * `config/shell-policy.ts`'s `isToolGatedAtRung` is the single rule for all of that, and both the
+ * live gated set and this module's grant are projections of it, so what a rung gates and the grant
+ * reported here cannot disagree.
  */
 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,
+ * - `manual` 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
+ * - `assisted` 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.
+ * - `auto` has its own sentence, and the difference it states is real: [[EXT-29]]'s negotiation
+ *   hands a call the rater will not clear back to the **model**, with the reason, so the first
+ *   consequence of an unsafe-looking call there is a refusal it can answer rather than a person
+ *   being asked — what changes is who answers first, and that is the one thing a model choosing a
+ *   tool can act on. A shared wording would hide it in the model's own tool-selection input.
+ *
+ *   Its `MAY` therefore sits **outside** the contrast the three bullets above draw: it qualifies
+ *   *"be refused by the auto-rater"*, not *"require the user's approval"*, so this sentence says
+ *   nothing either way about whether a person can be asked. That silence is deliberate — the
+ *   string is §4.5's row verbatim — and its cost is recorded here rather than left to be
+ *   discovered: `catastrophic` escalates to a human on the FIRST hit with no rounds at all, so a
+ *   person *can* be reached at `auto` and this input does not say so. Silent is not false, which
+ *   is why the wording stands and why the premise quoted above still holds; a wording claiming the
+ *   user is never asked would be false.
  * - `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>>;
@@ -57,11 +73,15 @@ export type BuiltInToolAccess = 'read' | 'write';
  * 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.)
+ * Deliberately absent: `run_shell_command`, deepagents' `execute`, 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, and at `manual`/`write` every one of them escalates to the human.
+ *
+ * **An MCP tool's own `readOnlyHint` earns it nothing here.** A server's self-declared annotation is
+ * least earned exactly where the ladder is strictest, so it must not skip the prompt at those two
+ * rungs; membership of this table is the only thing that does. Adding a name here grants it at a
+ * rung, so add one only for a tool that genuinely reads or writes files in the working folder.
  */
 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). */
@@ -99,23 +119,49 @@ export interface GrantedToolSummary {
 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;
+/**
+ * §2 — does `rung`'s own grant cover this tool's **access class**, i.e. is the tool free *on its
+ * class alone*, before anything is asked about whether the gate gates it?
+ *
+ * - `read` — granted at every rung (§2.1).
+ * - `write` — granted from `write` up (§2.2, and §2.3/§2.4 which grant "everything `write` grants"),
+ *   so it escalates at `manual`.
+ * - **no class at all** — the shell, deepagents' `execute`, a network call, an MCP tool, a custom or
+ *   agent-authored tool: granted by no rung. There is no implicit exemption; a tool is free here
+ *   only by appearing in {@link BUILT_IN_TOOL_ACCESS}.
+ *
+ * **This is the one implementation of that rule.** {@link isGrantedAtRung} decides a grant with it,
+ * and `config/shell-policy.ts`'s `isToolGatedAtRung` decides gated-set membership with it — which
+ * is in turn what the backends' interrupt set and `GthAgentRunner`'s own live-rung check are built
+ * from. So the gate cannot escalate a call the descriptions and the rater's granted list call free
+ * — the drift §4.5 names as worse than having no description at all. Two derivations of one rule is
+ * exactly what this function exists to prevent; do not inline it back into either caller.
+ *
+ * `bypass` is not special-cased: it grants everything for a reason unrelated to access class (the
+ * gate is off), which {@link isGrantedAtRung} states where that belongs.
+ */
+export declare function isAccessClassGrantedAtRung(toolName: string, rung: ApprovalRung): boolean;
 /**
  * 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`.
+ * @param gatedTools The LIVE gated set — what `rung` actually gates, i.e.
+ *   `resolveGatedToolNames` for the rung in force. **This is the parameter that keeps the
+ *   descriptions honest**: a tool the rung does not gate cannot require approval, whatever a rung's
+ *   table row says about tool classes, so it is granted. It is deliberately NOT the wider,
+ *   rung-independent set the backends wire into `interruptOn` (`resolveInterruptToolNames`): a call
+ *   the live rung does not gate is auto-approved the moment it arrives at the runner, so describing
+ *   it as needing approval would be a promise nothing keeps.
  *
  * 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`.
+ * 2. A tool the live rung does not gate cannot require approval, so it is granted at every rung.
+ * 3. A gated tool is granted only where the rung's own grant covers its access class —
+ *    {@link isAccessClassGrantedAtRung}, the same rule `resolveGatedToolNames` selects the gated set
+ *    with. At the two deterministic rungs those two uses are complementary by construction: a tool
+ *    is gated there precisely when this returns false, so step 3 answers false for every tool step 2
+ *    let through, and the gate and the description say the same thing.
  */
 export declare function isGrantedAtRung(toolName: string, rung: ApprovalRung, gatedTools: readonly string[]): boolean;
 /**

package/dist/config/tool-descriptions.js

@@ -2,24 +2,35 @@
  * §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,
+ * - `manual` 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
+ * - `assisted` 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.
+ * - `auto` has its own sentence, and the difference it states is real: [[EXT-29]]'s negotiation
+ *   hands a call the rater will not clear back to the **model**, with the reason, so the first
+ *   consequence of an unsafe-looking call there is a refusal it can answer rather than a person
+ *   being asked — what changes is who answers first, and that is the one thing a model choosing a
+ *   tool can act on. A shared wording would hide it in the model's own tool-selection input.
+ *
+ *   Its `MAY` therefore sits **outside** the contrast the three bullets above draw: it qualifies
+ *   *"be refused by the auto-rater"*, not *"require the user's approval"*, so this sentence says
+ *   nothing either way about whether a person can be asked. That silence is deliberate — the
+ *   string is §4.5's row verbatim — and its cost is recorded here rather than left to be
+ *   discovered: `catastrophic` escalates to a human on the FIRST hit with no rounds at all, so a
+ *   person *can* be reached at `auto` and this input does not say so. Silent is not false, which
+ *   is why the wording stands and why the premise quoted above still holds; a wording claiming the
+ *   user is never asked would be false.
  * - `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 " +
+    manual: "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 " +
+    assisted: "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.',
+    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.',
-    '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. */
@@ -30,11 +41,15 @@ const ALL_SUFFIXES = Array.from(new Set(Object.values(RUNG_TOOL_DESCRIPTION_SUFF
  * 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.)
+ * Deliberately absent: `run_shell_command`, deepagents' `execute`, 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, and at `manual`/`write` every one of them escalates to the human.
+ *
+ * **An MCP tool's own `readOnlyHint` earns it nothing here.** A server's self-declared annotation is
+ * least earned exactly where the ladder is strictest, so it must not skip the prompt at those two
+ * rungs; membership of this table is the only thing that does. Adding a name here grants it at a
+ * rung, so add one only for a tool that genuinely reads or writes files in the working folder.
  */
 export const BUILT_IN_TOOL_ACCESS = {
     // gsloth GthFileSystemToolkit (lean backend)
@@ -114,35 +129,63 @@ export const BUILT_IN_TOOL_SUMMARIES = {
 export function getRungToolDescriptionSuffix(rung) {
     return RUNG_TOOL_DESCRIPTION_SUFFIXES[rung] ?? null;
 }
+/**
+ * §2 — does `rung`'s own grant cover this tool's **access class**, i.e. is the tool free *on its
+ * class alone*, before anything is asked about whether the gate gates it?
+ *
+ * - `read` — granted at every rung (§2.1).
+ * - `write` — granted from `write` up (§2.2, and §2.3/§2.4 which grant "everything `write` grants"),
+ *   so it escalates at `manual`.
+ * - **no class at all** — the shell, deepagents' `execute`, a network call, an MCP tool, a custom or
+ *   agent-authored tool: granted by no rung. There is no implicit exemption; a tool is free here
+ *   only by appearing in {@link BUILT_IN_TOOL_ACCESS}.
+ *
+ * **This is the one implementation of that rule.** {@link isGrantedAtRung} decides a grant with it,
+ * and `config/shell-policy.ts`'s `isToolGatedAtRung` decides gated-set membership with it — which
+ * is in turn what the backends' interrupt set and `GthAgentRunner`'s own live-rung check are built
+ * from. So the gate cannot escalate a call the descriptions and the rater's granted list call free
+ * — the drift §4.5 names as worse than having no description at all. Two derivations of one rule is
+ * exactly what this function exists to prevent; do not inline it back into either caller.
+ *
+ * `bypass` is not special-cased: it grants everything for a reason unrelated to access class (the
+ * gate is off), which {@link isGrantedAtRung} states where that belongs.
+ */
+export function isAccessClassGrantedAtRung(toolName, rung) {
+    const access = BUILT_IN_TOOL_ACCESS[toolName];
+    if (access === 'read')
+        return true;
+    if (access === 'write')
+        return rung !== 'manual';
+    return false;
+}
 /**
  * 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`.
+ * @param gatedTools The LIVE gated set — what `rung` actually gates, i.e.
+ *   `resolveGatedToolNames` for the rung in force. **This is the parameter that keeps the
+ *   descriptions honest**: a tool the rung does not gate cannot require approval, whatever a rung's
+ *   table row says about tool classes, so it is granted. It is deliberately NOT the wider,
+ *   rung-independent set the backends wire into `interruptOn` (`resolveInterruptToolNames`): a call
+ *   the live rung does not gate is auto-approved the moment it arrives at the runner, so describing
+ *   it as needing approval would be a promise nothing keeps.
  *
  * 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`.
+ * 2. A tool the live rung does not gate cannot require approval, so it is granted at every rung.
+ * 3. A gated tool is granted only where the rung's own grant covers its access class —
+ *    {@link isAccessClassGrantedAtRung}, the same rule `resolveGatedToolNames` selects the gated set
+ *    with. At the two deterministic rungs those two uses are complementary by construction: a tool
+ *    is gated there precisely when this returns false, so step 3 answers false for every tool step 2
+ *    let through, and the gate and the description say the same thing.
  */
 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;
+    return isAccessClassGrantedAtRung(toolName, rung);
 }
 /**
  * Remove a previously-appended §4.5 suffix (any rung's), returning the tool's own description.

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

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

@@ -109,7 +109,12 @@ export interface GthConfig {
      *   summarization, tool-result offload). Selecting it emits a warning. It can exhibit
      *   path-divergence and sporadic failures and carries extra internal workarounds; prefer `lean`.
      *
-     * Honored everywhere; the ACP server is still structurally deep-only and always runs deep.
+     * **Command-scoped**, and `docs/configuration/profiles.md` carries the one list of which commands
+     * honor it — don't restate it here, or the copies drift. What the type itself must say: `review`
+     * and `pr` — including the `pr` change-requirements discovery agent — always run lean, because
+     * `@gaunt-sloth/review` cannot reach the deep backend; a run that asks for `deep` there says so
+     * rather than dropping the key silently. The ACP server is the mirror image: structurally
+     * deep-only, it always runs deep and rejects `lean` outright.
      */
     agent?: {
         backend?: 'deep' | 'lean';
@@ -194,8 +199,8 @@ export interface GthConfig {
      */
     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
+     * CFG-27 — the tool-approval **ladder**: one of the five rungs (`manual` · `write` ·
+     * `assisted` · `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.
@@ -206,7 +211,7 @@ export interface GthConfig {
      * 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`.
+     * Absent = `assisted`, resolved by `resolveApprovals`.
      */
     approvals?: ApprovalsConfig;
     tools?: StructuredToolInterface[] | BaseToolkit[] | ServerTool[];

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AA+rBA,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":"AAosBA,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/core/GthAbstractAgent.d.ts

@@ -98,11 +98,19 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      *    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".
+     * `gatedTools` MUST be the **LIVE gated set for the rung in force** — `resolveGatedToolNames` for
+     * that rung — and NOT the set the caller wires into the approval interrupt. The two are different
+     * on purpose: the interrupt is installed once, at agent init, and is deliberately
+     * rung-independent (`resolveInterruptToolNames`, the union over every rung) so that
+     * `/approvals <mode>` can move the mode underneath it for the rest of the session. Passing that
+     * wider set here would describe tools as needing approval that the live mode does not gate — and
+     * a call the live mode does not gate is auto-approved the moment it reaches the runner, so the
+     * sentence would be a promise nothing keeps.
+     *
+     * What keeps a description from promising an approval the gate will not ask for is therefore that
+     * both this and `GthAgentRunner`'s own check are projections of the SAME rule,
+     * `isToolGatedAtRung`, evaluated against the SAME live mode — §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

package/dist/core/GthAbstractAgent.js

@@ -11,6 +11,7 @@ import { IterableReadableStream } from '@langchain/core/utils/stream';
 import { interrupt, Command, GraphInterrupt } from '@langchain/langgraph';
 import { extractInlineBinaryBlocks, materializeBinaryOutputs, renderAssistantContent, } from '#src/utils/binaryOutputUtils.js';
 import { detectRefusal, buildRefusalMessage } from '#src/core/refusal.js';
+import { answerTextOf, segmentAssistantContent, stripReasoningBlocks, } from '#src/core/reasoningBlocks.js';
 const THINK_OPEN = '<think>';
 const THINK_CLOSE = '</think>';
 /**
@@ -216,11 +217,19 @@ export class GthAbstractAgent {
      *    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".
+     * `gatedTools` MUST be the **LIVE gated set for the rung in force** — `resolveGatedToolNames` for
+     * that rung — and NOT the set the caller wires into the approval interrupt. The two are different
+     * on purpose: the interrupt is installed once, at agent init, and is deliberately
+     * rung-independent (`resolveInterruptToolNames`, the union over every rung) so that
+     * `/approvals <mode>` can move the mode underneath it for the rest of the session. Passing that
+     * wider set here would describe tools as needing approval that the live mode does not gate — and
+     * a call the live mode does not gate is auto-approved the moment it reaches the runner, so the
+     * sentence would be a promise nothing keeps.
+     *
+     * What keeps a description from promising an approval the gate will not ask for is therefore that
+     * both this and `GthAgentRunner`'s own check are projections of the SAME rule,
+     * `isToolGatedAtRung`, evaluated against the SAME live mode — §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
@@ -358,7 +367,12 @@ export class GthAbstractAgent {
                 if (refusal) {
                     return this.surfaceRefusal(refusal);
                 }
-                const finalContent = finalMessage?.content;
+                // CFG-33: Gemini's thought summaries ride inside `content` as `thought: true` text blocks,
+                // which renderAssistantContent would print as part of the answer (and write to the output
+                // file). The plain surface has never shown reasoning — every other provider's arrives
+                // out-of-band in additional_kwargs — so drop them for rendering only; graph state keeps the
+                // message whole so the thought parts still replay as history.
+                const finalContent = stripReasoningBlocks(finalMessage?.content);
                 const processedContent = !this.config.writeBinaryOutputsToFile
                     ? {
                         renderedContent: renderAssistantContent(finalContent),
@@ -524,7 +538,9 @@ export class GthAbstractAgent {
                         // completed call when its ToolMessage arrives; a no-op for plain text chunks).
                         toolIndication.observe(chunk);
                         if (AIMessage.isInstance(chunk)) {
-                            const text = chunk.text ?? '';
+                            // CFG-33: the ANSWER text only. `.text` folds Gemini's `thought: true` blocks into the
+                            // answer, which would print the model's thinking inline here and in the output file.
+                            const text = answerTextOf(chunk.content);
                             totalChunks++;
                             if (text.length > 0) {
                                 statusUpdate(StatusLevel.STREAM, text);
@@ -763,6 +779,20 @@ export class GthAbstractAgent {
                 }
             }
         }
+        // CFG-33 — emit a message's content segments in order. A segment already classified as the
+        // model's thinking (a Gemini `thought: true` block) goes straight to the reasoning channel;
+        // answer text still passes through the TUI-C22 think splitter, so an inline `<think>` tag is
+        // peeled exactly as before. With no reasoning block this is the previous `.text` behaviour.
+        function* emitContentSegments(segments) {
+            for (const segment of segments) {
+                if (segment.kind === 'reasoning') {
+                    yield* emitSegments([segment]);
+                }
+                else {
+                    yield* emitSegments(thinkSplitter.push(segment.text));
+                }
+            }
+        }
         function* flushAggregated() {
             if (!aggregatedAIChunk)
                 return;
@@ -812,9 +842,10 @@ export class GthAbstractAgent {
                 // which is cumulative. TUI-C22 routes it through the think splitter so inline
                 // <think>...</think> (buffered across chunks) is peeled into the reasoning channel and
                 // stripped from the answer; text with no think tags passes straight through unchanged.
-                if (chunk.text) {
-                    yield* emitSegments(thinkSplitter.push(chunk.text));
-                }
+                // CFG-33 classifies the chunk's content blocks first, in order, so Gemini's `thought: true`
+                // blocks reach the reasoning channel instead of the answer; answer text still goes through
+                // the think splitter, thought text does not (it is already classified).
+                yield* emitContentSegments(segmentAssistantContent(chunk.content));
             }
             else if (AIMessage.isInstance(chunk)) {
                 // Reasoning on a non-chunk AIMessage — a non-streamed / resumed thinking message
@@ -834,9 +865,7 @@ export class GthAbstractAgent {
                     });
                     aggregatedAIChunk = aggregatedAIChunk ? aggregatedAIChunk.concat(synthetic) : synthetic;
                 }
-                if (chunk.text) {
-                    yield* emitSegments(thinkSplitter.push(chunk.text));
-                }
+                yield* emitContentSegments(segmentAssistantContent(chunk.content));
                 // A non-chunk AIMessage is a COMPLETE message, not a delta — drain any residual now
                 // (an unterminated <think> becomes reasoning, a dangling partial becomes answer) so its
                 // buffered state never leaks into a subsequent message (TUI-C22).