@wrongstack/tools 0.9.20 → 0.10.0

package/dist/index.js

@@ -2,7 +2,7 @@ import * as fs4 from 'node:fs/promises';
 import { stat } from 'node:fs/promises';
 import * as path from 'node:path';
 import { resolve, sep, dirname } from 'node:path';
-import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, buildChildEnv, stripAnsi, loadPlan, emptyPlan, clearPlan, savePlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, formatPlan } from '@wrongstack/core';
+import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, buildChildEnv, loadPlan, emptyPlan, clearPlan, savePlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, formatPlan, stripAnsi, resolveWstackPaths } from '@wrongstack/core';
 import { spawn, execFileSync, spawnSync } from 'node:child_process';
 import * as os from 'node:os';
 import * as dns from 'node:dns/promises';
@@ -78,24 +78,104 @@ function isBinaryBuffer(buf) {
   }
   return false;
 }
+var COMMAND_OUTPUT_MAX_BYTES = 32768;
+var REPEAT_RUN_THRESHOLD = 3;
+function collapseCarriageReturns(text) {
+  const lf = text.replace(/\r\n/g, "\n");
+  if (!lf.includes("\r")) return lf;
+  return lf.split("\n").map((line) => line.includes("\r") ? line.slice(line.lastIndexOf("\r") + 1) : line).join("\n");
+}
+function collapseConsecutiveDuplicates(text, minRun = REPEAT_RUN_THRESHOLD) {
+  const lines = text.split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    let j = i + 1;
+    while (j < lines.length && lines[j] === lines[i]) j++;
+    const run = j - i;
+    if (run >= minRun) {
+      out.push(lines[i], `\u2026 \u27E8repeated ${run}\xD7\u27E9`);
+    } else {
+      for (let k = i; k < j; k++) out.push(lines[k]);
+    }
+    i = j;
+  }
+  return out.join("\n");
+}
+function takeHeadBytes(s, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(s, "utf8") <= maxBytes) return s;
+  let lo = 0;
+  let hi = s.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (Buffer.byteLength(s.slice(0, mid), "utf8") <= maxBytes) lo = mid;
+    else hi = mid - 1;
+  }
+  return s.slice(0, lo);
+}
+function takeTailBytes(s, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(s, "utf8") <= maxBytes) return s;
+  let lo = 0;
+  let hi = s.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (Buffer.byteLength(s.slice(s.length - mid), "utf8") <= maxBytes) lo = mid;
+    else hi = mid - 1;
+  }
+  return s.slice(s.length - lo);
+}
+function truncateHeadTail(s, maxBytes) {
+  const total = Buffer.byteLength(s, "utf8");
+  if (total <= maxBytes) return s;
+  const MARKER_RESERVE = 64;
+  const avail = Math.max(0, maxBytes - MARKER_RESERVE);
+  const headBudget = Math.floor(avail * 0.45);
+  const head = takeHeadBytes(s, headBudget);
+  const tail = takeTailBytes(s, avail - Buffer.byteLength(head, "utf8"));
+  const kept = Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
+  return `${head}
+\u2026[truncated ${total - kept} bytes]\u2026
+${tail}`;
+}
+function normalizeCommandOutput(raw, opts = {}) {
+  if (!raw) return raw;
+  let text = stripAnsi(raw);
+  text = collapseCarriageReturns(text);
+  text = text.replace(/[ \t]+$/gm, "");
+  text = collapseConsecutiveDuplicates(text);
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return truncateHeadTail(text, opts.maxBytes ?? COMMAND_OUTPUT_MAX_BYTES);
+}
 
 // src/read.ts
 var MAX_BYTES = 5 * 1024 * 1024;
 var readTool = {
   name: "read",
   category: "Filesystem",
-  description: "Read the contents of a file. Lines are 1-indexed and prefixed with line numbers.",
-  usageHint: "Read a file before editing it. Returns lines numbered like `   1\u2192content`. Use `offset` and `limit` for large files (default reads up to 2000 lines).",
+  description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed with a `   N| ` prefix for easy reference in edits.",
+  usageHint: "FOUNDATIONAL TOOL \u2014 call this before almost any edit operation.\n\nBest practices:\n- Always read a file before using `edit`, `replace`, or `write` on it (the system often requires it for safety).\n- Use `offset` + `limit` for very large files instead of reading everything at once.\n- Default limit is generous (2000 lines) but can be increased.\n- The output format is designed to be directly usable as context for `edit` operations.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   maxOutputBytes: 262144,
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
     properties: {
-      path: { type: "string", description: "File path (absolute or relative to cwd)" },
-      offset: { type: "integer", description: "1-based line number to start from" },
-      limit: { type: "integer", description: "Max lines to read (default 2000)" }
+      path: {
+        type: "string",
+        description: "Path to the file (relative to project root or absolute within project)."
+      },
+      offset: {
+        type: "integer",
+        description: "1-based starting line number. Use together with `limit` for large files."
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum number of lines to return (default is 2000)."
+      }
     },
     required: ["path"]
   },
