@occasiolabs/occasio 0.8.3 → 0.8.5

package/src/cli/help.js

@@ -0,0 +1,102 @@
+// `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';
+
+const VERSION = (() => {
+  try { return require('../../package.json').version; }
+  catch { return '0.0.0-unknown'; }
+})();
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, c: s => `\x1b[36m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function run() {
+  console.log(`
+${col.b(`⚡ Occasio v${VERSION}`)}
+
+${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
+  --preset strict               Block requests that contain detected secrets
+  --preset off                  Log only — no interception, no blocking
+
+${col.b('Flags:')}
+  --budget <N>                  Block requests once session cost exceeds $N (e.g. --budget 1.00)
+  --hardened                    Route Read/Glob/Grep through unified runtime (distill + secret scan)
+  --block-secrets               Alias for --preset strict
+  --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)
+
+${col.b('Multi-agent routing:')}
+  Default               → Claude Code adapter
+  Header x-occasio-agent: cline → Cline adapter (synthetic; live validation pending)
+
+${col.b('Logs:')} ~/.occasio/logs/YYYY-MM-DD.jsonl
+`);
+}
+
+module.exports = { run };

package/src/cli/register.js

@@ -0,0 +1,90 @@
+// `occasio register` — installs a `claude()` shell function so the user
+// can keep typing `claude` and silently get routed through the proxy.
+//
+// Idempotent: detects the canonical marker and exits; auto-upgrades the
+// legacy `--intercept` snippet to `claude` if found. Best-effort on
+// failure — prints a manual instruction rather than crashing.
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, d: s => `\x1b[2m${s}\x1b[0m`,
+};
+
+function registerWindows() {
+  const profileDir  = path.join(os.homedir(), 'Documents', 'PowerShell');
+  const profileFile = path.join(profileDir, 'Microsoft.PowerShell_profile.ps1');
+  const snippet = `\n# Occasio — intercept Claude Code traffic\nfunction claude { occasio claude @args }\n`;
+  const alreadyMarker = 'occasio claude @args';
+  const legacyMarker  = 'occasio --intercept @args';
+  try {
+    if (!fs.existsSync(profileDir)) fs.mkdirSync(profileDir, { recursive: true });
+    const existing = fs.existsSync(profileFile) ? fs.readFileSync(profileFile, 'utf8') : '';
+    if (existing.includes(alreadyMarker)) {
+      console.log(col.g('✓ Already registered (PowerShell)'));
+      console.log(col.d('  Type: claude'));
+    } else if (existing.includes(legacyMarker)) {
+      const updated = existing.replace(
+        /function claude \{ occasio --intercept @args \}/g,
+        'function claude { occasio claude @args }'
+      );
+      fs.writeFileSync(profileFile, updated);
+      console.log(col.g('✓ Updated to canonical form (occasio claude)'));
+      console.log('');
+      console.log(col.y(`  ⚠  Restart PowerShell — the 'claude' alias is not active yet.`));
+      console.log(col.d(`     Open a new terminal, or run:  . $PROFILE`));
+      console.log('');
+    } else {
+      fs.appendFileSync(profileFile, snippet);
+      console.log(col.g(`✓ Registered in ${profileFile}`));
+      console.log('');
+      console.log(col.y(`  ⚠  Restart PowerShell — the 'claude' alias is not active yet.`));
+      console.log(col.d(`     Open a new terminal, or run:  . $PROFILE`));
+      console.log('');
+    }
+  } catch (e) {
+    console.log(col.r(`✗ Could not write profile: ${e.message}`));
+    console.log(col.d(`  Add manually to your PowerShell profile:\n  function claude { occasio claude @args }`));
+  }
+}
+
+function registerPosix() {
+  const rcFile = (process.env.SHELL || '').includes('zsh')
+    ? path.join(os.homedir(), '.zshrc')
+    : path.join(os.homedir(), '.bashrc');
+  const snippet = `\n# Occasio — intercept Claude Code traffic\nclaude() { occasio claude "$@"; }\n`;
+  const alreadyMarker = 'occasio claude "$@"';
+  const legacyMarker  = 'occasio --intercept "$@"';
+  try {
+    const existing = fs.existsSync(rcFile) ? fs.readFileSync(rcFile, 'utf8') : '';
+    if (existing.includes(alreadyMarker)) {
+      console.log(col.g(`✓ Already registered (${rcFile})`));
+    } else if (existing.includes(legacyMarker)) {
+      const updated = existing.replace(
+        /claude\(\) \{ occasio --intercept "\$@"; \}/g,
+        'claude() { occasio claude "$@"; }'
+      );
+      fs.writeFileSync(rcFile, updated);
+      console.log(col.g(`✓ Updated to canonical form in ${rcFile}`));
+    } else {
+      fs.appendFileSync(rcFile, snippet);
+      console.log(col.g(`✓ Registered in ${rcFile}`));
+    }
+    console.log(col.d('  Run: source ' + rcFile + '  — then type: claude'));
+  } catch (e) {
+    console.log(col.r(`✗ Could not write ${rcFile}: ${e.message}`));
+    console.log(col.d(`  Add manually:\n  claude() { occasio claude "$@"; }`));
+  }
+}
+
+function run() {
+  if (process.platform === 'win32') registerWindows();
+  else registerPosix();
+}
+
+module.exports = { run };

package/src/cli/status.js

@@ -0,0 +1,94 @@
+// `occasio status` — session summary (cost, savings, coverage, budget).
+// Read-only against ~/.occasio/session.json + today's JSONL log.
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const { calcCompoundingSavings } = require('../cost/prices');
+const { fmtBudget }              = require('../budget');
+
+const LOG_DIR      = path.join(os.homedir(), '.occasio');
+const SESSION_FILE = path.join(LOG_DIR, 'session.json');
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, c: s => `\x1b[36m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function todayStr() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth()+1).padStart(2,'0')}-${String(d.getDate()).padStart(2,'0')}`;
+}
+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 { /* ignore */ }
+  console.log(col.b('\n⚡ Occasio\n'));
+  if (!s) { console.log(col.d('  No session data yet. Run: occasio claude\n')); return; }
+
+  const cacheSav  = s.cache_savings      || 0;
+  const laoSav    = s.lao_cost_saved     || 0;
+  const distSav   = s.distill_cost_saved || 0;
+  const payload   = laoSav + distSav;
+  const { savings: context } =
+    calcCompoundingSavings(s.run_id, s.log_file || getLogFile(), s.model || '');
+  const totalSav  = payload + context + cacheSav;
+  const broaderCf = (s.cost || 0) + totalSav;
+  const savedPct  = broaderCf > 0.00001 ? Math.round(totalSav / broaderCf * 100) : 0;
+
+  // Headline
+  if (totalSav > 0.00001) {
+    console.log(col.g(`  Saved:       $${totalSav.toFixed(4)}`) +
+      col.d(`  (${savedPct}% off — would have cost $${broaderCf.toFixed(4)})`));
+  } else {
+    console.log(col.d(`  Saved:       $0.0000  (no interceptable tool calls in this session yet)`));
+  }
+  console.log(col.y(`  Cost:        $${s.cost.toFixed(4)}`));
+
+  // Plain-English coverage. Defensive: legacy sessions (pre-multi-round-fix)
+  // may have tools_attempted undercounted relative to tools_local_count.
+  // We clamp the denominator to at least the numerator so the displayed
+  // ratio is always 0–100% and never reads "X of Y < X (>100%)".
+  const localCnt   = s.tools_local_count || 0;
+  const mcpCnt     = s.tools_mcp_count   || 0;
+  const attempted  = s.tools_attempted   || 0;
+  const totalLocal = localCnt + mcpCnt;
+  const denom      = Math.max(attempted, totalLocal);
+  if (denom > 0) {
+    const cpct = Math.round(totalLocal / denom * 100);
+    const cColor = cpct >= 80 ? col.g : cpct >= 50 ? col.y : col.r;
+    console.log(cColor(`  Ran locally: ${totalLocal} of ${denom} tool calls (${cpct}%)`));
+  }
+  if (s.blocked) console.log(col.r(`  Blocked:     ${s.blocked} secrets`));
+  if (s.secrets_redacted) console.log(col.c(`  Redacted:    ${s.secrets_redacted} secret${s.secrets_redacted !== 1 ? 's' : ''} in tool results`));
+  if (s.tools_transformed) console.log(col.c(`  Transforms:  ${s.tools_transformed} tool result${s.tools_transformed !== 1 ? 's' : ''} shaped`));
+  if (s.budget != null) {
+    const pct = Math.min(999, Math.round((s.cost || 0) / s.budget * 100));
+    const budgetStr = fmtBudget(s.cost || 0, s.budget);
+    const budgetColor = pct >= 100 ? col.r : pct >= 80 ? col.y : col.g;
+    console.log(budgetColor(`  Budget:      ${budgetStr}`));
+    if (s.budget_exceeded_count) console.log(col.r(`  BudgetBlk:   ${s.budget_exceeded_count} request(s) blocked`));
+  }
+
+  // Detail
+  console.log(col.d(`  ────`));
+  console.log(col.d(`  Requests:    ${s.requests} · ${(s.input_tokens/1000).toFixed(1)}k tokens in · ${(s.output_tokens/1000).toFixed(1)}k out`));
+  if (totalSav > 0.00001) {
+    const parts = [];
+    if (payload  > 0.00001) parts.push(`$${payload.toFixed(4)} payload`);
+    if (context  > 0.00001) parts.push(`$${context.toFixed(4)} context`);
+    if (cacheSav > 0.00001) parts.push(`$${cacheSav.toFixed(4)} cache`);
+    if (parts.length) console.log(col.d(`  Breakdown:   ${parts.join(' + ')}`));
+  }
+  const tail = [];
+  if (s.mode)  tail.push(`Mode: ${s.mode}`);
+  if (s.start) tail.push(`Since: ${new Date(s.start).toLocaleString()}`);
+  if (tail.length) console.log(col.d(`  ${tail.join('   ·   ')}`));
+  console.log('');
+}
+
+module.exports = { run };

