@claude-code-kit/tools 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minnzen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @claude-code-kit/tools
+
+Built-in tool collection for the [claude-code-kit](https://github.com/Minnzen/claude-code-kit) agent framework.
+
+## Tools
+
+| Tool | Description | Read-only |
+|------|-------------|-----------|
+| `bash` | Execute shell commands | No |
+| `read` | Read file contents with line numbers | Yes |
+| `edit` | Edit files via unique string replacement | No |
+| `write` | Write/create files with auto-mkdir | No |
+| `glob` | Find files by glob pattern | Yes |
+| `grep` | Search file contents with regex | Yes |
+| `web_fetch` | Make HTTP requests | Yes (GET) |
+
+## Usage
+
+```ts
+import { Agent, AnthropicProvider } from "@claude-code-kit/agent";
+import { builtinTools } from "@claude-code-kit/tools";
+
+const agent = new Agent({
+  provider: new AnthropicProvider({ apiKey: "..." }),
+  model: "claude-sonnet-4-20250514",
+  tools: builtinTools,
+});
+```
+
+Or import individual tools:
+
+```ts
+import { bashTool, readTool, editTool } from "@claude-code-kit/tools";
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { ToolDefinition } from '@claude-code-kit/agent';
+
+declare const inputSchema$6: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type Input$6 = z.infer<typeof inputSchema$6>;
+declare const bashTool: ToolDefinition<Input$6>;
+
+declare const inputSchema$5: z.ZodObject<{
+    path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Input$5 = z.infer<typeof inputSchema$5>;
+declare const readTool: ToolDefinition<Input$5>;
+
+declare const inputSchema$4: z.ZodObject<{
+    path: z.ZodString;
+    oldString: z.ZodString;
+    newString: z.ZodString;
+}, z.core.$strip>;
+type Input$4 = z.infer<typeof inputSchema$4>;
+declare const editTool: ToolDefinition<Input$4>;
+
+declare const inputSchema$3: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+type Input$3 = z.infer<typeof inputSchema$3>;
+declare const writeTool: ToolDefinition<Input$3>;
+
+declare const inputSchema$2: z.ZodObject<{
+    pattern: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input$2 = z.infer<typeof inputSchema$2>;
+declare const globTool: ToolDefinition<Input$2>;
+
+declare const inputSchema$1: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input$1 = z.infer<typeof inputSchema$1>;
+declare const grepTool: ToolDefinition<Input$1>;
+
+declare const inputSchema: z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input = z.infer<typeof inputSchema>;
+declare const webFetchTool: ToolDefinition<Input>;
+
+/** All built-in tools as an array, ready to pass to AgentConfig.tools */
+declare const builtinTools: ToolDefinition[];
+
+export { bashTool, builtinTools, editTool, globTool, grepTool, readTool, webFetchTool, writeTool };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { ToolDefinition } from '@claude-code-kit/agent';
+
+declare const inputSchema$6: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type Input$6 = z.infer<typeof inputSchema$6>;
+declare const bashTool: ToolDefinition<Input$6>;
+
+declare const inputSchema$5: z.ZodObject<{
+    path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Input$5 = z.infer<typeof inputSchema$5>;
+declare const readTool: ToolDefinition<Input$5>;
+
+declare const inputSchema$4: z.ZodObject<{
+    path: z.ZodString;
+    oldString: z.ZodString;
+    newString: z.ZodString;
+}, z.core.$strip>;
+type Input$4 = z.infer<typeof inputSchema$4>;
+declare const editTool: ToolDefinition<Input$4>;
+
+declare const inputSchema$3: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+type Input$3 = z.infer<typeof inputSchema$3>;
+declare const writeTool: ToolDefinition<Input$3>;
+
+declare const inputSchema$2: z.ZodObject<{
+    pattern: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input$2 = z.infer<typeof inputSchema$2>;
+declare const globTool: ToolDefinition<Input$2>;
+
+declare const inputSchema$1: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input$1 = z.infer<typeof inputSchema$1>;
+declare const grepTool: ToolDefinition<Input$1>;
+
+declare const inputSchema: z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input = z.infer<typeof inputSchema>;
+declare const webFetchTool: ToolDefinition<Input>;
+
+/** All built-in tools as an array, ready to pass to AgentConfig.tools */
+declare const builtinTools: ToolDefinition[];
+
+export { bashTool, builtinTools, editTool, globTool, grepTool, readTool, webFetchTool, writeTool };

package/dist/index.js

@@ -0,0 +1,412 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  bashTool: () => bashTool,
+  builtinTools: () => builtinTools,
+  editTool: () => editTool,
+  globTool: () => globTool,
+  grepTool: () => grepTool,
+  readTool: () => readTool,
+  webFetchTool: () => webFetchTool,
+  writeTool: () => writeTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/bash.ts
+var import_node_child_process = require("child_process");
+var import_zod = require("zod");
+var MAX_RESULT_SIZE = 1e5;
+var inputSchema = import_zod.z.object({
+  command: import_zod.z.string().describe("The shell command to execute"),
+  cwd: import_zod.z.string().optional().describe("Working directory for the command"),
+  timeout: import_zod.z.number().optional().default(3e4).describe("Timeout in milliseconds")
+});
+async function execute(input, ctx) {
+  const cwd = input.cwd ?? ctx.workingDirectory;
+  const timeout = input.timeout;
+  return new Promise((resolve5) => {
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      resolve5({ content: "Command aborted", isError: true });
+    };
+    const child = (0, import_node_child_process.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 });
+        return;
+      }
+      if (err) {
+        resolve5({ content: output || err.message, isError: true, metadata: { exitCode: err.code } });
+        return;
+      }
+      resolve5({ content: output || "(no output)" });
+    });
+    if (ctx.abortSignal.aborted) {
+      onAbort();
+      return;
+    }
+    ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var bashTool = {
+  name: "bash",
+  description: "Execute a shell command and return its stdout/stderr output",
+  inputSchema,
+  execute,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 3e4
+};
+
+// src/read.ts
+var fs = __toESM(require("fs/promises"));
+var path = __toESM(require("path"));
+var import_zod2 = require("zod");
+var MAX_RESULT_SIZE2 = 1e5;
+var inputSchema2 = import_zod2.z.object({
+  path: import_zod2.z.string().describe("Absolute or relative file path to read"),
+  offset: import_zod2.z.number().optional().describe("Line number to start reading from (1-based)"),
+  limit: import_zod2.z.number().optional().describe("Maximum number of lines to read")
+});
+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 };
+  }
+  try {
+    const raw = await fs.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 startLine = input.offset ?? 1;
+    const numbered = lines.map((line, i) => `${startLine + i}	${line}`);
+    const content = numbered.join("\n").slice(0, MAX_RESULT_SIZE2);
+    return { content, metadata: { totalLines: raw.split("\n").length } };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading file: ${msg}`, isError: true };
+  }
+}
+var readTool = {
+  name: "read",
+  description: "Read file contents with optional line offset and limit, returning numbered lines",
+  inputSchema: inputSchema2,
+  execute: execute2,
+  isReadOnly: true,
+  timeout: 1e4
+};
+
+// src/edit.ts
+var fs2 = __toESM(require("fs/promises"));
+var path2 = __toESM(require("path"));
+var import_zod3 = require("zod");
+var inputSchema3 = import_zod3.z.object({
+  path: import_zod3.z.string().describe("Absolute or relative file path to edit"),
+  oldString: import_zod3.z.string().describe("Exact string to find and replace (must be unique in file)"),
+  newString: import_zod3.z.string().describe("Replacement string")
+});
+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 };
+  }
+  try {
+    const content = await fs2.readFile(filePath, "utf-8");
+    const occurrences = content.split(input.oldString).length - 1;
+    if (occurrences === 0) {
+      return { content: "Error: oldString not found in file", isError: true };
+    }
+    if (occurrences > 1) {
+      return {
+        content: `Error: oldString found ${occurrences} times \u2014 must be unique. Provide more context to disambiguate.`,
+        isError: true
+      };
+    }
+    const updated = content.replace(input.oldString, input.newString);
+    await fs2.writeFile(filePath, updated, "utf-8");
+    return { content: `Successfully edited ${filePath}` };
+  } 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",
+  inputSchema: inputSchema3,
+  execute: execute3,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 1e4
+};
+
+// src/write.ts
+var fs3 = __toESM(require("fs/promises"));
+var path3 = __toESM(require("path"));
+var import_zod4 = require("zod");
+var inputSchema4 = import_zod4.z.object({
+  path: import_zod4.z.string().describe("Absolute or relative file path to write"),
+  content: import_zod4.z.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 };
+  }
+  try {
+    await fs3.mkdir(path3.dirname(filePath), { recursive: true });
+    await fs3.writeFile(filePath, input.content, "utf-8");
+    return {
+      content: `Successfully wrote ${Buffer.byteLength(input.content)} bytes to ${filePath}`
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error writing file: ${msg}`, isError: true };
+  }
+}
+var writeTool = {
+  name: "write",
+  description: "Write content to a file, creating parent directories as needed",
+  inputSchema: inputSchema4,
+  execute: execute4,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 1e4
+};
+
+// src/glob.ts
+var import_fast_glob = __toESM(require("fast-glob"));
+var import_zod5 = require("zod");
+var MAX_RESULT_SIZE3 = 1e5;
+var inputSchema5 = import_zod5.z.object({
+  pattern: import_zod5.z.string().describe("Glob pattern to match files (e.g. **/*.ts)"),
+  cwd: import_zod5.z.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;
+  try {
+    const files = await (0, import_fast_glob.default)(input.pattern, {
+      cwd,
+      dot: false,
+      ignore: ["**/node_modules/**", "**/.git/**"],
+      onlyFiles: true,
+      absolute: false
+    });
+    files.sort();
+    if (files.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 } };
+  } 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",
+  inputSchema: inputSchema5,
+  execute: execute5,
+  isReadOnly: true,
+  timeout: 15e3
+};
+
+// src/grep.ts
+var fs4 = __toESM(require("fs/promises"));
+var path4 = __toESM(require("path"));
+var import_zod6 = require("zod");
+var import_fast_glob2 = __toESM(require("fast-glob"));
+var MAX_RESULT_SIZE4 = 1e5;
+var MAX_FILES = 5e3;
+var inputSchema6 = import_zod6.z.object({
+  pattern: import_zod6.z.string().describe("Regex pattern to search for in file contents"),
+  path: import_zod6.z.string().optional().describe("Directory or file to search in"),
+  glob: import_zod6.z.string().optional().describe("Glob filter for files (e.g. *.ts)")
+});
+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 ?? "**/*";
+  try {
+    const regex = new RegExp(input.pattern);
+    const stat2 = await fs4.stat(searchPath);
+    let files;
+    if (stat2.isFile()) {
+      files = [searchPath];
+    } else {
+      files = await (0, import_fast_glob2.default)(globPattern, {
+        cwd: searchPath,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/node_modules/**", "**/.git/**", "**/*.min.*"]
+      });
+      files = files.slice(0, MAX_FILES);
+    }
+    const matches = [];
+    let totalSize = 0;
+    for (const file of files) {
+      if (ctx.abortSignal.aborted) break;
+      try {
+        const content = await fs4.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);
+          }
+        }
+      } catch {
+      }
+      if (totalSize > MAX_RESULT_SIZE4) break;
+    }
+    if (matches.length === 0) {
+      return { content: "No matches found" };
+    }
+    return { content: matches.join("\n"), metadata: { matchCount: matches.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",
+  inputSchema: inputSchema6,
+  execute: execute6,
+  isReadOnly: true,
+  timeout: 3e4
+};
+
+// src/web-fetch.ts
+var import_zod7 = require("zod");
+var MAX_RESULT_SIZE5 = 5e4;
+function isPrivateUrl(urlStr) {
+  const url = new URL(urlStr);
+  const hostname = url.hostname;
+  const blocked = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^192\.168\./,
+    /^169\.254\./,
+    /^0\./,
+    /^localhost$/i,
+    /^::1$/,
+    /^\[::1\]$/,
+    /^metadata\.google/,
+    /^169\.254\.169\.254$/
+  ];
+  return blocked.some((re) => re.test(hostname));
+}
+var inputSchema7 = import_zod7.z.object({
+  url: import_zod7.z.string().url().describe("URL to fetch"),
+  method: import_zod7.z.string().optional().default("GET").describe("HTTP method"),
+  headers: import_zod7.z.record(import_zod7.z.string(), import_zod7.z.string()).optional().describe("HTTP headers"),
+  body: import_zod7.z.string().optional().describe("Request body")
+});
+async function execute7(input, ctx) {
+  if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  try {
+    if (isPrivateUrl(input.url)) {
+      return { content: `Error: request to private/internal address denied \u2014 ${input.url}`, isError: true };
+    }
+  } catch {
+    return { content: `Error: invalid URL \u2014 ${input.url}`, isError: true };
+  }
+  try {
+    const res = await fetch(input.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}
+
+${truncated}${suffix}`;
+    return {
+      content,
+      isError: res.status >= 400,
+      metadata: { status: res.status, headers: Object.fromEntries(res.headers.entries()) }
+    };
+  } 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",
+  inputSchema: inputSchema7,
+  execute: execute7,
+  isReadOnly: false,
+  timeout: 3e4
+};
+
+// src/index.ts
+var builtinTools = [
+  bashTool,
+  readTool,
+  editTool,
+  writeTool,
+  globTool,
+  grepTool,
+  webFetchTool
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  bashTool,
+  builtinTools,
+  editTool,
+  globTool,
+  grepTool,
+  readTool,
+  webFetchTool,
+  writeTool
+});

