@yanzc/claude-pro 0.0.0-stage → 0.4.0

package/src/tools/search.js

@@ -0,0 +1,458 @@
+// Glob and Grep tools. Grep uses ripgrep when available and otherwise a JS scanner that follows
+// ripgrep's rules: .gitignore files are honoured, --glob overrides win (last match, "!" excludes),
+// ^ and $ anchor at line boundaries, hidden files are searched and binary files are skipped.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolvePath, displayPath } from '../utils/paths.js';
+import { ripgrepPath } from '../utils/shell.js';
+
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.svn', '.hg', '__pycache__', '.venv', 'dist-newstyle']);
+
+export const GlobTool = {
+  name: 'Glob',
+  readOnly: true,
+  description: `- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time (most recent first)
+- Use this tool when you need to find files by name patterns
+- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
+- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'The glob pattern to match files against' },
+      path: { type: 'string', description: 'The directory to search in. If not specified, the current working directory will be used. Omit this field to use the default directory; do not pass "undefined" or "null".' },
+    },
+    required: ['pattern'],
+  },
+  summarize(input, ctx) {
+    return input.path ? `pattern: "${input.pattern}", path: "${displayPath(resolvePath(input.path, ctx.cwd), ctx.cwd)}"` : `pattern: "${input.pattern}"`;
+  },
+  async call(input, ctx) {
+    const base = resolvePath(input.path && input.path !== 'undefined' && input.path !== 'null' ? input.path : ctx.cwd, ctx.cwd);
+    if (!fs.existsSync(base)) return { isError: true, content: `Directory does not exist: ${base}` };
+    let pattern = String(input.pattern || '').replace(/\\/g, '/');
+    // Absolute patterns inside the base dir become relative.
+    if (path.isAbsolute(pattern)) {
+      const rel = path.relative(base, pattern).replace(/\\/g, '/');
+      if (!rel.startsWith('..')) pattern = rel;
+    }
+    const explicit = [...IGNORED_DIRS].filter((d) => pattern.includes(d));
+    const exclude = (p) => {
+      const name = path.basename(p);
+      return IGNORED_DIRS.has(name) && !explicit.includes(name);
+    };
+    const files = [];
+    const start = Date.now();
+    try {
+      for await (const f of fs.promises.glob(pattern, { cwd: base, exclude })) {
+        if (ctx.signal?.aborted) break;
+        const abs = path.resolve(base, f);
+        try {
+          const st = fs.statSync(abs);
+          if (st.isFile()) files.push({ abs, mtime: st.mtimeMs });
+        } catch { /* vanished */ }
+        if (files.length >= 20_000) break;
+      }
+    } catch (e) {
+      return { isError: true, content: `Glob failed: ${e.message}` };
+    }
+    files.sort((a, b) => b.mtime - a.mtime);
+    const limit = 1000;
+    const shown = files.slice(0, limit).map((f) => f.abs);
+    let content = shown.length ? shown.join('\n') : 'No files found';
+    if (files.length > limit) content += `\n(Results are truncated: showing ${limit} of ${files.length}. Consider using a more specific path or pattern.)`;
+    return { content, display: { summary: `Found ${files.length} file${files.length === 1 ? '' : 's'} in ${Date.now() - start}ms` } };
+  },
+};
+
+// rg --type names (plus a few aliases) → file extensions, for the JS scanner.
+const TYPE_EXT = {
+  js: ['js', 'jsx', 'mjs', 'cjs'], ts: ['ts', 'tsx', 'mts', 'cts'], py: ['py', 'pyi'], rust: ['rs'], go: ['go'],
+  java: ['java'], c: ['c', 'h'], cpp: ['cpp', 'cc', 'cxx', 'hpp', 'hh', 'h'], cs: ['cs'], csharp: ['cs'], rb: ['rb'], ruby: ['rb'],
+  php: ['php'], swift: ['swift'], kotlin: ['kt', 'kts'], css: ['css', 'scss', 'less'], html: ['html', 'htm'], json: ['json'],
+  md: ['md', 'markdown'], markdown: ['md', 'markdown'], yaml: ['yaml', 'yml'], sh: ['sh', 'bash'], sql: ['sql'], vue: ['vue'],
+  xml: ['xml'], toml: ['toml'], txt: ['txt'], lua: ['lua'], dart: ['dart'], scala: ['scala', 'sc'], svelte: ['svelte'],
+  ps: ['ps1', 'psm1', 'psd1'], bat: ['bat', 'cmd'],
+};
+
+const MAX_COLUMNS = 500; // same as the rg flags below: --max-columns 500 --max-columns-preview
+const MAX_FILE_BYTES = 20 * 1024 * 1024; // the JS scanner reads whole files, so huge ones are skipped
+const CONCURRENCY = 16;
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+
+// Compile a gitignore/ripgrep glob: `*` and `?` stay inside one path segment, a whole `**`
+// segment spans directories, `{a,b}` and `[...]` work, and dotfiles are not special.
+export function globToRegExp(glob, ignoreCase = false) {
+  let re = '';
+  let braces = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*') {
+      const segmentStart = i === 0 || glob[i - 1] === '/';
+      if (segmentStart && glob[i + 1] === '*' && (i + 2 === glob.length || glob[i + 2] === '/')) {
+        if (i + 2 === glob.length) { re += '.*'; i += 1; } else { re += '(?:.*/)?'; i += 2; }
+      } else {
+        while (glob[i + 1] === '*') i++;
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if (ch === '[') {
+      let j = i + 1;
+      const negate = glob[j] === '!' || glob[j] === '^';
+      if (negate) j++;
+      const bodyStart = j;
+      if (glob[j] === ']') j++;
+      while (j < glob.length && glob[j] !== ']') j++;
+      if (j >= glob.length) { re += '\\['; continue; }
+      const body = glob.slice(bodyStart, j).replace(/[\\\][^]/g, '\\$&');
+      re += negate ? `[^/${body}]` : `[${body}]`;
+      i = j;
+    } else if (ch === '{') {
+      braces++;
+      re += '(?:';
+    } else if (ch === '}' && braces) {
+      braces--;
+      re += ')';
+    } else if (ch === ',' && braces) {
+      re += '|';
+    } else if (ch === '\\' && i + 1 < glob.length) {
+      re += escapeRegExp(glob[++i]);
+    } else {
+      re += escapeRegExp(ch);
+    }
+  }
+  if (braces) throw new Error(`unclosed alternate group in glob: ${glob}`);
+  return new RegExp(`^${re}$`, ignoreCase ? 'i' : '');
+}
+
+// A .gitignore line or a --glob override. "!" flips it, a trailing "/" limits it to directories,
+// and any other "/" anchors it to its base directory instead of matching basenames at any depth.
+function parseRule(text, ignoreCase = false) {
+  let pattern = text;
+  const negate = pattern.startsWith('!');
+  if (negate) pattern = pattern.slice(1);
+  else if (pattern.startsWith('\\!') || pattern.startsWith('\\#')) pattern = pattern.slice(1);
+  const dirOnly = pattern.endsWith('/');
+  pattern = pattern.replace(/\/+$/, '');
+  const anchored = pattern.includes('/');
+  pattern = pattern.replace(/^(?:\.\/|\/)/, '');
+  if (!pattern) return null;
+  return { source: text, negate, dirOnly, anchored, re: globToRegExp(pattern, ignoreCase) };
+}
+
+// The last matching rule decides, as in .gitignore files and rg --glob.
+function lastRule(rules, rel, name, isDir) {
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const r = rules[i];
+    if ((!r.dirOnly || isDir) && r.re.test(r.anchored ? rel : name)) return r;
+  }
+  return null;
+}
+
+// "*.js,*.ts" or "*.js *.ts" are two globs; commas inside {...} are not separators.
+function splitGlobs(glob) {
+  if (!glob) return [];
+  const globs = String(glob).split(/[ ,]+(?![^{]*})/).filter(Boolean);
+  return process.platform === 'win32' ? globs.map((g) => g.replace(/\\/g, '/')) : globs;
+}
+
+const IGNORE_FILES = ['.gitignore', '.ignore', '.rgignore']; // lowest precedence first
+
+async function readIgnoreFile(dir, name) {
+  let text;
+  try { text = await fs.promises.readFile(path.join(dir, name), 'utf8'); } catch { return null; }
+  const ignoreCase = name === '.gitignore' && process.platform === 'win32'; // git for Windows defaults to core.ignorecase
+  const rules = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/(?<!\\)\s+$/, '');
+    if (!line || line.startsWith('#')) continue;
+    try {
+      const rule = parseRule(line, ignoreCase);
+      if (rule) rules.push(rule);
+    } catch { /* git skips patterns it cannot parse */ }
+  }
+  return rules.length ? { dir, rules } : null;
+}
+
+// Ignore files of one directory, lowest precedence first. Like ripgrep, .gitignore only counts
+// inside a git work tree; .ignore and .rgignore always count.
+async function ignoreScopes(dir, inRepo) {
+  const names = IGNORE_FILES.filter((n) => inRepo || n !== '.gitignore');
+  return (await Promise.all(names.map((n) => readIgnoreFile(dir, n)))).filter(Boolean);
+}
+
+// Ignore files above the search root apply too, up to the top of the git work tree.
+async function ancestorScopes(base) {
+  const above = [];
+  for (let d = base; ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) {
+      const scopes = [];
+      for (const dir of above.reverse()) scopes.push(...await ignoreScopes(dir, true));
+      return { inRepo: true, scopes };
+    }
+    const parent = path.dirname(d);
+    if (parent === d) return { inRepo: false, scopes: [] };
+    above.push(parent);
+  }
+}
+
+// Deeper .gitignore files take precedence over the ones above them.
+function isIgnored(scopes, abs, name, isDir) {
+  for (let i = scopes.length - 1; i >= 0; i--) {
+    const rule = lastRule(scopes[i].rules, path.relative(scopes[i].dir, abs).replace(/\\/g, '/'), name, isDir);
+    if (rule) return !rule.negate;
+  }
+  return false;
+}
+
+async function collectFiles(base, globs, exts, signal) {
+  if (!(await fs.promises.stat(base)).isDirectory()) return [base];
+  const overrides = globs.map((g) => parseRule(g)).filter(Boolean);
+  const whitelist = overrides.some((r) => !r.negate);
+  // A directory that is skipped by default (node_modules, ...) is searched when a glob names it.
+  const named = new Set([...IGNORED_DIRS].filter((d) => d !== '.git' && overrides.some((r) => !r.negate && r.source.includes(d))));
+  const files = [];
+  const walk = async (dir, scopes, inRepo) => {
+    if (signal?.aborted) return;
+    let entries;
+    try { entries = await fs.promises.readdir(dir, { withFileTypes: true }); } catch { return; }
+    inRepo ||= entries.some((e) => e.name === '.git');
+    if (entries.some((e) => IGNORE_FILES.includes(e.name))) scopes = [...scopes, ...await ignoreScopes(dir, inRepo)];
+    for (const e of entries) {
+      const isDir = e.isDirectory();
+      if ((!isDir && !e.isFile()) || e.name === '.git') continue;
+      const abs = path.join(dir, e.name);
+      const override = lastRule(overrides, path.relative(base, abs).replace(/\\/g, '/'), e.name, isDir);
+      if (override?.negate) continue;
+      if (isDir) {
+        const skip = !override && !named.has(e.name) && (IGNORED_DIRS.has(e.name) || isIgnored(scopes, abs, e.name, true));
+        if (!skip) await walk(abs, scopes, inRepo);
+      } else if (override || (!whitelist && !isIgnored(scopes, abs, e.name, false))) {
+        if (!exts || exts.includes(path.extname(e.name).slice(1).toLowerCase())) files.push(abs);
+      }
+    }
+  };
+  const above = await ancestorScopes(base);
+  await walk(base, above.scopes, above.inRepo);
+  return files;
+}
+
+// Text of a file, or null for binary files. UTF-16 with a BOM is decoded like ripgrep does.
+function decodeText(buf) {
+  if (buf[0] === 0xFF && buf[1] === 0xFE) return buf.toString('utf16le', 2);
+  if (buf[0] === 0xFE && buf[1] === 0xFF) return new TextDecoder('utf-16be').decode(buf.subarray(2));
+  if (buf.subarray(0, 8000).includes(0)) return null;
+  const text = buf.toString('utf8');
+  return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+}
+
+const clip = (line) => (line.length > MAX_COLUMNS ? `${line.slice(0, MAX_COLUMNS)} [... omitted end of long line]` : line);
+
+function runRg(bin, args, cwd, signal) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { cwd, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    child.stdout.on('data', (d) => { if (out.length < 20_000_000) out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    const onAbort = () => child.kill();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.on('close', (code) => { signal?.removeEventListener('abort', onAbort); resolve({ code, out, err }); });
+    child.on('error', (e) => { signal?.removeEventListener('abort', onAbort); resolve({ code: 2, out: '', err: e.message, spawnError: true }); });
+  });
+}
+
+// JS scanner used when ripgrep isn't available. Returns output lines in rg's format.
+async function jsGrep(input, base, mode, signal) {
+  const exts = input.type ? TYPE_EXT[String(input.type).toLowerCase()] : null;
+  if (input.type && !exts) throw new Error(`unrecognized file type: ${input.type} (known types: ${Object.keys(TYPE_EXT).join(', ')})`);
+  const flags = input['-i'] ? 'i' : '';
+  const dotAll = input.multiline ? 's' : '';
+  // ripgrep treats ^ and $ as line anchors, so whole-file matching needs the m flag.
+  const anyRe = new RegExp(input.pattern, `${flags}m${dotAll}`);
+  const allRe = new RegExp(input.pattern, `${flags}gm${dotAll}`);
+  const lineRe = new RegExp(input.pattern, flags);
+  const content = mode === 'content';
+  const before = content ? Math.max(0, Number(input['-B'] ?? input['-C'] ?? 0) || 0) : 0;
+  const after = content ? Math.max(0, Number(input['-A'] ?? input['-C'] ?? 0) || 0) : 0;
+  const files = await collectFiles(base, splitGlobs(input.glob), exts, signal);
+  let skipped = 0;
+
+  const searchFile = async (file) => {
+    let text;
+    try {
+      if ((await fs.promises.stat(file)).size > MAX_FILE_BYTES) { skipped++; return null; }
+      text = decodeText(await fs.promises.readFile(file));
+    } catch { return null; }
+    if (text === null) return null;
+    if (text.includes('\r')) text = text.replace(/\r\n/g, '\n');
+    // Cheap whole-file check first; it can only over-match, so lines are checked below.
+    if (!anyRe.test(text)) return null;
+    const lines = text.split('\n');
+    if (lines.length > 1 && lines.at(-1) === '') lines.pop();
+    let hits;
+    if (input.multiline) {
+      const starts = [0];
+      for (let i = text.indexOf('\n'); i !== -1 && i + 1 < text.length; i = text.indexOf('\n', i + 1)) starts.push(i + 1);
+      const lineAt = (pos) => {
+        let lo = 0, hi = starts.length - 1;
+        while (lo < hi) {
+          const mid = (lo + hi + 1) >> 1;
+          if (starts[mid] <= pos) lo = mid; else hi = mid - 1;
+        }
+        return lo;
+      };
+      const set = new Set();
+      for (const m of text.matchAll(allRe)) {
+        const last = lineAt(m.index + Math.max(0, m[0].length - 1));
+        for (let i = lineAt(m.index); i <= last; i++) set.add(i);
+      }
+      hits = [...set];
+    } else {
+      hits = [];
+      for (let i = 0; i < lines.length; i++) if (lineRe.test(lines[i])) hits.push(i);
+    }
+    if (!hits.length) return null;
+    if (mode === 'files_with_matches') return [file];
+    if (mode === 'count') return [`${file}:${hits.length}`];
+    const isHit = new Set(hits);
+    const out = [];
+    let end = -1;
+    for (const h of hits) {
+      const from = Math.max(0, h - before, end + 1);
+      const to = Math.min(lines.length - 1, h + after);
+      if ((before || after) && out.length && from > end + 1) out.push('--');
+      for (let i = from; i <= to; i++) {
+        const sep = isHit.has(i) ? ':' : '-';
+        out.push(`${file}${sep}${input['-n'] === false ? '' : `${i + 1}${sep}`}${clip(lines[i])}`);
+      }
+      end = Math.max(end, to);
+    }
+    return out;
+  };
+
+  const results = new Array(files.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < files.length && !signal?.aborted) {
+      const i = next++;
+      results[i] = await searchFile(files[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, files.length) }, worker));
+  const lines = [];
+  for (const r of results) {
+    if (!r) continue;
+    if ((before || after) && lines.length) lines.push('--');
+    for (const l of r) lines.push(l);
+  }
+  return { lines, skipped };
+}
+
+export const GrepTool = {
+  name: 'Grep',
+  readOnly: true,
+  description: `A powerful search tool built on ripgrep
+
+Usage:
+- ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command.
+- 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, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Use Task tool for open-ended searches requiring multiple rounds
+- Pattern syntax: Uses ripgrep (not grep) - 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\``,
+  input_schema: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'The regular expression pattern to search for in file contents' },
+      path: { type: 'string', description: 'File or directory to search in. Defaults to current working directory.' },
+      glob: { type: 'string', description: 'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")' },
+      output_mode: { type: 'string', enum: ['content', 'files_with_matches', 'count'], description: 'Output mode. Defaults to "files_with_matches".' },
+      '-B': { type: 'number', description: 'Lines to show before each match. Requires output_mode "content".' },
+      '-A': { type: 'number', description: 'Lines to show after each match. Requires output_mode "content".' },
+      '-C': { type: 'number', description: 'Lines to show before and after each match. Requires output_mode "content".' },
+      '-n': { type: 'boolean', description: 'Show line numbers in output. Requires output_mode "content". Defaults to true.' },
+      '-i': { type: 'boolean', description: 'Case insensitive search' },
+      type: { type: 'string', description: 'File type to search (rg --type). Common types: js, py, rust, go, java, etc.' },
+      head_limit: { type: 'number', description: 'Limit output to first N lines/entries. Defaults to 1000; pass 0 for unlimited.' },
+      offset: { type: 'number', description: 'Skip first N lines/entries before applying head_limit.' },
+      multiline: { type: 'boolean', description: 'Enable multiline mode where . matches newlines and patterns can span lines. Default: false.' },
+    },
+    required: ['pattern'],
+  },
+  summarize(input, ctx) {
+    let s = `pattern: "${input.pattern}"`;
+    if (input.path) s += `, path: "${displayPath(resolvePath(input.path, ctx.cwd), ctx.cwd)}"`;
+    if (input.glob) s += `, glob: "${input.glob}"`;
+    if (input.type) s += `, type: "${input.type}"`;
+    if (input.output_mode && input.output_mode !== 'files_with_matches') s += `, output_mode: "${input.output_mode}"`;
+    return s;
+  },
+  async call(input, ctx) {
+    const base = resolvePath(input.path || ctx.cwd, ctx.cwd);
+    if (!fs.existsSync(base)) return { isError: true, content: `Path does not exist: ${base}` };
+    const mode = input.output_mode || 'files_with_matches';
+    let lines = null;
+    let note = '';
+    const rg = ripgrepPath(ctx.config);
+    if (rg) {
+      // --crlf lets `$` match before \r\n, so line-end anchors also work in Windows (CRLF) files.
+      const args = ['--no-config', '--hidden', '--crlf', '--glob', '!.git', '--max-columns', String(MAX_COLUMNS), '--max-columns-preview', '--color', 'never'];
+      if (input['-i']) args.push('-i');
+      if (input.multiline) args.push('-U', '--multiline-dotall');
+      if (input.type) args.push('--type', input.type);
+      for (const g of splitGlobs(input.glob)) args.push('--glob', g);
+      if (mode === 'files_with_matches') args.push('-l');
+      else if (mode === 'count') args.push('-c');
+      else {
+        if (input['-n'] !== false) args.push('-n');
+        if (input['-C'] != null) args.push('-C', String(input['-C']));
+        if (input['-A'] != null) args.push('-A', String(input['-A']));
+        if (input['-B'] != null) args.push('-B', String(input['-B']));
+      }
+      args.push('-e', input.pattern, '--', base);
+      const r = await runRg(rg, args, ctx.cwd, ctx.signal);
+      if (!r.spawnError) {
+        if (r.code === 2 && !r.out) return { isError: true, content: `ripgrep error: ${r.err.trim()}` };
+        lines = r.out.split(/\r?\n/).filter(Boolean);
+      }
+    }
+    if (!lines) {
+      try {
+        const found = await jsGrep(input, base, mode, ctx.signal);
+        lines = found.lines;
+        if (found.skipped) note = `\n\n(${found.skipped} file${found.skipped === 1 ? '' : 's'} larger than ${MAX_FILE_BYTES / 1024 / 1024}MB not searched; install ripgrep to search them)`;
+      } catch (e) {
+        return { isError: true, content: `Grep failed: ${e.message}` };
+      }
+    }
+    if (mode === 'files_with_matches') {
+      lines = lines.map((f) => ({ f, t: (() => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } })() }))
+        .sort((a, b) => b.t - a.t).map((x) => x.f);
+    }
+    const total = lines.length;
+    const offset = Math.max(0, input.offset || 0);
+    const limit = input.head_limit === 0 ? Infinity : (input.head_limit || 1000);
+    const page = lines.slice(offset, offset + limit);
+    let content;
+    let summary;
+    if (mode === 'files_with_matches') {
+      content = total ? `Found ${total} file${total === 1 ? '' : 's'}\n${page.join('\n')}` : 'No files found';
+      summary = `Found ${total} file${total === 1 ? '' : 's'}`;
+    } else if (mode === 'count') {
+      const sum = lines.reduce((n, l) => n + (parseInt(l.split(':').pop(), 10) || 0), 0);
+      content = total ? page.join('\n') + `\n\nFound ${sum} total occurrences across ${total} files.` : 'No matches found';
+      summary = `Found ${sum} match${sum === 1 ? '' : 'es'} in ${total} file${total === 1 ? '' : 's'}`;
+    } else {
+      content = total ? page.join('\n') : 'No matches found';
+      summary = `Found ${total} line${total === 1 ? '' : 's'}`;
+    }
+    if (total > offset + page.length) content += `\n\n(Showing ${page.length} of ${total} results. Use offset/head_limit to page, or narrow the search.)`;
+    return { content: content + note, display: { summary } };
+  },
+};

