chill-agent 1.5.0 → 1.6.0

package/hooks/ponytail-band-import.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// ponytail — imports past Claude Code sessions into the band's task ledger, so the board can
+// compare them: cost, agent time, tokens, turns, name and model. Started in the background by
+// `/ponytail band import`; also runs by hand. Sessions already in the ledger are left alone.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { StringDecoder } = require('string_decoder');
+const { getClaudeDir } = require('./ponytail-config');
+
+// The band's columns (CSV_HEADER in hooks/band/metrics.ts; a test keeps the two equal).
+const CSV_HEADER = 'key,started,project,name,cost_usd,turns,agent_minutes,tokens_total,tokens_output,reuse_pct,reused,new,callers_open,tests,level,model';
+
+// USD per million tokens from https://platform.claude.com/docs/en/about-claude/pricing, checked
+// 2026-10-17: [input, 5-minute cache write, 1-hour cache write, cache read, output]. Opus 5.5 and
+// Fable 5.1 also match Claude Code's own totals in real transcripts. A model missing here, or a
+// fast-mode reply, gets no estimate: an empty cost beats a guessed one.
+const OPUS = [5, 6.25, 10, 0.5, 25];
+const PRICES = {
+  'claude-fable-5-1': [10, 12.5, 20, 0.25, 50],
+  'claude-fable-5': [10, 12.5, 20, 1, 50],
+  'claude-opus-5-5': [4, 5, 8, 0.2, 20],
+  'claude-opus-5': OPUS,
+  'claude-opus-4-8': OPUS,
+  'claude-opus-4-7': OPUS,
+  'claude-opus-4-6': OPUS,
+  'claude-opus-4-5': OPUS,
+  'claude-sonnet-5-5': [2, 2.5, 4, 0.1, 10],
+  'claude-sonnet-5': [2, 2.5, 4, 0.2, 10],
+  'claude-sonnet-4-6': [3, 3.75, 6, 0.3, 15],
+  'claude-sonnet-4-5': [3, 3.75, 6, 0.3, 15],
+  'claude-haiku-5-5': [0.1, 0.125, 0.2, 0.01, 0.5],
+  'claude-haiku-4-5': [1, 1.25, 2, 0.1, 5],
+};
+// Haiku 5.5 bills a request whose prompt (input, cache reads and writes) is over 100,000 tokens higher.
+const HAIKU_55_LONG = [0.5, 0.625, 1, 0.05, 2.5];
+const WEB_SEARCH = 10 / 1000;
+const IDLE_MS = 30 * 60000;
+const modelId = m => m.replace(/\[.*\]$/, '').replace(/-\d{8}$/, '');
+
+// One reply's price from its usage, or null when the price is not known.
+function replyCost(model, u) {
+  let p = PRICES[modelId(model)];
+  if (!p || u.speed === 'fast') return null;
+  const cc = u.cache_creation || {};
+  const split = cc.ephemeral_5m_input_tokens !== undefined || cc.ephemeral_1h_input_tokens !== undefined;
+  const w5 = split ? cc.ephemeral_5m_input_tokens || 0 : u.cache_creation_input_tokens || 0;
+  const w1 = split ? cc.ephemeral_1h_input_tokens || 0 : 0;
+  const input = u.input_tokens || 0;
+  const read = u.cache_read_input_tokens || 0;
+  if (modelId(model) === 'claude-haiku-5-5' && input + read + w5 + w1 > 100000) p = HAIKU_55_LONG;
+  const searches = (u.server_tool_use && u.server_tool_use.web_search_requests) || 0;
+  return (input * p[0] + w5 * p[1] + w1 * p[2] + read * p[3] + (u.output_tokens || 0) * p[4]) / 1e6 + searches * WEB_SEARCH;
+}
+
+const human = r => r.type === 'user' && (r.turnOrigin === 'human' || (r.origin && r.origin.kind === 'human'));
+const promptText = r => {
+  const c = r.message && r.message.content;
+  const t = typeof c === 'string' ? c : Array.isArray(c) ? (c.find(b => b && b.type === 'text') || {}).text || '' : '';
+  return t.trim();
+};
+const ms = r => (r.timestamp ? Date.parse(r.timestamp) : NaN);
+const toolResult = r => (r.toolResult !== undefined ? r.toolResult
+  : Array.isArray(r.message && r.message.content) && r.message.content.some(b => b && b.type === 'tool_result'));
+
+// Only what the numbers need from one record: a long session's transcript can pass 500 MB.
+function slim(r) {
+  const m = r.message || {};
+  const c = human(r) ? m.content : undefined;
+  const text = typeof c === 'string' ? c.slice(0, 500)
+    : Array.isArray(c) ? c.filter(b => b && b.type === 'text').slice(0, 1).map(b => ({ type: 'text', text: String(b.text).slice(0, 500) })) : undefined;
+  return {
+    type: r.type, timestamp: r.timestamp, turnOrigin: r.turnOrigin, origin: r.origin && { kind: r.origin.kind },
+    isMeta: r.isMeta, toolResult: toolResult(r),
+    sessionId: r.sessionId, customTitle: r.customTitle, totalCostUSD: r.totalCostUSD,
+    message: { id: m.id, model: m.model, usage: m.usage, content: text },
+  };
+}
+
+// A JSONL file line by line, so no transcript is too big to read (one string stops at 512 MB).
+function readRecords(file) {
+  const out = [];
+  const take = l => { if (l.startsWith('{')) try { out.push(slim(JSON.parse(l))); } catch (e) {} };
+  const fd = fs.openSync(file, 'r');
+  const buf = Buffer.alloc(1 << 20);
+  const dec = new StringDecoder('utf8');
+  let rest = '';
+  try {
+    for (let n; (n = fs.readSync(fd, buf, 0, buf.length, null)) > 0;) {
+      const parts = (rest + dec.write(buf.subarray(0, n))).split('\n');
+      rest = parts.pop();
+      parts.forEach(take);
+    }
+    take(rest + dec.end());
+  } finally {
+    fs.closeSync(fd);
+  }
+  return out;
+}
+
+// One session's numbers from its transcript records and its subagents' records. Null for a session
+// nobody typed into (benchmarks, `claude -p`, scripts) or one without a model reply.
+function sessionStats(records, subagentRecords = [], sessionId = '') {
+  const prompts = records.filter(human);
+  if (prompts.length === 0) return null;
+
+  // Usage repeats on every record of one message: count each message id once, subagents included.
+  const seen = new Set();
+  const replies = {};
+  let tokens = 0;
+  let output = 0;
+  let estimate = 0;
+  const reply = r => r.type === 'assistant' && r.message && r.message.model && r.message.model !== '<synthetic>';
+  for (const r of records) if (reply(r)) replies[r.message.model] = (replies[r.message.model] || 0) + 1;
+  for (const r of [...records, ...subagentRecords]) {
+    if (!reply(r)) continue;
+    const { id, model, usage } = r.message;
+    if (!usage || !id || seen.has(id)) continue;
+    seen.add(id);
+    tokens += (usage.input_tokens || 0) + (usage.output_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+    output += usage.output_tokens || 0;
+    const c = replyCost(model, usage);
+    estimate = estimate === null || c === null ? null : estimate + c;
+  }
+  const models = Object.keys(replies);
+  if (models.length === 0) return null;
+
+  // A turn starts with any new message: a typed prompt, a slash command (not marked as typed) or a
+  // background notification. It lasts until the model's last reply or tool result before the next
+  // one, so time waiting between messages, even days before a session is reopened, never counts.
+  let turns = 0;
+  let agentMs = 0;
+  const starts = r => r.type === 'user' && !toolResult(r) && !r.isMeta;
+  const at = records.map((r, i) => (starts(r) ? i : -1)).filter(i => i >= 0);
+  for (let k = 0; k < at.length; k++) {
+    const work = records.slice(at[k] + 1, k + 1 < at.length ? at[k + 1] : records.length)
+      .filter(r => r.type === 'assistant' || (r.type === 'user' && toolResult(r)));
+    if (!work.some(r => r.type === 'assistant')) continue;
+    turns++;
+    // A pause of over 30 minutes inside a turn is someone not answering a permission prompt, not work.
+    // shortcut: a single tool run over 30 minutes counts as zero; raise IDLE_MS if long builds go missing.
+    let prev = ms(records[at[k]]);
+    for (const t of work.map(ms).filter(Number.isFinite)) {
+      if (Number.isFinite(prev) && t > prev && t - prev <= IDLE_MS) agentMs += t - prev;
+      prev = Math.max(Number.isFinite(prev) ? prev : t, t);
+    }
+  }
+  if (turns === 0) return null;
+
+  // Two sources, and each can only miss calls: Claude Code's own total covers just its last
+  // process run (a reopened session can say $0), the estimate misses side calls the transcript
+  // does not log (titles, compaction, internal Haiku). So the larger one wins.
+  // shortcut: without an own total the estimate runs 0-15% low in real sessions; nothing better is logged.
+  const last = (a, f) => { for (let i = a.length - 1; i >= 0; i--) if (f(a[i])) return i; return -1; };
+  const costAt = last(records, r => r.type === 'cost-state' && (!sessionId || r.sessionId === sessionId));
+  const own = costAt >= 0 && last(records, r => r.type === 'assistant') < costAt ? records[costAt].totalCostUSD : null;
+  const known = [own, estimate].filter(v => typeof v === 'number' && Number.isFinite(v) && v > 0);
+  const cost = known.length ? Math.max(...known) : null;
+  const titled = records.filter(r => r.type === 'custom-title' && typeof r.customTitle === 'string' && r.customTitle.trim());
+  const first = prompts.map(promptText).find(t => t && !t.startsWith('<') && !t.startsWith('/')) || '';
+  const started = records.map(ms).find(Number.isFinite);
+  return {
+    startedMs: started,
+    name: (titled.length ? titled[titled.length - 1].customTitle.trim() : first.split('\n')[0]).slice(0, 60),
+    model: models.sort((a, b) => replies[b] - replies[a])[0],
+    cost,
+    own,
+    estimate,
+    turns,
+    agentMs,
+    tokens,
+    output,
+  };
+}
+
+// Same stamp and quoting as the band (hooks/band/metrics.ts), so the board reads both alike.
+const two = n => String(n).padStart(2, '0');
+const stamp = t => { const d = new Date(t); return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`; };
+const field = v => { const s = v === null || v === undefined ? '' : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
+
+function csvRow(sessionId, project, s) {
+  return [`${sessionId.slice(0, 8)}-${s.startedMs}`, stamp(s.startedMs), project, s.name, s.cost === null ? '' : s.cost.toFixed(2), s.turns,
+    (s.agentMs / 60000).toFixed(1), s.tokens, s.output, '', '', '', '', '', 'import', s.model].map(field).join(',');
+}
+
+// New rows go in after the ledger's own: a newer header replaces an older one, and a session
+// already recorded anywhere in the ledger (same session id prefix) is never imported twice.
+const sessionOf = row => row.slice(0, 9);
+function mergeRows(existing, rows, have = new Set()) {
+  const kept = existing.split('\n').filter(l => l !== '' && !l.startsWith('key,'));
+  const added = rows.filter(r => !have.has(sessionOf(r)) && !kept.some(l => sessionOf(l) === sessionOf(r)));
+  return { text: [CSV_HEADER, ...kept, ...added].join('\n') + '\n', added: added.length };
+}
+
+const TEMP = [os.tmpdir(), '/tmp/', '/private/tmp/', '/var/folders/', '/private/var/folders/'];
+// A worktree counts for its main repo: the desktop app's <repo>/.claude/worktrees/<name> even
+// after it is gone, and any git worktree through its common .git dir.
+function projectOf(cwd, cache) {
+  if (!cache.has(cwd)) {
+    let root = cwd.split(/[\\/]\.claude[\\/]worktrees[\\/]/)[0];
+    if (fs.existsSync(root)) {
+      const git = spawnSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' });
+      if (git.status === 0 && /[\\/]\.git$/.test(git.stdout.trim())) root = path.dirname(git.stdout.trim());
+    }
+    cache.set(cwd, path.basename(root.replace(/[\\/]+$/, '')));
+  }
+  return cache.get(cwd);
+}
+
+function ledgerDir() {
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ponytail', 'band');
+}
+
+function run() {
+  const root = path.join(getClaudeDir(), 'projects');
+  const byProject = new Map();
+  const roots = new Map();
+  let dirs = [];
+  try { dirs = fs.readdirSync(root); } catch (e) { return { sessions: 0, added: 0 }; }
+  let sessions = 0;
+  for (const dir of dirs) {
+    let files = [];
+    try { files = fs.readdirSync(path.join(root, dir)).filter(f => f.endsWith('.jsonl')); } catch (e) { continue; }
+    for (const file of files) {
+      const p = path.join(root, dir, file);
+      // The working dir sits in the first records; scratch and temp dirs are never real projects.
+      let head = '';
+      try { const fd = fs.openSync(p, 'r'); const b = Buffer.alloc(65536); head = b.toString('utf8', 0, fs.readSync(fd, b, 0, b.length, 0)); fs.closeSync(fd); } catch (e) { continue; }
+      const m = /"cwd":"((?:[^"\\]|\\.)*)"/.exec(head);
+      if (!m) continue;
+      const cwd = JSON.parse(`"${m[1]}"`);
+      if (TEMP.some(t => cwd.startsWith(t)) || cwd === '/tmp') continue;
+      // A session's first prompt is typed by a person; automated runs (benchmarks, `claude -p`) never are.
+      if (head.includes('"type":"user"') && !/"turnOrigin":"human"|"origin":\{"kind":"human"/.test(head)) continue;
+      const id = file.slice(0, -'.jsonl'.length);
+      let records;
+      try { records = readRecords(p); } catch (e) { continue; }
+      const sub = path.join(root, dir, id, 'subagents');
+      let subRecords = [];
+      try { subRecords = fs.readdirSync(sub).filter(f => /^agent-.*\.jsonl$/.test(f)).flatMap(f => readRecords(path.join(sub, f))); } catch (e) {}
+      const stats = sessionStats(records, subRecords, id);
+      if (!stats || !Number.isFinite(stats.startedMs)) continue;
+      sessions++;
+      const project = projectOf(cwd, roots);
+      if (!byProject.has(project)) byProject.set(project, []);
+      byProject.get(project).push(csvRow(id, project, stats));
+    }
+  }
+  const dir = ledgerDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const have = new Set();
+  for (const f of fs.readdirSync(dir).filter(f => f.endsWith('.csv'))) {
+    try { fs.readFileSync(path.join(dir, f), 'utf8').split('\n').forEach(l => l && !l.startsWith('key,') && have.add(sessionOf(l))); } catch (e) {}
+  }
+  let added = 0;
+  for (const [project, rows] of byProject) {
+    const file = path.join(dir, `${project.replace(/[^\w.-]/g, '_')}.csv`);
+    let existing = '';
+    try { existing = fs.readFileSync(file, 'utf8'); } catch (e) {}
+    const merged = mergeRows(existing, rows, have);
+    if (merged.added > 0) fs.writeFileSync(file, merged.text);
+    added += merged.added;
+  }
+  return { sessions, added };
+}
+
+if (require.main === module) {
+  const { sessions, added } = run();
+  process.stdout.write(`ponytail band import: ${sessions} past sessions found, ${added} new rows in the board.\n`);
+}
+
+module.exports = { CSV_HEADER, PRICES, replyCost, sessionStats, csvRow, mergeRows, readRecords, run };

package/hooks/ponytail-config.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// ponytail — shared configuration resolver
+//
+// Resolution order for default mode:
+//   1. PONYTAIL_DEFAULT_MODE environment variable
+//   2. Config file defaultMode field:
+//      - $XDG_CONFIG_HOME/ponytail/config.json (any platform, if set)
+//      - ~/.config/ponytail/config.json (macOS / Linux fallback)
+//      - %APPDATA%\ponytail\config.json (Windows fallback)
+//   3. 'full'
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_MODE = 'full';
+const VALID_MODES = ['off', 'lite', 'full', 'ultra', 'review'];
+const RUNTIME_MODES = ['off', 'lite', 'full', 'ultra'];
+
+function normalizeMode(mode) {
+  if (typeof mode !== 'string') return null;
+  const normalized = mode.trim().toLowerCase();
+  return RUNTIME_MODES.includes(normalized) ? normalized : null;
+}
+
+function normalizeConfigMode(mode) {
+  if (typeof mode !== 'string') return null;
+  const normalized = mode.trim().toLowerCase();
+  return VALID_MODES.includes(normalized) ? normalized : null;
+}
+
+function normalizePersistedMode(mode) {
+  return normalizeMode(mode) || normalizeConfigMode(mode);
+}
+
+// "stop ponytail" / "normal mode" turn ponytail off, but only as a standalone
+// command. Matching the phrase anywhere in the message turned it off mid-task
+// for ordinary requests like "add a normal mode toggle" — so require the whole
+// message to be the command, ignoring case and trailing punctuation.
+function isDeactivationCommand(text) {
+  const t = String(text || '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
+  return t === 'stop ponytail' || t === 'normal mode';
+}
+
+// ponytail: only embed the plugin install path in a statusline shell command when
+// it's made of ordinary path characters. An allowlist beats escaping every shell's
+// metacharacters; a hostile clone path (quotes, &, $, backtick, ;, etc.) falls back
+// to manual setup instead. Allows : \ / for normal Windows and POSIX paths. Full
+// per-shell escaper only if a real need appears.
+function isShellSafe(p) {
+  return typeof p === 'string' && /^[A-Za-z0-9 _.\-:/\\~]+$/.test(p);
+}
+
+function getConfigDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'ponytail');
+  }
+  if (process.platform === 'win32') {
+    return path.join(
+      process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+      'ponytail'
+    );
+  }
+  return path.join(os.homedir(), '.config', 'ponytail');
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function getClaudeDir() {
+  // ponytail: CLAUDE_CONFIG_DIR overrides ~/.claude, matching Claude Code.
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function getQoderDir() {
+  return process.env.QODER_CONFIG_DIR || path.join(os.homedir(), '.qoder');
+}
+
+function getDefaultMode() {
+  // 1. Environment variable (highest priority)
+  // ponytail: a default must be a runtime level (off/lite/full/ultra); review is
+  // a session-only mode, never a valid default (#377). Normalize here so values
+  // with whitespace or mixed casing still resolve correctly.
+  const envMode = normalizeMode(process.env.PONYTAIL_DEFAULT_MODE);
+  if (envMode) {
+    return envMode;
+  }
+
+  // 2. Config file
+  try {
+    const configPath = getConfigPath();
+    // Strip UTF-8 BOM (common on Windows-saved files) so JSON.parse doesn't choke
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''));
+    const configMode = normalizeMode(config.defaultMode);
+    if (configMode) {
+      return configMode;
+    }
+  } catch (e) {
+    // Config file doesn't exist or is invalid — fall through
+  }
+
+  // 3. Default
+  return DEFAULT_MODE;
+}
+
+// Silence the pi "Ponytail loaded" startup toast while keeping ponytail active.
+// PONYTAIL_QUIET_STARTUP=1 (or any truthy value; 0/false/empty mean "show it")
+// takes precedence, else config.quietStartup === true. Mirrors getHideStatus.
+function getQuietStartup() {
+  const env = process.env.PONYTAIL_QUIET_STARTUP;
+  if (env !== undefined) {
+    const v = env.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+  }
+  try {
+    const config = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8').replace(/^\uFEFF/, ''));
+    return config.quietStartup === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// Hide the status-bar indicator while keeping ponytail active (#324).
+// PONYTAIL_HIDE_STATUS=1 (or any truthy value; 0/false/empty mean "don't hide")
+// takes precedence, else config.hideStatus === true.
+function getHideStatus() {
+  const env = process.env.PONYTAIL_HIDE_STATUS;
+  if (env !== undefined) {
+    const v = env.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+  }
+  try {
+    const config = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8').replace(/^\uFEFF/, ''));
+    return config.hideStatus === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function writeDefaultMode(mode) {
+  // ponytail: only a runtime level can be a default; review is session-only (#377).
+  const normalized = normalizeMode(mode);
+  if (!normalized) return null;
+
+  const configPath = getConfigPath();
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  let config = {};
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''));
+    if (!config || typeof config !== 'object' || Array.isArray(config)) config = {};
+  } catch (_) {}
+  config.defaultMode = normalized;
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+  return normalized;
+}
+
+module.exports = {
+  DEFAULT_MODE,
+  VALID_MODES,
+  RUNTIME_MODES,
+  getDefaultMode,
+  getConfigDir,
+  getConfigPath,
+  getClaudeDir,
+  getQoderDir,
+  getHideStatus,
+  getQuietStartup,
+  isShellSafe,
+  normalizeMode,
+  normalizeConfigMode,
+  normalizePersistedMode,
+  isDeactivationCommand,
+  writeDefaultMode,
+};

package/hooks/ponytail-map.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// ponytail — codebase map: what already exists, so "reuse first" costs no search.
+//
+// Lists the top-level functions, classes and exports of the project's source files, one line
+// per folder, inside a character budget. No model, no dependencies: `git ls-files` (or a short
+// directory walk) plus a regex per language. Tests, generated and vendored files are skipped;
+// shared code (utils, lib, services, components, hooks) is listed first when the budget is tight.
+//
+// ponytail: regex, not a parser. Misses nested or dynamic definitions; a tree-sitter index is the
+// upgrade if the map ever needs to be exact.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const BUDGET = Number(process.env.PONYTAIL_MAP_CHARS || 2000);
+const MAX_FILES = 4000;
+const SRC = /\.(py|js|jsx|mjs|cjs|ts|tsx|go|rs|rb|java|kt|php|swift|cs)$/;
+const SKIP_DIR = /(^|\/)(node_modules|\.git|dist|build|out|vendor|venv|\.venv|__pycache__|coverage|\.next|target|migrations|versions|fixtures|tests?|__tests__|spec)(\/|$)/;
+const SKIP_FILE = /(^|\/)(test_[^/]*|[^/]*(_test|\.test|\.spec|\.gen|\.min|\.d)\.[a-z]+)$/;
+const NAME = /^(?:type\s+)?(?:[\w$]+\s+as\s+)?([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)$/;
+const SAFE_PATH = /^[\w.@+$()[\]\/-]+$/;
+const SHARED = /(util|helper|lib|common|shared|service|component|hook|core|model|schema|api)/i;
+
+const PATTERNS = {
+  py: [/^(?:async\s+)?def\s+([A-Za-z]\w*)/gm, /^class\s+([A-Za-z]\w*)/gm],
+  js: [/^export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm,
+       /^export\s*\{([^}]*)\}/gm],
+  go: [/^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)/gm, /^type\s+([A-Z]\w*)/gm],
+  rs: [/^pub\s+(?:async\s+)?(?:fn|struct|enum|trait|type)\s+(\w+)/gm],
+  rb: [/^\s*(?:def|class|module)\s+([A-Za-z][\w.]*)/gm],
+  jvm: [/^\s*(?:public\s+)?(?:static\s+)?(?:final\s+)?(?:class|interface|enum|record)\s+(\w+)/gm],
+};
+const LANG = { py: 'py', js: 'js', jsx: 'js', mjs: 'js', cjs: 'js', ts: 'js', tsx: 'js', go: 'go', rs: 'rs',
+               rb: 'rb', java: 'jvm', kt: 'jvm', swift: 'jvm', cs: 'jvm', php: 'jvm' };
+
+function listFiles(root) {
+  try {
+    // 64 MiB: in repos with many tracked files `git ls-files` overflows Node's 1 MiB
+    // default, and the catch below reads that as "not a git repo" and falls back to a
+    // walk that ignores .gitignore. The list is capped at MAX_FILES * 5 lines anyway.
+    const tracked = execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, maxBuffer: 64 * 1024 * 1024 })
+      .split('\n').filter(Boolean).slice(0, MAX_FILES * 5);
+    if (tracked.length) return tracked;
+  } catch (e) { /* not a git repo: walk below */ }
+  {
+    // No git, or an untracked folder inside a parent repo (git ls-files is then empty, not an error).
+    const out = [];
+    (function walk(dir, depth) {
+      if (depth > 6 || out.length > MAX_FILES * 5) return;
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (ent.name.startsWith('.')) continue;
+        const rel = path.relative(root, path.join(dir, ent.name)).replace(/\\/g, '/');
+        if (ent.isDirectory()) { if (!SKIP_DIR.test(rel + '/')) walk(path.join(dir, ent.name), depth + 1); }
+        else out.push(rel);
+      }
+    })(root, 0);
+    return out;
+  }
+}
+
+function namesIn(file, text) {
+  const lang = LANG[path.extname(file).slice(1)];
+  const names = [];
+  for (const re of PATTERNS[lang] || []) {
+    for (const m of text.matchAll(re)) {
+      for (const n of m[1].split(',').map((s) => (s.trim().match(NAME) || [])[1]).filter(Boolean)) {
+        if (!n.startsWith('_') && !names.includes(n)) names.push(n);
+      }
+    }
+  }
+  return names;
+}
+
+function buildMap(root = process.cwd()) {
+  const files = listFiles(root)
+    .filter((f) => SAFE_PATH.test(f) && SRC.test(f) && !SKIP_DIR.test(f) && !SKIP_FILE.test(f))
+    .slice(0, MAX_FILES)
+    .sort((a, b) => (SHARED.test(b) - SHARED.test(a)) || a.localeCompare(b));
+  // One line per directory: names are enough to know something exists; grep finds the file.
+  const dirs = new Map();
+  for (const f of files) {
+    let text;
+    try {
+      if (!fs.lstatSync(path.join(root, f)).isFile()) continue;
+      text = fs.readFileSync(path.join(root, f), 'utf8').slice(0, 65536);
+    } catch (e) { continue; }
+    const names = namesIn(f, text);
+    if (!names.length) continue;
+    const dir = path.dirname(f) === '.' ? '.' : path.dirname(f);
+    dirs.set(dir, [...(dirs.get(dir) || []), names]);
+  }
+  const lines = [];
+  let used = 0;
+  let skipped = 0;
+  for (const [dir, perFile] of dirs) {
+    // The first exports say what a file is; in a folder of many files (a UI kit) one name each.
+    const names = [...new Set(perFile.flatMap((n) => n.slice(0, perFile.length > 8 ? 1 : 3)))];
+    const line = `${dir}/: ${names.slice(0, 30).join(', ')}${names.length > 30 ? ', ...' : ''}`;
+    if (used + line.length > BUDGET) { skipped++; continue; }
+    lines.push(line);
+    used += line.length + 1;
+  }
+  if (!lines.length) return '';
+  return 'Codebase map (what already exists; reuse it, read a file only when you need its details):\n' +
+    lines.join('\n') + (skipped ? `\n(${skipped} more folders not listed)` : '');
+}
+
+module.exports = { buildMap };
+
+if (require.main === module) process.stdout.write(buildMap(process.argv[2] || process.cwd()) + '\n');

package/hooks/ponytail-subagent.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// ponytail — Claude Code SubagentStart hook
+//
+// SessionStart context is parent-thread only and never reaches subagents, so
+// without this every Task-spawned agent runs ponytail-unaware (issue #252).
+// When ponytail mode is active, inject the same ruleset into each subagent.
+//
+// Scoping (opt-in, issue #506): set PONYTAIL_SUBAGENT_MATCHER to a regex and
+// the ruleset is injected only into subagents whose agent_type matches. The
+// regex is unanchored and case-insensitive — "explore|general" matches either,
+// "^general$" is exact. Unset means inject into every subagent, as before.
+
+const { getPonytailInstructions } = require('./ponytail-instructions');
+const { readMode, writeHookOutput } = require('./ponytail-runtime');
+const vm = require('vm');
+
+const mode = readMode();
+
+// Absent flag or off → ponytail isn't active; inject nothing.
+if (!mode || mode === 'off') {
+  process.exit(0);
+}
+
+function inject() {
+  try {
+    writeHookOutput('SubagentStart', mode, getPonytailInstructions(mode));
+  } catch (e) {
+    // Silent fail — a stdout error at hook exit must not surface as a hook failure.
+  }
+}
+
+// A bad regex must never crash the hook; treat it as "no matcher" and inject.
+let matcherRe = null;
+try {
+  if (process.env.PONYTAIL_SUBAGENT_MATCHER) {
+    matcherRe = new RegExp(process.env.PONYTAIL_SUBAGENT_MATCHER, 'i');
+  }
+} catch (e) {
+  matcherRe = null;
+}
+
+// No matcher → keep the original synchronous, stdin-independent path. On Windows
+// the PowerShell `if {}` wrapper can swallow the piped JSON so stdin 'end' never
+// fires (#443); the default path must not wait on stdin or it would stall every
+// subagent spawn.
+if (!matcherRe) {
+  inject();
+  process.exit(0);
+}
+
+// Matcher set → read agent_type from stdin and skip only on a definite
+// mismatch. Missing/unparseable agent_type, a stdin error, or the timeout all
+// fail open (inject), so scoping never silently drops the persona.
+let input = '';
+let done = false;
+
+function finish() {
+  if (done) return;
+  done = true;
+
+  let agentType = '';
+  try {
+    // Strip UTF-8 BOM some shells prepend when piping (breaks JSON.parse)
+    agentType = String(JSON.parse(input.replace(/^\uFEFF/, '')).agent_type || '').trim();
+  } catch (e) {
+    // Unparseable payload — fall through and inject to be safe.
+  }
+  // .test() is synchronous, so a backtracking-heavy matcher like (a+)+$ would
+  // block the event loop and the fallback timer below could never fire (#658).
+  // Run it under a vm timeout; a timeout fails open like every other doubt.
+  let matches = true;
+  try {
+    if (agentType) {
+      matches = vm.runInNewContext('re.test(s)', { re: matcherRe, s: agentType }, { timeout: 100 });
+    }
+  } catch (e) {
+    matches = true;
+  }
+  if (!matches) {
+    process.exit(0);
+  }
+  inject();
+}
+
+process.stdin.on('data', chunk => { input += chunk; });
+// Exit on 'end' (not just finish()) so the ref'd fallback timer below can't
+// add its full 1000ms to the normal fast path.
+process.stdin.on('end', () => { finish(); process.exit(0); });
+// Never block the session (#443): recover on stdin error or a short fallback.
+// The fallback stays ref'd: on Windows a stuck ref'd stdin keeps the loop
+// alive and an unref'd timer is never scheduled, so the hook hung to the
+// external watchdog instead of exiting at 1s (#790).
+process.stdin.on('error', () => { finish(); process.exit(0); });
+setTimeout(() => { finish(); process.exit(0); }, 1000);