package/dist/index.mjs

@@ -0,0 +1,368 @@
+// src/bash.ts
+import { exec } from "child_process";
+import { z } from "zod";
+var MAX_RESULT_SIZE = 1e5;
+var inputSchema = z.object({
+  command: z.string().describe("The shell command to execute"),
+  cwd: z.string().optional().describe("Working directory for the command"),
+  timeout: z.number().optional().default(3e4).describe("Timeout in milliseconds")
+});
+async function execute(input, ctx) {
+  const cwd = input.cwd ?? ctx.workingDirectory;
+  const timeout = input.timeout;
+  return new Promise((resolve5) => {
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      resolve5({ content: "Command aborted", isError: true });
+    };
+    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 });
+        return;
+      }
+      if (err) {
+        resolve5({ content: output || err.message, isError: true, metadata: { exitCode: err.code } });
+        return;
+      }
+      resolve5({ content: output || "(no output)" });
+    });
+    if (ctx.abortSignal.aborted) {
+      onAbort();
+      return;
+    }
+    ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var bashTool = {
+  name: "bash",
+  description: "Execute a shell command and return its stdout/stderr output",
+  inputSchema,
+  execute,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 3e4
+};
+
+// src/read.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { z as z2 } from "zod";
+var MAX_RESULT_SIZE2 = 1e5;
+var inputSchema2 = z2.object({
+  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")
+});
+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 };
+  }
+  try {
+    const raw = await fs.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 startLine = input.offset ?? 1;
+    const numbered = lines.map((line, i) => `${startLine + i}	${line}`);
+    const content = numbered.join("\n").slice(0, MAX_RESULT_SIZE2);
+    return { content, metadata: { totalLines: raw.split("\n").length } };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading file: ${msg}`, isError: true };
+  }
+}
+var readTool = {
+  name: "read",
+  description: "Read file contents with optional line offset and limit, returning numbered lines",
+  inputSchema: inputSchema2,
+  execute: execute2,
+  isReadOnly: true,
+  timeout: 1e4
+};
+
+// src/edit.ts
+import * as fs2 from "fs/promises";
+import * as path2 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")
+});
+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 };
+  }
+  try {
+    const content = await fs2.readFile(filePath, "utf-8");
+    const occurrences = content.split(input.oldString).length - 1;
+    if (occurrences === 0) {
+      return { content: "Error: oldString not found in file", isError: true };
+    }
+    if (occurrences > 1) {
+      return {
+        content: `Error: oldString found ${occurrences} times \u2014 must be unique. Provide more context to disambiguate.`,
+        isError: true
+      };
+    }
+    const updated = content.replace(input.oldString, input.newString);
+    await fs2.writeFile(filePath, updated, "utf-8");
+    return { content: `Successfully edited ${filePath}` };
+  } 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",
+  inputSchema: inputSchema3,
+  execute: execute3,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 1e4
+};
+
+// src/write.ts
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+import { z as z4 } from "zod";
+var inputSchema4 = z4.object({
+  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 };
+  }
+  try {
+    await fs3.mkdir(path3.dirname(filePath), { recursive: true });
+    await fs3.writeFile(filePath, input.content, "utf-8");
+    return {
+      content: `Successfully wrote ${Buffer.byteLength(input.content)} bytes to ${filePath}`
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error writing file: ${msg}`, isError: true };
+  }
+}
+var writeTool = {
+  name: "write",
+  description: "Write content to a file, creating parent directories as needed",
+  inputSchema: inputSchema4,
+  execute: execute4,
+  isReadOnly: false,
+  requiresConfirmation: true,
+  timeout: 1e4
+};
+
+// src/glob.ts
+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")
+});
+async function execute5(input, ctx) {
+  if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  const cwd = input.cwd ?? ctx.workingDirectory;
+  try {
+    const files = await fg(input.pattern, {
+      cwd,
+      dot: false,
+      ignore: ["**/node_modules/**", "**/.git/**"],
+      onlyFiles: true,
+      absolute: false
+    });
+    files.sort();
+    if (files.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 } };
+  } 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",
+  inputSchema: inputSchema5,
+  execute: execute5,
+  isReadOnly: true,
+  timeout: 15e3
+};
+
+// src/grep.ts
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
+import { z as z6 } from "zod";
+import fg2 from "fast-glob";
+var MAX_RESULT_SIZE4 = 1e5;
+var MAX_FILES = 5e3;
+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)")
+});
+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 ?? "**/*";
+  try {
+    const regex = new RegExp(input.pattern);
+    const stat2 = await fs4.stat(searchPath);
+    let files;
+    if (stat2.isFile()) {
+      files = [searchPath];
+    } else {
+      files = await fg2(globPattern, {
+        cwd: searchPath,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/node_modules/**", "**/.git/**", "**/*.min.*"]
+      });
+      files = files.slice(0, MAX_FILES);
+    }
+    const matches = [];
+    let totalSize = 0;
+    for (const file of files) {
+      if (ctx.abortSignal.aborted) break;
+      try {
+        const content = await fs4.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);
+          }
+        }
+      } catch {
+      }
+      if (totalSize > MAX_RESULT_SIZE4) break;
+    }
+    if (matches.length === 0) {
+      return { content: "No matches found" };
+    }
+    return { content: matches.join("\n"), metadata: { matchCount: matches.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",
+  inputSchema: inputSchema6,
+  execute: execute6,
+  isReadOnly: true,
+  timeout: 3e4
+};
+
+// src/web-fetch.ts
+import { z as z7 } from "zod";
+var MAX_RESULT_SIZE5 = 5e4;
+function isPrivateUrl(urlStr) {
+  const url = new URL(urlStr);
+  const hostname = url.hostname;
+  const blocked = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^192\.168\./,
+    /^169\.254\./,
+    /^0\./,
+    /^localhost$/i,
+    /^::1$/,
+    /^\[::1\]$/,
+    /^metadata\.google/,
+    /^169\.254\.169\.254$/
+  ];
+  return blocked.some((re) => re.test(hostname));
+}
+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")
+});
+async function execute7(input, ctx) {
+  if (ctx.abortSignal.aborted) return { content: "Aborted", isError: true };
+  try {
+    if (isPrivateUrl(input.url)) {
+      return { content: `Error: request to private/internal address denied \u2014 ${input.url}`, isError: true };
+    }
+  } catch {
+    return { content: `Error: invalid URL \u2014 ${input.url}`, isError: true };
+  }
+  try {
+    const res = await fetch(input.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}
+
+${truncated}${suffix}`;
+    return {
+      content,
+      isError: res.status >= 400,
+      metadata: { status: res.status, headers: Object.fromEntries(res.headers.entries()) }
+    };
+  } 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",
+  inputSchema: inputSchema7,
+  execute: execute7,
+  isReadOnly: false,
+  timeout: 3e4
+};
+
+// src/index.ts
+var builtinTools = [
+  bashTool,
+  readTool,
+  editTool,
+  writeTool,
+  globTool,
+  grepTool,
+  webFetchTool
+];
+export {
+  bashTool,
+  builtinTools,
+  editTool,
+  globTool,
+  grepTool,
+  readTool,
+  webFetchTool,
+  writeTool
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@claude-code-kit/tools",
+  "version": "0.2.0",
+  "description": "Built-in tool collection for claude-code-kit agent framework",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.0",
+    "zod": ">=3.20.0",
+    "@claude-code-kit/agent": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "tsup": "*",
+    "typescript": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Minnzen/claude-code-kit.git",
+    "directory": "packages/tools"
+  },
+  "homepage": "https://github.com/Minnzen/claude-code-kit",
+  "bugs": "https://github.com/Minnzen/claude-code-kit/issues",
+  "keywords": [
+    "tools",
+    "agent",
+    "claude",
+    "bash",
+    "file",
+    "glob",
+    "grep"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome check src/"
+  }
+}