@tyvm/knowhow 0.0.145 → 0.0.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.145",
+  "version": "0.0.146",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/chat/CliChatService.ts

@@ -43,6 +43,22 @@ export class CliChatService implements ChatService {
       chatHistory: this.chatHistory,
       plugins,
     };
+    this.registerCommand({
+      name: "reload",
+      description: "Reload configuration, tools, MCP connections, and modules",
+      handler: async () => {
+        try {
+          console.log("Reloading configuration...");
+          const result = await services().RuntimeReload.reload();
+          console.log(
+            `✓ Reloaded ${result.tools} tools, ${result.mcps} MCP servers, and ${result.modules} modules`
+          );
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`⚠ Reload failed: ${message}`);
+        }
+      },
+    });
     this.loadInputHistory();
 
     // Set up callback to add entries to inputHistory immediately when user presses Enter

package/src/chat/modules/AgentModule.ts

@@ -18,7 +18,12 @@ import { BaseChatModule } from "./BaseChatModule";
 import { services } from "../../services/index";
 import { BaseAgent } from "../../agents/index";
 import { ChatCommand, ChatMode, ChatContext, ChatService } from "../types";
-import { Message, CompletionOptions } from "../../clients/types";
+import {
+  Message,
+  CompletionOptions,
+  REASONING_EFFORTS,
+  isReasoningEffort,
+} from "../../clients/types";
 import { ChatInteraction } from "../../types";
 import { Marked } from "../../utils/index";
 import { TokenCompressor } from "../../processors/TokenCompressor";
