@claude-code-kit/tools 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,34 +1,61 @@
 // src/bash.ts
-import { exec } from "child_process";
+import { exec, spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
 import { z } from "zod";
 var MAX_RESULT_SIZE = 1e5;
+var DEFAULT_TIMEOUT = 12e4;
+var MAX_TIMEOUT = 6e5;
 var inputSchema = z.object({
   command: z.string().describe("The shell command to execute"),
+  description: z.string().describe("A description of what this command does"),
   cwd: z.string().optional().describe("Working directory for the command"),
-  timeout: z.number().optional().default(3e4).describe("Timeout in milliseconds")
+  timeout: z.number().optional().default(DEFAULT_TIMEOUT).describe("Timeout in milliseconds (max 600000)"),
+  run_in_background: z.boolean().optional().default(false).describe("Run the command in the background and return immediately with PID"),
+  dangerously_disable_sandbox: z.boolean().optional().default(false).describe("Set to true to disable sandbox restrictions. Use with caution \u2014 bypasses security constraints.")
 });
 async function execute(input, ctx) {
   const cwd = input.cwd ?? ctx.workingDirectory;
-  const timeout = input.timeout;
-  return new Promise((resolve5) => {
+  const timeout = Math.min(input.timeout ?? DEFAULT_TIMEOUT, MAX_TIMEOUT);
+  const sandboxed = !input.dangerously_disable_sandbox;
+  if (input.run_in_background) {
+    const outFile = path.join(os.tmpdir(), `cck-bg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.log`);
+    const out = fs.openSync(outFile, "w");
+    const child = spawn("sh", ["-c", input.command], {
+      cwd,
+      env: { ...process.env, ...ctx.env },
+      detached: true,
+      stdio: ["ignore", out, out]
+    });
+    child.unref();
+    const pid = child.pid;
+    fs.closeSync(out);
+    return {
+      content: `Background process started (PID: ${pid})
+Output file: ${outFile}`,
+      metadata: { pid, outputFile: outFile, sandboxed }
+    };
+  }
+  return new Promise((resolve9) => {
     const onAbort = () => {
       child.kill("SIGTERM");
-      resolve5({ content: "Command aborted", isError: true });
+      resolve9({ content: "Command aborted", isError: true, metadata: { sandboxed } });
     };
     const child = exec(input.command, { cwd, timeout, env: { ...process.env, ...ctx.env } }, (err, stdout, stderr) => {
       ctx.abortSignal.removeEventListener("abort", onAbort);
       const output = (stdout + (stderr ? `
 ${stderr}` : "")).slice(0, MAX_RESULT_SIZE);
       if (err && err.killed) {
-        resolve5({ content: `Command timed out after ${timeout}ms
-${output}`, isError: true });
+        resolve9({ content: `Command timed out after ${timeout}ms
+${output}`, isError: true, metadata: { sandboxed } });
         return;
       }
       if (err) {
-        resolve5({ content: output || err.message, isError: true, metadata: { exitCode: err.code } });
+        resolve9({ content: output || err.message, isError: true, metadata: { exitCode: err.code, sandboxed } });
         return;
       }
-      resolve5({ content: output || "(no output)" });
+      resolve9({ content: output || "(no output)", metadata: { sandboxed } });
     });
     if (ctx.abortSignal.aborted) {
       onAbort();
@@ -38,40 +65,111 @@ ${output}`, isError: true });
   });
 }
 var bashTool = {
-  name: "bash",
-  description: "Execute a shell command and return its stdout/stderr output",
+  name: "Bash",
+  description: `Executes a given bash command and returns its output.
+
+The working directory persists between commands via the \`cwd\` parameter, but shell state does not (no environment variables or aliases carry over between calls).
+
+# Sandbox
+
+Commands run with a \`sandboxed\` metadata flag (default: true). Set \`dangerously_disable_sandbox: true\` to mark a command as running outside the sandbox boundary. Note: this is currently a policy flag for permission systems and audit trails \u2014 actual OS-level sandboxing (Docker/nsjail) is not yet implemented. The flag allows permission handlers to apply different rules for sandboxed vs unsandboxed commands.
+
+# Description field
+
+Always provide a clear, concise description in active voice (5-10 words for simple commands, more context for complex ones):
+- ls \u2192 "List files in current directory"
+- git status \u2192 "Show working tree status"
+- find . -name "*.tmp" -exec rm {} \\; \u2192 "Find and delete all .tmp files recursively"
+
+# Avoid running these as Bash commands
+
+Use dedicated tools instead \u2014 they provide a better experience:
+- File search: use Glob (NOT find or ls)
+- Content search: use Grep (NOT grep or rg)
+- Read files: use Read (NOT cat/head/tail)
+- Edit files: use Edit (NOT sed/awk)
+- Write files: use Write (NOT echo >/cat <<EOF)
+
+# File paths
+
+Always quote file paths that contain spaces with double quotes in the command string.
+
+# Multiple commands
+
+- If commands are independent and can run in parallel, make multiple Bash tool calls in the same turn.
+- If commands depend on each other and must run sequentially, use \`&&\` to chain them in a single call.
+- Use \`;\` only when you need sequential execution but don't care if earlier commands fail.
+- Do NOT use newlines to separate commands (newlines are ok in quoted strings).
+
+# Avoiding unnecessary sleep
+
+- Do not sleep between commands that can run immediately \u2014 just run them.
+- If a command is long-running and you want to be notified when it finishes, set \`run_in_background: true\`. No sleep needed.
+- Do not retry failing commands in a sleep loop \u2014 diagnose the root cause instead.
+- If waiting for a background task, check its status with a follow-up command rather than sleeping.
+- If you must sleep, keep the duration short (1-5 seconds) to avoid blocking.
+
+# Timeout
+
+Default timeout is 120 seconds. Override with the \`timeout\` field (max 600000 ms / 10 minutes) for long-running operations like builds or test suites.
+
+# Background execution
+
+Set \`run_in_background: true\` to start a detached process and return immediately with its PID and output log path. Only use this when you don't need the result right away and are OK being notified when the command completes later. Do not use \`&\` at the end of the command when using this parameter.`,
   inputSchema,
   execute,
   isReadOnly: false,
+  isDestructive: true,
   requiresConfirmation: true,
-  timeout: 3e4
+  timeout: DEFAULT_TIMEOUT
 };
 
 // src/read.ts
-import * as fs from "fs/promises";
-import * as path from "path";
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
 import { z as z2 } from "zod";
+var IMAGE_EXTENSIONS = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp"
+};
 var MAX_RESULT_SIZE2 = 1e5;
+var DEFAULT_LIMIT = 2e3;
 var inputSchema2 = z2.object({
-  path: z2.string().describe("Absolute or relative file path to read"),
+  file_path: z2.string().describe("Absolute or relative file path to read"),
   offset: z2.number().optional().describe("Line number to start reading from (1-based)"),
-  limit: z2.number().optional().describe("Maximum number of lines to read")
+  limit: z2.number().optional().describe("Maximum number of lines to read (default 2000)"),
+  pages: z2.string().optional().describe("Page range for PDF files (e.g. '1-5', '3', '10-20')")
 });
 async function execute2(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
-  const filePath = path.resolve(ctx.workingDirectory, input.path);
-  if (!filePath.startsWith(ctx.workingDirectory + path.sep) && filePath !== ctx.workingDirectory) {
-    return { content: `Error: path traversal denied \u2014 ${input.path} escapes working directory`, isError: true };
+  const filePath = path2.resolve(ctx.workingDirectory, input.file_path);
+  if (!filePath.startsWith(ctx.workingDirectory + path2.sep) && filePath !== ctx.workingDirectory) {
+    return { content: `Error: path traversal denied \u2014 ${input.file_path} escapes working directory`, isError: true };
+  }
+  const isPdf = filePath.toLowerCase().endsWith(".pdf");
+  if (input.pages !== void 0 && !isPdf) {
+    return { content: "Error: the 'pages' parameter is only supported for PDF files", isError: true };
+  }
+  if (isPdf) {
+    return readPdf(filePath, input.pages);
+  }
+  const ext = path2.extname(filePath).toLowerCase();
+  const mimeType = IMAGE_EXTENSIONS[ext];
+  if (mimeType) {
+    return readImage(filePath, mimeType);
   }
   try {
-    const raw = await fs.readFile(filePath, "utf-8");
+    const raw = await fs2.readFile(filePath, "utf-8");
     let lines = raw.split("\n");
     if (input.offset !== void 0) {
       lines = lines.slice(Math.max(0, input.offset - 1));
     }
-    if (input.limit !== void 0) {
-      lines = lines.slice(0, input.limit);
-    }
+    const limit = input.limit ?? DEFAULT_LIMIT;
+    lines = lines.slice(0, limit);
     const startLine = input.offset ?? 1;
     const numbered = lines.map((line, i) => `${startLine + i}	${line}`);
     const content = numbered.join("\n").slice(0, MAX_RESULT_SIZE2);
@@ -81,9 +179,85 @@ async function execute2(input, ctx) {
     return { content: `Error reading file: ${msg}`, isError: true };
   }
 }
+async function readImage(filePath, mimeType) {
+  try {
+    const buffer = await fs2.readFile(filePath);
+    const base64Data = buffer.toString("base64");
+    const filename = path2.basename(filePath);
+    return {
+      content: `[Image: ${filename}]
+Data type: ${mimeType}
+Base64: ${base64Data}`,
+      metadata: { mimeType, sizeBytes: buffer.length }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading image: ${msg}`, isError: true };
+  }
+}
+async function readPdf(filePath, pages) {
+  try {
+    const moduleName = "pdf-parse";
+    let pdfParse = null;
+    try {
+      const mod = await import(
+        /* webpackIgnore: true */
+        moduleName
+      );
+      pdfParse = mod.default ?? mod;
+    } catch {
+    }
+    if (!pdfParse) {
+      return {
+        content: "Error: pdf-parse is not installed. Run `npm install pdf-parse` or `pnpm add pdf-parse` to enable PDF reading.",
+        isError: true
+      };
+    }
+    const buffer = await fs2.readFile(filePath);
+    const data = await pdfParse(buffer);
+    const totalPages = data.numpages ?? 0;
+    let text = data.text ?? "";
+    if (pages) {
+      text = `[PDF pages ${pages} requested, ${totalPages} total pages]
+
+${text}`;
+    }
+    return {
+      content: text.slice(0, MAX_RESULT_SIZE2),
+      metadata: { totalPages }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading PDF: ${msg}`, isError: true };
+  }
+}
 var readTool = {
-  name: "read",
-  description: "Read file contents with optional line offset and limit, returning numbered lines",
+  name: "Read",
+  description: `Reads a file from the local filesystem and returns its contents with line numbers.
+
+# File paths
+
+The \`file_path\` parameter must be an absolute path. Relative paths are resolved against the agent's working directory. It is OK to read a file that does not exist \u2014 an error will be returned.
+
+# Line limits
+
+By default, reads up to 2000 lines starting from the beginning of the file. When you already know which part of the file you need, use \`offset\` and \`limit\` to read only that part \u2014 this is important for large files.
+
+# Output format
+
+Results are returned in cat -n format, with line numbers starting at 1, followed by a tab character, then the line content.
+
+# Supported file types
+
+- Plain text, source code, JSON, YAML, Markdown, etc.: read directly.
+- Image files (.png, .jpg, .jpeg, .gif, .webp, .bmp): returned as base64-encoded data with MIME type. The \`offset\` and \`limit\` parameters are ignored for binary image files.
+- SVG files (.svg): read as text (XML source), so \`offset\` and \`limit\` work normally.
+- PDF files (.pdf): use the \`pages\` parameter to read specific page ranges (e.g. "1-5", "3", "10-20"). For large PDFs (more than 10 pages), you MUST provide the \`pages\` parameter \u2014 reading a large PDF without it will return the entire extracted text, which may be truncated. Requires the optional \`pdf-parse\` dependency to be installed.
+- The \`pages\` parameter is only valid for PDF files and will return an error for other file types.
+
+# Limitations
+
+This tool reads files only, not directories. To list directory contents, use a Bash tool call with \`ls\`.`,
   inputSchema: inputSchema2,
   execute: execute2,
   isReadOnly: true,
@@ -91,67 +265,97 @@ var readTool = {
 };
 
 // src/edit.ts
-import * as fs2 from "fs/promises";
-import * as path2 from "path";
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
 import { z as z3 } from "zod";
 var inputSchema3 = z3.object({
-  path: z3.string().describe("Absolute or relative file path to edit"),
-  oldString: z3.string().describe("Exact string to find and replace (must be unique in file)"),
-  newString: z3.string().describe("Replacement string")
+  file_path: z3.string().describe("Absolute or relative file path to edit"),
+  old_string: z3.string().describe("Exact string to find and replace (must be unique in file unless replace_all is true)"),
+  new_string: z3.string().describe("Replacement string"),
+  replace_all: z3.boolean().optional().default(false).describe("Replace all occurrences of old_string (default false)")
 });
 async function execute3(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
-  const filePath = path2.resolve(ctx.workingDirectory, input.path);
-  if (!filePath.startsWith(ctx.workingDirectory + path2.sep) && filePath !== ctx.workingDirectory) {
-    return { content: `Error: path traversal denied \u2014 ${input.path} escapes working directory`, isError: true };
+  const filePath = path3.resolve(ctx.workingDirectory, input.file_path);
+  if (!filePath.startsWith(ctx.workingDirectory + path3.sep) && filePath !== ctx.workingDirectory) {
+    return { content: `Error: path traversal denied \u2014 ${input.file_path} escapes working directory`, isError: true };
   }
   try {
-    const content = await fs2.readFile(filePath, "utf-8");
-    const occurrences = content.split(input.oldString).length - 1;
+    const content = await fs3.readFile(filePath, "utf-8");
+    const occurrences = content.split(input.old_string).length - 1;
     if (occurrences === 0) {
-      return { content: "Error: oldString not found in file", isError: true };
+      return { content: "Error: old_string not found in file", isError: true };
     }
-    if (occurrences > 1) {
+    if (!input.replace_all && occurrences > 1) {
       return {
-        content: `Error: oldString found ${occurrences} times \u2014 must be unique. Provide more context to disambiguate.`,
+        content: `Error: old_string found ${occurrences} times \u2014 must be unique. Provide more context to disambiguate, or use replace_all.`,
         isError: true
       };
     }
-    const updated = content.replace(input.oldString, input.newString);
-    await fs2.writeFile(filePath, updated, "utf-8");
-    return { content: `Successfully edited ${filePath}` };
+    let updated;
+    if (input.replace_all) {
+      updated = content.split(input.old_string).join(input.new_string);
+    } else {
+      updated = content.replace(input.old_string, input.new_string);
+    }
+    await fs3.writeFile(filePath, updated, "utf-8");
+    const replacedCount = input.replace_all ? occurrences : 1;
+    return { content: `Successfully edited ${filePath} (${replacedCount} replacement${replacedCount > 1 ? "s" : ""})` };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Error editing file: ${msg}`, isError: true };
   }
 }
 var editTool = {
-  name: "edit",
-  description: "Edit a file by replacing a unique string occurrence with a new string",
+  name: "Edit",
+  description: `Performs exact string replacements in files.
+
+# Reading before editing
+
+You MUST use the Read tool at least once before editing a file. This tool will error if you attempt an edit on a file you have not read. Reading the file first ensures you match the exact content including indentation and whitespace.
+
+# old_string must be unique
+
+The edit will FAIL if \`old_string\` is not unique in the file. Either:
+- Provide a larger string with more surrounding context to make it unique, or
+- Use \`replace_all: true\` to change every instance of \`old_string\`.
+
+# Preserve indentation
+
+When editing text from Read tool output, preserve the exact indentation (tabs/spaces) as it appears after the line number prefix. The line number prefix format is: line number + tab. Never include any part of the line number prefix in \`old_string\` or \`new_string\`.
+
+# Prefer Edit over Write
+
+ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+
+# replace_all for global renaming
+
+Use \`replace_all: true\` for replacing and renaming strings across the entire file \u2014 for example, renaming a variable or updating a repeated string pattern.`,
   inputSchema: inputSchema3,
   execute: execute3,
   isReadOnly: false,
+  isDestructive: false,
   requiresConfirmation: true,
   timeout: 1e4
 };
 
 // src/write.ts
-import * as fs3 from "fs/promises";
-import * as path3 from "path";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
 import { z as z4 } from "zod";
 var inputSchema4 = z4.object({
-  path: z4.string().describe("Absolute or relative file path to write"),
+  file_path: z4.string().describe("Absolute or relative file path to write"),
   content: z4.string().describe("Content to write to the file")
 });
 async function execute4(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
-  const filePath = path3.resolve(ctx.workingDirectory, input.path);
-  if (!filePath.startsWith(ctx.workingDirectory + path3.sep) && filePath !== ctx.workingDirectory) {
-    return { content: `Error: path traversal denied \u2014 ${input.path} escapes working directory`, isError: true };
+  const filePath = path4.resolve(ctx.workingDirectory, input.file_path);
+  if (!filePath.startsWith(ctx.workingDirectory + path4.sep) && filePath !== ctx.workingDirectory) {
+    return { content: `Error: path traversal denied \u2014 ${input.file_path} escapes working directory`, isError: true };
   }
   try {
-    await fs3.mkdir(path3.dirname(filePath), { recursive: true });
-    await fs3.writeFile(filePath, input.content, "utf-8");
+    await fs4.mkdir(path4.dirname(filePath), { recursive: true });
+    await fs4.writeFile(filePath, input.content, "utf-8");
     return {
       content: `Successfully wrote ${Buffer.byteLength(input.content)} bytes to ${filePath}`
     };
@@ -161,26 +365,41 @@ async function execute4(input, ctx) {
   }
 }
 var writeTool = {
-  name: "write",
-  description: "Write content to a file, creating parent directories as needed",
+  name: "Write",
+  description: `Writes a file to the local filesystem. Creates parent directories automatically if they do not exist.
+
+# Overwrite behavior
+
+This tool will overwrite the existing file if there is one at the provided path. Always read the file first with the Read tool before overwriting an existing file to avoid accidentally discarding content.
+
+# Prefer Edit over Write for existing files
+
+ALWAYS prefer using Edit to modify existing files \u2014 it only sends the diff and makes changes easier to review. Only use Write to create brand new files or for complete rewrites where you intend to replace the entire contents.
+
+# Avoid unnecessary files
+
+NEVER create documentation files (*.md) or README files unless explicitly requested. Do not create new files when editing an existing file would accomplish the same goal.`,
   inputSchema: inputSchema4,
   execute: execute4,
   isReadOnly: false,
+  isDestructive: false,
   requiresConfirmation: true,
   timeout: 1e4
 };
 
 // src/glob.ts
+import * as fs5 from "fs/promises";
+import * as path5 from "path";
 import fg from "fast-glob";
 import { z as z5 } from "zod";
 var MAX_RESULT_SIZE3 = 1e5;
 var inputSchema5 = z5.object({
   pattern: z5.string().describe("Glob pattern to match files (e.g. **/*.ts)"),
-  cwd: z5.string().optional().describe("Directory to search in")
+  path: z5.string().optional().describe("Directory to search in")
 });
 async function execute5(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
-  const cwd = input.cwd ?? ctx.workingDirectory;
+  const cwd = input.path ?? ctx.workingDirectory;
   try {
     const files = await fg(input.pattern, {
       cwd,
@@ -189,20 +408,57 @@ async function execute5(input, ctx) {
       onlyFiles: true,
       absolute: false
     });
-    files.sort();
-    if (files.length === 0) {
+    const withStats = await Promise.all(
+      files.map(async (f) => {
+        try {
+          const stat3 = await fs5.stat(path5.resolve(cwd, f));
+          return { file: f, mtime: stat3.mtimeMs };
+        } catch {
+          return { file: f, mtime: 0 };
+        }
+      })
+    );
+    withStats.sort((a, b) => b.mtime - a.mtime);
+    const sorted = withStats.map((s) => s.file);
+    if (sorted.length === 0) {
       return { content: "No files matched the pattern" };
     }
-    const content = files.join("\n").slice(0, MAX_RESULT_SIZE3);
-    return { content, metadata: { matchCount: files.length } };
+    const content = sorted.join("\n").slice(0, MAX_RESULT_SIZE3);
+    return { content, metadata: { matchCount: sorted.length } };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Error searching files: ${msg}`, isError: true };
   }
 }
 var globTool = {
-  name: "glob",
-  description: "Find files matching a glob pattern, excluding node_modules and .git",
+  name: "Glob",
+  description: `Fast file pattern matching tool that works with any codebase size.
+
+# Glob patterns
+
+Supports standard glob syntax. Examples:
+- "**/*.js" \u2014 all JavaScript files recursively
+- "src/**/*.ts" \u2014 all TypeScript files under src/
+- "packages/*/src/index.ts" \u2014 index files in each package
+
+# Result ordering
+
+Returns matching file paths sorted by modification time (most recently modified first).
+
+# When to use Glob vs other tools
+
+- Finding files by name pattern: use Glob.
+- Searching file contents for a string or regex: use Grep instead.
+- Reading a specific file you already know the path to: use Read instead.
+- For open-ended searches that require multiple rounds of globbing and grepping, chain multiple tool calls.
+
+# Exclusions
+
+node_modules and .git directories are automatically excluded from results.
+
+# Search scope
+
+The \`path\` parameter sets the root directory to search in. If omitted, the agent's working directory is used.`,
   inputSchema: inputSchema5,
   execute: execute5,
   isReadOnly: true,
@@ -210,68 +466,285 @@ var globTool = {
 };
 
 // src/grep.ts
-import * as fs4 from "fs/promises";
-import * as path4 from "path";
+import * as fs6 from "fs/promises";
+import * as path6 from "path";
 import { z as z6 } from "zod";
 import fg2 from "fast-glob";
-var MAX_RESULT_SIZE4 = 1e5;
 var MAX_FILES = 5e3;
+var DEFAULT_HEAD_LIMIT = 250;
+var FILE_TYPE_MAP = {
+  js: [".js", ".mjs", ".cjs", ".jsx"],
+  ts: [".ts", ".tsx", ".mts", ".cts"],
+  py: [".py", ".pyi"],
+  rust: [".rs"],
+  go: [".go"],
+  java: [".java"],
+  c: [".c", ".h"],
+  cpp: [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx", ".h"],
+  cs: [".cs"],
+  rb: [".rb"],
+  php: [".php"],
+  swift: [".swift"],
+  kt: [".kt", ".kts"],
+  scala: [".scala"],
+  html: [".html", ".htm"],
+  css: [".css"],
+  scss: [".scss"],
+  less: [".less"],
+  json: [".json"],
+  yaml: [".yml", ".yaml"],
+  toml: [".toml"],
+  xml: [".xml"],
+  md: [".md", ".markdown"],
+  sh: [".sh", ".bash", ".zsh"],
+  sql: [".sql"],
+  graphql: [".graphql", ".gql"],
+  proto: [".proto"],
+  lua: [".lua"],
+  r: [".r", ".R"],
+  dart: [".dart"],
+  ex: [".ex", ".exs"],
+  zig: [".zig"],
+  vue: [".vue"],
+  svelte: [".svelte"],
+  astro: [".astro"],
+  txt: [".txt"]
+};
 var inputSchema6 = z6.object({
   pattern: z6.string().describe("Regex pattern to search for in file contents"),
-  path: z6.string().optional().describe("Directory or file to search in"),
-  glob: z6.string().optional().describe("Glob filter for files (e.g. *.ts)")
+  path: z6.string().optional().describe("File or directory to search in"),
+  glob: z6.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
+  output_mode: z6.enum(["content", "files_with_matches", "count"]).optional().default("files_with_matches").describe("Output mode: content (matching lines), files_with_matches (file paths), count (match counts)"),
+  "-A": z6.number().optional().describe("Lines after each match (requires output_mode: content)"),
+  "-B": z6.number().optional().describe("Lines before each match (requires output_mode: content)"),
+  "-C": z6.number().optional().describe("Alias for context"),
+  context: z6.number().optional().describe("Lines before and after each match (requires output_mode: content)"),
+  head_limit: z6.number().optional().default(DEFAULT_HEAD_LIMIT).describe("Limit output entries. Defaults to 250."),
+  offset: z6.number().optional().default(0).describe("Skip first N entries before applying head_limit"),
+  multiline: z6.boolean().optional().default(false).describe("Enable multiline mode (dotAll flag, patterns can span lines)"),
+  type: z6.string().optional().describe("File type filter (js, ts, py, etc.)"),
+  "-i": z6.boolean().optional().describe("Case insensitive search"),
+  "-n": z6.boolean().optional().default(true).describe("Show line numbers (content mode only). Defaults to true.")
 });
+function offsetToLine(offsets, charOffset) {
+  let lo = 0;
+  let hi = offsets.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >>> 1;
+    if (offsets[mid] <= charOffset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+function findMatchRanges(lines, fullContent, regex, multiline) {
+  const ranges = [];
+  if (multiline) {
+    const lineOffsets = [];
+    let offset = 0;
+    for (const line of lines) {
+      lineOffsets.push(offset);
+      offset += line.length + 1;
+    }
+    const globalRegex = new RegExp(regex.source, `${regex.flags.replace("g", "")}g`);
+    let match;
+    while ((match = globalRegex.exec(fullContent)) !== null) {
+      const startChar = match.index;
+      const endChar = startChar + match[0].length - 1;
+      const startLine = offsetToLine(lineOffsets, startChar);
+      const endLine = offsetToLine(lineOffsets, endChar);
+      ranges.push({ lineStart: startLine, lineEnd: endLine });
+      if (match[0].length === 0) {
+        globalRegex.lastIndex++;
+      }
+    }
+  } else {
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i])) {
+        ranges.push({ lineStart: i, lineEnd: i });
+      }
+    }
+  }
+  return ranges;
+}
+function buildContextBlocks(lines, ranges, beforeCtx, afterCtx, showLineNumbers, relPath) {
+  if (ranges.length === 0) return [];
+  const blocks = [];
+  for (const range of ranges) {
+    const start = Math.max(0, range.lineStart - beforeCtx);
+    const end = Math.min(lines.length - 1, range.lineEnd + afterCtx);
+    const matchLines = /* @__PURE__ */ new Set();
+    for (let i = range.lineStart; i <= range.lineEnd; i++) {
+      matchLines.add(i);
+    }
+    const prev = blocks[blocks.length - 1];
+    if (prev && start <= prev.end + 1) {
+      prev.end = Math.max(prev.end, end);
+      for (const ml of matchLines) prev.matchLines.add(ml);
+    } else {
+      blocks.push({ start, end, matchLines });
+    }
+  }
+  const output = [];
+  for (let bi = 0; bi < blocks.length; bi++) {
+    if (bi > 0) output.push("--");
+    const block = blocks[bi];
+    for (let i = block.start; i <= block.end; i++) {
+      const separator = block.matchLines.has(i) ? ":" : "-";
+      if (showLineNumbers) {
+        output.push(`${relPath}${separator}${i + 1}${separator}${lines[i]}`);
+      } else {
+        output.push(`${relPath}${separator}${lines[i]}`);
+      }
+    }
+  }
+  return output;
+}
+function resolveTypeGlobs(fileType) {
+  const extensions = FILE_TYPE_MAP[fileType.toLowerCase()];
+  if (!extensions) return [];
+  return extensions.map((ext) => `**/*${ext}`);
+}
+function matchesType(filePath, fileType) {
+  const extensions = FILE_TYPE_MAP[fileType.toLowerCase()];
+  if (!extensions) return false;
+  const ext = path6.extname(filePath).toLowerCase();
+  return extensions.includes(ext);
+}
 async function execute6(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
-  const searchPath = input.path ? path4.resolve(ctx.workingDirectory, input.path) : ctx.workingDirectory;
-  const globPattern = input.glob ?? "**/*";
+  const searchPath = input.path ? path6.resolve(ctx.workingDirectory, input.path) : ctx.workingDirectory;
+  const outputMode = input.output_mode ?? "files_with_matches";
+  const headLimit = input.head_limit ?? DEFAULT_HEAD_LIMIT;
+  const offsetSkip = input.offset ?? 0;
+  const isMultiline = input.multiline ?? false;
+  const caseInsensitive = input["-i"] ?? false;
+  const showLineNumbers = input["-n"] ?? true;
+  const contextVal = input["-C"] ?? input.context ?? 0;
+  const beforeCtx = input["-B"] ?? contextVal;
+  const afterCtx = input["-A"] ?? contextVal;
   try {
-    const regex = new RegExp(input.pattern);
-    const stat2 = await fs4.stat(searchPath);
+    let flags = "";
+    if (isMultiline) flags += "s";
+    if (caseInsensitive) flags += "i";
+    const regex = new RegExp(input.pattern, flags);
+    const stat3 = await fs6.stat(searchPath);
     let files;
-    if (stat2.isFile()) {
+    if (stat3.isFile()) {
       files = [searchPath];
     } else {
-      files = await fg2(globPattern, {
+      let globPatterns;
+      if (input.type) {
+        const typeGlobs = resolveTypeGlobs(input.type);
+        if (typeGlobs.length === 0) {
+          return { content: `Unknown file type: ${input.type}`, isError: true };
+        }
+        if (input.glob) {
+          globPatterns = typeGlobs;
+        } else {
+          globPatterns = typeGlobs;
+        }
+      } else {
+        globPatterns = [input.glob ?? "**/*"];
+      }
+      files = await fg2(globPatterns, {
         cwd: searchPath,
         absolute: true,
         onlyFiles: true,
         ignore: ["**/node_modules/**", "**/.git/**", "**/*.min.*"]
       });
+      if (input.type && input.glob) {
+        const globFilter = await fg2([input.glob], {
+          cwd: searchPath,
+          absolute: true,
+          onlyFiles: true,
+          ignore: ["**/node_modules/**", "**/.git/**", "**/*.min.*"]
+        });
+        const globSet = new Set(globFilter);
+        files = files.filter((f) => globSet.has(f));
+      }
+      files.sort();
       files = files.slice(0, MAX_FILES);
     }
-    const matches = [];
-    let totalSize = 0;
+    const entries = [];
+    let entryIndex = 0;
+    const endIndex = headLimit > 0 ? offsetSkip + headLimit : Number.MAX_SAFE_INTEGER;
     for (const file of files) {
       if (ctx.abortSignal.aborted) break;
+      if (entryIndex >= endIndex) break;
+      if (input.type && stat3.isFile() && !matchesType(file, input.type)) {
+        continue;
+      }
       try {
-        const content = await fs4.readFile(file, "utf-8");
+        const content = await fs6.readFile(file, "utf-8");
         const lines = content.split("\n");
-        for (let i = 0; i < lines.length; i++) {
-          if (regex.test(lines[i])) {
-            const rel = path4.relative(ctx.workingDirectory, file);
-            const line = `${rel}:${i + 1}: ${lines[i]}`;
-            totalSize += line.length;
-            if (totalSize > MAX_RESULT_SIZE4) break;
-            matches.push(line);
+        const relPath = path6.relative(ctx.workingDirectory, file);
+        const matchRanges = findMatchRanges(lines, content, regex, isMultiline);
+        if (matchRanges.length === 0) continue;
+        if (outputMode === "files_with_matches") {
+          if (entryIndex >= offsetSkip && entryIndex < endIndex) {
+            entries.push(relPath);
+          }
+          entryIndex++;
+        } else if (outputMode === "count") {
+          if (entryIndex >= offsetSkip && entryIndex < endIndex) {
+            entries.push(`${relPath}:${matchRanges.length}`);
+          }
+          entryIndex++;
+        } else {
+          const hasContext = beforeCtx > 0 || afterCtx > 0;
+          if (hasContext) {
+            const blockLines = buildContextBlocks(lines, matchRanges, beforeCtx, afterCtx, showLineNumbers, relPath);
+            for (const line of blockLines) {
+              if (entryIndex >= offsetSkip && entryIndex < endIndex) {
+                entries.push(line);
+              }
+              if (line !== "--") {
+                entryIndex++;
+              }
+            }
+          } else {
+            for (const range of matchRanges) {
+              for (let li = range.lineStart; li <= range.lineEnd; li++) {
+                if (entryIndex >= offsetSkip && entryIndex < endIndex) {
+                  if (showLineNumbers) {
+                    entries.push(`${relPath}:${li + 1}:${lines[li]}`);
+                  } else {
+                    entries.push(`${relPath}:${lines[li]}`);
+                  }
+                }
+                entryIndex++;
+              }
+            }
           }
         }
       } catch {
       }
-      if (totalSize > MAX_RESULT_SIZE4) break;
     }
-    if (matches.length === 0) {
+    if (entries.length === 0) {
       return { content: "No matches found" };
     }
-    return { content: matches.join("\n"), metadata: { matchCount: matches.length } };
+    return {
+      content: entries.join("\n"),
+      metadata: { matchCount: entries.filter((e) => e !== "--").length }
+    };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Error searching: ${msg}`, isError: true };
   }
 }
 var grepTool = {
-  name: "grep",
-  description: "Search file contents using regex, returning matching lines with file:line format",
+  name: "Grep",
+  description: `A powerful search tool built on ripgrep
+
+  Usage:
+  - ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+  - Output modes: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".
+  - Use Agent tool for open-ended searches requiring multiple rounds
+  - Pattern syntax: Uses ripgrep conventions \u2014 literal braces need escaping (use \`interface\\{\\}\` to find \`interface{}\` in Go code)
+  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like \`struct \\{[\\s\\S]*?field\`, use \`multiline: true\`
+`,
   inputSchema: inputSchema6,
   execute: execute6,
   isReadOnly: true,
@@ -280,7 +753,8 @@ var grepTool = {
 
 // src/web-fetch.ts
 import { z as z7 } from "zod";
-var MAX_RESULT_SIZE5 = 5e4;
+var MAX_RESULT_SIZE4 = 5e4;
+var CACHE_TTL_MS = 15 * 60 * 1e3;
 function isPrivateUrl(urlStr) {
   const url = new URL(urlStr);
   const hostname = url.hostname;
@@ -299,53 +773,1225 @@ function isPrivateUrl(urlStr) {
   ];
   return blocked.some((re) => re.test(hostname));
 }
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0",
+  mdash: "\u2014",
+  ndash: "\u2013",
+  laquo: "\xAB",
+  raquo: "\xBB",
+  copy: "\xA9",
+  reg: "\xAE",
+  trade: "\u2122",
+  hellip: "\u2026"
+};
+function decodeHtmlEntities(text) {
+  return text.replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCharCode(parseInt(hex, 16))).replace(/&#(\d+);/g, (_, dec) => String.fromCharCode(parseInt(dec, 10))).replace(/&([a-zA-Z]+);/g, (full, name) => NAMED_ENTITIES[name] ?? full);
+}
+function htmlToMarkdown(html) {
+  let md = html;
+  md = md.replace(/<script[\s\S]*?<\/script>/gi, "");
+  md = md.replace(/<style[\s\S]*?<\/style>/gi, "");
+  for (let i = 1; i <= 6; i++) {
+    const prefix = "#".repeat(i);
+    const re = new RegExp(`<h${i}[^>]*>([\\s\\S]*?)<\\/h${i}>`, "gi");
+    md = md.replace(re, (_, inner) => `
+
+${prefix} ${inner.trim()}
+
+`);
+  }
+  md = md.replace(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi, (_, inner) => `
+
+\`\`\`
+${decodeHtmlEntities(inner.replace(/<[^>]*>/g, "").trim())}
+\`\`\`
+
+`);
+  md = md.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (_, inner) => `
+
+\`\`\`
+${decodeHtmlEntities(inner.replace(/<[^>]*>/g, "").trim())}
+\`\`\`
+
+`);
+  md = md.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, (_, inner) => `\`${inner.replace(/<[^>]*>/g, "").trim()}\``);
+  md = md.replace(/<(?:strong|b)\b[^>]*>([\s\S]*?)<\/(?:strong|b)>/gi, (_, inner) => `**${inner.trim()}**`);
+  md = md.replace(/<(?:em|i)\b[^>]*>([\s\S]*?)<\/(?:em|i)>/gi, (_, inner) => `*${inner.trim()}*`);
+  md = md.replace(/<a[^>]+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_, href, text) => `[${text.replace(/<[^>]*>/g, "").trim()}](${href})`);
+  md = md.replace(/<img[^>]+alt="([^"]*)"[^>]*src="([^"]*)"[^>]*\/?>/gi, (_, alt, src) => `![${alt}](${src})`);
+  md = md.replace(/<img[^>]+src="([^"]*)"[^>]*alt="([^"]*)"[^>]*\/?>/gi, (_, src, alt) => `![${alt}](${src})`);
+  md = md.replace(/<img[^>]+src="([^"]*)"[^>]*\/?>/gi, (_, src) => `![](${src})`);
+  md = md.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_, inner) => `- ${inner.replace(/<[^>]*>/g, "").trim()}
+`);
+  md = md.replace(/<br\s*\/?>/gi, "\n");
+  md = md.replace(/<\/p>/gi, "\n\n");
+  md = md.replace(/<\/div>/gi, "\n\n");
+  md = md.replace(/<\/blockquote>/gi, "\n\n");
+  md = md.replace(/<hr\s*\/?>/gi, "\n\n---\n\n");
+  md = md.replace(/<[^>]*>/g, "");
+  md = decodeHtmlEntities(md);
+  md = md.replace(/[ \t]+$/gm, "");
+  md = md.replace(/\n{3,}/g, "\n\n");
+  md = md.trim();
+  return md;
+}
+function upgradeToHttps(url) {
+  if (url.startsWith("http://")) {
+    return `https://${url.slice(7)}`;
+  }
+  return url;
+}
+var cache = /* @__PURE__ */ new Map();
+function getCached(url) {
+  const entry = cache.get(url);
+  if (!entry) return void 0;
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    cache.delete(url);
+    return void 0;
+  }
+  return entry;
+}
+function setCache(url, result) {
+  cache.set(url, {
+    content: result.content,
+    isError: result.isError,
+    metadata: result.metadata,
+    timestamp: Date.now()
+  });
+}
 var inputSchema7 = z7.object({
   url: z7.string().url().describe("URL to fetch"),
   method: z7.string().optional().default("GET").describe("HTTP method"),
   headers: z7.record(z7.string(), z7.string()).optional().describe("HTTP headers"),
-  body: z7.string().optional().describe("Request body")
+  body: z7.string().optional().describe("Request body"),
+  prompt: z7.string().optional().describe("Instructions for processing the fetched content")
 });
 async function execute7(input, ctx) {
   if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  const url = upgradeToHttps(input.url);
   try {
-    if (isPrivateUrl(input.url)) {
-      return { content: `Error: request to private/internal address denied \u2014 ${input.url}`, isError: true };
+    if (isPrivateUrl(url)) {
+      return { content: `Error: request to private/internal address denied \u2014 ${url}`, isError: true };
     }
   } catch {
-    return { content: `Error: invalid URL \u2014 ${input.url}`, isError: true };
+    return { content: `Error: invalid URL \u2014 ${url}`, isError: true };
+  }
+  if ((!input.method || input.method === "GET") && !input.body) {
+    const cached = getCached(url);
+    if (cached) {
+      const promptPrefix = input.prompt ? `[Prompt: ${input.prompt}]
+
+` : "";
+      return {
+        content: `${promptPrefix}[Cached] ${cached.content}`,
+        isError: cached.isError,
+        metadata: { ...cached.metadata, cached: true }
+      };
+    }
   }
   try {
-    const res = await fetch(input.url, {
+    const res = await fetch(url, {
       method: input.method,
       headers: input.headers,
       body: input.body,
       signal: ctx.abortSignal
     });
-    const text = await res.text();
-    const truncated = text.slice(0, MAX_RESULT_SIZE5);
-    const suffix = text.length > MAX_RESULT_SIZE5 ? "\n...(truncated)" : "";
-    const content = `HTTP ${res.status} ${res.statusText}
+    let text = await res.text();
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/html")) {
+      text = htmlToMarkdown(text);
+    }
+    const truncated = text.slice(0, MAX_RESULT_SIZE4);
+    const suffix = text.length > MAX_RESULT_SIZE4 ? "\n...(truncated)" : "";
+    const rawContent = `HTTP ${res.status} ${res.statusText}
 
 ${truncated}${suffix}`;
-    return {
-      content,
+    const result = {
+      content: rawContent,
       isError: res.status >= 400,
       metadata: { status: res.status, headers: Object.fromEntries(res.headers.entries()) }
     };
+    if ((!input.method || input.method === "GET") && !input.body) {
+      setCache(url, result);
+    }
+    const promptPrefix = input.prompt ? `[Prompt: ${input.prompt}]
+
+` : "";
+    return {
+      ...result,
+      content: `${promptPrefix}${rawContent}`
+    };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Fetch error: ${msg}`, isError: true };
   }
 }
 var webFetchTool = {
-  name: "web_fetch",
-  description: "Make HTTP requests and return the response body",
+  name: "WebFetch",
+  description: `Fetches content from a specified URL and returns the response body.
+
+  IMPORTANT: This tool WILL FAIL for authenticated or private URLs (e.g. pages behind login, internal services). Do not use it for those cases.
+
+  Usage notes:
+  - The URL must be a fully-formed, valid URL pointing to a publicly accessible resource
+  - HTML responses (Content-Type: text/html) are automatically converted to Markdown for easier reading
+  - HTTP URLs are automatically upgraded to HTTPS
+  - Successful GET responses are cached in memory for 15 minutes; cached responses are marked with [Cached]
+  - Use the prompt parameter to describe what information you want to extract from the page; the raw response body is returned along with the prompt prefix so you can process it yourself
+  - Requests to private/internal network addresses are blocked (localhost, 10.x, 172.16-31.x, 192.168.x, link-local, cloud metadata endpoints) to prevent SSRF attacks
+  - Response bodies are capped at ${MAX_RESULT_SIZE4.toLocaleString()} characters; larger responses are truncated
+  - HTTP 4xx/5xx responses are returned with isError=true so you can detect failures
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api)
+`,
   inputSchema: inputSchema7,
   execute: execute7,
   isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 3e4
+};
+
+// src/web-search.ts
+import { z as z8 } from "zod";
+var MAX_RESULTS_LIMIT = 20;
+var DEFAULT_MAX_RESULTS = 5;
+var MAX_RESPONSE_SIZE = 2e5;
+var STRUCTURE_WARNING_THRESHOLD = 5e3;
+var USER_AGENT = "Mozilla/5.0 (compatible; ClaudeCodeKit/1.0; +https://github.com/minnzen/claude-code-kit)";
+var inputSchema8 = z8.object({
+  query: z8.string().min(1).describe("Search query"),
+  max_results: z8.number().int().min(1).max(MAX_RESULTS_LIMIT).optional().default(DEFAULT_MAX_RESULTS).describe("Maximum number of results to return (default 5, max 20)"),
+  allowed_domains: z8.array(z8.string()).optional().describe("Only include results from these domains (hostname endsWith check)"),
+  blocked_domains: z8.array(z8.string()).optional().describe("Exclude results from these domains (hostname endsWith check)")
+});
+function parseSearchResults(html, maxResults) {
+  const results = [];
+  const resultBlockRegex = /<div[^>]*class="[^"]*result\b[^"]*"[^>]*>([\s\S]*?)<\/div>\s*<\/div>/g;
+  let blockMatch;
+  while ((blockMatch = resultBlockRegex.exec(html)) !== null && results.length < maxResults) {
+    const block = blockMatch[1];
+    const titleMatch = block.match(/<a[^>]*class="result__a"[^>]*>([\s\S]*?)<\/a>/);
+    if (!titleMatch) continue;
+    const urlMatch = block.match(/<a[^>]*class="result__url"[^>]*href="([^"]*)"[^>]*>/);
+    const urlFallback = block.match(/<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>/);
+    const snippetMatch = block.match(/<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/);
+    const rawUrl = urlMatch?.[1] || urlFallback?.[1] || "";
+    const actualUrl = decodeRedirectUrl(rawUrl);
+    const title = stripHtmlTags(titleMatch[1]).trim();
+    const snippet = stripHtmlTags(snippetMatch?.[1] || "").trim();
+    if (title && actualUrl) {
+      results.push({ title, url: actualUrl, snippet });
+    }
+  }
+  return results;
+}
+function stripHtmlTags(html) {
+  return html.replace(/<[^>]*>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&nbsp;/g, " ").replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16))).replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10))).replace(/\s+/g, " ").trim();
+}
+function decodeRedirectUrl(url) {
+  if (url.includes("duckduckgo.com/l/?")) {
+    const match = url.match(/[?&]uddg=([^&]+)/);
+    if (match) {
+      try {
+        return decodeURIComponent(match[1]);
+      } catch {
+        return match[1];
+      }
+    }
+  }
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    return url;
+  }
+  if (url.startsWith("//")) {
+    return `https:${url}`;
+  }
+  return url;
+}
+function extractHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return "";
+  }
+}
+function filterByDomain(results, allowedDomains, blockedDomains) {
+  let filtered = results;
+  if (allowedDomains && allowedDomains.length > 0) {
+    filtered = filtered.filter((r) => {
+      const hostname = extractHostname(r.url);
+      return allowedDomains.some((d) => hostname.endsWith(d));
+    });
+  }
+  if (blockedDomains && blockedDomains.length > 0) {
+    filtered = filtered.filter((r) => {
+      const hostname = extractHostname(r.url);
+      return !blockedDomains.some((d) => hostname.endsWith(d));
+    });
+  }
+  return filtered;
+}
+function formatResults(results) {
+  if (results.length === 0) {
+    return "No search results found.";
+  }
+  return results.map(
+    (r, i) => `${i + 1}. ${r.title}
+   URL: ${r.url}${r.snippet ? `
+   ${r.snippet}` : ""}`
+  ).join("\n\n");
+}
+async function execute8(input, ctx) {
+  if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  const searchUrl = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(input.query)}`;
+  try {
+    const res = await fetch(searchUrl, {
+      method: "GET",
+      headers: {
+        "User-Agent": USER_AGENT,
+        Accept: "text/html",
+        "Accept-Language": "en-US,en;q=0.9"
+      },
+      signal: ctx.abortSignal
+    });
+    if (!res.ok) {
+      return {
+        content: `Search request failed: HTTP ${res.status} ${res.statusText}`,
+        isError: true
+      };
+    }
+    const fullHtml = await res.text();
+    const html = fullHtml.slice(0, MAX_RESPONSE_SIZE);
+    let results = parseSearchResults(html, input.max_results);
+    results = filterByDomain(results, input.allowed_domains, input.blocked_domains);
+    let formatted = formatResults(results);
+    if (results.length === 0 && html.length > STRUCTURE_WARNING_THRESHOLD) {
+      formatted += "\n\n[Warning: received a large HTML response but extracted 0 results. DuckDuckGo's HTML structure may have changed.]";
+    }
+    return {
+      content: formatted,
+      isError: false,
+      metadata: { resultCount: results.length, query: input.query }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Search error: ${msg}`, isError: true };
+  }
+}
+var webSearchTool = {
+  name: "WebSearch",
+  description: `Searches the web using DuckDuckGo and returns structured results with titles, URLs, and snippets.
+
+  Usage notes:
+  - Use this tool to access up-to-date information beyond the model's knowledge cutoff, look up current events, or find documentation
+  - Results are returned as a numbered list; each entry includes a title, URL, and short snippet
+  - Use allowed_domains to restrict results to specific sites (e.g. ["docs.python.org"]) \u2014 matching uses hostname endsWith, so "github.com" also matches "docs.github.com"
+  - Use blocked_domains to exclude unwanted sites
+  - CRITICAL REQUIREMENT: After answering the user's question using search results, you MUST include a "Sources:" section listing the relevant URLs as markdown hyperlinks
+
+  Example Sources format:
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+`,
+  inputSchema: inputSchema8,
+  execute: execute8,
+  isReadOnly: true,
   timeout: 3e4
 };
 
+// src/task.ts
+import { z as z9 } from "zod";
+var taskStatus = z9.enum(["pending", "in_progress", "completed", "cancelled"]);
+var createInputSchema = z9.object({
+  title: z9.string().describe("Task title"),
+  description: z9.string().optional().describe("Optional task description"),
+  owner: z9.string().optional().describe("Who this task is assigned to")
+});
+var updateInputSchema = z9.object({
+  id: z9.string().describe("Task ID to update"),
+  status: taskStatus.optional().describe("New task status"),
+  title: z9.string().optional().describe("New task title"),
+  description: z9.string().optional().describe("New task description"),
+  owner: z9.string().optional().describe("Assign task to this owner"),
+  add_blocks: z9.array(z9.string()).optional().describe("Task IDs that this task blocks (appended)"),
+  add_blocked_by: z9.array(z9.string()).optional().describe("Task IDs that block this task (appended)")
+});
+var getInputSchema = z9.object({
+  id: z9.string().describe("Task ID to retrieve")
+});
+var listInputSchema = z9.object({
+  status: taskStatus.optional().describe("Filter tasks by status"),
+  owner: z9.string().optional().describe("Filter tasks by owner")
+});
+function createTaskTool() {
+  const tasks = /* @__PURE__ */ new Map();
+  let nextId = 1;
+  async function executeCreate(input, ctx) {
+    if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+    const id = `task-${nextId++}`;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const task = {
+      id,
+      title: input.title,
+      description: input.description,
+      status: "pending",
+      owner: input.owner,
+      createdAt: now,
+      updatedAt: now
+    };
+    tasks.set(id, task);
+    return {
+      content: `Created task ${id}: ${input.title}`,
+      metadata: { task }
+    };
+  }
+  async function executeUpdate(input, ctx) {
+    if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+    const existing = tasks.get(input.id);
+    if (!existing) {
+      return { content: `Error: task ${input.id} not found`, isError: true };
+    }
+    const mergedBlocks = input.add_blocks ? [.../* @__PURE__ */ new Set([...existing.blocks ?? [], ...input.add_blocks])] : existing.blocks;
+    const mergedBlockedBy = input.add_blocked_by ? [.../* @__PURE__ */ new Set([...existing.blockedBy ?? [], ...input.add_blocked_by])] : existing.blockedBy;
+    const updated = {
+      ...existing,
+      ...input.status !== void 0 && { status: input.status },
+      ...input.title !== void 0 && { title: input.title },
+      ...input.description !== void 0 && { description: input.description },
+      ...input.owner !== void 0 && { owner: input.owner },
+      ...mergedBlocks !== void 0 && { blocks: mergedBlocks },
+      ...mergedBlockedBy !== void 0 && { blockedBy: mergedBlockedBy },
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    tasks.set(input.id, updated);
+    const changedFields = [];
+    if (input.status !== void 0) changedFields.push(`status to ${input.status}`);
+    if (input.title !== void 0) changedFields.push(`title to "${input.title}"`);
+    if (input.description !== void 0) changedFields.push(`description`);
+    if (input.owner !== void 0) changedFields.push(`owner to "${input.owner}"`);
+    if (input.add_blocks) changedFields.push(`blocks +${input.add_blocks.join(",")}`);
+    if (input.add_blocked_by) changedFields.push(`blockedBy +${input.add_blocked_by.join(",")}`);
+    return {
+      content: `Updated task ${input.id}: ${changedFields.join(", ") || "no changes"}`,
+      metadata: { task: updated }
+    };
+  }
+  async function executeGet(input, ctx) {
+    if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+    const task = tasks.get(input.id);
+    if (!task) {
+      return { content: `Error: task ${input.id} not found`, isError: true };
+    }
+    const lines = [
+      `ID: ${task.id}`,
+      `Title: ${task.title}`,
+      `Status: ${task.status}`
+    ];
+    if (task.description) lines.push(`Description: ${task.description}`);
+    if (task.owner) lines.push(`Owner: ${task.owner}`);
+    if (task.blocks && task.blocks.length > 0) lines.push(`Blocks: ${task.blocks.join(", ")}`);
+    if (task.blockedBy && task.blockedBy.length > 0) lines.push(`Blocked by: ${task.blockedBy.join(", ")}`);
+    lines.push(`Created: ${task.createdAt}`);
+    lines.push(`Updated: ${task.updatedAt}`);
+    return {
+      content: lines.join("\n"),
+      metadata: { task }
+    };
+  }
+  async function executeList(input, ctx) {
+    if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+    let all = Array.from(tasks.values());
+    if (input.status) {
+      all = all.filter((t) => t.status === input.status);
+    }
+    if (input.owner) {
+      all = all.filter((t) => t.owner === input.owner);
+    }
+    if (all.length === 0) {
+      const qualifiers = [];
+      if (input.status) qualifiers.push(`status "${input.status}"`);
+      if (input.owner) qualifiers.push(`owner "${input.owner}"`);
+      const qualifier = qualifiers.length > 0 ? ` with ${qualifiers.join(" and ")}` : "";
+      return { content: `No tasks${qualifier}`, metadata: { tasks: [] } };
+    }
+    const lines = all.map(
+      (t) => `[${t.status}] ${t.id}: ${t.title}${t.description ? ` \u2014 ${t.description}` : ""}${t.owner ? ` (${t.owner})` : ""}`
+    );
+    return {
+      content: lines.join("\n"),
+      metadata: { tasks: all }
+    };
+  }
+  const taskCreate = {
+    name: "TaskCreate",
+    description: `Creates a new task and adds it to the in-session task list.
+
+  Use this tool proactively to track progress on complex multi-step work or when the user provides multiple things to accomplish.
+
+  Parameters:
+  - title: Short, actionable title in imperative form (e.g. "Fix authentication bug in login flow")
+  - description: What needs to be done and any relevant context
+  - owner: Optional \u2014 the agent or person this task is assigned to
+
+  All tasks start with status "pending". Use TaskUpdate to move them through the workflow.
+`,
+    inputSchema: createInputSchema,
+    execute: executeCreate,
+    isReadOnly: false,
+    isDestructive: false,
+    requiresConfirmation: true,
+    timeout: 5e3
+  };
+  const taskUpdate = {
+    name: "TaskUpdate",
+    description: `Updates an existing task in the task list.
+
+  Use this tool to advance tasks through their lifecycle and to maintain accurate dependency graphs.
+
+  Fields you can update:
+  - status: "pending" \u2192 "in_progress" \u2192 "completed" | "cancelled"
+  - title / description: Change the task subject or requirements
+  - owner: Reassign the task to a different agent or person
+  - add_blocks: Append task IDs that this task blocks (tasks that cannot start until this one is done); deduplicated automatically
+  - add_blocked_by: Append task IDs that must complete before this task can start; deduplicated automatically
+
+  Important:
+  - Mark a task in_progress BEFORE beginning work on it
+  - Only mark a task completed when the work is fully done \u2014 never if tests are failing or implementation is partial
+  - Use TaskGet to read the latest state before updating to avoid stale overwrites
+`,
+    inputSchema: updateInputSchema,
+    execute: executeUpdate,
+    isReadOnly: false,
+    isDestructive: false,
+    requiresConfirmation: true,
+    timeout: 5e3
+  };
+  const taskGet = {
+    name: "TaskGet",
+    description: `Retrieves full details of a single task by ID.
+
+  Use this tool before starting work on a task to understand its complete requirements, and to inspect dependency relationships.
+
+  Returns:
+  - id, title, status, description, owner
+  - blocks: task IDs that cannot start until this task is completed
+  - blockedBy: task IDs that must complete before this task can start
+  - createdAt / updatedAt timestamps
+
+  Tip: Check that blockedBy is empty (or all dependencies are completed) before marking a task in_progress.
+`,
+    inputSchema: getInputSchema,
+    execute: executeGet,
+    isReadOnly: true,
+    isDestructive: false,
+    timeout: 5e3
+  };
+  const taskList = {
+    name: "TaskList",
+    description: `Lists all tasks in the current session, with optional filtering.
+
+  Use this tool to get an overview of all work in progress, check what is available to claim, or verify overall completion status.
+
+  Filters:
+  - status: Return only tasks with this status ("pending", "in_progress", "completed", "cancelled")
+  - owner: Return only tasks assigned to this owner
+
+  Each result shows id, title, status, owner, and a summary of blockedBy dependencies. Use TaskGet with a specific id to view the full description and all dependency details.
+
+  Prefer working on tasks in ID order (lowest first) when multiple tasks are available, as earlier tasks often set up context for later ones.
+`,
+    inputSchema: listInputSchema,
+    execute: executeList,
+    isReadOnly: true,
+    isDestructive: false,
+    timeout: 5e3
+  };
+  return {
+    taskCreate,
+    taskUpdate,
+    taskGet,
+    taskList,
+    getTasks() {
+      return Array.from(tasks.values());
+    },
+    clear() {
+      tasks.clear();
+      nextId = 1;
+    }
+  };
+}
+
+// src/subagent.ts
+import { z as z10 } from "zod";
+var DEFAULT_TIMEOUT2 = 12e4;
+var inputSchema9 = z10.object({
+  task: z10.string().describe("The task for the subagent to complete"),
+  description: z10.string().optional().describe("Optional additional context for the subagent")
+});
+function createSubagentTool(config) {
+  const timeout = config.timeout ?? DEFAULT_TIMEOUT2;
+  async function execute12(input, ctx) {
+    if (ctx.abortSignal.aborted) {
+      return { content: "Aborted before subagent started", isError: true };
+    }
+    const prompt = input.description ? `${input.task}
+
+Additional context: ${input.description}` : input.task;
+    const childController = new AbortController();
+    let subagent;
+    try {
+      subagent = config.agentFactory({
+        task: input.task,
+        description: input.description,
+        signal: childController.signal
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Failed to create subagent: ${msg}`, isError: true };
+    }
+    try {
+      const result = await raceWithTimeoutAndAbort(
+        subagent.chat(prompt),
+        timeout,
+        ctx.abortSignal
+      );
+      return { content: result || "(subagent returned empty response)" };
+    } catch (err) {
+      childController.abort();
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg === "Subagent timed out" || msg === "Subagent aborted") {
+        return { content: msg, isError: true };
+      }
+      return { content: `Subagent error: ${msg}`, isError: true };
+    }
+  }
+  return {
+    name: "Agent",
+    description: `Spawns an independent subagent to complete a delegated task and returns its result.
+
+  The subagent runs with its own isolated session \u2014 it does not share message history or state with the parent agent. It receives the task and optional description, executes independently, and returns its final text response.
+
+  Use this tool for tasks that:
+  - Can be completed without access to the parent's conversation context
+  - Are self-contained enough to delegate to a separate execution unit
+  - Benefit from parallel or isolated execution
+
+  Timeout and abort behavior:
+  - The subagent is subject to a configurable timeout (default: ${DEFAULT_TIMEOUT2 / 1e3}s); it will be forcibly stopped and return an error if it exceeds this limit
+  - If the parent agent's AbortSignal fires (e.g. user cancels), the cancellation is propagated to the subagent via its own AbortController, stopping in-flight work immediately
+  - The signal passed to agentFactory can be used to wire the AbortSignal into the subagent's underlying provider calls
+`,
+    inputSchema: inputSchema9,
+    execute: execute12,
+    isReadOnly: false,
+    isDestructive: false,
+    requiresConfirmation: true,
+    timeout
+  };
+}
+function raceWithTimeoutAndAbort(promise, timeoutMs, signal) {
+  return new Promise((resolve9, reject) => {
+    let settled = false;
+    const settle = () => {
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settle();
+        reject(new Error("Subagent timed out"));
+      }
+    }, timeoutMs);
+    const onAbort = () => {
+      if (!settled) {
+        settle();
+        reject(new Error("Subagent aborted"));
+      }
+    };
+    if (signal.aborted) {
+      settled = true;
+      clearTimeout(timer);
+      reject(new Error("Subagent aborted"));
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        if (!settled) {
+          settle();
+          resolve9(value);
+        }
+      },
+      (err) => {
+        if (!settled) {
+          settle();
+          reject(err);
+        }
+      }
+    );
+  });
+}
+
+// src/notebook-edit.ts
+import * as fs7 from "fs/promises";
+import * as path7 from "path";
+import { z as z11 } from "zod";
+var inputSchema10 = z11.object({
+  notebook_path: z11.string().describe("Absolute or relative path to a .ipynb notebook file"),
+  edit_mode: z11.enum(["insert", "replace", "delete"]).describe("Action to perform on the cell"),
+  cell_number: z11.number().int().min(0).optional().describe("0-based cell index (insert position or target cell)"),
+  cell_id: z11.string().optional().describe("Cell ID to locate by metadata.id (alternative to cell_number)"),
+  cell_type: z11.enum(["code", "markdown"]).optional().describe("Cell type for insert/replace (default: code for insert, preserves original for replace)"),
+  new_source: z11.string().optional().describe("Cell content for insert/replace")
+});
+function sourceToLines(source) {
+  if (source === "") return [];
+  const lines = source.split("\n");
+  const result = lines.map((line, i) => i < lines.length - 1 ? `${line}
+` : line);
+  if (result.length > 0 && result[result.length - 1] === "") {
+    result.pop();
+  }
+  return result;
+}
+function makeCell(cellType, source) {
+  const cell = {
+    cell_type: cellType,
+    source: sourceToLines(source),
+    metadata: {}
+  };
+  if (cellType === "code") {
+    cell.outputs = [];
+    cell.execution_count = null;
+  }
+  return cell;
+}
+async function execute9(input, ctx) {
+  if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  const filePath = path7.resolve(ctx.workingDirectory, input.notebook_path);
+  if (!filePath.startsWith(ctx.workingDirectory + path7.sep) && filePath !== ctx.workingDirectory) {
+    return { content: `Error: path traversal denied \u2014 ${input.notebook_path} escapes working directory`, isError: true };
+  }
+  if (path7.extname(filePath).toLowerCase() !== ".ipynb") {
+    return { content: "Error: only .ipynb files are allowed", isError: true };
+  }
+  try {
+    const raw = await fs7.readFile(filePath, "utf-8");
+    let notebook;
+    try {
+      notebook = JSON.parse(raw);
+    } catch {
+      return { content: "Error: file is not valid JSON", isError: true };
+    }
+    if (typeof notebook.nbformat !== "number") {
+      return { content: "Error: invalid notebook format \u2014 missing nbformat field", isError: true };
+    }
+    const cells = notebook.cells;
+    if (!Array.isArray(cells)) {
+      return { content: "Error: invalid notebook format \u2014 missing cells array", isError: true };
+    }
+    if (input.cell_id !== void 0 && input.cell_number !== void 0) {
+      return { content: "Error: provide either cell_id or cell_number, not both", isError: true };
+    }
+    let resolvedCellNumber = input.cell_number;
+    if (input.cell_id !== void 0) {
+      const idx = cells.findIndex(
+        (c) => c.metadata.id === input.cell_id
+      );
+      if (idx === -1) {
+        return { content: `Error: no cell found with metadata.id "${input.cell_id}"`, isError: true };
+      }
+      resolvedCellNumber = idx;
+    }
+    if (resolvedCellNumber === void 0) {
+      return { content: "Error: either cell_number or cell_id must be provided", isError: true };
+    }
+    const { edit_mode: action, cell_type: cellType, new_source: source } = input;
+    const cellIndex = resolvedCellNumber;
+    switch (action) {
+      case "insert": {
+        if (cellIndex < 0 || cellIndex > cells.length) {
+          return {
+            content: `Error: cellIndex ${cellIndex} out of range \u2014 valid insert range is 0..${cells.length}`,
+            isError: true
+          };
+        }
+        if (source === void 0) {
+          return { content: "Error: source is required for insert action", isError: true };
+        }
+        const newCell = makeCell(cellType ?? "code", source);
+        cells.splice(cellIndex, 0, newCell);
+        break;
+      }
+      case "replace": {
+        if (cellIndex < 0 || cellIndex >= cells.length) {
+          return {
+            content: `Error: cellIndex ${cellIndex} out of range \u2014 valid range is 0..${cells.length - 1}`,
+            isError: true
+          };
+        }
+        if (source === void 0) {
+          return { content: "Error: source is required for replace action", isError: true };
+        }
+        const original = cells[cellIndex];
+        const effectiveCellType = cellType ?? original.cell_type;
+        cells[cellIndex] = {
+          ...original,
+          cell_type: effectiveCellType,
+          source: sourceToLines(source)
+        };
+        break;
+      }
+      case "delete": {
+        if (cellIndex < 0 || cellIndex >= cells.length) {
+          return {
+            content: `Error: cellIndex ${cellIndex} out of range \u2014 valid range is 0..${cells.length - 1}`,
+            isError: true
+          };
+        }
+        cells.splice(cellIndex, 1);
+        break;
+      }
+    }
+    await fs7.writeFile(filePath, JSON.stringify(notebook, null, 1) + "\n", "utf-8");
+    const totalCells = cells.length;
+    switch (action) {
+      case "insert":
+        return { content: `Inserted ${cellType} cell at index ${cellIndex} in ${filePath} (${totalCells} cells total)` };
+      case "replace":
+        return { content: `Replaced cell at index ${cellIndex} with ${cellType} cell in ${filePath} (${totalCells} cells total)` };
+      case "delete":
+        return { content: `Deleted cell at index ${cellIndex} from ${filePath} (${totalCells} cells total)` };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error editing notebook: ${msg}`, isError: true };
+  }
+}
+var notebookEditTool = {
+  name: "NotebookEdit",
+  description: `Edits a Jupyter Notebook (.ipynb file) by inserting, replacing, or deleting cells.
+
+  Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing.
+
+  Edit modes:
+  - "replace": Overwrites the source of the cell at the given index while preserving its metadata, outputs, and execution_count. Specify cell_type to change the cell type.
+  - "insert": Inserts a new cell before the position given by cell_number (0-indexed). cell_type is required; defaults to "code".
+  - "delete": Removes the cell at the given index. new_source is not needed.
+
+  Locating cells:
+  - Use cell_number (0-indexed) to target a cell by its position in the notebook.
+  - Use cell_id to target a cell by its metadata.id field. Provide one or the other, not both.
+
+  Requirements:
+  - notebook_path must point to a .ipynb file. Both absolute and working-directory-relative paths are accepted, but the resolved path must remain inside the working directory.
+  - new_source is required for "insert" and "replace" modes; omit it for "delete".
+`,
+  inputSchema: inputSchema10,
+  execute: execute9,
+  isReadOnly: false,
+  isDestructive: false,
+  requiresConfirmation: true,
+  timeout: 1e4
+};
+
+// src/enter-worktree.ts
+import { exec as exec2 } from "child_process";
+import * as fs8 from "fs";
+import * as path8 from "path";
+import { z as z12 } from "zod";
+var DEFAULT_TIMEOUT3 = 3e4;
+var inputSchema11 = z12.object({
+  branch: z12.string().optional().describe("Branch name for the worktree. Auto-generated if omitted (e.g. worktree-<timestamp>)"),
+  path: z12.string().optional().describe("Filesystem path for the worktree. Defaults to .worktrees/<branch> relative to the repo root")
+});
+function generateBranchName() {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `worktree-${ts}-${rand}`;
+}
+function getRepoRoot(cwd) {
+  return new Promise((resolve9, reject) => {
+    exec2("git rev-parse --show-toplevel", { cwd }, (err, stdout) => {
+      if (err) {
+        reject(new Error("Not inside a git repository"));
+        return;
+      }
+      resolve9(stdout.trim());
+    });
+  });
+}
+async function execute10(input, ctx) {
+  const cwd = ctx.workingDirectory;
+  let repoRoot;
+  try {
+    repoRoot = await getRepoRoot(cwd);
+  } catch {
+    return { content: "Not inside a git repository", isError: true };
+  }
+  const branch = input.branch ?? generateBranchName();
+  const worktreePath = input.path ? path8.resolve(cwd, input.path) : path8.join(repoRoot, ".worktrees", branch);
+  fs8.mkdirSync(path8.dirname(worktreePath), { recursive: true });
+  const cmd = `git worktree add ${JSON.stringify(worktreePath)} -b ${JSON.stringify(branch)}`;
+  return new Promise((resolve9) => {
+    exec2(cmd, { cwd: repoRoot, timeout: DEFAULT_TIMEOUT3 }, (err, stdout, stderr) => {
+      const output = (stdout + (stderr ? `
+${stderr}` : "")).trim();
+      if (err) {
+        resolve9({ content: output || err.message, isError: true });
+        return;
+      }
+      resolve9({
+        content: `Worktree created.
+Branch: ${branch}
+Path: ${worktreePath}`,
+        metadata: { branch, path: worktreePath }
+      });
+    });
+  });
+}
+var enterWorktreeTool = {
+  name: "EnterWorktree",
+  description: `Creates an isolated git worktree so the agent can work in a separate directory without affecting the main working tree.
+
+A worktree is a linked checkout of the same repository at a different path, on its own branch. This is useful for:
+- Running experimental changes without touching the current branch
+- Parallel work on multiple features
+- Safe exploration that can be discarded cleanly
+
+The tool creates a new branch and checks it out in the worktree directory. Use ExitWorktree to clean up when done.
+
+# Inputs
+
+- \`branch\`: Name for the new branch. Auto-generated if omitted.
+- \`path\`: Filesystem path for the worktree. Defaults to \`.worktrees/<branch>\` under the repo root.
+
+# Notes
+
+- The worktree shares the same git object store as the main repo \u2014 commits, stashes, and refs are visible across all worktrees.
+- You cannot check out a branch that is already checked out in another worktree.
+- After creation, use the returned path as the working directory for subsequent tool calls.`,
+  inputSchema: inputSchema11,
+  execute: execute10,
+  isReadOnly: false,
+  isDestructive: false,
+  requiresConfirmation: true,
+  timeout: DEFAULT_TIMEOUT3
+};
+
+// src/exit-worktree.ts
+import { exec as exec3 } from "child_process";
+import * as path9 from "path";
+import { z as z13 } from "zod";
+var DEFAULT_TIMEOUT4 = 3e4;
+var inputSchema12 = z13.object({
+  path: z13.string().describe("Filesystem path of the worktree to exit"),
+  keep: z13.boolean().optional().default(false).describe("If true, keep the worktree on disk (only unregister from git). If false (default), remove the worktree directory entirely")
+});
+async function execute11(input, ctx) {
+  const worktreePath = path9.resolve(ctx.workingDirectory, input.path);
+  if (input.keep) {
+    return {
+      content: `Worktree kept at: ${worktreePath}
+The worktree directory and branch remain intact. Use \`git worktree remove <path>\` later to clean up, or \`git worktree prune\` after manually deleting the directory.`,
+      metadata: { path: worktreePath, kept: true }
+    };
+  }
+  const cmd = `git worktree remove ${JSON.stringify(worktreePath)} --force`;
+  return new Promise((resolve9) => {
+    exec3(cmd, { cwd: ctx.workingDirectory, timeout: DEFAULT_TIMEOUT4 }, (err, stdout, stderr) => {
+      const output = (stdout + (stderr ? `
+${stderr}` : "")).trim();
+      if (err) {
+        resolve9({ content: output || err.message, isError: true });
+        return;
+      }
+      resolve9({
+        content: `Worktree removed: ${worktreePath}`,
+        metadata: { path: worktreePath, kept: false }
+      });
+    });
+  });
+}
+var exitWorktreeTool = {
+  name: "ExitWorktree",
+  description: `Removes or keeps a git worktree that was previously created with EnterWorktree.
+
+# Behavior
+
+- \`keep=false\` (default): Runs \`git worktree remove\` to delete the worktree directory and unregister it from git. Any uncommitted changes in the worktree will be lost.
+- \`keep=true\`: Leaves the worktree directory and branch intact. Returns a reminder of how to clean up manually later.
+
+# Inputs
+
+- \`path\`: The filesystem path of the worktree (as returned by EnterWorktree).
+- \`keep\`: Whether to preserve the worktree on disk (default: false).
+
+# Notes
+
+- The branch created by EnterWorktree is NOT deleted \u2014 only the worktree checkout is removed. Delete the branch separately with \`git branch -d <name>\` if no longer needed.
+- If the worktree has uncommitted changes and \`keep=false\`, the removal is forced.`,
+  inputSchema: inputSchema12,
+  execute: execute11,
+  isReadOnly: false,
+  isDestructive: true,
+  requiresConfirmation: true,
+  timeout: DEFAULT_TIMEOUT4
+};
+
+// src/lsp.ts
+import { z as z14 } from "zod";
+var actionEnum = z14.enum([
+  "goToDefinition",
+  "findReferences",
+  "hover",
+  "documentSymbol",
+  "workspaceSymbol"
+]);
+var inputSchema13 = z14.object({
+  action: actionEnum.describe(
+    "The LSP action to perform: goToDefinition, findReferences, hover, documentSymbol, or workspaceSymbol"
+  ),
+  file_path: z14.string().optional().describe("Absolute path to the file (required for all actions except workspaceSymbol)"),
+  line: z14.number().optional().describe("0-based line number (required for goToDefinition, findReferences, hover)"),
+  character: z14.number().optional().describe("0-based character offset (required for goToDefinition, findReferences, hover)"),
+  query: z14.string().optional().describe("Search query for workspaceSymbol")
+}).superRefine((data, ctx) => {
+  const positionActions = ["goToDefinition", "findReferences", "hover"];
+  const needsPosition = positionActions.includes(data.action);
+  if (data.action !== "workspaceSymbol" && !data.file_path) {
+    ctx.addIssue({
+      code: z14.ZodIssueCode.custom,
+      message: "file_path is required for this action",
+      path: ["file_path"]
+    });
+  }
+  if (needsPosition && data.line === void 0) {
+    ctx.addIssue({
+      code: z14.ZodIssueCode.custom,
+      message: "line is required for this action",
+      path: ["line"]
+    });
+  }
+  if (needsPosition && data.character === void 0) {
+    ctx.addIssue({
+      code: z14.ZodIssueCode.custom,
+      message: "character is required for this action",
+      path: ["character"]
+    });
+  }
+});
+function filePathToUri(filePath) {
+  const normalized = filePath.startsWith("/") ? filePath : `/${filePath}`;
+  return `file://${normalized}`;
+}
+function buildLspRequest(input) {
+  const uri = input.file_path ? filePathToUri(input.file_path) : void 0;
+  switch (input.action) {
+    case "goToDefinition":
+      return {
+        method: "textDocument/definition",
+        params: {
+          textDocument: { uri },
+          position: { line: input.line, character: input.character }
+        }
+      };
+    case "findReferences":
+      return {
+        method: "textDocument/references",
+        params: {
+          textDocument: { uri },
+          position: { line: input.line, character: input.character },
+          context: { includeDeclaration: true }
+        }
+      };
+    case "hover":
+      return {
+        method: "textDocument/hover",
+        params: {
+          textDocument: { uri },
+          position: { line: input.line, character: input.character }
+        }
+      };
+    case "documentSymbol":
+      return {
+        method: "textDocument/documentSymbol",
+        params: {
+          textDocument: { uri }
+        }
+      };
+    case "workspaceSymbol":
+      return {
+        method: "workspace/symbol",
+        params: {
+          query: input.query ?? ""
+        }
+      };
+  }
+}
+var SYMBOL_KIND_MAP = {
+  1: "File",
+  2: "Module",
+  3: "Namespace",
+  4: "Package",
+  5: "Class",
+  6: "Method",
+  7: "Property",
+  8: "Field",
+  9: "Constructor",
+  10: "Enum",
+  11: "Interface",
+  12: "Function",
+  13: "Variable",
+  14: "Constant",
+  15: "String",
+  16: "Number",
+  17: "Boolean",
+  18: "Array",
+  19: "Object",
+  20: "Key",
+  21: "Null",
+  22: "EnumMember",
+  23: "Struct",
+  24: "Event",
+  25: "Operator",
+  26: "TypeParameter"
+};
+function symbolKindName(kind) {
+  return SYMBOL_KIND_MAP[kind] ?? `Kind(${kind})`;
+}
+function formatLocation(loc) {
+  const path10 = loc.uri.replace(/^file:\/\//, "");
+  return `${path10}:${loc.range.start.line + 1}:${loc.range.start.character + 1}`;
+}
+function formatLocations(result) {
+  if (!result) return "No results found";
+  if (!Array.isArray(result) && typeof result === "object" && "uri" in result) {
+    return formatLocation(result);
+  }
+  if (Array.isArray(result)) {
+    if (result.length === 0) return "No results found";
+    return result.map((loc) => formatLocation(loc)).join("\n");
+  }
+  return JSON.stringify(result, null, 2);
+}
+function formatHover(result) {
+  if (!result) return "No hover information available";
+  const hover = result;
+  const contents = hover.contents;
+  if (typeof contents === "string") return contents;
+  if (typeof contents === "object" && contents !== null) {
+    if ("value" in contents) {
+      return contents.value;
+    }
+    if (Array.isArray(contents)) {
+      return contents.map((c) => typeof c === "string" ? c : c.value ?? JSON.stringify(c)).join("\n\n");
+    }
+  }
+  return JSON.stringify(contents, null, 2);
+}
+function formatDocumentSymbols(result, indent = 0) {
+  if (!result || Array.isArray(result) && result.length === 0) {
+    return "No symbols found";
+  }
+  if (!Array.isArray(result)) return JSON.stringify(result, null, 2);
+  const lines = [];
+  const prefix = "  ".repeat(indent);
+  for (const sym of result) {
+    if ("range" in sym) {
+      const ds = sym;
+      lines.push(
+        `${prefix}${symbolKindName(ds.kind)} ${ds.name}  (L${ds.range.start.line + 1}-${ds.range.end.line + 1})`
+      );
+      if (ds.children && ds.children.length > 0) {
+        lines.push(formatDocumentSymbols(ds.children, indent + 1));
+      }
+    } else {
+      const si = sym;
+      const loc = formatLocation(si.location);
+      const container = si.containerName ? ` [${si.containerName}]` : "";
+      lines.push(`${prefix}${symbolKindName(si.kind)} ${si.name}${container}  ${loc}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatResult(action, result) {
+  switch (action) {
+    case "goToDefinition":
+    case "findReferences":
+      return formatLocations(result);
+    case "hover":
+      return formatHover(result);
+    case "documentSymbol":
+    case "workspaceSymbol":
+      return formatDocumentSymbols(result);
+    default:
+      return JSON.stringify(result, null, 2);
+  }
+}
+var NO_CONNECTION_MESSAGE = "LSP not available. Start a language server and pass its connection to the tool via createLspTool(connection).";
+function createLspTool(connection) {
+  async function execute12(input, ctx) {
+    if (ctx.abortSignal.aborted) {
+      return { content: "Aborted", isError: true };
+    }
+    if (!connection) {
+      return { content: NO_CONNECTION_MESSAGE, isError: true };
+    }
+    const { method, params } = buildLspRequest(input);
+    try {
+      const result = await connection.request(method, params);
+      const formatted = formatResult(input.action, result);
+      return {
+        content: formatted,
+        metadata: { action: input.action, method, raw: result }
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `LSP request failed: ${msg}`, isError: true };
+    }
+  }
+  return {
+    name: "LSP",
+    description: `Interacts with a Language Server via the Language Server Protocol (LSP) to navigate and understand code.
+
+Supported actions:
+
+- **goToDefinition** \u2014 Jump to the definition of the symbol at the given position. Returns file path and location of the definition. Useful for navigating to function implementations, type definitions, variable declarations, and imported symbols.
+
+- **findReferences** \u2014 Find all references to the symbol at the given position across the workspace. Returns a list of file locations where the symbol is used. Useful for understanding impact before renaming or refactoring, and for tracing how a function or variable is consumed.
+
+- **hover** \u2014 Get type information and documentation for the symbol at the given position. Returns type signatures, JSDoc/docstrings, and inferred types. Useful for understanding what a symbol is without navigating away from the current context.
+
+- **documentSymbol** \u2014 List all symbols (functions, classes, variables, interfaces, etc.) defined in a file. Returns a hierarchical tree of symbols with their kinds and line ranges. Useful for getting an overview of a file's structure and finding specific declarations.
+
+- **workspaceSymbol** \u2014 Search for symbols across the entire workspace by name. Returns matching symbols with their file locations. Useful for finding where a type, function, or class is defined when you don't know which file it's in.
+
+# Position parameters
+
+For goToDefinition, findReferences, and hover, provide the exact cursor position using 0-based \`line\` and \`character\` offsets. These correspond to the position in the file where the symbol of interest is located.
+
+# File path
+
+Provide the absolute file path for all actions except workspaceSymbol. The tool converts it to a file:// URI for the LSP request.
+
+# When LSP is not available
+
+If no language server connection has been configured, the tool returns an error explaining how to set one up. The connection is provided at tool creation time via \`createLspTool(connection)\`.`,
+    inputSchema: inputSchema13,
+    execute: execute12,
+    isReadOnly: true,
+    isDestructive: false,
+    timeout: 3e4
+  };
+}
+
 // src/index.ts
 var builtinTools = [
   bashTool,
@@ -354,15 +2000,25 @@ var builtinTools = [
   writeTool,
   globTool,
   grepTool,
-  webFetchTool
+  webFetchTool,
+  webSearchTool,
+  enterWorktreeTool,
+  exitWorktreeTool
 ];
 export {
   bashTool,
   builtinTools,
+  createLspTool,
+  createSubagentTool,
+  createTaskTool,
   editTool,
+  enterWorktreeTool,
+  exitWorktreeTool,
   globTool,
   grepTool,
+  notebookEditTool,
   readTool,
   webFetchTool,
+  webSearchTool,
   writeTool
 };