@@ -145,16 +225,23 @@ var readTool = {
 var writeTool = {
   name: "write",
   category: "Filesystem",
-  description: "Write or overwrite a file. For existing files, prefer `edit` over `write`.",
-  usageHint: "Use `write` for new files or full replacements. For partial edits use `edit`. Existing files must have been `read` first in this session.",
+  description: "Write or completely overwrite a file on disk. This is a high-privilege operation. For modifying existing files, you should almost always prefer the `edit` tool instead, because `edit` is safer and works on the last-read version of the file.",
+  usageHint: "RULES FOR CORRECT USAGE:\n- Use `write` primarily for **new files** or when you want to replace the entire content.\n- For any existing file, strongly prefer `edit` (it requires a prior `read` in the same session and is more precise).\n- You MUST have called `read` on the file earlier in the conversation before using `write` on an existing path (the system enforces this for safety).\n- The path is resolved relative to the project root and protected against escaping the workspace.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 5e3,
+  capabilities: ["fs.write"],
   inputSchema: {
     type: "object",
     properties: {
-      path: { type: "string" },
-      content: { type: "string" }
+      path: {
+        type: "string",
+        description: "Relative path from project root. Must not escape the project."
+      },
+      content: {
+        type: "string",
+        description: "The complete new content of the file."
+      }
     },
     required: ["path", "content"]
   },
@@ -202,10 +289,11 @@ var writeTool = {
 var editTool = {
   name: "edit",
   category: "Filesystem",
-  description: "Make a surgical edit by replacing exact text. Fails if `old_string` is not unique unless `replace_all` is true.",
-  usageHint: "Always `read` the file first. `old_string` must be an EXACT match (whitespace included). If multiple matches exist, either narrow `old_string` with more context or set `replace_all: true`.",
+  description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It requires that you have previously called `read` on the file in the current session. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
+  usageHint: "MANDATORY WORKFLOW:\n1. Call `read` on the target file first (in the same conversation).\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nThis tool is much safer than `write` for existing files because it works against the last-read version.",
   permission: "confirm",
   mutating: true,
+  capabilities: ["fs.write"],
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -367,10 +455,11 @@ var DEFAULT_IGNORE = ["node_modules", ".git", "dist", "build", ".next", "coverag
 var replaceTool = {
   name: "replace",
   category: "Transform",
-  description: "Batch replace a pattern across multiple files matched by glob. Returns diff for each modified file.",
-  usageHint: 'Use `glob` for broad patterns (e.g. "**/*.ts"). Set `dry_run: true` to preview without modifying. `files` can be a single path, comma-separated list, or glob pattern.',
+  description: "Perform a search-and-replace across multiple files using a regex pattern. This is a powerful bulk transformation tool. Always use `dry_run: true` first on anything non-trivial.",
+  usageHint: "DANGEROUS IF USED CARELESSLY \u2014 review the diff output carefully.\n\nRecommended workflow:\n1. Start with `dry_run: true` to see exactly what would change.\n2. Use a specific enough `pattern` (and `glob` / `files`) to avoid accidental broad changes.\n3. `replace_all` controls whether only the first match per file or all matches are replaced.\nThis tool is excellent for large-scale refactors (renaming, import updates, etc.) but must be used with caution.",
   permission: "confirm",
   mutating: true,
+  capabilities: ["fs.write"],
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -562,18 +651,28 @@ var DEFAULT_IGNORE2 = ["node_modules", ".git", "dist", "build", ".next", "covera
 var globTool = {
   name: "glob",
   category: "Filesystem",
-  description: "Find files matching a glob pattern. Returns paths sorted by mtime (newest first).",
-  usageHint: "Examples: `**/*.ts`, `src/**/*.test.ts`, `*.json`. Common dirs (node_modules, .git, dist) are ignored by default. Returns up to 1000 paths.",
+  description: "Find files matching a glob pattern. Fast way to discover relevant files before reading, grepping, or editing them.",
+  usageHint: "RECOMMENDED FOR SCOPING SEARCHES:\n\n- Use early to get a list of files you actually care about.\n- Combine with `path` and `limit`.\n- Default ignores common build/dependency directories.\nMuch more efficient than shell `find` for most use cases inside the agent.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   maxOutputBytes: 65536,
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
     properties: {
-      pattern: { type: "string" },
-      path: { type: "string", description: "Base directory (defaults to cwd)" },
-      limit: { type: "integer" }
+      pattern: {
+        type: "string",
+        description: 'Glob pattern to match (e.g. "**/*.ts", "src/**").'
+      },
+      path: {
+        type: "string",
+        description: "Base directory to search from (defaults to project root)."
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum number of results to return (default 1000, max 5000)."
+      }
     },
     required: ["pattern"]
   },
@@ -637,22 +736,45 @@ var DEFAULT_IGNORE3 = ["node_modules", ".git", "dist", "build", ".next", "covera
 var grepTool = {
   name: "grep",
   category: "Search",
-  description: "Search file contents with a regex. Uses ripgrep when available.",
-  usageHint: 'Pattern is regex. Use `output_mode: "content"` for matched lines, `"files_with_matches"` for paths, `"count"` for tallies. `glob` filters files (e.g. `*.ts`).',
+  description: "Search across files using a regular expression. This is one of the primary code search tools. Prefers ripgrep for speed and features when available.",
+  usageHint: 'POWERFUL CODE SEARCH TOOL:\n\n- `pattern` is a regular expression.\n- Use `output_mode: "content"` (default) to get matching lines with context.\n- Use `"files_with_matches"` when you only need the list of files.\n- Use `"count"` for quick statistics.\n- `glob` and `path` let you narrow the search scope significantly.\n- Always prefer this over `bash grep` when searching code.',
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   maxOutputBytes: 131072,
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
     properties: {
-      pattern: { type: "string" },
-      path: { type: "string" },
-      glob: { type: "string" },
-      output_mode: { type: "string", enum: ["content", "files_with_matches", "count"] },
-      context_lines: { type: "integer" },
-      case_insensitive: { type: "boolean" },
-      limit: { type: "integer" }
+      pattern: {
+        type: "string",
+        description: "Regular expression pattern to search for in file contents."
+      },
+      path: {
+        type: "string",
+        description: "Limit search to this directory or file (relative to project root)."
+      },
+      glob: {
+        type: "string",
+        description: 'Glob filter for which files to include (e.g. "**/*.ts", "src/**").'
+      },
+      output_mode: {
+        type: "string",
+        enum: ["content", "files_with_matches", "count"],
+        description: "Return style: detailed matches, just file list, or count only."
+      },
+      context_lines: {
+        type: "integer",
+        description: "How many lines of surrounding context to include with each match."
+      },
+      case_insensitive: {
+        type: "boolean",
+        description: "Ignore case when matching."
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum number of matches to return."
+      }
     },
     required: ["pattern"]
   },
@@ -1250,23 +1372,33 @@ var STREAM_FLUSH_BYTES = 4 * 1024;
 var bashTool = {
   name: "bash",
   category: "Shell",
-  description: "Run a shell command. stdout and stderr are merged.",
-  usageHint: "Runs via `bash -c` (or `cmd /c` on Windows). Cwd is the project root. Default timeout 30s. Output truncated from the middle if oversized. Use for git, npm, builds, tests.",
+  description: "Execute an arbitrary command in the user's default shell (bash/zsh/pwsh/cmd). stdout and stderr are merged into one stream. This is the most powerful and dangerous tool \u2014 it gives the model full access to the developer's machine. Prefer specialized tools whenever possible.",
+  usageHint: "SECURITY WARNING: This tool runs with the full privileges of the current user.\n\nBest practices for the model:\n- Strongly prefer `exec` for known safe commands (node, npm, pnpm, tsc, git, etc.).\n- Use bash only when you genuinely need shell features (pipes, redirection, complex one-liners).\n- Prefer single focused commands over huge `&&` chains.\n- Use `background: true` only for long-running processes (dev servers, watchers).\n- The working directory is the project root.\n- Output may be truncated in the middle for very large results.",
   permission: "confirm",
   mutating: true,
   // Trust rules match on the literal `command` string. Without subjectKey
   // the policy heuristic would have done the same here, but declaring it
   // explicitly removes the implicit cross-tool aliasing.
   subjectKey: "command",
+  capabilities: ["shell.arbitrary"],
   timeoutMs: 3e4,
   maxOutputBytes: MAX_OUTPUT,
   estimatedDurationMs: 3e3,
   inputSchema: {
     type: "object",
     properties: {
-      command: { type: "string" },
-      timeout_ms: { type: "integer" },
-      background: { type: "boolean" }
+      command: {
+        type: "string",
+        description: "The exact shell command to run. Prefer simple, focused commands."
+      },
+      timeout_ms: {
+        type: "integer",
+        description: "Optional timeout for this specific command in milliseconds."
+      },
+      background: {
+        type: "boolean",
+        description: "If true, launch the process in the background and return the PID immediately."
+      }
     },
     required: ["command"]
   },
@@ -1348,7 +1480,7 @@ var bashTool = {
       yield {
         type: "final",
         output: {
-          output: truncated ? buf2.slice(0, MAX_OUTPUT) + "\u2026[truncated]" : buf2,
+          output: normalizeCommandOutput(buf2),
           exit_code: null,
           timed_out: false,
           pid: pid2
@@ -1475,11 +1607,10 @@ var bashTool = {
           if (remainder !== null) {
             yield { type: "partial_output", text: remainder };
           }
-          const cleaned = stripAnsi(buf).replace(/\r\n?/g, "\n");
           yield {
             type: "final",
             output: {
-              output: truncateMiddle(cleaned, MAX_OUTPUT),
+              output: normalizeCommandOutput(buf),
               exit_code: c.code,
               timed_out: timedOut
             }
@@ -1600,18 +1731,32 @@ function validateArgs(cmd, args) {
 var execTool = {
   name: "exec",
   category: "Shell",
-  description: "Restricted shell that only runs pre-approved commands with constrained arguments. Safer alternative to `bash`.",
-  usageHint: "Set `command` (must be in allowlist). `args` passed through. For arbitrary shell access use the `bash` tool instead.",
+  description: "Execute a **whitelisted, restricted set of commands** with strict argument validation. This is the **preferred and safer** alternative to the `bash` tool for running development tools (node, npm, pnpm, tsc, git, tests, linters, etc.). It prevents arbitrary command injection and limits what the model can do.",
+  usageHint: "PREFERRED SHELL TOOL for most cases.\n\nUse this instead of `bash` whenever possible.\n- `command` must be one of the allowed commands (node, npm, pnpm, git, tsc, eslint, vitest, etc.).\n- Arguments are passed as a clean array (no shell interpretation).\n- `cwd` is validated to stay inside the project.\n- For anything that requires real shell features (pipes, complex redirection, arbitrary commands), fall back to `bash` (with strong justification).\nThis tool significantly reduces the risk compared to full shell access.",
   permission: "confirm",
   mutating: true,
   timeoutMs: TIMEOUT_MS,
+  capabilities: ["shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
-      command: { type: "string", description: "Command to run (must be in allowlist)" },
-      args: { type: "array", items: { type: "string" }, description: "Arguments" },
-      cwd: { type: "string", description: "Working directory (must resolve inside project root)" },
-      timeout: { type: "integer", description: "Timeout in ms (default: 30000)" }
+      command: {
+        type: "string",
+        description: 'The base command to run. Must be in the internal allowlist (e.g. "node", "pnpm", "git", "tsc").'
+      },
+      args: {
+        type: "array",
+        items: { type: "string" },
+        description: "Arguments passed to the command. Passed as an array (no shell parsing)."
+      },
+      cwd: {
+        type: "string",
+        description: "Optional working directory. Must resolve inside the project root."
+      },
+      timeout: {
+        type: "integer",
+        description: "Per-command timeout in milliseconds."
+      }
     },
     required: ["command"]
   },
@@ -1720,10 +1865,10 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       resolve7({
         command: cmd,
         args,
-        stdout: stdout.slice(0, MAX_OUTPUT2),
-        stderr: stderr.slice(0, MAX_OUTPUT2),
+        stdout: normalizeCommandOutput(stdout),
+        stderr: normalizeCommandOutput(stderr),
         exitCode,
-        truncated: stdout.length >= MAX_OUTPUT2 || stderr.length >= MAX_OUTPUT2,
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES || Buffer.byteLength(stderr, "utf8") > COMMAND_OUTPUT_MAX_BYTES,
         allowed: true
       });
     });
@@ -1734,10 +1879,10 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       resolve7({
         command: cmd,
         args,
-        stdout: stdout.slice(0, MAX_OUTPUT2),
+        stdout: normalizeCommandOutput(stdout),
         stderr: err.message,
         exitCode: 1,
-        truncated: false,
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES,
         allowed: true
       });
     });
@@ -1827,10 +1972,11 @@ async function guardedFetch(url, maxRedirects, signal, headers = {
 var fetchTool = {
   name: "fetch",
   category: "Network",
-  description: "Fetch the contents of a URL. HTML is converted to markdown by default.",
-  usageHint: "HTTPS only by default. Localhost and RFC1918 ranges blocked unless WRONGSTACK_FETCH_ALLOW_PRIVATE=1. Max 5 redirects, 20s timeout, 128KB cap.",
+  description: "Fetch a URL and return its content. HTML pages are automatically converted to clean markdown. This tool has strong SSRF protections (private IPs, localhost, and cloud metadata endpoints are blocked by default).",
+  usageHint: "Use this when you need external information (documentation, API responses, web pages, etc.).\n\nSecurity notes:\n- Only HTTPS is allowed by default.\n- Internal/private networks are blocked unless explicitly enabled via environment variable.\n- Redirects are followed but re-validated at each hop.\n- Output is capped (128KB by default) to avoid flooding context.\nPrefer this over raw `bash curl` or `bash wget`.",
   permission: "confirm",
   mutating: false,
+  capabilities: ["net.outbound"],
   // Trust rules for fetch match on the literal URL — declare it explicitly
   // so a user can trust `https://api.example.com/*` without accidentally
   // matching that pattern on any other tool that happens to have a `url`
@@ -1841,8 +1987,15 @@ var fetchTool = {
   inputSchema: {
     type: "object",
     properties: {
-      url: { type: "string" },
-      format: { type: "string", enum: ["markdown", "text", "raw"] }
+      url: {
+        type: "string",
+        description: "The target URL (must use https://)."
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "text", "raw"],
+        description: 'Output format. "markdown" is recommended for HTML pages.'
+      }
     },
     required: ["url"]
   },
@@ -2082,10 +2235,11 @@ var TIMEOUT_MS3 = 15e3;
 var searchTool = {
   name: "search",
   category: "Search",
-  description: "Search the web for information. Returns title, URL, and snippet for each result.",
-  usageHint: "Set `num_results` (1-50, default 10). Use `source` to pick engine: duckduckgo (default), google, bing.",
+  description: "Perform a web search and return results with title, URL, and snippet. Use this when you need up-to-date external information that is not in the local codebase.",
+  usageHint: "Good for: API documentation, error messages, library usage examples, current best practices.\n\n- Prefer specific queries over very broad ones.\n- Results go through the guarded fetch system (same protections as the `fetch` tool).\n- This is often better than the model trying to recall outdated knowledge.",
   permission: "confirm",
   mutating: false,
+  capabilities: ["net.outbound"],
   timeoutMs: TIMEOUT_MS3,
   inputSchema: {
     type: "object",
@@ -2290,8 +2444,8 @@ function stripTags2(html) {
 var todoTool = {
   name: "todo",
   category: "Session",
-  description: "Replace the current todo list with a new set of items.",
-  usageHint: "Use for multi-step tasks. Replace the full list on each call. At most ONE task may be in_progress at a time. Items have id, content, status (pending|in_progress|completed), and optional activeForm.",
+  description: "Manage the session-level todo list. This is the primary mechanism for tracking multi-step work. The list is fully replaced on every call (not appended).",
+  usageHint: "BEST PRACTICE for complex tasks:\n- At the beginning of a non-trivial task, create a clear todo list with specific, actionable items.\n- Only **one** item should be `in_progress` at any time.\n- Update the list frequently as work progresses (mark items done, add new ones, change status).\n- The system and user can see this list, so keep it honest and up-to-date.\nThis tool is extremely valuable for maintaining focus and giving the user visibility into your plan.",
   permission: "auto",
   mutating: false,
   timeoutMs: 1e3,
@@ -2303,13 +2457,27 @@ var todoTool = {
         items: {
           type: "object",
           properties: {
-            id: { type: "string" },
-            content: { type: "string" },
-            status: { type: "string", enum: ["pending", "in_progress", "completed"] },
-            activeForm: { type: "string" }
+            id: {
+              type: "string",
+              description: 'Unique identifier for the todo item (e.g. "1", "auth-flow").'
+            },
+            content: {
+              type: "string",
+              description: "Clear, actionable description of the task."
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "in_progress", "completed"],
+              description: 'Current status. Only one item should be "in_progress" at a time.'
+            },
+            activeForm: {
+              type: "string",
+              description: 'Optional present-tense form shown while the task is active (e.g. "Fixing auth bug").'
+            }
           },
           required: ["id", "content", "status"]
-        }
+        },
+        description: "The complete new list of todos. This replaces the previous list entirely."
       }
     },
     required: ["todos"]
@@ -2339,8 +2507,8 @@ var todoTool = {
 var planTool = {
   name: "plan",
   category: "Session",
-  description: "Inspect or edit the strategic plan board for this session. Plans persist across resume (unlike todos). Use this to lay out the multi-step approach before diving in, then mark steps in_progress/done as the work proceeds. Promote a plan item to todos to start working on it. Apply templates for common workflows.",
-  usageHint: 'Set action to one of: show | add | start | done | remove | promote | derive | template_use | clear. Pass `title` for add. Pass `target` (item id, 1-based index, or title substring) for start/done/remove/promote/derive. Pass `subtasks` for promote/derive to break the plan item into multiple todos. Pass `template` (e.g. "new-feature", "bug-fix", "refactor", "release") for template_use. Always returns the formatted plan plus open/total counts.',
+  description: "Manage a persistent strategic plan for the current session. Unlike todos, plans are meant for higher-level, multi-phase approaches and survive across conversation resumptions. Use this to outline big-picture work, then promote concrete items into the todo list when ready to execute.",
+  usageHint: 'RECOMMENDED FOR COMPLEX, MULTI-PHASE WORK:\n\n- Start by creating a high-level plan with `action: "add"` or using templates (`template_use`).\n- Use `promote` to turn a plan item into actionable todos.\n- Keep plans at the "why and what" level, and todos at the "how and next step" level.\n- Common templates: "new-feature", "bug-fix", "refactor", "release", "security-audit".\n\nThis tool is excellent for maintaining long-term direction across many turns or even multiple sessions.',
   permission: "auto",
   mutating: false,
   timeoutMs: 2e3,
@@ -2349,22 +2517,29 @@ var planTool = {
     properties: {
       action: {
         type: "string",
-        enum: ["show", "add", "start", "done", "remove", "promote", "derive", "template_use", "clear"]
+        enum: ["show", "add", "start", "done", "remove", "promote", "derive", "template_use", "clear"],
+        description: "The operation to perform on the plan board."
+      },
+      title: {
+        type: "string",
+        description: "Title of the plan item. Required for action=add."
+      },
+      details: {
+        type: "string",
+        description: "Additional details or description for a new plan item (action=add)."
       },
-      title: { type: "string", description: "Required when action = add." },
-      details: { type: "string", description: "Optional extra context for add." },
       target: {
         type: "string",
-        description: "Plan item id, 1-based index, or title substring. Required for start/done/remove/promote/derive."
+        description: "Identifier for the target plan item (id, 1-based index, or partial title). Required for most actions except add/show/clear."
       },
       subtasks: {
         type: "array",
         items: { type: "string" },
-        description: "Optional subtasks for promote/derive. If omitted, a single todo is created from the plan item title."
+        description: "List of subtask titles. Used with promote or derive to break a plan item into multiple todos."
       },
       template: {
         type: "string",
-        description: "Template name for template_use action. Available: new-feature, bug-fix, refactor, release, security-audit, onboarding."
+        description: "Template identifier when using action=template_use. Common values: new-feature, bug-fix, refactor, release, security-audit."
       }
     },
     required: ["action"]
@@ -2478,13 +2653,14 @@ var MAX_OUTPUT3 = 1e5;
 var gitTool = {
   name: "git",
   category: "Git",
-  description: "Run git commands. Wraps common operations: status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset, worktree.",
-  usageHint: "Prefer built-in subcommands over raw args. `command` is required. `message` for commits. `branch` for checkout/branch. `files` for status/diff. `format` for log.",
+  description: "Safe wrapper around common git operations. Supports status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset, worktree, etc. This is the preferred way to interact with git instead of using the raw `bash` or `exec` tools.",
+  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
   permission: "confirm",
   // Conservative: any of these may mutate. The non-mutating commands
   // (status/log/diff/branch/fetch) are still gated on `permission: 'confirm'`
   // and `MUTATING_SUBCOMMANDS` is consulted at runtime for per-call checks.
   mutating: true,
+  capabilities: ["fs.write", "shell.restricted"],
   timeoutMs: TIMEOUT_MS4,
   inputSchema: {
     type: "object",
@@ -2699,19 +2875,19 @@ function runGit(args, cwd, signal) {
     child.on("error", (err) => {
       resolve7({
         command: args[0],
-        stdout,
+        stdout: normalizeCommandOutput(stdout),
         stderr: err.message,
         exitCode: 1,
-        truncated: stdout.length >= MAX_OUTPUT3
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES
       });
     });
     child.on("close", (code) => {
       resolve7({
         command: args[0],
-        stdout: stdout.slice(0, MAX_OUTPUT3),
-        stderr: stderr.slice(0, MAX_OUTPUT3),
+        stdout: normalizeCommandOutput(stdout),
+        stderr: normalizeCommandOutput(stderr),
         exitCode: code ?? 1,
-        truncated: stdout.length >= MAX_OUTPUT3 || stderr.length >= MAX_OUTPUT3
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES || Buffer.byteLength(stderr, "utf8") > COMMAND_OUTPUT_MAX_BYTES
       });
     });
   });
@@ -2719,10 +2895,11 @@ function runGit(args, cwd, signal) {
 var patchTool = {
   name: "patch",
   category: "Filesystem",
-  description: "Apply a unified diff patch to files. Writes .orig and .rej files on failure.",
-  usageHint: "Set `patch` (the diff text). `directory` defaults to cwd. `strip` removes leading path components. `dry_run` previews.",
+  description: "Apply a unified diff (patch) to the project. This is the correct tool when you have a diff that needs to be applied precisely, including handling of rejects.",
+  usageHint: "Best used when you already have a diff (from generation, external source, or previous step).\n- Use `dry_run: true` to see what would happen without modifying files.\n- On failure it creates .rej and .orig files for manual review.\nOften cleaner than many small `edit` operations for larger changes.",
   permission: "confirm",
   mutating: true,
+  capabilities: ["fs.write"],
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -2828,8 +3005,8 @@ function extractPatchedFiles(output) {
 var jsonTool = {
   name: "json",
   category: "Data",
-  description: "Parse, query, and validate JSON/JSON5/YAML. Use `query` with JMESPath-like paths to extract values.",
-  usageHint: 'Provide `file` path or `data` string. `query` supports dot notation (e.g. "results[0].name"). `format` outputs in specified format.',
+  description: "Parse, pretty-print, query, and convert between JSON, JSON5, and YAML. Supports simple path-based queries.",
+  usageHint: "VERY USEFUL FOR DATA INSPECTION:\n\n- Use on package.json, tsconfig, config files, or any structured data.\n- `query` lets you extract specific values without reading the whole file.\n- Great for validating that a file has the expected structure.\nPrefer this over raw `read` + manual parsing when dealing with configuration or data files.",
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
@@ -2949,28 +3126,44 @@ function toYaml(data, indent = 0) {
 var diffTool = {
   name: "diff",
   category: "Filesystem",
-  description: "Show differences between files, commits, or branches. Supports staged vs working tree.",
-  usageHint: "Use `files` for file paths, `a`/`b` for commit refs, `staged` for git index. `mode`: unified (default), stat, side-by-side.",
+  description: "Show code differences between files, commits, branches, or staged changes. A safer and more structured alternative to raw `git diff` via shell.",
+  usageHint: 'USE FOR CODE REVIEW AND CHANGE INSPECTION:\n\n- `files` + no `a`/`b` \u2192 diff working tree vs HEAD for those files.\n- `a` and/or `b` \u2192 git-style commit/branch diff.\n- `staged: true` \u2192 only show staged changes.\n- `mode` can be "unified", "stat", or "side-by-side".\nThis tool has important safety guards against flag injection (see previous security findings).',
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
     properties: {
-      path: { type: "string", description: "Working directory for diff" },
+      path: {
+        type: "string",
+        description: "Working directory for the diff operation (defaults to project root)."
+      },
       files: {
         type: "string",
-        description: 'File(s) to diff: single path, comma-separated, or "**/*.ts" glob'
+        description: 'Files or globs to diff (e.g. "src/**/*.ts" or comma-separated list).'
+      },
+      a: {
+        type: "string",
+        description: "First ref/commit/branch for git diff (e.g. HEAD, main, a commit hash)."
+      },
+      b: {
+        type: "string",
+        description: "Second ref/commit/branch for git diff."
+      },
+      staged: {
+        type: "boolean",
+        description: "If true, only show changes that are staged in git."
       },
-      a: { type: "string", description: "First commit/branch/ref (for git diff)" },
-      b: { type: "string", description: "Second commit/branch/ref (for git diff)" },
-      staged: { type: "boolean", description: "Diff staged changes only" },
       mode: {
         type: "string",
         enum: ["unified", "side-by-side", "stat"],
-        description: "Output mode (default: unified)"
+        description: 'Output format. "unified" is default, "stat" shows summary only.'
       },
-      context: { type: "integer", description: "Context lines for unified diff (default: 3)" }
+      context: {
+        type: "integer",
+        description: "Number of context lines for unified diffs (default: 3)."
+      }
     }
   },
   async execute(input, ctx, opts) {
@@ -3089,34 +3282,41 @@ var DEFAULT_IGNORE4 = [
 var treeTool = {
   name: "tree",
   category: "Filesystem",
-  description: "Display directory structure as an ASCII tree. Shows files and folders with indentation.",
-  usageHint: "Set `path` (default: cwd). `depth` limits nesting (default: 3). `glob` filters files. `exclude` ignores dirs. `show_files` toggles file listing (default: true).",
+  description: "Display a directory tree of the project (or a subpath). This is the recommended way to explore the high-level structure of a codebase before reading specific files.",
+  usageHint: "BEST PRACTICE FOR INITIAL EXPLORATION:\n\n- Call early when working with an unfamiliar project or module.\n- Tune `depth` (default 3) and use `glob`/`exclude` to focus the view.\n- Prefer this over raw `bash find` or `glob` + manual reading when you need a quick structural overview.\nOutput is truncated for very large trees.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 15e3,
   inputSchema: {
     type: "object",
     properties: {
-      path: { type: "string", description: "Root directory (default: cwd)" },
+      path: {
+        type: "string",
+        description: "Root directory to display the tree from (defaults to project root)."
+      },
       depth: {
         type: "integer",
-        description: "Max nesting depth (default: 3, 0 for unlimited)",
+        description: "Maximum directory depth to traverse (default 3, use 0 for unlimited).",
         minimum: 0,
         maximum: 20
       },
-      glob: { type: "string", description: 'Filter files matching glob (e.g. "*.ts")' },
+      glob: {
+        type: "string",
+        description: "Only include files matching this glob pattern."
+      },
       exclude: {
         type: "array",
         items: { type: "string" },
-        description: "Directory names to exclude"
+        description: "List of directory names to completely ignore."
       },
       show_files: {
         type: "boolean",
-        description: "Show files (default: true, false shows dirs only)"
+        description: "Whether to show individual files (default true)."
       },
       show_dirs: {
         type: "boolean",
-        description: "Show directories (default: true)"
+        description: "Whether to show directories (default true)."
       },
       show_hidden: {
         type: "boolean",
@@ -3324,8 +3524,8 @@ async function* spawnStream(opts) {
 var lintTool = {
   name: "lint",
   category: "Code Quality",
-  description: "Run a linter on files. Auto-detects biome, eslint, or tslint. Use `fix` to auto-fix issues.",
-  usageHint: "Set `files` (glob or comma-separated). `fix` applies corrections. `linter` forces specific tool.",
+  description: "Run the project linter (primarily Biome in this repo). Detects style violations, potential bugs, and formatting issues.",
+  usageHint: "RUN OFTEN DURING DEVELOPMENT:\n\n- `fix: true` will automatically correct what it can.\n- Target specific files or globs when you only want to check part of the project.\nThis is a fast and important quality gate. Use it before typecheck in most workflows.",
   permission: "confirm",
   mutating: false,
   timeoutMs: 6e4,
@@ -3390,7 +3590,7 @@ var lintTool = {
         files_checked: input.files ? Array.isArray(input.files) ? input.files.length : input.files.split(",").length : 0,
         errors,
         warnings,
-        output: result.stdout,
+        output: normalizeCommandOutput(result.stdout),
         fix_applied: input.fix ?? false,
         truncated: result.truncated
       }
@@ -3416,8 +3616,8 @@ async function detectLinter(cwd) {
 var formatTool = {
   name: "format",
   category: "Code Quality",
-  description: "Format files with biome or prettier. Use `check` to verify without modifying.",
-  usageHint: "Set `files` (glob or comma-separated). `check` only validates. `fixer` forces tool.",
+  description: "Format source files according to project style (Biome). Can also run in check-only mode.",
+  usageHint: "RUN REGULARLY:\n\n- Use on changed files before committing.\n- `check: true` verifies formatting without making changes (useful in CI-like flows).\nThis project has very consistent formatting expectations. Always ensure your changes are formatted.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 6e4,
@@ -3490,7 +3690,7 @@ var formatTool = {
         fixer: detected,
         files_checked: 0,
         files_changed: changed,
-        output: result.stdout || result.stderr || result.error || "",
+        output: normalizeCommandOutput(result.stdout || result.stderr || result.error || ""),
         truncated: result.truncated
       }
     };
@@ -3513,8 +3713,8 @@ async function detectFixer(cwd) {
 var typecheckTool = {
   name: "typecheck",
   category: "Code Quality",
-  description: "Run TypeScript type checking with `tsc --noEmit`. Checks for type errors without compiling.",
-  usageHint: "Set `project` for tsconfig path (default: nearest). `strict` enables strictest flags. `all` checks all projects in workspace.",
+  description: "Run the project's TypeScript type checker (`tsc --noEmit` or equivalent). Essential for verifying type safety before making changes or committing.",
+  usageHint: "ALWAYS RUN BEFORE CONSIDERING WORK COMPLETE:\n\n- Use this to catch type errors early.\n- In monorepos, `all: true` will check every package.\n- This is one of the most important quality gates in this project.\nNever claim a task is done without a clean typecheck (unless the user explicitly says otherwise).",
   permission: "confirm",
   mutating: false,
   timeoutMs: 12e4,
@@ -3572,7 +3772,7 @@ var typecheckTool = {
         exit_code: result.exitCode,
         errors,
         warnings,
-        output: result.stdout || result.stderr || result.error || "",
+        output: normalizeCommandOutput(result.stdout || result.stderr || result.error || ""),
         truncated: result.truncated
       }
     };
@@ -3593,8 +3793,8 @@ async function findTsConfig(cwd) {
 var testTool = {
   name: "test",
   category: "Code Quality",
-  description: "Run tests with vitest, jest, or mocha. Returns pass/fail counts and output.",
-  usageHint: "Set `files` for specific tests. `watch` enables watch mode. `coverage` generates coverage report. `grep` filters by name.",
+  description: "Execute the project's test suite. This is one of the most critical tools for validating that your changes are correct.",
+  usageHint: "ESSENTIAL BEFORE CONSIDERING WORK DONE:\n\n- Use `files` or `grep` to run only relevant tests during development.\n- `coverage: true` is useful when working on critical paths.\nRun tests frequently. A clean test run is usually required before the task can be considered complete.",
   permission: "confirm",
   mutating: false,
   timeoutMs: 12e4,
@@ -3732,7 +3932,7 @@ function parseResult(runner, result, duration) {
     passed,
     failed,
     duration_ms: duration,
-    output: result.stdout || result.error || "",
+    output: normalizeCommandOutput(result.stdout || result.error || ""),
     truncated: result.truncated
   };
 }
@@ -3741,11 +3941,12 @@ function parseResult(runner, result, duration) {
 var installTool = {
   name: "install",
   category: "Package Management",
-  description: "Install npm packages. Detects pnpm/npm/yarn and uses the right package manager.",
-  usageHint: "Set `packages` to install. `save` as dependency type. `global` for global install. `dry_run` to preview.",
+  description: "Install, update or manage packages using the detected package manager (pnpm/npm/yarn). Strongly preferred over raw shell commands for dependency management because it is structured and safer.",
+  usageHint: "ALWAYS USE THIS INSTEAD OF BASH FOR PACKAGE WORK:\n\n- Empty `packages` \u2192 normal `install` (respects lockfile).\n- Provide names \u2192 adds/updates specific packages.\n- `dry_run: true` for safe preview.\n- Set `save` appropriately.\nThis tool has proper capability declaration and is heavily recommended in the security posture of the project.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 12e4,
+  capabilities: ["package.install", "shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
@@ -3756,14 +3957,20 @@ var installTool = {
       save: {
         type: "string",
         enum: ["dependency", "dev", "optional"],
-        description: "Save as regular, dev, or optional dependency"
+        description: 'Where to save the package(s): "dependency", "devDependencies", or "optionalDependencies".'
+      },
+      cwd: {
+        type: "string",
+        description: "Working directory for the install command (must stay inside project)."
       },
-      cwd: { type: "string", description: "Working directory (default: cwd)" },
       dry_run: {
         type: "boolean",
-        description: "Preview install without modifying (default: false)"
+        description: "If true, show what would be installed without actually modifying package.json or node_modules."
       },
-      global: { type: "boolean", description: "Install globally (default: false)" }
+      global: {
+        type: "boolean",
+        description: "Whether to perform a global install (use with caution)."
+      }
     }
   },
   async execute(input, ctx, opts) {
@@ -3827,7 +4034,7 @@ var installTool = {
       output: {
         packages: pkgList,
         exit_code: result.exitCode,
-        output: result.stdout || result.stderr || result.error || "",
+        output: normalizeCommandOutput(result.stdout || result.stderr || result.error || ""),
         dry_run: args.includes("--dry-run"),
         truncated: result.truncated
       }
@@ -3853,8 +4060,8 @@ async function detectPackageManager(cwd) {
 var auditTool = {
   name: "audit",
   category: "Package Management",
-  description: "Run npm/pnpm security audit. Returns vulnerabilities sorted by severity.",
-  usageHint: "Set `level` to filter minimum severity. `fix` attempts auto-fix. `packages` checks specific packages.",
+  description: "Run a security audit against project dependencies (using pnpm/npm audit). Reports known vulnerabilities with severity.",
+  usageHint: "CRITICAL SECURITY TOOL:\n\n- Run regularly and especially before any release.\n- Use `level` to focus on high/critical issues.\n- `fix` can attempt automatic remediation for some vulnerabilities.\nThis is one of the most important tools for supply chain security.",
   permission: "confirm",
   mutating: false,
   timeoutMs: 6e4,
@@ -3961,8 +4168,8 @@ function parseAuditOutput(json, exitCode) {
 var outdatedTool = {
   name: "outdated",
   category: "Package Management",
-  description: "Check for outdated npm packages. Shows current, wanted, and latest versions.",
-  usageHint: "Set `check` to filter specific packages. `format` as list or table. `include_deprecated` shows deprecated packages.",
+  description: "Check for outdated dependencies in the project. Reports current, wanted (semver range), and latest versions available.",
+  usageHint: "MAINTENANCE & SECURITY TOOL:\n\n- Run periodically or before dependency-related work.\n- Helps surface packages that may need updates for security or features.\n- Safe, read-only operation.\nUse the output to decide on upgrades. Prefer this over manual shell commands for dependency hygiene.",
   permission: "auto",
   mutating: true,
   timeoutMs: 6e4,
@@ -4071,8 +4278,8 @@ function parseOutdatedOutput(json, exitCode) {
 var logsTool = {
   name: "logs",
   category: "Logs",
-  description: "Stream or fetch logs from a service or file. Supports Docker, systemd, or plain log files.",
-  usageHint: "Set `service` for Docker/systemd, `path` for file. `lines` limits output. `stream` for tail -f behavior. `filter` regex filters lines.",
+  description: "Read or stream logs from files, Docker containers, or systemd services. Useful for debugging running applications.",
+  usageHint: "DEBUGGING TOOL \u2014 USE CAREFULLY IN AUTONOMOUS MODE:\n\n- Prefer `path` for local files or `service` for containers/systemd.\n- `stream: true` = live tail (can be expensive).\n- Always use `filter` (regex) when possible to reduce noise and token usage.\n- Long-running streams should be avoided unless the user explicitly wants live logs.",
   permission: "confirm",
   mutating: false,
   timeoutMs: 3e4,
@@ -4272,8 +4479,8 @@ function parseLine(line) {
 var documentTool = {
   name: "document",
   category: "Project",
-  description: "Generate or update documentation comments for functions, classes, and types. Supports JSDoc, TSDoc, and block comments.",
-  usageHint: "Set `target` for what to document. `files` for paths. `style` for comment format. `overwrite` replaces existing docs.",
+  description: "Automatically generate or update documentation comments (JSDoc/TSDoc style) for code. Can target specific symbols or entire files/directories.",
+  usageHint: "USE FOR IMPROVING CODE DOCUMENTATION:\n\n- Good for adding missing docs to public APIs or complex functions.\n- `overwrite: true` will replace existing documentation (use carefully).\n- You can target specific symbols via `target` or whole files/directories via `files`.\nAlways review the generated documentation before committing \u2014 the model can hallucinate details.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 3e4,
@@ -4511,10 +4718,11 @@ describe('{{Name}}', () => {
 var scaffoldTool = {
   name: "scaffold",
   category: "Project",
-  description: "Generate boilerplate code from built-in templates or paths. Creates package.json, source files, tests.",
-  usageHint: "Set `template` (npm-package, cli-tool, react-component) and `name`. `vars` for template variables. `dry_run` preview.",
+  description: "Generate new files and folder structures from built-in templates or custom definitions. This is the recommended way to bootstrap new packages, components, or modules instead of creating files one by one with `write`.",
+  usageHint: "PREFERRED FOR SCAFFOLDING:\n\n- Use built-in templates when they match your needs (e.g. react-component, npm-package).\n- Supports `dry_run` so you can preview exactly what will be created.\n- Has the powerful `fs.write.outside-project` capability \u2014 review paths carefully.\nMuch cleaner and safer than manually writing multiple files.",
   permission: "confirm",
   mutating: true,
+  capabilities: ["fs.write.outside-project", "fs.write"],
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -4604,8 +4812,8 @@ function substituteVars(content, name, vars) {
 var toolSearchTool = {
   name: "tool_search",
   category: "Meta",
-  description: "Search available tools by name, description, tags, permission level, or mutating flag.",
-  usageHint: "Set `query` for keyword search. `tags` to filter by category. `permission` to filter by required permission. `mutating` to filter by mutating flag.",
+  description: "Search the catalog of available tools. Very useful when you are unsure which tool to use for a task.",
+  usageHint: "SELF-DISCOVERY TOOL:\n\n- Use when you need to find the right tool for a job.\n- `query` searches names and descriptions.\n- You can filter by `tags` (category), `permission`, or `mutating`.\nCall this before guessing tool names. It helps you discover the best tool for the current situation.",
   permission: "auto",
   mutating: false,
   timeoutMs: 1e3,
@@ -4678,8 +4886,8 @@ var toolSearchTool = {
 var toolUseTool = {
   name: "tool_use",
   category: "Meta",
-  description: "Execute a specific tool by name with given input. Useful when the agent knows exactly which tool to call.",
-  usageHint: "Set `tool` with exact tool name and `input` with the tool parameters. Returns result or error.",
+  description: "Directly execute any registered tool by its exact name, bypassing normal discovery. This is a powerful meta-tool intended for cases where the agent has a clear plan and knows precisely which tool to invoke.",
+  usageHint: "ADVANCED META TOOL \u2014 USE WITH CARE:\n\n- Only use when you are certain of the exact tool name and its expected input shape.\n- Prefer using the normal tool calling mechanism when possible.\n- Very useful in batch-tool-use or when orchestrating complex workflows programmatically.\n- The call still goes through full permission checks and capability validation.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 6e4,
@@ -4688,11 +4896,11 @@ var toolUseTool = {
     properties: {
       tool: {
         type: "string",
-        description: "Exact name of the tool to execute"
+        description: 'The exact registered name of the tool to invoke (e.g. "bash", "read", "codebase-search").'
       },
       input: {
         type: "object",
-        description: "Input parameters for the tool"
+        description: "The input object matching the target tool's inputSchema."
       }
     },
     required: ["tool"]
@@ -4747,8 +4955,8 @@ var toolUseTool = {
 var batchToolUseTool = {
   name: "batch_tool_use",
   category: "Meta",
-  description: "Execute multiple tool calls in sequence or parallel. Returns all results.",
-  usageHint: "Set `calls` array with tool names and inputs. `stop_on_error` halts on first failure. `parallel` runs concurrently (default: true).",
+  description: "Execute a batch of tool calls either sequentially or in parallel. Returns structured results for every call.",
+  usageHint: "ADVANCED / POWER USER TOOL:\n\n- Useful when you have a clear list of independent operations to perform.\n- `parallel: true` (default) runs them concurrently for speed.\n- `stop_on_error: true` makes it fail fast on the first error.\nUse with care \u2014 batching many mutating operations can be risky. Prefer explicit sequential steps for important work.",
   permission: "confirm",
   mutating: true,
   timeoutMs: 12e4,
@@ -4851,8 +5059,8 @@ async function executeSingle(call, ctx, opts) {
 var toolHelpTool = {
   name: "tool_help",
   category: "Meta",
-  description: "Get help and usage information for a specific tool or list all available tools.",
-  usageHint: "Set `tool` for specific help. Omit to list all tools. `format`: short (one-liner), full (schema), markdown (formatted).",
+  description: "Get detailed help for one or more tools, including their full schema and usage guidance. This is the best way to understand exactly how to call a specific tool.",
+  usageHint: "USE WHEN YOU NEED PRECISE TOOL INFORMATION:\n\n- Call with a specific `tool` name when you want the full schema and current usageHint.\n- Omit `tool` (or use a broad query) to get an overview of available tools.\n- Different `format` options give you different levels of detail.\nThis tool is extremely valuable for self-correction when you are unsure about a tool's interface.",
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
@@ -4861,16 +5069,16 @@ var toolHelpTool = {
     properties: {
       tool: {
         type: "string",
-        description: "Tool name to get help for (omit for all tools)"
+        description: "Specific tool name to get detailed help for. Omit to get a list of all tools."
       },
       format: {
         type: "string",
         enum: ["short", "full", "markdown"],
-        description: "Output format (default: short)"
+        description: 'Level of detail: "short" (summary), "full" (with full schema), "markdown" (human readable).'
       },
       include_examples: {
         type: "boolean",
-        description: "Include usage examples in output (default: false)"
+        description: "Whether to include example usage in the response."
       }
     }
   },
@@ -4974,16 +5182,23 @@ function rememberTool(memory) {
   return {
     name: "remember",
     category: "Session",
-    description: "Persist a short note to project or user memory.",
-    usageHint: "Use sparingly. Only for facts that should outlive the session (project conventions, user preferences). Transient state belongs in `todo`. Scope defaults to project-memory.",
+    description: "Persist important long-term facts into project or user memory. These memories survive conversation restarts and are available to future sessions.",
+    usageHint: 'USE VERY SPARINGLY \u2014 ONLY FOR HIGH-VALUE RECURRING KNOWLEDGE:\n\n- Good: coding standards, project conventions, user preferences, recurring architecture decisions, important facts.\n- Bad: temporary state, current task progress, one-off notes \u2192 use `todo` or `plan` instead.\n- `scope: "project"` \u2192 visible to all agents on this codebase.\n- `scope: "user"` \u2192 personal to you.\n\nPolluting memory with noise hurts future context quality. Be extremely deliberate.',
     permission: "auto",
     mutating: true,
     timeoutMs: 2e3,
     inputSchema: {
       type: "object",
       properties: {
-        text: { type: "string" },
-        scope: { type: "string", enum: ["project-agents", "project-memory", "user-memory"] }
+        text: {
+          type: "string",
+          description: "The fact or note to remember. Keep it concise and factual."
+        },
+        scope: {
+          type: "string",
+          enum: ["project-agents", "project-memory", "user-memory"],
+          description: "Where to store it: project-memory (shared), user-memory (personal), or project-agents."
+        }
       },
       required: ["text"]
     },
@@ -4999,8 +5214,8 @@ function forgetTool(memory) {
   return {
     name: "forget",
     category: "Session",
-    description: "Remove memory entries matching a substring (case-insensitive).",
-    usageHint: "Removes ALL matching bullet lines in the given scope. Use a unique substring.",
+    description: "Remove memory entries that contain the given substring (case-insensitive). Use with caution.",
+    usageHint: "This permanently deletes matching memories in the chosen scope.\n- Provide a reasonably specific `query` to avoid deleting unrelated memories.\n- Always double-check before calling with broad queries.\n- Use `remember` + `forget` together to maintain clean long-term memory.",
     permission: "confirm",
     mutating: true,
     timeoutMs: 2e3,
@@ -5026,8 +5241,8 @@ function createModeTool(modeStore) {
   return {
     name: "mode",
     category: "Session",
-    description: "Get, list, or switch the agent mode. Modes inject role-specific prompts into the system prompt.",
-    usageHint: "Set `action`: `get` (current mode), `list` (all modes), `set <modeId>` (switch), `clear` (reset to default).",
+    description: "Manage agent operating modes. Modes change the agent's behavior, personality, and system prompt for different workflows (e.g. coding, security review, planning).",
+    usageHint: "POWERFUL BEHAVIOR CONTROL TOOL:\n\n- Use `list` to see available modes.\n- Use `set <modeId>` to switch the agent into a specific role/mode.\n- Use `get` to check current mode.\n- Use `clear` to return to default behavior.\nSwitching modes is very effective for specialized tasks. The mode change affects how the agent reasons and which guidelines it follows.",
     permission: "confirm",
     mutating: true,
     timeoutMs: 5e3,
@@ -5037,11 +5252,11 @@ function createModeTool(modeStore) {
         action: {
           type: "string",
           enum: ["get", "list", "set", "clear"],
-          description: "Action: get current, list all, set mode, or clear"
+          description: "The mode operation to perform."
         },
         mode: {
           type: "string",
-          description: "Mode ID to switch to (required for action=set)"
+          description: "The mode identifier to activate (only required when action=set)."
         }
       },
       required: ["action"]
@@ -5141,8 +5356,14 @@ function lspKindToInternalKind(k) {
 }
 
 // src/codebase-index/writer.ts
-var INDEX_DIR = ".codebase-index";
 var DB_FILE = "index.db";
+function resolveIndexDir(projectRoot, override) {
+  return override ?? resolveWstackPaths({ projectRoot }).projectCodebaseIndex;
+}
+function codebaseIndexDirOverride(ctx) {
+  const v = ctx.meta?.["codebaseIndexDir"];
+  return typeof v === "string" ? v : void 0;
+}
 var warningSilenced = false;
 function silenceSqliteExperimentalWarning() {
   if (warningSilenced) return;
@@ -5170,16 +5391,16 @@ function loadDatabaseSync() {
   return DatabaseSyncCtor;
 }
 var IndexStore = class {
-  constructor(projectRoot) {
-    this.projectRoot = projectRoot;
-    const dir = path.join(projectRoot, INDEX_DIR);
-    fs13.mkdirSync(dir, { recursive: true });
+  db;
+  /** Absolute path to this project's index directory. */
+  indexDir;
+  constructor(projectRoot, opts = {}) {
+    this.indexDir = resolveIndexDir(projectRoot, opts.indexDir);
+    fs13.mkdirSync(this.indexDir, { recursive: true });
     const Database = loadDatabaseSync();
-    this.db = new Database(path.join(dir, DB_FILE));
+    this.db = new Database(path.join(this.indexDir, DB_FILE));
     this.initSchema();
   }
-  projectRoot;
-  db;
   initSchema() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS metadata (
@@ -5370,7 +5591,7 @@ var IndexStore = class {
       totalFiles,
       byLang,
       byKind,
-      indexPath: path.join(this.projectRoot, INDEX_DIR),
+      indexPath: this.indexDir,
       lastIndexed,
       sizeBytes,
       version: SCHEMA_VERSION
@@ -5463,7 +5684,7 @@ var IndexStore = class {
     }));
   }
   sizeBytes() {
-    const dbPath = path.join(this.projectRoot, INDEX_DIR, DB_FILE);
+    const dbPath = path.join(this.indexDir, DB_FILE);
     try {
       return fs13.statSync(dbPath).size;
     } catch {
@@ -6739,8 +6960,8 @@ async function parseFile(file, content, lang) {
   }
 }
 async function runIndexer(_ctx, opts) {
-  const { projectRoot, force = false, langs, ignore = [] } = opts;
-  const store = new IndexStore(projectRoot);
+  const { projectRoot, force = false, langs, ignore = [], indexDir } = opts;
+  const store = new IndexStore(projectRoot, { indexDir });
   const startMs = Date.now();
   const errors = [];
   const langStats = {};
@@ -6857,8 +7078,8 @@ async function runIndexer(_ctx, opts) {
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
-  description: "Build or update the symbol index for the project. Runs incrementally by default \u2014 only re-indexes files that changed since the last run.",
-  usageHint: "Call with `force: true` to wipe and rebuild the index from scratch. Use `langs` to limit to specific languages. First call without arguments to do an incremental index.",
+  description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
+  usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "auto",
   mutating: true,
   timeoutMs: 12e4,
@@ -6880,7 +7101,8 @@ var codebaseIndexTool = {
     const result = await runIndexer(ctx, {
       projectRoot: ctx.projectRoot,
       force: input.force ?? false,
-      langs: input.langs
+      langs: input.langs,
+      indexDir: codebaseIndexDirOverride(ctx)
     });
     return result;
   }
@@ -6978,10 +7200,11 @@ var Bm25Index = class {
 var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
-  description: "Search indexed code symbols by name, signature, or doc comment. Uses BM25 ranking for relevance.",
-  usageHint: "Pass `query` for keyword search. Filter with `kind` (class/function/interface/etc), `lang` (ts/js/etc), `file` (substring). `limit` caps results (default 20).",
+  description: "Semantic/keyword search over the indexed codebase symbols (functions, classes, interfaces, etc.). Uses BM25 ranking. Much more powerful and structured than raw `grep` for finding code by name or concept.",
+  usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
@@ -7016,7 +7239,7 @@ var codebaseSearchTool = {
     required: ["query"]
   },
   async execute(input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const limit = Math.min(input.limit ?? 20, 100);
       const candidates = store.search(input.query, {
@@ -7061,10 +7284,11 @@ var codebaseSearchTool = {
 var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
-  description: "Return statistics about the symbol index: total symbols, files, breakdown by language and kind, index size, and last update time.",
-  usageHint: "No arguments needed. Use to check if the index is stale or healthy before running a search.",
+  description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
+  usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -7072,7 +7296,7 @@ var codebaseStatsTool = {
     additionalProperties: false
   },
   async execute(_input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const stats = store.getStats();
       return {
@@ -7132,7 +7356,7 @@ var builtinTools = [
 // src/pack.ts
 var builtinToolsPack = {
   name: "builtin-tools",
-  description: "WrongStack built-in filesystem, execution, network, lifecycle, and agent-control tools.",
+  description: "The complete set of built-in tools that ship with WrongStack. Covers filesystem (read/write/edit/replace/glob/grep/tree), execution (bash/exec/git/install), networking (fetch/search), code quality (lint/test/typecheck/format), planning (todo/plan/memory), and meta tools (tool-search/tool-help/batch-tool-use/codebase-*).",
   tools: builtinTools
 };