@@ -173,21 +178,15 @@ export class AgentModule extends BaseChatModule {
       {
         name: "reasoning_effort",
         description:
-          "Set the reasoning effort for the agent (none, low, medium, high). Use 'none' to disable thinking on models that support it.",
+          `Set the reasoning effort for the agent (${REASONING_EFFORTS.join(", ")}). Individual models support different subsets.`,
         handler: async (args: string[]): Promise<void> => {
-          const validEfforts: CompletionOptions["reasoning_effort"][] = [
-            "none",
-            "low",
-            "medium",
-            "high",
-          ];
-          const effort = args[0] as CompletionOptions["reasoning_effort"];
-          if (!effort || !validEfforts.includes(effort)) {
+          const effort = args[0];
+          if (!isReasoningEffort(effort)) {
             console.log(
               `Current reasoning effort: ${this.reasoningEffort ?? "(not set — model default)"}`
             );
             console.log(
-              `Usage: /reasoning_effort <${validEfforts.join("|")}>`
+              `Usage: /reasoning_effort <${REASONING_EFFORTS.join("|")}>`
             );
             return;
           }
@@ -201,19 +200,13 @@ export class AgentModule extends BaseChatModule {
         name: "effort",
         description: "Alias for /reasoning_effort",
         handler: async (args: string[]): Promise<void> => {
-          const validEfforts: CompletionOptions["reasoning_effort"][] = [
-            "none",
-            "low",
-            "medium",
-            "high",
-          ];
-          const effort = args[0] as CompletionOptions["reasoning_effort"];
-          if (!effort || !validEfforts.includes(effort)) {
+          const effort = args[0];
+          if (!isReasoningEffort(effort)) {
             console.log(
               `Current reasoning effort: ${this.reasoningEffort ?? "(not set — model default)"}`
             );
             console.log(
-              `Usage: /effort <${validEfforts.join("|")}>`
+              `Usage: /effort <${REASONING_EFFORTS.join("|")}>`
             );
             return;
           }
@@ -247,8 +240,15 @@ export class AgentModule extends BaseChatModule {
         description: "Detach from the currently attached agent",
         modes: ["agent:attached"],
         handler: async (_args: string[]): Promise<void> => {
+          const agent = this.attachedAgent;
           console.log("Detached from agent");
-          this.detachFromAgent();
+          // Only detach if we are still attached to THIS agent. If the user
+          // killed this agent and started a new one while this agent was
+          // finishing a long tool call, detachFromAgent() would rip out the
+          // new agent's rendering and reset the mode.
+          if (agent && this.attachedAgent === agent) {
+            this.detachFromAgent();
+          }
         },
       },
       {
@@ -1468,8 +1468,15 @@ export class AgentModule extends BaseChatModule {
           }
 
           resolve("done");
-          // Exit agent:attached mode so the prompt resets back to the default
-          this.detachFromAgent();
+          // Exit agent:attached mode so the prompt resets back to the default.
+          // Only detach if we are still attached to THIS agent. If the user
+          // killed this agent and started a new one (or /attached to a different
+          // one) while this agent was finishing a long tool call, calling
+          // detachFromAgent() unconditionally would rip out the new agent's
+          // rendering listeners and reset the mode, making new output invisible.
+          if (this.attachedAgent === agent) {
+            this.detachFromAgent();
+          }
         });
       });
 

package/src/chat/modules/SessionsModule.ts

@@ -214,7 +214,6 @@ export class SessionsModule extends BaseChatModule {
     // ── Case 1: in-memory running task ──────────────────────────────────────
     if (taskRegistry.has(id)) {
       const taskInfo = taskRegistry.get(id)!;
-      const renderer = this.agentModule.getRenderer();
       const context = this.chatService?.getContext();
       const selectedAgent = taskInfo.agent;
 
@@ -222,13 +221,9 @@ export class SessionsModule extends BaseChatModule {
         context.selectedAgent = selectedAgent;
         context.agentMode = true;
         context.currentAgent = taskInfo.agentName;
-        context.activeAgentTaskId = id;
         context.currentModel = selectedAgent.getModel();
         context.currentProvider = selectedAgent.getProvider();
       }
-      this.agentModule.setActiveAgentTaskId(id);
-      renderer.setActiveTaskId(id);
-      if (this.chatService) this.chatService.setMode("agent:attached");
 
       console.log(`🔄 Attached to running task: ${id}`);
       console.log(`   Agent : ${taskInfo.agentName}`);
@@ -237,6 +232,13 @@ export class SessionsModule extends BaseChatModule {
       console.log(
         `   Type /logs to see recent messages, or /detach to detach.`
       );
+
+      // Route through attachedAgentChatLoop so that:
+      // 1. wireAgentRendering is called (new output becomes visible)
+      // 2. attachedAgent is set (so /poke, /kill, /compact work)
+      // 3. a done listener is registered (mode resets when agent finishes)
+      // Do NOT pass initialInput — agent is already running, no need to call it again.
+      await this.agentModule.attachedAgentChatLoop(id, selectedAgent as any);
       return;
     }
 

package/src/chat/types.ts

@@ -3,6 +3,7 @@
  */
 import { ChatInteraction, Config } from "../types";
 import { BaseAgent } from "../agents/base/base";
+import { ReasoningEffort } from "../clients/types";
 import { ToolsService } from "../services";
 import { AgentRenderer } from "./renderer/types";
 
@@ -101,7 +102,7 @@ export interface TaskInfo {
   // restore the exact configuration instead of falling back to agent defaults.
   model?: string;
   provider?: string;
-  reasoningEffort?: "none" | "low" | "medium" | "high";
+  reasoningEffort?: ReasoningEffort;
   summarizeReasoning?: boolean;
 }
 
@@ -123,7 +124,7 @@ export interface ChatSession {
   // Persisted run configuration for exact resume restoration.
   model?: string;
   provider?: string;
-  reasoningEffort?: "none" | "low" | "medium" | "high";
+  reasoningEffort?: ReasoningEffort;
   summarizeReasoning?: boolean;
 }
 

package/src/clients/anthropic.ts

@@ -88,6 +88,25 @@ export class GenericAnthropicClient implements GenericClient {
     return undefined;
   }
 
+  /** Map provider-neutral effort names to Anthropic's output_config.effort. */
+  getEffortOutputConfig(
+    model: string,
+    reasoningEffort?: CompletionOptions["reasoning_effort"]
+  ): Anthropic.OutputConfig | undefined {
+    if (
+      reasoningEffort === undefined ||
+      reasoningEffort === "none" ||
+      (!alwaysOnModels.includes(model) && !optInModels.includes(model))
+    ) {
+      return undefined;
+    }
+
+    return {
+      // Anthropic uses `low` for the provider-neutral `minimal` level.
+      effort: reasoningEffort === "minimal" ? "low" : reasoningEffort,
+    };
+  }
+
   /**
    * Clean JSON Schema for Anthropic API compatibility.
    * Removes unsupported fields like additionalProperties, $ref, $defs, positional.
@@ -423,6 +442,10 @@ export class GenericAnthropicClient implements GenericClient {
       options.reasoning_effort,
       options.reasoning_summary,
     );
+    const effortOutputConfig = this.getEffortOutputConfig(
+      options.model,
+      options.reasoning_effort
+    );
 
     const systemMessage = options.messages
       .filter((msg) => msg.role === "system")
@@ -447,6 +470,7 @@ export class GenericAnthropicClient implements GenericClient {
           : undefined,
         max_tokens: options.max_tokens || 8000,
         ...(thinkingParam && { thinking: thinkingParam }),
+        ...(effortOutputConfig && { output_config: effortOutputConfig }),
         ...(tools.length && {
           tool_choice: { type: "auto" },
           tools,

package/src/clients/fireworks.ts

@@ -51,6 +51,9 @@ export class GenericFireworksClient extends HttpClient {
       ...options,
       // Strip Anthropic-specific field not accepted by Fireworks
       long_ttl_cache: undefined,
+      // This is translated by the OpenAI/Anthropic clients, but is not part of
+      // Fireworks' OpenAI-compatible chat completion schema.
+      reasoning_summary: undefined,
     };
 
     if (sanitized.tools) {

package/src/clients/gemini.ts

@@ -434,9 +434,13 @@ export class GenericGeminiClient implements GenericClient {
     // Gemini 3.x — use thinkingLevel
     if (GoogleThinkingLevelModels.includes(model)) {
       const levelMap: Record<string, string> = {
+        none: "minimal",
+        minimal: "minimal",
         low: "low",
         medium: "medium",
         high: "high",
+        xhigh: "high",
+        max: "high",
       };
       return {
         thinkingLevel: levelMap[effort] ?? "low",
@@ -447,9 +451,13 @@ export class GenericGeminiClient implements GenericClient {
     if (GoogleThinkingBudgetModels.includes(model)) {
       // Map effort to token budget
       const budgetMap: Record<string, number> = {
+        none: 0,
+        minimal: 512,
         low: 1024,
         medium: 8192,
         high: -1, // dynamic
+        xhigh: -1,
+        max: -1,
       };
       return {
         thinkingBudget: budgetMap[effort] ?? 1024,

package/src/clients/openai.ts

@@ -112,9 +112,10 @@ export class GenericOpenAiClient implements GenericClient {
 
   resolveReasoningEffort(options: CompletionOptions): "low" | "medium" | "high" {
     const effort = options.reasoning_effort ?? this.detectReasoningEffort(options.messages);
-    // "none" is not a valid SDK ReasoningEffort — callers that need "none" should
-    // check isReasoningDisabled() separately and skip the reasoning params.
-    if (effort === "none") return "low";
+    // Chat Completions only accepts low/medium/high. Preserve newer values on
+    // the Responses API, but map them to the nearest legacy level here.
+    if (effort === "none" || effort === "minimal") return "low";
+    if (effort === "xhigh" || effort === "max") return "high";
     return effort;
   }
 
@@ -125,7 +126,9 @@ export class GenericOpenAiClient implements GenericClient {
    */
   resolveReasoningEffortForModel(options: CompletionOptions): string {
     const raw = options.reasoning_effort ?? this.detectReasoningEffort(options.messages);
-    const requested = raw === "none" ? "none" : raw;
+    // Anthropic calls its highest level `max`; OpenAI calls it `xhigh`.
+    // Accept both provider-neutral CLI spellings.
+    const requested = raw === "max" ? "xhigh" : raw;
     const pricing = OpenAiTextPricing[options.model];
     const supportedLevels = pricing?.reasoningLevels;
     if (!supportedLevels || supportedLevels.length === 0) {

package/src/clients/types.ts

@@ -136,6 +136,26 @@ export interface RetryOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Every reasoning-effort spelling currently exposed by a supported provider.
+ * Individual models may support only a subset; provider clients are responsible
+ * for translating or clamping values where their APIs require it.
+ */
+export const REASONING_EFFORTS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+export function isReasoningEffort(value: unknown): value is ReasoningEffort {
+  return typeof value === "string" && REASONING_EFFORTS.includes(value as ReasoningEffort);
+}
+
 export interface CompletionOptions extends RetryOptions {
   model: string;
   messages: Message[];
@@ -147,14 +167,17 @@ export interface CompletionOptions extends RetryOptions {
    * Maps to: OpenAI reasoning_effort/reasoning.effort, xAI reasoning.effort,
    *          Gemini thinkingLevel/thinkingBudget, Anthropic thinking mode.
    *
-   * "none"   = disable thinking entirely (Anthropic: thinking.type="disabled",
-   *            OpenAI: reasoning.effort="none").  Only supported by models that
-   *            allow disabling thinking (e.g. claude-sonnet-5).
-   * "low"    = minimal thinking
-   * "medium" = balanced (default for most models)
-   * "high"   = maximum reasoning
+   * "none"    = disable thinking where supported
+   * "minimal" = provider-defined minimum (for example Gemini/OpenAI)
+   * "low"     = low reasoning
+   * "medium"  = balanced reasoning
+   * "high"    = high reasoning
+   * "xhigh"   = extra-high reasoning (for example OpenAI/xAI/Anthropic)
+   * "max"     = maximum reasoning (Anthropic)
+   *
+   * A model may support only a subset of these provider-level values.
    */
-  reasoning_effort?: "none" | "low" | "medium" | "high";
+  reasoning_effort?: ReasoningEffort;
   /**
    * When true, request a summarized view of the model's thinking process.
    * - Anthropic: thinking.display = "summarized"

package/src/clients/xai.ts

@@ -52,6 +52,15 @@ export class GenericXAIClient implements GenericClient {
     });
   }
 
+  resolveLegacyReasoningEffort(
+    effort: CompletionOptions["reasoning_effort"]
+  ): "low" | "medium" | "high" | undefined {
+    if (effort === undefined || effort === "none") return undefined;
+    if (effort === "minimal") return "low";
+    if (effort === "xhigh" || effort === "max") return "high";
+    return effort;
+  }
+
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
@@ -72,13 +81,14 @@ export class GenericXAIClient implements GenericClient {
       return msg as ChatCompletionMessageParam;
     });
 
+    const reasoningEffort = this.resolveLegacyReasoningEffort(options.reasoning_effort);
     const response = await this.client.chat.completions.create({
       model: options.model,
       messages: xaiMessages,
       max_tokens: options.max_tokens,
-      ...(XaiReasoningModels.includes(options.model) && options.reasoning_effort && options.reasoning_effort !== "none" && {
+      ...(XaiReasoningModels.includes(options.model) && reasoningEffort && {
         // grok-3-mini models support reasoning_effort: "low" | "medium" | "high"
-        reasoning_effort: options.reasoning_effort as "low" | "medium" | "high",
+        reasoning_effort: reasoningEffort,
       }),
       ...(options.tools && {
         tools: options.tools,
@@ -206,8 +216,17 @@ export class GenericXAIClient implements GenericClient {
     // Resolve reasoning effort, clamping to supported levels if defined in pricing
     const pricing = XaiTextPricing[options.model];
     const supportedLevels = pricing?.reasoningLevels;
-    let reasoningEffort: string | undefined = options.reasoning_effort;
-    if (supportedLevels?.length) {
+    const requestedEffort = options.reasoning_effort;
+    let reasoningEffort: string | undefined;
+    if (requestedEffort !== "none") {
+      reasoningEffort =
+        requestedEffort === "minimal"
+          ? "low"
+          : requestedEffort === "max"
+            ? "xhigh"
+            : requestedEffort;
+    }
+    if (requestedEffort !== "none" && supportedLevels?.length) {
       if (!reasoningEffort || !supportedLevels.includes(reasoningEffort)) {
         reasoningEffort = supportedLevels[0];
       }

package/src/commands/agent.ts

@@ -8,6 +8,7 @@ import { SessionsModule } from "../chat/modules/SessionsModule";
 import { SetupModule } from "../chat/modules/SetupModule";
 import { PlainRenderer } from "../chat/renderer/PlainRenderer";
 import { loadRenderer } from "../chat/renderer/loadRenderer";
+import { isReasoningEffort, REASONING_EFFORTS } from "../clients/types";
 import { getConfig } from "../config";
 
 async function setupRenderer(chatService: any, rendererSpecifier: string): Promise<void> {
@@ -57,7 +58,7 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
     .option("--agent-name <name>", "Which agent to use", "Patcher")
     .option(
       "--reasoning-effort <effort>",
-      "Reasoning effort: none, low, medium, or high. Use 'none' to disable thinking on models that support it (e.g. for faster computer-use)."
+      `Reasoning effort: ${REASONING_EFFORTS.join(", ")}. Individual models support different subsets.`
     )
     .option(
       "--max-time-limit <minutes>",
@@ -103,6 +104,14 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
     )
     .action(async (options) => {
       try {
+        if (
+          options.reasoningEffort !== undefined &&
+          !isReasoningEffort(options.reasoningEffort)
+        ) {
+          throw new Error(
+            `Invalid reasoning effort "${options.reasoningEffort}". Expected one of: ${REASONING_EFFORTS.join(", ")}.`
+          );
+        }
         const { setupServices } = await import("./services");
         await setupServices();
         const chatService = getChatService();

package/src/commands/services.ts

@@ -1,6 +1,6 @@
 import { includedTools } from "../agents/tools/list";
 import * as allTools from "../agents/tools";
-import { LazyToolsService, services, MinimalToolsService } from "../services";
+import { LazyToolsService, services, MinimalToolsService, TracingService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
 import { getConfig } from "../config";
@@ -19,8 +19,10 @@ export async function setupServices() {
     Events,
     MediaProcessor,
     Behaviors,
+    RuntimeReload,
   } = services();
 
+  await Plugins.refreshConfiguredState();
   // cli uses LazyTools to keep context slim
   const Tools = new LazyToolsService();
   await Behaviors.initFromConfig();
@@ -80,7 +82,7 @@ export async function setupServices() {
 
   console.log("📦 Loading modules from config...");
   const modulesService = new ModulesService();
-  await modulesService.loadModulesFromConfig({
+  const moduleContext = {
     Agents,
     Embeddings,
     Plugins,
@@ -89,7 +91,51 @@ export async function setupServices() {
     MediaProcessor,
     Behaviors,
     Events,
+    Tracing: TracingService,
+  };
+
+  // Call destroy() on all modules when the process is shutting down so they
+  // can flush buffers (e.g. OTEL spans), close connections, etc.
+  const destroyAll = async () => {
+    await modulesService.destroyModules();
+  };
+  process.on("beforeExit", destroyAll);
+  process.on("SIGINT", async () => {
+    await destroyAll();
+    process.exit(0);
+  });
+  await modulesService.loadModulesFromConfig(moduleContext);
+
+  RuntimeReload.configure(async () => {
+    await modulesService.destroyModules();
+    await Plugins.refreshConfiguredState();
+    await Mcp.closeAll();
+
+    Tools.resetTools();
+    Tools.defineTools(includedTools, allTools);
+    try {
+      const agentCallDef = AllTools.getTool?.("agentCall");
+      const agentCallFn = AllTools.getFunction?.("agentCall");
+      if (agentCallDef) Tools.addTool(agentCallDef);
+      if (agentCallFn) Tools.setFunction("agentCall", agentCallFn);
+    } catch (_) {}
+
+    await Behaviors.initFromConfig();
+    await Mcp.connectToConfigured(Tools);
+    await Clients.registerConfiguredModels();
+    await modulesService.loadModulesFromConfig(moduleContext);
+
+    const config = await getConfig();
+    return {
+      tools: Tools.getTools().length,
+      mcps: (config.mcps || []).length,
+      modules: (config.modules || []).length,
+    };
+  });
+  process.on("SIGTERM", async () => {
+    await destroyAll();
+    process.exit(0);
   });
 
-  return { Tools, Clients };
+  return { Tools, Clients, modulesService };
 }

package/src/plugins/plugins.ts

@@ -52,6 +52,22 @@ export class PluginService {
     return true;
   }
 
+  /** Apply the enabled/disabled state from the current Knowhow config. */
+  async refreshConfiguredState(): Promise<void> {
+    const config = await getConfig();
+    const disabled = new Set(getDisabledPlugins(config.plugins));
+
+    for (const [key, plugin] of this.pluginMap) {
+      if (disabled.has(key)) {
+        plugin.disable();
+      } else {
+        // Configuration is authoritative when services start or reload. This
+        // also re-enables a plugin after it is removed from `disabled`.
+        plugin.enable();
+      }
+    }
+  }
+
   /* -------- existing public API (updated for compatibility) ---------------------- */
 
   listPlugins() {

package/src/processors/TokenCompressor.ts

@@ -7,6 +7,7 @@ import {
   CompressionMetadata,
   JsonCompressorStorage,
 } from "./JsonCompressor";
+import { paginateToolResponse } from "./tools/boundedToolResponse";
 
 export interface KeyInfo {
   key: string;
@@ -419,15 +420,25 @@ export class TokenCompressor implements JsonCompressorStorage {
     if (toolsService) {
       toolsService.addTools([expandTokensDefinition]);
       toolsService.addFunctions({
-        [this.toolName]: (key: string, fromLine?: number, toLine?: number) => {
+        [this.toolName]: (
+          key: string,
+          fromLine?: number,
+          toLine?: number,
+          characterOffset?: number,
+          maxCharacters?: number
+        ) => {
           // Auto-stitch: follow any NEXT_CHUNK_KEY chain and return the full,
           // reassembled content so the agent never has to chase nested keys.
           const data = this.retrieveFullString(key);
 
           if (data === null) {
-            return `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
-              ", "
-            )}`;
+            return paginateToolResponse(
+              `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
+                ", "
+              )}`,
+              { characterOffset, maxCharacters },
+              "available-key list"
+            );
           }
 
           // Optional ranged read: return only the requested 1-based, inclusive
@@ -435,7 +446,11 @@ export class TokenCompressor implements JsonCompressorStorage {
           const hasRange =
             typeof fromLine === "number" || typeof toLine === "number";
           if (!hasRange) {
-            return data;
+            return paginateToolResponse(
+              data,
+              { characterOffset, maxCharacters },
+              `expanded value for ${key}`
+            );
           }
 
           const lines = data.split("\n");
@@ -447,14 +462,22 @@ export class TokenCompressor implements JsonCompressorStorage {
           );
 
           if (start > end) {
-            return `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`;
+            return paginateToolResponse(
+              `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`,
+              { characterOffset, maxCharacters },
+              "line-range error"
+            );
           }
 
           const numbered: string[] = [];
           for (let i = start; i <= end; i++) {
             numbered.push(`${i}: ${lines[i - 1]}`);
           }
-          return numbered.join("\n");
+          return paginateToolResponse(
+            numbered.join("\n"),
+            { characterOffset, maxCharacters },
+            `expanded lines ${start}-${end} for ${key}`
+          );
         },
       });
     }
@@ -559,7 +582,7 @@ export const expandTokensDefinition: Tool = {
   function: {
     name: "expandTokens",
     description:
-      "Retrieve compressed data that was stored during message processing. The full content is automatically reassembled (any chunk chain is followed for you, so you never need to chase NEXT_CHUNK_KEY references). Optionally pass fromLine/toLine (1-based, inclusive) to return just a range of lines, prefixed with real line numbers. NOTE: Can also use jqToolResponse, grepToolResponse, tailToolResponse to access/filter/search compressed content without needing to expand all tokens.",
+      "Retrieve a bounded page of compressed data. Chunk chains are automatically reassembled, but output is limited to 20,000 characters by default. Use characterOffset to continue, or fromLine/toLine for line-based selection. Prefer jqToolResponse, grepToolResponse, or tailToolResponse when possible.",
     parameters: {
       type: "object",
       positional: true,
@@ -578,6 +601,15 @@ export const expandTokensDefinition: Tool = {
           description:
             "Optional 1-based end line (inclusive). Defaults to the end of the content when omitted.",
         },
+        characterOffset: {
+          type: "number",
+          description:
+            "Optional zero-based character offset within the expanded value or selected line range.",
+        },
+        maxCharacters: {
+          type: "number",
+          description: "Response size (default 20000, hard maximum 50000).",
+        },
       },
       required: ["key"],
     },