package/src/tools/skill.js

@@ -0,0 +1,32 @@
+// Skill tool: lets the model load a skill (packaged instructions for one kind of task) when
+// the task at hand matches its description.
+
+import { renderSkill } from '../agents.js';
+
+export function makeSkillTool(skills) {
+  return {
+    name: 'Skill',
+    readOnly: true,
+    description: () => `Load a skill: a packaged set of instructions for a particular kind of task.
+
+Available skills:
+${[...skills.values()].map((s) => `- ${s.name}: ${s.description}`).join('\n')}
+
+When the task matches a skill's description, call this tool with the skill name BEFORE doing the work, then follow the instructions it returns. Do not mention a skill without calling it, and do not call a skill that is already loaded in this conversation. Pass arguments in \`args\` when the user gave any.`,
+    input_schema: {
+      type: 'object',
+      properties: {
+        skill: { type: 'string', description: 'The skill name, e.g. "pdf"' },
+        args: { type: 'string', description: 'Optional arguments for the skill' },
+      },
+      required: ['skill'],
+    },
+    summarize(input) { return input.skill || ''; },
+    async call(input) {
+      const name = String(input.skill || '').replace(/^\//, '');
+      const skill = skills.get(name);
+      if (!skill) return { isError: true, content: `Unknown skill: ${name}. Available skills: ${[...skills.keys()].join(', ') || 'none'}` };
+      return { content: renderSkill(skill, input.args || ''), display: { summary: `Loaded skill ${skill.name}` } };
+    },
+  };
+}

package/src/tools/task.js

@@ -0,0 +1,139 @@
+// Task tool: launches a sub-agent with its own context window and tool set, in the
+// foreground or (run_in_background) as a background task. TaskOutput / TaskStop manage
+// background tasks.
+
+import { taskResultText } from '../tasks.js';
+
+// Wait for `promise`, at most `ms`, or until `signal` aborts. The timer is always cleared so a
+// finished wait never keeps the process alive.
+function waitFor(promise, ms, signal) {
+  let timer, onAbort;
+  const limit = new Promise((resolve) => {
+    timer = setTimeout(resolve, ms);
+    onAbort = () => resolve();
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+  return Promise.race([promise, limit]).finally(() => {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', onAbort);
+  });
+}
+
+export function makeTaskTool(agents) {
+  const list = [...agents.values()]
+    .map((a) => `- ${a.name}: ${a.description} (Tools: ${a.tools === '*' ? 'All tools' : a.tools.join(', ')})`)
+    .join('\n');
+  return {
+    name: 'Task',
+    readOnly: true, // sub-agents ask for their own permissions; multiple tasks may run in parallel
+    description: `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+Available agent types and the tools they have access to:
+${list}
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead
+
+Usage notes:
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- Each agent invocation is stateless. Your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+- Set run_in_background: true to start the agent and continue working while it runs (e.g. a long investigation, or several independent jobs). You get a task id back immediately, and the agent's final report arrives automatically in a <task-notification> once it finishes; you do not need to poll. Use TaskOutput to check on or wait for it early, and TaskStop to cancel it. Do not start background agents that edit the same files at the same time.`,
+    input_schema: {
+      type: 'object',
+      properties: {
+        description: { type: 'string', description: 'A short (3-5 word) description of the task' },
+        prompt: { type: 'string', description: 'The task for the agent to perform' },
+        subagent_type: { type: 'string', description: 'The type of specialized agent to use for this task' },
+        run_in_background: { type: 'boolean', description: 'Run the agent in the background and return immediately with a task id' },
+      },
+      required: ['description', 'prompt', 'subagent_type'],
+    },
+    summarize(input) { return `${input.description || ''}${input.run_in_background ? ' (background)' : ''}`; },
+    label(input) { return input.subagent_type && input.subagent_type !== 'general-purpose' ? input.subagent_type : 'Task'; },
+    async call(input, ctx) {
+      const def = agents.get(input.subagent_type) || agents.get('general-purpose');
+      if (!agents.has(input.subagent_type) && input.subagent_type) {
+        return { isError: true, content: `Agent type '${input.subagent_type}' not found. Available agents: ${[...agents.keys()].join(', ')}` };
+      }
+      if (input.run_in_background) {
+        if (!ctx.tasks) return { isError: true, content: 'Background agents are not available here; run the task in the foreground.' };
+        // The task outlives this turn, so it gets its own signal and no live progress display.
+        const base = { cwd: ctx.cwd, projectRoot: ctx.projectRoot, config: ctx.config, modes: ctx.modes, checkpoints: ctx.checkpoints, io: ctx.io, depth: ctx.agent?.depth ?? 0 };
+        const task = ctx.tasks.start({
+          description: input.description || def.name,
+          subagentType: def.name,
+          run: (signal) => ctx.spawnSubagent({ def, prompt: input.prompt, description: input.description, ctx: { ...base, signal } }),
+        });
+        return {
+          content: `Started background agent ${task.id} (${def.name}): ${input.description}. Its final report will arrive in a <task-notification> when it finishes. Continue with other work; use TaskOutput with task_id "${task.id}" only if you need to wait for it.`,
+          display: { summary: `Running in background (${task.id})` },
+        };
+      }
+      const started = Date.now();
+      const { text, toolUses, tokens } = await ctx.spawnSubagent({ def, prompt: input.prompt, description: input.description, ctx });
+      const secs = Math.round((Date.now() - started) / 100) / 10;
+      const kTok = tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
+      return {
+        content: text || '(the agent returned no text)',
+        display: { summary: `Done (${toolUses} tool use${toolUses === 1 ? '' : 's'} · ${kTok} tokens · ${secs}s)` },
+      };
+    },
+  };
+}
+
+export const TaskOutputTool = {
+  name: 'TaskOutput',
+  readOnly: true,
+  description: `Gets the status and result of a background agent started with Task run_in_background.
+- By default waits (block: true) until the agent finishes or the timeout passes.
+- You normally do not need this: a finished agent's report arrives automatically in a <task-notification>. Use it when you cannot continue without the result.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'The background task id, e.g. agent_1' },
+      block: { type: 'boolean', description: 'Wait for the task to finish (default true)' },
+      timeout: { type: 'number', description: 'Maximum time to wait in milliseconds (default 120000, max 600000)' },
+    },
+    required: ['task_id'],
+  },
+  summarize(input) { return input.task_id; },
+  async call(input, ctx) {
+    const task = ctx.tasks?.get(input.task_id);
+    if (!task) return { isError: true, content: `No background task with id ${input.task_id}. Known: ${ctx.tasks?.list().map((t) => t.id).join(', ') || 'none'}` };
+    if (task.status === 'running' && input.block !== false) {
+      const timeout = Math.min(Math.max(1000, input.timeout || 120_000), 600_000);
+      await waitFor(task.promise, timeout, ctx.signal);
+      if (ctx.signal?.aborted) throw Object.assign(new Error('aborted'), { name: 'AbortError' });
+    }
+    if (task.status === 'running') {
+      return { content: `<status>running</status>\nTask ${task.id} ("${task.description}") is still running after ${Math.round((Date.now() - task.started) / 1000)}s.`, display: { summary: 'Still running' } };
+    }
+    // The result is delivered here, so drop the pending notification for it.
+    if (ctx.agent) ctx.agent.notifications = ctx.agent.notifications.filter((n) => n.taskId !== task.id);
+    return { content: `<status>${task.status}</status>\n<result>\n${taskResultText(task)}\n</result>`, isError: task.status === 'failed', display: { summary: task.status } };
+  },
+};
+
+export const TaskStopTool = {
+  name: 'TaskStop',
+  description: 'Stops a running background agent by its task id.',
+  input_schema: {
+    type: 'object',
+    properties: { task_id: { type: 'string', description: 'The background task id to stop' } },
+    required: ['task_id'],
+  },
+  summarize(input) { return input.task_id; },
+  async call(input, ctx) {
+    const task = ctx.tasks?.get(input.task_id);
+    if (!task) return { isError: true, content: `No background task with id ${input.task_id}` };
+    if (!ctx.tasks.kill(task.id)) return { content: `Task ${task.id} is not running (status: ${task.status})` };
+    return { content: `Stopped background agent ${task.id} ("${task.description}")` };
+  },
+};