package/src/cost/prices.js

@@ -0,0 +1,106 @@
+// Token-cost arithmetic for Anthropic-priced models. Extracted from
+// src/index.js so the proxy hot-path doesn't carry pricing data, and so
+// MODEL_PRICES updates land in a file small enough to review at a glance.
+//
+// Prices are USD per 1M tokens. Cache-write is the one-time cost to
+// populate a cache breakpoint; cache-read is the cheap subsequent hit.
+//
+// Substring matching is intentional — Anthropic's model_id strings often
+// carry a dated suffix (claude-haiku-4-5-20251001) we want to absorb
+// without a table update. The trade-off: a truly unknown model silently
+// falls back to `default`. We warn once per unknown model so the failure
+// is loud the first time and quiet thereafter.
+
+'use strict';
+
+const fs = require('fs');
+
+const MODEL_PRICES = {
+  'claude-opus-4-6':   { in: 15.00, out: 75.00, cache_write:  18.75, cache_read:  1.50 },
+  'claude-opus-4':     { in: 15.00, out: 75.00, cache_write:  18.75, cache_read:  1.50 },
+  'claude-sonnet-4-6': { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+  'claude-sonnet-4':   { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+  'claude-haiku-4-5':  { in:  0.25, out:  1.25, cache_write:   0.30, cache_read:  0.03 },
+  'claude-haiku-4':    { in:  0.25, out:  1.25, cache_write:   0.30, cache_read:  0.03 },
+  'default':           { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+};
+
+// Track which unknown model names we've already complained about, so a
+// long session with a new model surfaces the warning exactly once instead
+// of on every request.
+const _warnedUnknown = new Set();
+
+function getPrice(model) {
+  if (!model) return MODEL_PRICES.default;
+  for (const [k, v] of Object.entries(MODEL_PRICES)) {
+    if (k !== 'default' && model.includes(k)) return v;
+  }
+  if (!_warnedUnknown.has(model)) {
+    _warnedUnknown.add(model);
+    // stderr so it doesn't pollute proxy stdout. Silenceable via env for
+    // CI runs that legitimately want to price unknown models as default.
+    if (!process.env.OCCASIO_QUIET_PRICING) {
+      process.stderr.write(
+        `[occasio] warning: unknown model "${model}" — falling back to default pricing ` +
+        `(in:$${MODEL_PRICES.default.in}/M, out:$${MODEL_PRICES.default.out}/M). ` +
+        `Add it to src/cost/prices.js to silence this.\n`
+      );
+    }
+  }
+  return MODEL_PRICES.default;
+}
+
+function calcCost(model, inp, out, cacheWrite = 0, cacheRead = 0) {
+  const p = getPrice(model);
+  return (inp / 1e6 * p.in) + (out / 1e6 * p.out)
+       + (cacheWrite / 1e6 * p.cache_write) + (cacheRead / 1e6 * p.cache_read);
+}
+
+// Savings from Anthropic prompt caching: cache reads are 10× cheaper than fresh input.
+function calcCacheSavings(model, cacheReadTokens) {
+  if (!cacheReadTokens) return 0;
+  const p = getPrice(model);
+  return (cacheReadTokens / 1e6) * (p.in - p.cache_read);
+}
+
+// Cross-request compounding savings: reads the run's JSONL entries in sequence order
+// and weights each distilled batch by the exact number of subsequent API calls that
+// carry the smaller result in their conversation history.
+// Formula: Σ (distill_tokens_saved[i] / 1M × price_in × (N - i - 1))
+// Returns { savings: float, carryInstances: int }
+// carryInstances = total sum of subsequent-call counts across all distilled batches
+// — the actual multiplier used — so the display is self-explanatory.
+// Assumption: tool results accumulate in Claude Code's message history for all
+// subsequent requests in the session (true for normal sessions; may not hold if
+// Claude Code resets context mid-session).
+function calcCompoundingSavings(runId, logFile, model) {
+  if (!runId) return { savings: 0, carryInstances: 0 };
+  let entries;
+  try {
+    const lines = fs.readFileSync(logFile, 'utf8').trim().split('\n').filter(Boolean);
+    entries = lines
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(e => e && e.run_id === runId);
+  } catch { return { savings: 0, carryInstances: 0 }; }
+  const N = entries.length;
+  if (N < 2) return { savings: 0, carryInstances: 0 };
+  const p = getPrice(model);
+  let savings = 0, carryInstances = 0;
+  for (let i = 0; i < N; i++) {
+    const dt = entries[i].distill_tokens_saved || 0;
+    if (dt > 0) {
+      const subsequent = N - i - 1;
+      savings += (dt / 1e6) * p.in * subsequent;
+      carryInstances += subsequent;
+    }
+  }
+  return { savings, carryInstances };
+}
+
+module.exports = {
+  MODEL_PRICES,
+  getPrice,
+  calcCost,
+  calcCacheSavings,
+  calcCompoundingSavings,
+};

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,
+};