@occasiolabs/occasio 0.8.4 → 0.8.5

package/src/cli/help.js

@@ -1,6 +1,11 @@
 // `occasio help` — top-level usage. Pure text; no side effects other
 // than console.log. Each CLI command lives in its own file under
 // src/cli/ as part of the index.js decomposition (see CHANGELOG).
+//
+// Maturity tags follow the bewertung pillars:
+//   (stable) — load-bearing, has test coverage and field validation
+//   (beta)   — works end-to-end but missing breadth (one detector, one preset)
+//   (alpha)  — scaffold; needs operator calibration before relying on it
 
 'use strict';
 
@@ -19,42 +24,58 @@ function run() {
   console.log(`
 ${col.b(`⚡ Occasio v${VERSION}`)}
 
-${col.b('Usage:')}
-  occasio claude [args...]   Start Claude with local proxy (intercept + log)
-  occasio demo               10-second proof: see Occasio block real secrets
-  occasio demo attest        End-to-end attestation pipeline against a synthetic audit chain
-  occasio demo anomalies     End-to-end EDR test: synthetic adversarial chain → all 4 detectors
-  occasio dashboard          Open live dashboard for the running session
-  occasio register           Register shell alias (type 'claude' directly)
-  occasio status             Show session stats and savings breakdown
-  occasio doctor             Check setup: Node, claude CLI, port, Python, profile
-  occasio clear              Reset today's log and session data
-  occasio clear --history    Wipe all historical logs
-  occasio ledger             Inspect token ledger (--last N, --summary, --scope session|today)
-  occasio replay             Replay run audit (--last N, --detail, --run <id>, --attribute)
-  occasio distill            Inspect distilled outputs (--last N, --entry <N> for raw)
-  occasio inspect            Cloud-boundary manifest (--last N, --entry N, --run <id>)
-  occasio boundary           Per-request three-column view: produced / re-entered / prevented
-  occasio baseline           Behavior baseline: [learn|show|compare|reset] (per project cwd)
-  occasio harness            Run a real Claude Code session against scratch fixtures and verify governance claims (needs ANTHROPIC_API_KEY)
-  occasio redteam            Autonomous adversarial test — tester LLM probes a subject Claude Code session under Occasio (needs ANTHROPIC_API_KEY + @anthropic-ai/sdk)
-  occasio policy [show]      Show active policy: flags, tool routing, overrides
-  occasio policy show --diff Only values that differ from defaults
-  occasio policy validate    Validate policy.yml and report errors/warnings
-  occasio policy init        Create a starter policy.yml (safe, non-destructive)
-                                Use --template strict|finance for a non-default starter
-  occasio policy doctor      Cross-reference session logs with policy; surface suggestions
-  occasio audit [verify]     Verify tamper-evident hash chain in pipeline-events.jsonl
-  occasio audit repair       Truncate a crash-partial trailing line (--file <path> [--dry-run])
-  occasio report             Governance export: file access log, blocked paths, secret events
-  occasio anomalies          Live anomaly detection over the audit chain (--window 15m, --json)
-  occasio computer-use       Apply a Computer-Use policy to a JSONL of tool_use blocks (--dry-run --example)
-  occasio attest --run-id <uuid>  AI-Agent Behavioral Attestation v1: hash-chain commitment + execution summary for one run
-                              Add --sign in GitHub Actions (with permissions: id-token: write) for Sigstore keyless signing
-  occasio attest verify <file>   Re-verify a signed attestation: Sigstore bundle + DSSE payload match + audit chain integrity
-  occasio selftest           Run governance self-checks on a scratch chain (does not touch your audit log)
-  occasio report --format csv  CSV export for auditors / SIEM import
-  occasio mcp-experiment     MCP vs. built-in tool adoption stats (experiment)
+${col.b('60-Second Start:')}
+  ${col.c('occasio init')}        Create policy.yml from a template
+  ${col.c('occasio register')}    Install shell alias so 'claude' uses the proxy
+  ${col.c('claude --version')}    Confirm the wrapper resolves Claude Code
+
+${col.b('Usage:')}  occasio <command> [args...]   (or  oc <command>)
+
+${col.b('Setup')} ${col.d('— one-time, per project')}
+  init                       ${col.d('(stable)')} Create starter policy.yml (--template strict|finance)
+  register                   ${col.d('(stable)')} Register shell alias (type 'claude' directly)
+  doctor                     ${col.d('(stable)')} Check setup: Node, claude CLI, port, Python, profile
+
+${col.b('Run')} ${col.d('— start a session, observe live state')}
+  claude [args...]           ${col.d('(stable)')} Start Claude with local proxy (intercept + log)
+  status                     ${col.d('(stable)')} Session stats, savings breakdown, coverage
+  clear                      ${col.d('(stable)')} Reset today's log and session data
+  clear --history            ${col.d('(stable)')} Wipe all historical logs
+  ledger                     ${col.d('(stable)')} Inspect token ledger (--last N, --summary, --scope)
+  dashboard                  ${col.d('(beta)')}   Open live dashboard at http://localhost:3001
+
+${col.b('Inspect')} ${col.d('— forensics over what the agent did')}
+  replay                     ${col.d('(stable)')} Replay run audit (--last N, --detail, --run <id>)
+  boundary                   ${col.d('(stable)')} Per-request: produced / re-entered / prevented
+  inspect                    ${col.d('(stable)')} Cloud-boundary manifest (--last N, --entry N)
+  distill                    ${col.d('(stable)')} Inspect distilled outputs (--last N, --entry <N>)
+  report                     ${col.d('(stable)')} Governance export (--format csv for SIEM)
+  preflight                  ${col.d('(beta)')}   Read-only miner over past logs
+  baseline                   ${col.d('(beta)')}   Behavior baseline: [learn|show|compare|reset]
+
+${col.b('Audit')} ${col.d('— tamper-evidence and attestation')}
+  audit verify               ${col.d('(stable)')} Verify hash chain in pipeline-events.jsonl
+  audit repair               ${col.d('(stable)')} Truncate crash-partial trailing line (--file --dry-run)
+  attest --run-id <uuid>     ${col.d('(stable)')} Behavioral attestation: hash-chain + execution summary
+                             ${col.d('Add --sign in GitHub Actions for Sigstore keyless signing')}
+  attest verify <file>       ${col.d('(stable)')} Re-verify signed attestation (bundle + DSSE + chain)
+  selftest                   ${col.d('(stable)')} Run governance self-checks on scratch chain
+
+${col.b('Detect')} ${col.d('— anomalies, adversarial probes')}
+  anomalies                  ${col.d('(beta)')}   Windowed EDR over the audit chain (--window 15m --json)
+  harness                    ${col.d('(alpha)')}  Real Claude Code run vs. governance claims (API key required)
+  redteam                    ${col.d('(alpha)')}  Autonomous adversarial probe (API key + SDK required)
+
+${col.b('Policy & extras')}
+  policy [show]              ${col.d('(stable)')} Show active policy: flags, routing, overrides
+  policy show --diff         ${col.d('(stable)')} Only values that differ from defaults
+  policy validate            ${col.d('(stable)')} Validate policy.yml and report errors/warnings
+  policy doctor              ${col.d('(beta)')}   Cross-reference logs with policy; suggest tightening
+  computer-use               ${col.d('(alpha)')}  Apply policy to a JSONL of tool_use blocks (--dry-run --example)
+  mcp-experiment             ${col.d('(beta)')}   MCP vs. built-in tool adoption stats
+  demo                       ${col.d('(stable)')} 10-second proof: see Occasio block real secrets
+  demo attest                ${col.d('(stable)')} End-to-end attestation pipeline against a synthetic chain
+  demo anomalies             ${col.d('(stable)')} End-to-end EDR test: synthetic adversarial chain
 
 ${col.b('Presets:')}
   --preset balanced  (default)  Intercept safe reads locally, log all requests
@@ -68,7 +89,7 @@ ${col.b('Flags:')}
   --log-only                    Alias for --preset off
   --dashboard                   Open live dashboard at http://localhost:3001
   --port <N>                    Proxy port (default: 8081)
-  --verbose                     Print live per-request chatter (off by default — quiet for Claude Code's TUI)
+  --verbose                     Print live per-request chatter (off by default)
 
 ${col.b('Multi-agent routing:')}
   Default               → Claude Code adapter

package/src/cli/status.js

@@ -26,7 +26,7 @@ function todayStr() {
 function getLogFile() { return path.join(LOG_DIR, 'logs', `${todayStr()}.jsonl`); }
 
 function run() {
-  let s = null; try { s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')); } catch {}
+  let s = null; try { s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')); } catch { /* ignore */ }
   console.log(col.b('\n⚡ Occasio\n'));
   if (!s) { console.log(col.d('  No session data yet. Run: occasio claude\n')); return; }
 

package/src/dashboard.js

@@ -16,7 +16,6 @@ const path = require('path');
 const os   = require('os');
 
 const DASHBOARD_PORT = 3001;
-const PROXY_PORT     = 8081;
 const LOG_DIR      = path.join(os.homedir(), '.occasio');
 const SESSION_FILE = path.join(LOG_DIR, 'session.json');
 
@@ -97,8 +96,8 @@ const server = http.createServer((req, res) => {
   }
 
   if (req.url === '/api/clear' && req.method === 'POST') {
-    try { fs.writeFileSync(todayLogFile(), ''); } catch {}
-    try { fs.writeFileSync(SESSION_FILE, '{}'); } catch {}
+    try { fs.writeFileSync(todayLogFile(), ''); } catch { /* ignore */ }
+    try { fs.writeFileSync(SESSION_FILE, '{}'); } catch { /* ignore */ }
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end('{"ok":true}');
     broadcast({ type: 'update', session: {}, entries: [] });

package/src/distiller.js

@@ -120,7 +120,7 @@ const FAIL_RE = /\b(FAIL|FAILED|ERROR|error:|✗|×|AssertionError|not ok|ERRORE
  * Keeps all failure-related lines (plus 1 line of context each side) and the
  * last 15 lines (usually the summary).  Clips total to TEST_MAX_LINES.
  */
-function distillTestOutput(output, rawBytes, cmd) {
+function distillTestOutput(output, rawBytes, _cmd) {
   const lines = output.split('\n');
   const none  = { content: output, distilled: false, savedTokens: 0, label: '', rawBytes, rawContent: null };
   if (lines.length <= TEST_MAX_LINES) return none;

package/src/executor/dispatcher.js

@@ -44,7 +44,7 @@ const NATIVE_HANDLERS = {
   // but nativeHandle returned null, fall back to the exec subprocess. The
   // returned `native` field tells the caller which path was taken.
   [CANONICAL.SHELL_BASH]: async (input) => {
-    const cmd = (input?.command || '').trim();
+    const cmd = (typeof input?.command === 'string' ? input.command : '').trim();
     if (!cmd) return null;
     const nr = nativeHandle(cmd);
     if (nr !== null) {
@@ -63,7 +63,7 @@ const NATIVE_HANDLERS = {
   // then native-only execution. expandedCmd is returned so the caller can
   // record the actually-executed command in toolsRun.
   [CANONICAL.SHELL_POWERSHELL]: (input) => {
-    const rawCmd = (input?.command || '').trim();
+    const rawCmd = (typeof input?.command === 'string' ? input.command : '').trim();
     if (!rawCmd) return null;
     const cmd = expandPsEnvVars(rawCmd);
     const nr = nativeHandle(cmd);

package/src/executor/native-handlers/glob.js

@@ -0,0 +1,173 @@
+'use strict';
+
+/**
+ * Native handler for the Glob tool.
+ *
+ * Pure filesystem function: takes a glob pattern (+ optional base path) and
+ * returns a sorted list of matching paths. No dependency on the interceptor
+ * pipeline, Anthropic API, or shell execution. Safe to import in any process
+ * context.
+ *
+ * Extracted from src/runtime.js as Stage-2 Step 3 of the executor migration
+ * (see docs/ADAPTER-STAGE-2-MIGRATION.md). src/runtime.js re-exports these
+ * so existing consumers keep working unchanged.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Glob tool support ──────────────────────────────────────────────────────────
+
+// Characters that indicate shell injection in a glob pattern.
+// We reject patterns containing these so handleGlobTool stays read-only.
+const GLOB_INJECTION_RE = /[;&|`$<>!]/;
+
+// Directories skipped during recursive glob walks.
+const GLOB_SKIP = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build', '__pycache__', '.venv', 'venv']);
+
+// Maximum number of matches returned to avoid overwhelming the model context.
+const GLOB_MAX = 500;
+
+// Maximum recursion depth from baseDir. Hard cap on path-traversal DoS
+// (a fuzz-discovered class — see THREAT-MODEL.md residual risk #5).
+// Tunable via env for special-case repos.
+const GLOB_MAX_DEPTH = Number(process.env.OCCASIO_GLOB_MAX_DEPTH) || 16;
+
+// Soft wall-clock limit per walk in ms. Stops a walk that strayed onto a huge
+// subtree (e.g. agent globbed up from /) before it burns seconds. Stop is
+// best-effort — the caller still receives whatever was collected so far.
+const GLOB_MAX_MS = Number(process.env.OCCASIO_GLOB_MAX_MS) || 2_000;
+
+function isGlobHandleable(input) {
+  if (!input || typeof input !== 'object') return false;
+  const pattern = input.pattern;
+  if (!pattern || typeof pattern !== 'string' || !pattern.trim()) return false;
+  if (GLOB_INJECTION_RE.test(pattern)) return false;
+  if (input.path != null && typeof input.path !== 'string') return false;
+  return true;
+}
+
+// Escape regex metacharacters in a literal string segment.
+function escapeRegexChars(s) {
+  return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports: ** (any path depth), * (single segment), ? (single char),
+ * {ts,tsx} (alternation), [abc] (character classes).
+ * Exported for unit testing.
+ */
+function globToRegex(pattern) {
+  // Normalise Windows separators in the pattern.
+  const p = pattern.replace(/\\/g, '/');
+
+  let re = '';
+  let i = 0;
+  while (i < p.length) {
+    // ** — match any path segments (including none), consuming the trailing /
+    if (p[i] === '*' && p[i + 1] === '*') {
+      re += '.*';
+      i += 2;
+      if (p[i] === '/') i++; // consume separator after **
+      continue;
+    }
+    // * — match within a single path segment
+    if (p[i] === '*') { re += '[^/]*'; i++; continue; }
+    // ? — match a single character within a segment
+    if (p[i] === '?') { re += '[^/]'; i++; continue; }
+    // {a,b,c} — alternation
+    if (p[i] === '{') {
+      const end = p.indexOf('}', i);
+      if (end !== -1) {
+        const alts = p.slice(i + 1, end).split(',').map(escapeRegexChars);
+        re += `(?:${alts.join('|')})`;
+        i = end + 1;
+        continue;
+      }
+    }
+    // [abc] / [^abc] — pass character classes through verbatim
+    if (p[i] === '[') {
+      const end = p.indexOf(']', i);
+      if (end !== -1) { re += p.slice(i, end + 1); i = end + 1; continue; }
+    }
+    re += escapeRegexChars(p[i]);
+    i++;
+  }
+
+  // On Windows, matching is case-insensitive; on POSIX it's case-sensitive.
+  const flags = process.platform === 'win32' ? 'i' : '';
+  return new RegExp(`^${re}$`, flags);
+}
+
+/**
+ * Walk `dir` recursively, collecting paths that match `regex`.
+ * Results are relative to `baseDir`.
+ */
+function walkGlob(dir, baseDir, regex, results, depth = 0, deadline = Infinity) {
+  if (results.length >= GLOB_MAX) return;
+  if (depth >= GLOB_MAX_DEPTH) return;
+  if (Date.now() >= deadline) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const entry of entries) {
+    if (results.length >= GLOB_MAX) break;
+    if (Date.now() >= deadline) break;
+    if (GLOB_SKIP.has(entry.name)) continue;
+    const abs     = path.join(dir, entry.name);
+    // Normalise to forward slashes for matching (consistent on all platforms).
+    const rel     = path.relative(baseDir, abs).replace(/\\/g, '/');
+    if (entry.isDirectory()) {
+      walkGlob(abs, baseDir, regex, results, depth + 1, deadline);
+    } else if (regex.test(rel)) {
+      results.push(rel);
+    }
+  }
+}
+
+/**
+ * Resolve glob pattern + optional base path to a sorted list of matching paths,
+ * relative to CWD.  Returns { output, exitCode, matchCount }.
+ */
+function handleGlobTool(input) {
+  const pattern = (typeof input?.pattern === 'string' ? input.pattern : '').trim();
+  if (!pattern) return { output: '(no pattern provided)', exitCode: 1, matchCount: 0 };
+
+  const baseDir = input?.path
+    ? path.resolve(process.cwd(), input.path)
+    : process.cwd();
+
+  const cwd = process.cwd();
+
+  let regex;
+  try { regex = globToRegex(pattern); }
+  catch (e) { return { output: `Glob: invalid pattern: ${e.message}`, exitCode: 1, matchCount: 0 }; }
+
+  const results = [];
+  const deadline = Date.now() + GLOB_MAX_MS;
+  walkGlob(baseDir, baseDir, regex, results, 0, deadline);
+  const timedOut = Date.now() >= deadline;
+  results.sort();
+
+  const truncated = results.length >= GLOB_MAX;
+  const lines = results.map(r => path.join(baseDir !== cwd ? baseDir : '', r).replace(/\\/g, '/'));
+  const suffix = truncated ? `\n(truncated at ${GLOB_MAX} results)`
+               : timedOut  ? `\n(truncated — walk exceeded ${GLOB_MAX_MS} ms)`
+               : '';
+  const output = lines.join('\n') + suffix;
+  return { output: output || '(no matches)', exitCode: 0, matchCount: results.length };
+}
+
+module.exports = {
+  GLOB_INJECTION_RE,
+  GLOB_SKIP,
+  GLOB_MAX,
+  GLOB_MAX_DEPTH,
+  GLOB_MAX_MS,
+  isGlobHandleable,
+  globToRegex,
+  walkGlob,
+  handleGlobTool,
+};

package/src/executor/native-handlers/grep.js

@@ -0,0 +1,258 @@
+'use strict';
+
+/**
+ * Native handler for the Grep tool.
+ *
+ * Pure filesystem function: takes a regex pattern (+ optional path, glob, type,
+ * output_mode, context flags) and returns matches in one of three formats
+ * (files_with_matches | content | count). No dependency on the interceptor
+ * pipeline, Anthropic API, or shell execution.
+ *
+ * Extracted from src/runtime.js as Stage-2 Step 4 of the executor migration
+ * (see docs/ADAPTER-STAGE-2-MIGRATION.md). src/runtime.js re-exports these so
+ * existing consumers keep working unchanged.
+ *
+ * Imports `globToRegex` and `GLOB_SKIP` from the Glob handler — the Grep file
+ * filter shares the glob grammar, and both walks skip the same vendor dirs.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { MAX_OUTPUT }                                            = require('./read');
+const { globToRegex, GLOB_SKIP, GLOB_MAX_DEPTH, GLOB_MAX_MS }   = require('./glob');
+
+// ── Grep tool support ──────────────────────────────────────────────────────────
+
+const GREP_MAX_RESULTS = 250;   // default output cap — matches Claude Code head_limit default
+const GREP_FILE_CAP   = 10_000; // safety limit on files walked before stopping
+
+// File-type → extension mapping, matching ripgrep's --type names.
+const GREP_TYPE_EXTS = new Map([
+  ['js',   ['.js', '.mjs', '.cjs']],
+  ['ts',   ['.ts', '.tsx', '.mts', '.cts']],
+  ['py',   ['.py', '.pyi']],
+  ['rust', ['.rs']],
+  ['go',   ['.go']],
+  ['java', ['.java']],
+  ['rb',   ['.rb']],
+  ['css',  ['.css', '.scss', '.sass', '.less']],
+  ['html', ['.html', '.htm']],
+  ['json', ['.json', '.jsonc']],
+  ['md',   ['.md', '.mdx']],
+  ['yaml', ['.yaml', '.yml']],
+  ['sh',   ['.sh', '.bash', '.zsh']],
+  ['c',    ['.c', '.h']],
+  ['cpp',  ['.cpp', '.cc', '.cxx', '.hpp', '.hh']],
+]);
+
+const VALID_GREP_MODES = new Set(['content', 'files_with_matches', 'count']);
+
+function isGrepHandleable(input) {
+  if (!input || typeof input !== 'object') return false;
+  const pattern = input.pattern;
+  if (!pattern || typeof pattern !== 'string' || !pattern.trim()) return false;
+  // Optional fields must be the right type when present.
+  if (input.path        != null && typeof input.path        !== 'string')  return false;
+  if (input.glob        != null && typeof input.glob        !== 'string')  return false;
+  if (input.type        != null && typeof input.type        !== 'string')  return false;
+  if (input.output_mode != null && !VALID_GREP_MODES.has(input.output_mode)) return false;
+  // Cross-line matching (rg -U) requires full-file regex — not supported natively.
+  if (input.multiline === true) return false;
+  return true;
+}
+
+// Read a file for grep: returns null for binary files or on read error.
+function tryReadGrep(absPath) {
+  try {
+    const buf = fs.readFileSync(absPath);
+    if (buf.slice(0, 512).includes(0)) return null;  // binary file — skip
+    return (buf.length > MAX_OUTPUT ? buf.slice(0, MAX_OUTPUT) : buf).toString('utf8');
+  } catch { return null; }
+}
+
+// Walk directory collecting absolute file paths, honouring glob and type filters.
+function walkGrepFiles(dir, baseDir, globRegex, globHasDir, typeExts, results, depth = 0, deadline = Infinity) {
+  if (results.length >= GREP_FILE_CAP) return;
+  if (depth >= GLOB_MAX_DEPTH) return;
+  if (Date.now() >= deadline) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    if (results.length >= GREP_FILE_CAP) break;
+    if (Date.now() >= deadline) break;
+    if (GLOB_SKIP.has(entry.name)) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkGrepFiles(abs, baseDir, globRegex, globHasDir, typeExts, results, depth + 1, deadline);
+    } else {
+      if (typeExts && !typeExts.includes(path.extname(abs).toLowerCase())) continue;
+      if (globRegex) {
+        // Glob patterns with path separators match against the relative path;
+        // plain filename globs (e.g. "*.ts") match against the basename only.
+        const testStr = globHasDir
+          ? path.relative(baseDir, abs).replace(/\\/g, '/')
+          : path.basename(abs);
+        if (!globRegex.test(testStr)) continue;
+      }
+      results.push(abs);
+    }
+  }
+}
+
+/**
+ * Execute a structured Grep tool call locally.
+ *
+ * Supports: pattern, path, glob, type, output_mode (files_with_matches | content | count),
+ * -i (case-insensitive), -C / context / -A / -B (context lines), head_limit, offset.
+ *
+ * Does NOT support multiline (cross-line regex) — isGrepHandleable rejects those.
+ */
+function handleGrepTool(input) {
+  const pattern = (typeof input?.pattern === 'string' ? input.pattern : '').trim();
+  if (!pattern) return { output: '(no pattern provided)', exitCode: 1, matchCount: 0 };
+
+  const searchRoot = input?.path
+    ? path.resolve(process.cwd(), input.path)
+    : process.cwd();
+
+  const outputMode  = input?.output_mode || 'files_with_matches';
+  const caseInsens  = input?.['-i'] === true;
+  const contextN    = typeof input?.['-C'] === 'number' ? input['-C'] :
+                      typeof input?.context === 'number' ? input.context : 0;
+  const linesBefore = typeof input?.['-B'] === 'number' ? input['-B'] : contextN;
+  const linesAfter  = typeof input?.['-A'] === 'number' ? input['-A'] : contextN;
+  const headLimit   = typeof input?.head_limit === 'number' && input.head_limit > 0
+    ? Math.min(input.head_limit, GREP_MAX_RESULTS)
+    : GREP_MAX_RESULTS;
+  const skipLines   = typeof input?.offset === 'number' && input.offset > 0 ? input.offset : 0;
+
+  let regex;
+  try {
+    regex = new RegExp(pattern, 'g' + (caseInsens ? 'i' : ''));
+  } catch (e) {
+    return { output: `Grep: invalid pattern: ${e.message}`, exitCode: 1, matchCount: 0 };
+  }
+
+  // Build type extension filter.
+  let typeExts = null;
+  if (input?.type) {
+    const t = input.type.toLowerCase();
+    typeExts = GREP_TYPE_EXTS.get(t) || [t.startsWith('.') ? t : `.${t}`];
+  }
+
+  // Build glob file filter.
+  let globRegex  = null;
+  let globHasDir = false;
+  if (input?.glob) {
+    try {
+      globRegex  = globToRegex(input.glob);
+      globHasDir = input.glob.includes('/') || input.glob.includes('**');
+    } catch { /* ignore invalid glob — no filter applied */ }
+  }
+
+  // Collect candidate files.
+  let files = [];
+  const deadline = Date.now() + GLOB_MAX_MS;
+  try {
+    const stat = fs.statSync(searchRoot);
+    if (stat.isFile()) {
+      files.push(searchRoot);
+    } else {
+      walkGrepFiles(searchRoot, searchRoot, globRegex, globHasDir, typeExts, files, 0, deadline);
+      files.sort();
+    }
+  } catch (e) {
+    return { output: `Grep: cannot access path: ${e.message}`, exitCode: 1, matchCount: 0 };
+  }
+
+  const outputLines = [];
+  let totalMatches  = 0;
+  let truncated     = false;
+  // wantMore also enforces the per-call wall-clock budget so the
+  // file-read+match loop can't blow past it even if walkGrepFiles already
+  // collected thousands of paths before the walk-deadline tripped.
+  const wantMore    = () => outputLines.length < skipLines + headLimit
+                         && Date.now() < deadline;
+  const relOf       = abs => path.relative(searchRoot, abs).replace(/\\/g, '/') || path.basename(abs);
+
+  if (outputMode === 'files_with_matches') {
+    for (const absFile of files) {
+      if (!wantMore()) { truncated = true; break; }
+      const content = tryReadGrep(absFile);
+      if (!content) continue;
+      regex.lastIndex = 0;
+      if (regex.test(content)) { totalMatches++; outputLines.push(relOf(absFile)); }
+    }
+
+  } else if (outputMode === 'count') {
+    for (const absFile of files) {
+      if (!wantMore()) { truncated = true; break; }
+      const content = tryReadGrep(absFile);
+      if (!content) continue;
+      let count = 0;
+      for (const line of content.split('\n')) { regex.lastIndex = 0; if (regex.test(line)) count++; }
+      if (count > 0) { totalMatches += count; outputLines.push(`${relOf(absFile)}:${count}`); }
+    }
+
+  } else {  // content
+    for (const absFile of files) {
+      if (!wantMore()) { truncated = true; break; }
+      const content = tryReadGrep(absFile);
+      if (!content) continue;
+      const fileLabel = relOf(absFile);
+      const fileLines = content.split('\n');
+      const matchSet  = new Set();
+      for (let i = 0; i < fileLines.length; i++) {
+        regex.lastIndex = 0;
+        if (regex.test(fileLines[i])) matchSet.add(i);
+      }
+      if (!matchSet.size) continue;
+      totalMatches += matchSet.size;
+
+      // Merge context windows into non-overlapping groups.
+      const sorted = [...matchSet].sort((a, b) => a - b);
+      const groups = [];
+      let gs = -1, ge = -1;
+      for (const idx of sorted) {
+        const s = Math.max(0, idx - linesBefore);
+        const e = Math.min(fileLines.length - 1, idx + linesAfter);
+        if (gs === -1) { gs = s; ge = e; }
+        else if (s <= ge + 1) { ge = Math.max(ge, e); }
+        else { groups.push([gs, ge]); gs = s; ge = e; }
+      }
+      if (gs !== -1) groups.push([gs, ge]);
+
+      let firstGroup = true;
+      for (const [gStart, gEnd] of groups) {
+        if (!wantMore()) { truncated = true; break; }
+        if (!firstGroup) outputLines.push('--');
+        firstGroup = false;
+        for (let i = gStart; i <= gEnd && wantMore(); i++) {
+          const sep = matchSet.has(i) ? ':' : '-';
+          outputLines.push(`${fileLabel}${sep}${i + 1}${sep}${fileLines[i]}`);
+        }
+      }
+    }
+  }
+
+  const sliced  = outputLines.slice(skipLines, skipLines + headLimit);
+  const text    = sliced.join('\n') || '(no matches)';
+  const timedOut = Date.now() >= deadline;
+  const suffix  = truncated ? '\n(truncated — use head_limit/offset to paginate)'
+                : timedOut  ? `\n(truncated — walk exceeded ${GLOB_MAX_MS} ms)`
+                : '';
+  return { output: text + suffix, exitCode: 0, matchCount: totalMatches };
+}
+
+module.exports = {
+  GREP_MAX_RESULTS,
+  GREP_FILE_CAP,
+  GREP_TYPE_EXTS,
+  VALID_GREP_MODES,
+  isGrepHandleable,
+  tryReadGrep,
+  walkGrepFiles,
+  handleGrepTool,
+};