@theokit/sdk-tools 0.23.0 → 0.24.0

package/dist/index.d.cts

@@ -26,6 +26,11 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
  */
 
 interface CreateApplyPatchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
@@ -101,6 +106,11 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
  */
 
 interface CreateCurrentTimeToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Injectable clock — defaults to `() => new Date()`. Pass a fixed clock for deterministic tests. */
     clock?: () => Date;
 }
@@ -177,6 +187,11 @@ declare function formatError(message: string, code?: string): string;
  */
 
 interface CreateGitDiffToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
@@ -209,6 +224,15 @@ interface CreateGitStatusToolOptions {
     timeoutMs?: number;
     /** Cap on captured stdout; excess sets `truncated: true`. Default 5 MB. */
     maxStdoutBytes?: number;
+    /**
+     * Backend de execução injetado (`@theokit/sdk/sandbox`) — quando presente, `git status` roda via
+     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     *
+     * Simetria com `createGitDiffTool`, apontada pelo review do M76: sem isto `git_diff` rodaria
+     * confinado e `git_status` não, na mesma sessão — e a assimetria seria invisível até alguém
+     * perceber que uma das duas escapa do sandbox.
+     */
+    sandbox?: SandboxProvider;
     /**
      * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
      *
@@ -240,6 +264,11 @@ declare function createGitStatusTool(opts: CreateGitStatusToolOptions): CustomTo
  */
 
 interface CreateGlobToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. */
     projectRoot: string;
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
@@ -267,6 +296,11 @@ declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
  */
 
 interface CreateInteractiveShellToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** The interactive backend, or a per-request resolver of one (injected — never a direct native dep). */
     interactive: InteractiveProvider<unknown>;
 }
