@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/lib/exec.js

@@ -7,10 +7,52 @@
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import * as path from 'path';
+import { ALL_MODES } from './types.js';
+import { AGENTS } from './agents.js';
 import { parseTimeout } from './routines.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
-import { maybeRotate, createTimer, truncate } from './events.js';
+import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
+import { sanitizeProcessEnv } from './secrets/bundles.js';
+/**
+ * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
+ *
+ * Accepts the historical `full` spelling and rewrites it to `skip`. Throws on
+ * anything outside the four canonical values so bad input fails loud at the
+ * boundary rather than silently picking a wrong code path.
+ */
+export function normalizeMode(input) {
+    if (!input) {
+        throw new Error(`Mode is required. Use one of: ${ALL_MODES.join(', ')}.`);
+    }
+    const v = input.trim().toLowerCase();
+    if (v === 'full')
+        return 'skip';
+    if (ALL_MODES.includes(v))
+        return v;
+    throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as a deprecated alias for 'skip').`);
+}
+/**
+ * Resolve a requested mode against an agent's capability table.
+ *
+ * - `auto` on an agent without auto support silently degrades to `edit`
+ *   (every agent supports edit-like behavior as its default).
+ * - `skip` on an agent without skip support throws with a clear message
+ *   naming the agent's supported modes. No silent fallback — the user
+ *   explicitly asked to bypass permissions; pretending we did is unsafe.
+ * - `plan` on an agent without plan support throws the same way.
+ */
+export function resolveMode(agent, requested) {
+    const supported = AGENTS[agent].capabilities.modes;
+    if (supported.includes(requested))
+        return requested;
+    if (requested === 'auto') {
+        // Fall back to edit — guaranteed to exist on every agent (every agent has
+        // at least 'edit' in its modes table, since that's the default behavior).
+        return 'edit';
+    }
+    throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
+}
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -40,7 +82,7 @@ export function parseExecEnv(entries) {
  * into unrelated invocations.
  */
 export function buildExecEnv(options) {
-    const result = { ...process.env };
+    const result = { ...sanitizeProcessEnv(process.env) };
     // Config-dir env vars are agent-specific. When the caller is running inside
     // an agent-managed shell, process.env already carries one; spreading into a
     // different agent's env would leak a config pointer the target CLI doesn't
@@ -96,7 +138,12 @@ export function buildExecEnv(options) {
         ...options.env,
     };
 }
-/** CLI command templates for every supported agent. */
+/**
+ * CLI command templates for every supported agent.
+ *
+ * Each agent's `modeFlags` keys MUST match the modes listed in
+ * AGENTS[agent].capabilities.modes. A test in exec.test.ts asserts this.
+ */
 export const AGENT_COMMANDS = {
     claude: {
         base: ['claude'],
@@ -104,8 +151,8 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--permission-mode', 'plan'],
             edit: ['--permission-mode', 'acceptEdits'],
-            full: ['--dangerously-skip-permissions'],
             auto: ['--permission-mode', 'auto'],
+            skip: ['--dangerously-skip-permissions'],
         },
         jsonFlags: ['--output-format', 'stream-json', '--verbose'],
         modelFlag: '--model',
@@ -116,9 +163,13 @@ export const AGENT_COMMANDS = {
         base: ['codex', 'exec'],
         promptFlag: 'positional',
         modeFlags: {
+            // NOTE: codex has no read-only mode in --sandbox; 'plan' here means
+            // "workspace-write but no auto-approval" — closer to plan-as-restraint.
+            // True read-only requires --sandbox read-only which we haven't wired.
             plan: ['--sandbox', 'workspace-write'],
             edit: ['--sandbox', 'workspace-write', '--full-auto'],
-            full: ['--full-auto'],
+            // skip drops the sandbox entirely; --full-auto then approves anything.
+            skip: ['--full-auto'],
         },
         jsonFlags: ['--json'],
         modelFlag: '--model',
@@ -127,9 +178,9 @@ export const AGENT_COMMANDS = {
         base: ['gemini'],
         promptFlag: 'positional',
         modeFlags: {
-            plan: [],
-            edit: ['--yolo'],
-            full: ['--yolo'],
+            plan: ['--approval-mode', 'plan'],
+            edit: ['--approval-mode', 'auto_edit'],
+            skip: ['--yolo'],
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
@@ -138,9 +189,9 @@ export const AGENT_COMMANDS = {
         base: ['cursor-agent'],
         promptFlag: '-p',
         modeFlags: {
-            plan: [],
-            edit: ['-f'],
-            full: ['-f'],
+            // cursor-agent has no read-only flag; we only expose edit + skip.
+            edit: [],
+            skip: ['-f'],
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
@@ -151,7 +202,6 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--agent', 'plan'],
             edit: ['--agent', 'build'],
-            full: ['--agent', 'build'],
         },
         jsonFlags: ['--format', 'json'],
         modelFlag: '--model',
@@ -162,7 +212,7 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'plan'],
             edit: ['--mode', 'edit'],
-            full: ['--mode', 'full'],
+            skip: ['--mode', 'full'],
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
@@ -171,19 +221,21 @@ export const AGENT_COMMANDS = {
     // against `copilot --help` from v0.0.413+:
     //   -p, --prompt <text>          non-interactive one-shot
     //   --mode <interactive|plan|autopilot>
+    //   --autopilot                  start in autopilot (smart-classifier) mode
     //   --allow-all-tools            required for non-interactive tool exec
     //   --allow-all (alias --yolo)   tools + paths + URLs
     //   --output-format <text|json>  json => JSONL, one object per line
     //   --model <model>
-    // Plan mode is read-only so it does not need an allow-tools grant; edit/full
-    // need at minimum --allow-all-tools so headless runs don't stall on prompts.
+    // Plan mode is read-only so it does not need an allow-tools grant; edit
+    // needs --allow-all-tools so headless runs don't stall on prompts.
     copilot: {
         base: ['copilot'],
         promptFlag: '-p',
         modeFlags: {
             plan: ['--mode', 'plan'],
             edit: ['--allow-all-tools'],
-            full: ['--allow-all'],
+            auto: ['--autopilot'],
+            skip: ['--allow-all'],
         },
         jsonFlags: ['--output-format', 'json'],
         modelFlag: '--model',
@@ -194,7 +246,6 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'plan'],
             edit: ['--mode', 'edit'],
-            full: ['--mode', 'edit'],
         },
         modelFlag: '--model',
     },
@@ -202,9 +253,8 @@ export const AGENT_COMMANDS = {
         base: ['kiro-cli'],
         promptFlag: 'positional',
         modeFlags: {
-            plan: [],
+            // kiro-cli has no permission flags — edit is the default behavior.
             edit: [],
-            full: [],
         },
         modelFlag: '--model',
     },
@@ -212,9 +262,8 @@ export const AGENT_COMMANDS = {
         base: ['goose', 'run'],
         promptFlag: 'positional',
         modeFlags: {
-            plan: [],
+            // goose has no permission flags — edit is the default behavior.
             edit: [],
-            full: [],
         },
     },
     roo: {
@@ -223,11 +272,9 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'architect'],
             edit: ['--mode', 'code'],
-            full: ['--mode', 'code'],
         },
         modelFlag: '--model',
     },
-    // Antigravity full mode uses --dangerously-skip-permissions (YOLO).
     // TODO: --output-format json is documented but currently broken upstream
     // ("flags provided but not defined: -output-format"). Track resolution at
     // https://github.com/google-antigravity/antigravity-cli/issues/7 before
@@ -236,19 +283,22 @@ export const AGENT_COMMANDS = {
         base: ['agy'],
         promptFlag: 'positional',
         modeFlags: {
-            plan: [],
+            // agy --help shows no plan/edit flags; default behavior is edit-like
+            // (prompts on tool use). Only skip has an explicit flag.
             edit: [],
-            full: ['--dangerously-skip-permissions'],
+            skip: ['--dangerously-skip-permissions'],
         },
+        printFlags: ['--print'],
         modelFlag: '--model',
     },
     grok: {
         base: ['grok'],
         promptFlag: '-p',
         modeFlags: {
-            plan: ['--mode', 'plan'],
+            // grok --help lists `--permission-mode plan`; the TUI defaults to ask.
+            plan: ['--permission-mode', 'plan'],
             edit: [],
-            full: ['--always-approve'],
+            skip: ['--always-approve'],
         },
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',
@@ -283,8 +333,17 @@ export function buildExecCommand(options) {
             }
         }
     }
-    // Add mode flags. 'auto' is only defined for claude; other agents fall back to edit flags.
-    const modeFlags = template.modeFlags[options.mode] ?? template.modeFlags.edit;
+    // Resolve the requested mode against the agent's capability table.
+    // - `auto` on an agent without auto support → silently degrades to `edit`
+    // - `skip`/`plan` on an unsupported agent → throws a clear error
+    // After resolveMode, the chosen mode is guaranteed to be in template.modeFlags.
+    const resolvedMode = resolveMode(options.agent, normalizeMode(options.mode));
+    const modeFlags = template.modeFlags[resolvedMode];
+    if (!modeFlags) {
+        // Defense in depth: would only fire if AGENTS.capabilities.modes and
+        // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
+        throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
+    }
     cmd.push(...modeFlags);
     // Add print/headless flags only when a prompt is provided. Without a prompt
     // the caller wants an interactive REPL -- passing --print would immediately
@@ -370,9 +429,9 @@ async function spawnAgent(options) {
         model: options.model,
         interactive,
         sessionId: options.sessionId,
-        prompt: truncate(options.prompt, 200),
+        ...redactPrompt(options.prompt),
         command: executable,
-        args: args.slice(0, 10),
+        args: redactArgs(args.slice(0, 10)),
     });
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI

package/dist/lib/help.js

@@ -47,15 +47,21 @@ function formatHelpCommandsFirst(cmd, helper) {
     const helpWidth = helper.helpWidth || 80;
     const itemIndentWidth = 2;
     const itemSeparatorWidth = 2;
+    // commander v15 dropped `Help.wrap(str, width, indent)` in favor of
+    // `boxWrap(str, width)` plus a built-in `formatItem(term, termWidth,
+    // description, helper)` that handles the term-pad + continuation-indent
+    // math we used to do by hand. Delegate to it so callers get the same
+    // continuation-line alignment under the description column.
     function formatItem(term, description) {
         if (description) {
-            const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`;
-            return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth);
+            return helper.formatItem(term, termWidth, description, helper);
         }
-        return term;
+        return ' '.repeat(itemIndentWidth) + term;
     }
     function formatList(textArray) {
-        return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
+        // formatItem already prefixes each item with its 2-space indent, so just
+        // join. Single-line items (no description) are indented above.
+        return textArray.join('\n');
     }
     // Drop arguments flagged as hidden (deprecation / compat slots) from both
     // the Usage line and the Arguments section. Commander v12's Argument lacks
@@ -81,7 +87,7 @@ function formatHelpCommandsFirst(cmd, helper) {
     let output = [`Usage: ${usageLine}`, ''];
     const commandDescription = helper.commandDescription(cmd);
     if (commandDescription.length > 0) {
-        output = output.concat([helper.wrap(commandDescription, helpWidth, 0), '']);
+        output = output.concat([helper.boxWrap(commandDescription, helpWidth), '']);
     }
     const sections = helpSectionRegistry.get(cmd);
     if (sections?.examples) {

package/dist/lib/hooks/cache.d.ts

@@ -0,0 +1,38 @@
+import type { HookCache, HookCacheConfig } from '../types.js';
+/**
+ * Parse a `cache:` value from hooks.yaml into the canonical config form.
+ * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
+ * Returns null if the value is missing or unparseable.
+ */
+export declare function parseCacheConfig(raw: HookCache | undefined): HookCacheConfig | null;
+/** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
+export declare function parseDuration(d: number | string | undefined): number | null;
+/** Absolute path of the generated shim for a hook name. */
+export declare function getHookShimPath(name: string): string;
+/**
+ * Optional path overrides for tests that need to redirect cache + logs to a
+ * temp dir. Production callers omit `paths`; the shim uses real state.ts dirs.
+ * (state.ts captures HOME at module load, so mutating process.env.HOME in a
+ * test's beforeEach doesn't reach getHookCacheDir() — this is the explicit
+ * seam.)
+ */
+export interface HookShimPaths {
+    shimsDir?: string;
+    cacheDir?: string;
+    logsDir?: string;
+}
+/**
+ * Generate (or refresh) the shim script for a hook. Idempotent — only writes
+ * when the content differs from what's on disk. Returns the absolute shim path.
+ */
+export declare function generateHookShim(args: {
+    name: string;
+    scriptPath: string;
+    cache: HookCacheConfig;
+    paths?: HookShimPaths;
+}): string;
+/**
+ * Remove a hook's shim. Called by the registrar's garbage collection when a
+ * hook is renamed/deleted or has its `cache:` field removed.
+ */
+export declare function removeHookShim(name: string, shimsDir?: string): void;

package/dist/lib/hooks/cache.js

@@ -0,0 +1,242 @@
+/**
+ * Declarative hook caching + timing.
+ *
+ * Hooks that opt in via `cache:` in hooks.yaml get a generated bash shim
+ * (~/.agents/.cache/shims/hooks/<name>.sh) registered with the agent instead
+ * of the raw script path. The shim handles:
+ *
+ *   1. cache lookup — reads ~/.agents/.cache/state/hooks/<name>.<key>.out
+ *      and serves it if newer than ttl.
+ *   2. stale-while-revalidate — when prefetch=background, serves stale cache
+ *      and refreshes the cache file in a detached child.
+ *   3. timing — appends one JSONL line per fire to events-YYYY-MM-DD.jsonl.
+ *
+ * The shim is regenerated whenever the registrar runs; if its content doesn't
+ * change (idempotent), mtime is preserved. Stale shims for removed hooks are
+ * cleaned by the registrar's garbage collection (shims dir is in
+ * managedPrefixes).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHookCacheDir, getHookShimsDir, getLogsDir } from '../state.js';
+/**
+ * Parse a `cache:` value from hooks.yaml into the canonical config form.
+ * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
+ * Returns null if the value is missing or unparseable.
+ */
+export function parseCacheConfig(raw) {
+    if (raw == null)
+        return null;
+    if (typeof raw === 'string')
+        return parseShorthand(raw);
+    const ttlSec = parseDuration(raw.ttl);
+    if (ttlSec == null)
+        return null;
+    return {
+        ttl: ttlSec,
+        key: raw.key ?? 'global',
+        prefetch: raw.prefetch ?? 'none',
+    };
+}
+function parseShorthand(s) {
+    const trimmed = s.trim();
+    let prefetch = 'none';
+    let durationPart = trimmed;
+    if (trimmed.endsWith('-bg')) {
+        prefetch = 'background';
+        durationPart = trimmed.slice(0, -3);
+    }
+    const ttlSec = parseDuration(durationPart);
+    if (ttlSec == null)
+        return null;
+    return { ttl: ttlSec, key: 'global', prefetch };
+}
+/** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
+export function parseDuration(d) {
+    if (d == null)
+        return null;
+    if (typeof d === 'number')
+        return Number.isFinite(d) && d > 0 ? Math.floor(d) : null;
+    const m = d.trim().match(/^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs)?$/i);
+    if (!m)
+        return null;
+    const value = parseInt(m[1], 10);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    const unit = (m[2] || 's').toLowerCase();
+    if (unit.startsWith('h'))
+        return value * 3600;
+    if (unit.startsWith('m'))
+        return value * 60;
+    return value;
+}
+/** Absolute path of the generated shim for a hook name. */
+export function getHookShimPath(name) {
+    return path.join(getHookShimsDir(), `${name}.sh`);
+}
+/**
+ * Generate (or refresh) the shim script for a hook. Idempotent — only writes
+ * when the content differs from what's on disk. Returns the absolute shim path.
+ */
+export function generateHookShim(args) {
+    const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
+    const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
+    const logsDir = args.paths?.logsDir ?? getLogsDir();
+    const shimPath = path.join(shimsDir, `${args.name}.sh`);
+    const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
+    fs.mkdirSync(shimsDir, { recursive: true });
+    let existing = null;
+    if (fs.existsSync(shimPath)) {
+        try {
+            existing = fs.readFileSync(shimPath, 'utf-8');
+        }
+        catch { /* rewrite */ }
+    }
+    if (existing !== content) {
+        fs.writeFileSync(shimPath, content, { mode: 0o755 });
+    }
+    else {
+        // Ensure exec bit even when content unchanged (file mode can drift).
+        try {
+            fs.chmodSync(shimPath, 0o755);
+        }
+        catch { /* best effort */ }
+    }
+    return shimPath;
+}
+/**
+ * Render the bash shim. Bash 3.2-compatible (macOS default). Uses python3 for
+ * monotonic-ish nanosecond timing — already a hard dependency of other hooks
+ * in this repo (04-capture-session-start-metadata.sh does the same).
+ */
+function renderShim(name, scriptPath, cache, paths) {
+    const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
+    const key = cache.key ?? 'global';
+    const prefetch = cache.prefetch ?? 'none';
+    const { cacheDir, logsDir } = paths;
+    // sh-escape: wrap in single quotes, escape any embedded single quotes.
+    const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    return `#!/usr/bin/env bash
+# GENERATED by agents-cli. Do not edit — re-run \`agents hooks sync\` to refresh.
+# Hook: ${name}
+# Source: ${scriptPath}
+# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}
+set -u
+
+HOOK_NAME=${q(name)}
+SOURCE=${q(scriptPath)}
+CACHE_DIR=${q(cacheDir)}
+LOGS_DIR=${q(logsDir)}
+TTL=${ttl}
+PREFETCH=${q(prefetch)}
+KEY_MODE=${q(key)}
+
+mkdir -p "$CACHE_DIR" "$LOGS_DIR"
+
+# Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
+STDIN_PAYLOAD="$(cat || true)"
+
+# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
+# \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
+sha1_12() { python3 -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
+
+# Derive cache key suffix from KEY_MODE. All untrusted inputs (cwd, session_id,
+# project path) are hashed before going into the filename so a malicious stdin
+# payload can't write outside $CACHE_DIR via path traversal.
+cache_suffix=""
+case "$KEY_MODE" in
+  per-cwd)
+    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("cwd","") or "")
+except Exception: pass' 2>/dev/null || true)"
+    [ -z "$cwd_val" ] && cwd_val="$PWD"
+    cache_suffix=".$(printf '%s' "$cwd_val" | sha1_12)"
+    ;;
+  per-session)
+    sid_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("session_id","") or "")
+except Exception: pass' 2>/dev/null || true)"
+    # Hash + fall back to a sentinel so missing-session doesn't silently
+    # collapse to the same file as KEY_MODE=global.
+    [ -z "$sid_val" ] && sid_val="__nosession__"
+    cache_suffix=".$(printf '%s' "$sid_val" | sha1_12)"
+    ;;
+  per-project)
+    proj_val="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || echo "")"
+    [ -z "$proj_val" ] && proj_val="$PWD"
+    cache_suffix=".$(printf '%s' "$proj_val" | sha1_12)"
+    ;;
+  global|*)
+    cache_suffix=""
+    ;;
+esac
+CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
+
+# Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
+now_ns() { python3 -c 'import time; print(int(time.time()*1e9))'; }
+START_NS=$(now_ns)
+
+CACHE_STATUS=miss
+CACHE_AGE=-1
+EXIT=0
+
+if [ -f "$CACHE_FILE" ]; then
+  # python3 is already a hard dep (used for now_ns) and gives portable mtime
+  # without the macOS-vs-Linux \`stat\` flag divergence (-f %m vs -c %Y) that
+  # blew up under \`set -u\` when the wrong flag produced literal "%m".
+  mtime=$(python3 -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$CACHE_FILE" 2>/dev/null)
+  mtime=\${mtime:-0}
+  now_s=$(date +%s)
+  CACHE_AGE=$((now_s - mtime))
+  if [ "$CACHE_AGE" -ge 0 ] && [ "$CACHE_AGE" -lt "$TTL" ]; then
+    cat "$CACHE_FILE"
+    CACHE_STATUS=hit
+  fi
+fi
+
+if [ "$CACHE_STATUS" = miss ]; then
+  if [ -f "$CACHE_FILE" ] && [ "$PREFETCH" = background ]; then
+    # Stale-while-revalidate: serve stale immediately, refresh in detached child.
+    cat "$CACHE_FILE"
+    CACHE_STATUS=stale-prefetch
+    tmp="$CACHE_FILE.new.$$"
+    ( printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null && mv -f "$tmp" "$CACHE_FILE" || rm -f "$tmp" ) >/dev/null 2>&1 &
+    disown 2>/dev/null || true
+  else
+    # Synchronous fetch + cache.
+    tmp="$CACHE_FILE.new.$$"
+    if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp"; then
+      EXIT=0
+      cat "$tmp"
+      mv -f "$tmp" "$CACHE_FILE"
+    else
+      EXIT=$?
+      rm -f "$tmp"
+    fi
+  fi
+fi
+
+END_NS=$(now_ns)
+MS=$(( (END_NS - START_NS) / 1000000 ))
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
+  "$TS" "$HOOK_NAME" "$MS" "$CACHE_STATUS" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+
+exit "$EXIT"
+`;
+}
+/**
+ * Remove a hook's shim. Called by the registrar's garbage collection when a
+ * hook is renamed/deleted or has its `cache:` field removed.
+ */
+export function removeHookShim(name, shimsDir) {
+    const dir = shimsDir ?? getHookShimsDir();
+    const shimPath = path.join(dir, `${name}.sh`);
+    if (fs.existsSync(shimPath)) {
+        try {
+            fs.unlinkSync(shimPath);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/lib/hooks/profile.d.ts

@@ -0,0 +1,33 @@
+export interface HookProfileRow {
+    hook: string;
+    n: number;
+    p50Ms: number;
+    p99Ms: number;
+    meanMs: number;
+    maxMs: number;
+    cacheHitPct: number;
+    cacheStalePct: number;
+    cacheMissPct: number;
+    errorCount: number;
+}
+interface RawFireEvent {
+    event?: string;
+    hook?: string;
+    ms?: number;
+    cache?: 'hit' | 'miss' | 'stale-prefetch' | string;
+    exit?: number;
+}
+/**
+ * Load every `hook.fire` event from the last `days` daily log files.
+ * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
+ * the events log is multiplexed (version.switch, secrets.get, …).
+ */
+export declare function loadHookFireEvents(days?: number, logsDir?: string): RawFireEvent[];
+/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
+export declare function aggregateHookProfile(events: RawFireEvent[]): HookProfileRow[];
+/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
+export declare function formatMs(ms: number): string;
+/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
+export declare function formatCacheColumn(row: HookProfileRow): string;
+export declare const DEFAULT_SLOW_HOOK_WARN_MS = 2000;
+export {};