@@ -662,6 +696,11 @@ interface PlanModeToolWithStore {
  * @public
  */
 interface PlanModeToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Store the submitted `plan` is persisted to on `exit`. */
     artifactStore: SessionArtifactStore;
     /** Artifact id under which the plan is stored. Default `"plan"`. */
@@ -686,7 +725,13 @@ interface QuestionToolOptions {
      * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
      * permanece como fallback, para quem constrói a tool com um asker fixo (retrocompatível).
      */
-    askUser?: (question: string) => Promise<string>;
+    askUser?: (question: string, threadId?: string) => Promise<string>;
+    /**
+     * Chamado quando a pergunta é ABANDONADA (timeout ou cancelamento da run), para que o lado da UI
+     * libere o slot. Sem ele o timeout deixa a pergunta pendente para sempre — a UI segue mostrando
+     * um prompt que ninguém aguarda e a próxima pergunta falha com "já há uma pendente".
+     */
+    onAbandon?: (threadId?: string) => void;
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
@@ -773,6 +818,11 @@ declare class ReadTracker {
  */
 
 interface CreateReadFileToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every read is gated against this boundary. */
     projectRoot: string;
     /**
@@ -852,6 +902,11 @@ declare class ReasoningTools {
  */
 
 interface CreateRunVitestToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
@@ -1096,6 +1151,11 @@ declare function createUpdatePlanTool(): CustomTool;
  */
 
 interface CreateWebFetchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Default timeout in ms. */
     defaultTimeoutMs?: number;
     /**
@@ -1135,6 +1195,11 @@ interface WebSearchResult {
 }
 type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
 interface CreateWebSearchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Search provider callback — consumer injects the implementation. */
     search: WebSearchCallback;
     /** Default max results if not specified by the LLM. */
@@ -1224,6 +1289,11 @@ type WriteToolContext = {
     context?: unknown;
 };
 interface CreateWriteFileToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every write is gated against this boundary. */
     projectRoot: string;
     /**

package/dist/index.d.ts

@@ -26,6 +26,11 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
  */
 
 interface CreateApplyPatchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
@@ -101,6 +106,11 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
  */
 
 interface CreateCurrentTimeToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Injectable clock — defaults to `() => new Date()`. Pass a fixed clock for deterministic tests. */
     clock?: () => Date;
 }
@@ -177,6 +187,11 @@ declare function formatError(message: string, code?: string): string;
  */
 
 interface CreateGitDiffToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
@@ -209,6 +224,15 @@ interface CreateGitStatusToolOptions {
     timeoutMs?: number;
     /** Cap on captured stdout; excess sets `truncated: true`. Default 5 MB. */
     maxStdoutBytes?: number;
+    /**
+     * Backend de execução injetado (`@theokit/sdk/sandbox`) — quando presente, `git status` roda via
+     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     *
+     * Simetria com `createGitDiffTool`, apontada pelo review do M76: sem isto `git_diff` rodaria
+     * confinado e `git_status` não, na mesma sessão — e a assimetria seria invisível até alguém
+     * perceber que uma das duas escapa do sandbox.
+     */
+    sandbox?: SandboxProvider;
     /**
      * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
      *
@@ -240,6 +264,11 @@ declare function createGitStatusTool(opts: CreateGitStatusToolOptions): CustomTo
  */
 
 interface CreateGlobToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. */
     projectRoot: string;
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
@@ -267,6 +296,11 @@ declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
  */
 
 interface CreateInteractiveShellToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** The interactive backend, or a per-request resolver of one (injected — never a direct native dep). */
     interactive: InteractiveProvider<unknown>;
 }
@@ -662,6 +696,11 @@ interface PlanModeToolWithStore {
  * @public
  */
 interface PlanModeToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Store the submitted `plan` is persisted to on `exit`. */
     artifactStore: SessionArtifactStore;
     /** Artifact id under which the plan is stored. Default `"plan"`. */
@@ -686,7 +725,13 @@ interface QuestionToolOptions {
      * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
      * permanece como fallback, para quem constrói a tool com um asker fixo (retrocompatível).
      */
-    askUser?: (question: string) => Promise<string>;
+    askUser?: (question: string, threadId?: string) => Promise<string>;
+    /**
+     * Chamado quando a pergunta é ABANDONADA (timeout ou cancelamento da run), para que o lado da UI
+     * libere o slot. Sem ele o timeout deixa a pergunta pendente para sempre — a UI segue mostrando
+     * um prompt que ninguém aguarda e a próxima pergunta falha com "já há uma pendente".
+     */
+    onAbandon?: (threadId?: string) => void;
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
@@ -773,6 +818,11 @@ declare class ReadTracker {
  */
 
 interface CreateReadFileToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every read is gated against this boundary. */
     projectRoot: string;
     /**
@@ -852,6 +902,11 @@ declare class ReasoningTools {
  */
 
 interface CreateRunVitestToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
@@ -1096,6 +1151,11 @@ declare function createUpdatePlanTool(): CustomTool;
  */
 
 interface CreateWebFetchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Default timeout in ms. */
     defaultTimeoutMs?: number;
     /**
@@ -1135,6 +1195,11 @@ interface WebSearchResult {
 }
 type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
 interface CreateWebSearchToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Search provider callback — consumer injects the implementation. */
     search: WebSearchCallback;
     /** Default max results if not specified by the LLM. */
@@ -1224,6 +1289,11 @@ type WriteToolContext = {
     context?: unknown;
 };
 interface CreateWriteFileToolOptions {
+    /** M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo). O nome é contrato: chave
+     *  de approval, o que o modelo vê e o que o telemetry registra. */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every write is gated against this boundary. */
     projectRoot: string;
     /**

package/dist/index.js

@@ -225,8 +225,8 @@ ${chunk.oldLines.join("\n")}`
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
   return Tool.create({
-    name: "apply_patch",
-    description: "Apply a Codex-style V4A patch. The patch is `*** Begin Patch` \u2026 `*** End Patch` wrapping one or more hunks: `*** Add File: <path>` (then `+`lines), `*** Delete File: <path>`, or `*** Update File: <path>` (optional `*** Move to: <path>`) with `@@`-anchored `+` (add) / `-` (remove) / ` ` (context) lines. Read a file first so your context/removed lines match. Applied atomically \u2014 a mismatch anywhere aborts the whole patch with zero writes; each path is security-checked. Returns { ok, files_patched } or { ok: false, error }.",
+    name: opts.name ?? "apply_patch",
+    description: opts.description ?? "Apply a Codex-style V4A patch. The patch is `*** Begin Patch` \u2026 `*** End Patch` wrapping one or more hunks: `*** Add File: <path>` (then `+`lines), `*** Delete File: <path>`, or `*** Update File: <path>` (optional `*** Move to: <path>`) with `@@`-anchored `+` (add) / `-` (remove) / ` ` (context) lines. Read a file first so your context/removed lines match. Applied atomically \u2014 a mismatch anywhere aborts the whole patch with zero writes; each path is security-checked. Returns { ok, files_patched } or { ok: false, error }.",
     inputSchema: z.object({
       patch: z.string().min(1).describe("V4A patch: *** Begin Patch \u2026 *** End Patch.")
     }),
@@ -427,8 +427,8 @@ function formatInTimezone(now, tz) {
 function createCurrentTimeTool(opts = {}) {
   const clock = opts.clock ?? (() => /* @__PURE__ */ new Date());
   return Tool.create({
-    name: "current_time",
-    description: "Get the current date and time. Returns { current_time, iso, timezone } as a JSON string, where current_time is 'YYYY-MM-DD HH:MM:SS <timezone>' and iso is the ISO-8601 instant. Pass an optional IANA timezone (e.g. 'America/Sao_Paulo', 'Europe/Lisbon'); defaults to UTC. Never state the date or time from memory \u2014 always call this. Returns { ok: false, error: 'invalid_timezone' } for an unknown timezone.",
+    name: opts.name ?? "current_time",
+    description: opts.description ?? "Get the current date and time. Returns { current_time, iso, timezone } as a JSON string, where current_time is 'YYYY-MM-DD HH:MM:SS <timezone>' and iso is the ISO-8601 instant. Pass an optional IANA timezone (e.g. 'America/Sao_Paulo', 'Europe/Lisbon'); defaults to UTC. Never state the date or time from memory \u2014 always call this. Returns { ok: false, error: 'invalid_timezone' } for an unknown timezone.",
     inputSchema: z.object({
       timezone: z.string().optional().describe("IANA timezone, e.g. 'America/Sao_Paulo' or 'Europe/Lisbon'. Defaults to UTC.")
     }),
@@ -718,6 +718,9 @@ function attachChildSettlers(child, gate, onClose, onError, resolve) {
 }
 
 // src/internal/git-exec.ts
+function shq(arg) {
+  return `'${arg.replaceAll("'", `'\\''`)}'`;
+}
 function formatGitResult(result, timeoutMs) {
   if (result.kind === "timeout") {
     return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
@@ -799,9 +802,6 @@ function ehProibidoEmQualquerProfundidade(path) {
 // src/git-diff.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_STDOUT_BYTES = 5 * 1024 * 1024;
-function shq(arg) {
-  return `'${arg.replace(/'/g, `'\\''`)}'`;
-}
 async function diffViaSandbox(sandbox, ctx, cached, path, projectRoot, timeoutMs) {
   const scopeCheck = checkPathScope(path, projectRoot);
   if (scopeCheck !== null) return scopeCheck;
@@ -822,8 +822,8 @@ function createGitDiffTool(opts) {
     sandbox
   } = opts;
   return Tool.create({
-    name: "git_diff",
-    description: "Return the unified diff of the project's working tree (or staged changes when cached=true). Scoped to a single file when 'path' is provided. Requires the project to be a git repository. Returns { ok, diff, truncated? } or { ok: false, error }.",
+    name: opts.name ?? "git_diff",
+    description: opts.description ?? "Return the unified diff of the project's working tree (or staged changes when cached=true). Scoped to a single file when 'path' is provided. Requires the project to be a git repository. Returns { ok, diff, truncated? } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().optional().describe("Optional project-relative file or dir scope."),
       cached: z.boolean().optional().describe("If true, show staged changes (git diff --cached). Default false.")
@@ -857,7 +857,7 @@ function createGitStatusTool(opts) {
     inputSchema: z.object({
       path: z.string().optional().describe("Optional project-relative path to scope the status report.")
     }),
-    handler: async ({ path }) => {
+    handler: async ({ path }, ctx) => {
       if (!existsSync(join(projectRoot, ".git"))) {
         return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
@@ -866,18 +866,31 @@ function createGitStatusTool(opts) {
       const args = ["status", "--porcelain=v1"];
       if (opts.includeBranch !== false) args.push("-b");
       if (path !== void 0 && path !== "") args.push("--", path);
+      if (opts.sandbox !== void 0) {
+        return statusViaSandbox(opts.sandbox, ctx, args, timeoutMs);
+      }
       const result = await runGitProcess(projectRoot, args, timeoutMs, maxStdoutBytes);
       return formatGitResult(result, timeoutMs);
     }
   });
 }
+async function statusViaSandbox(sandbox, ctx, args, timeoutMs) {
+  const command = ["git", ...args].map(shq).join(" ");
+  const backend = await resolveSandbox(sandbox, ctx ?? {});
+  const r = await backend.execute(command, { timeoutMs });
+  if (r.timedOut) return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  if (r.exitCode !== 0) {
+    return /not a git repository/i.test(r.stderr) ? JSON.stringify({ ok: false, error: "not_a_repo" }) : JSON.stringify({ ok: false, error: "git_failed", stderr: r.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: r.stdout, truncated: false });
+}
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
 var MAX_BACKEND_WALK_DEPTH = 64;
 function createGlobTool(opts) {
   const { projectRoot, filesystem } = opts;
   return Tool.create({
-    name: "glob_files",
-    description: "Find files by glob pattern across the project \u2014 fast at any repo size. Use glob_files when you know the filename SHAPE; use search_text when you know the file CONTENT; use read_file when you know the exact path. The pattern supports * and ** wildcards (e.g. '**/*.ts', 'src/**/*.json'); node_modules/.git/dist/.theo are excluded and results are relative paths. Returns { ok, files } or { ok: false, error }.",
+    name: opts.name ?? "glob_files",
+    description: opts.description ?? "Find files by glob pattern across the project \u2014 fast at any repo size. Use glob_files when you know the filename SHAPE; use search_text when you know the file CONTENT; use read_file when you know the exact path. The pattern supports * and ** wildcards (e.g. '**/*.ts', 'src/**/*.json'); node_modules/.git/dist/.theo are excluded and results are relative paths. Returns { ok, files } or { ok: false, error }.",
     inputSchema: z.object({
       pattern: z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: z.string().optional().describe("Project-relative subdirectory to search from.")
@@ -996,8 +1009,8 @@ function toErrorJson(err) {
 function createInteractiveShellTool(opts) {
   const { interactive } = opts;
   return Tool.create({
-    name: "interactive_shell",
-    description: "Start an interactive shell session for a command that PROMPTS for input or is a REPL (python, node, `git rebase -i`, a `read` prompt) \u2014 NOT for one-shot commands (use shell_exec). Returns a session_id; drive it with write_stdin, reading the incremental output each step. Returns { ok, session_id, output } or { ok: false, error }.",
+    name: opts.name ?? "interactive_shell",
+    description: opts.description ?? "Start an interactive shell session for a command that PROMPTS for input or is a REPL (python, node, `git rebase -i`, a `read` prompt) \u2014 NOT for one-shot commands (use shell_exec). Returns a session_id; drive it with write_stdin, reading the incremental output each step. Returns { ok, session_id, output } or { ok: false, error }.",
     inputSchema: z.object({
       command: z.string().min(1).describe("Command to run interactively, e.g. 'python3' or 'bash -i'."),
       yield_time_ms: z.number().int().positive().optional().describe("How long to wait for startup output before returning (clamped by the backend).")
@@ -1701,8 +1714,8 @@ function createPlanModeTool(options) {
   }
   const { artifactStore, artifactId = "plan" } = options;
   return {
-    name: "plan_mode",
-    description: DESCRIPTION,
+    name: options.name ?? "plan_mode",
+    description: options.description ?? DESCRIPTION,
     inputSchema: planModeSchema(true),
     handler: async (input) => {
       if (input.action === "enter") {
@@ -1760,10 +1773,14 @@ function createQuestionTool(opts) {
         setTimeout(() => reject(new Error("timeout")), timeoutMs);
       });
       try {
-        const answer = await Promise.race([askUser(String(input.question ?? "")), timeout]);
+        const answer = await Promise.race([
+          askUser(String(input.question ?? ""), ctx?.threadId),
+          timeout
+        ]);
         return JSON.stringify({ ok: true, answer });
       } catch (err) {
         if (err instanceof Error && err.message === "timeout") {
+          opts.onAbandon?.(ctx?.threadId);
           return JSON.stringify({
             ok: false,
             error: "timeout",
@@ -1808,8 +1825,8 @@ function createReadFileTool(opts) {
   const numbered = lineNumbers === true ? " Returns a cat -n numbered view (`<n>\\t<line>`)." : "";
   const abs = allowAbsolute === true ? " Absolute paths outside the project are honored." : "";
   return Tool.create({
-    name: "read_file",
-    description: "Read a text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly." + numbered + abs + " By default returns the whole file; use the optional offset (1-based first line) + limit to page through a large file, or search_text to locate a symbol. Refuses sensitive files (.env, .git/, node_modules/, .theo/, lock files) and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
+    name: opts.name ?? "read_file",
+    description: opts.description ?? "Read a text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly." + numbered + abs + " By default returns the whole file; use the optional offset (1-based first line) + limit to page through a large file, or search_text to locate a symbol. Refuses sensitive files (.env, .git/, node_modules/, .theo/, lock files) and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("File path (project-relative; absolute when allowed)."),
       offset: z.number().int().min(1).optional().describe("1-based first line to read (default 1)."),
@@ -1983,8 +2000,8 @@ function createRunVitestTool(opts) {
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES2
   } = opts;
   return Tool.create({
-    name: "run_vitest",
-    description: "Run the project's vitest suite, optionally scoped to a file or pattern via 'path'. Returns parsed { ok, summary } or { ok: false, error }. Vitest stdout warnings are stripped \u2014 the parser extracts the trailing JSON report.",
+    name: opts.name ?? "run_vitest",
+    description: opts.description ?? "Run the project's vitest suite, optionally scoped to a file or pattern via 'path'. Returns parsed { ok, summary } or { ok: false, error }. Vitest stdout warnings are stripped \u2014 the parser extracts the trailing JSON report.",
     inputSchema: z.object({
       path: z.string().optional().describe("Optional vitest pattern or file path (project-relative).")
     }),
@@ -2581,8 +2598,8 @@ function createWebFetchTool(opts) {
   const fetchImpl = opts?.fetchImpl;
   const lookup = opts?.lookup;
   return Tool.create({
-    name: "web_fetch",
-    description: "Fetch the contents of a URL via HTTP/HTTPS. Use only for URLs the user provided or that you are confident help with the task; never invent or guess URLs. Rejects non-http(s) URLs and is SSRF-guarded by default (private/loopback/link-local/cloud-metadata hosts are refused with an ssrf_blocked error). The response body is capped at 1 MB. Returns { ok, content, status_code, content_type } or { ok: false, error }.",
+    name: opts?.name ?? "web_fetch",
+    description: opts?.description ?? "Fetch the contents of a URL via HTTP/HTTPS. Use only for URLs the user provided or that you are confident help with the task; never invent or guess URLs. Rejects non-http(s) URLs and is SSRF-guarded by default (private/loopback/link-local/cloud-metadata hosts are refused with an ssrf_blocked error). The response body is capped at 1 MB. Returns { ok, content, status_code, content_type } or { ok: false, error }.",
     inputSchema: z.object({
       url: z.string().min(1).describe("URL to fetch (http or https only)."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000).")
@@ -2668,8 +2685,8 @@ function createWebFetchTool(opts) {
 function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
   return Tool.create({
-    name: "web_search",
-    description: "Search the web for a query \u2014 use when you need current information beyond the repo or your training cutoff (library docs, an error message, an API). Returns a list of results with title, URL, and snippet; follow up with web_fetch on a promising result to read it in full. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
+    name: opts.name ?? "web_search",
+    description: opts.description ?? "Search the web for a query \u2014 use when you need current information beyond the repo or your training cutoff (library docs, an error message, an API). Returns a list of results with title, URL, and snippet; follow up with web_fetch on a promising result to read it in full. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
     inputSchema: z.object({
       query: z.string().min(1).describe("Search query."),
       max_results: z.number().int().positive().max(20).optional().describe("Maximum results to return (default 5, max 20).")
@@ -2755,8 +2772,8 @@ function createWriteFileTool(opts) {
   }
   const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
   return Tool.create({
-    name: "write_file",
-    description: "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the write root and sensitive files (.env, .git/, node_modules/, .theo/, lock files); the default local root also refuses binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
+    name: opts.name ?? "write_file",
+    description: opts.description ?? "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the write root and sensitive files (.env, .git/, node_modules/, .theo/, lock files); the default local root also refuses binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       content: z.string().describe("UTF-8 content to write.")