@phnx-labs/agents-cli 1.20.0 → 1.20.3

package/dist/lib/secrets/install-helper.js

@@ -0,0 +1,165 @@
+/**
+ * Stable install location for the signed macOS Keychain helper.
+ *
+ * Why a stable path: every npm publish re-signs `Agents CLI.app` with a fresh
+ * timestamp, producing a new code signature. macOS Keychain trusted-app ACLs
+ * are pinned to the exact signature, so the ACL invalidates on every release
+ * when the helper lives inside the npm package directory. Copying the .app
+ * once to `~/Library/Application Support/agents-cli/` gives it a path that
+ * survives `npm i -g`, `scripts/install.sh`, version bumps, etc.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the helper path. Other
+ * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
+ * than recomputing it.
+ */
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const APP_BUNDLE_NAME = 'Agents CLI.app';
+const INSTALL_DIR_NAME = 'agents-cli';
+/** Absolute path to the installed `.app` bundle directory (not the executable). */
+function installedAppPath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+}
+/** Absolute path to the executable inside the installed `.app` bundle. */
+function installedExecutablePath() {
+    return path.join(installedAppPath(), 'Contents', 'MacOS', 'Agents CLI');
+}
+/**
+ * Locate the source `.app` bundle shipped alongside the compiled JS.
+ *
+ * Resolution order:
+ *   1. dist/lib/secrets/Agents CLI.app — sibling of this compiled file (npm install layout)
+ *   2. <repo>/bin/Agents CLI.app       — raw working tree (`bun run dev`, tsx from src/)
+ *
+ * Throws if neither exists.
+ */
+function sourceAppPath() {
+    const candidates = [];
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        candidates.push(path.join(here, APP_BUNDLE_NAME));
+        // tsx/src case: src/lib/secrets/install-helper.ts -> ../../../bin/Agents CLI.app
+        candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
+    }
+    catch { /* import.meta.url unavailable */ }
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
+        'The npm package may have been built without the signed helper bundle. Reinstall agents-cli.');
+}
+function assertDarwin() {
+    if (process.platform !== 'darwin') {
+        throw new Error('Keychain helper is macOS only.');
+    }
+}
+function codesignVerify(appPath) {
+    const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
+}
+function spctlAssess(appPath) {
+    const r = spawnSync('spctl', ['--assess', '--type', 'execute', '--verbose=2', appPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
+}
+function copyAppBundle(src, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest))
+        fs.rmSync(dest, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature, symlinks, and resource forks.
+    // `fs.cpSync({recursive: true})` works on simple trees but has historically
+    // mishandled extended attributes on `.app` bundles, breaking codesign.
+    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
+    }
+}
+/**
+ * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
+ * if the destination already exists and `codesign --verify` passes, unless
+ * `forceReinstall=true`.
+ *
+ * Notarization is checked via `spctl --assess` after install — a failure is
+ * logged as a warning but does NOT throw. Notarization checks require network
+ * access (Gatekeeper ticket lookup) and are not load-bearing for the helper's
+ * keychain ACL semantics.
+ */
+export function ensureKeychainHelperInstalled(opts = {}) {
+    assertDarwin();
+    const dest = installedAppPath();
+    if (!opts.forceReinstall && fs.existsSync(dest)) {
+        const { ok } = codesignVerify(dest);
+        if (ok)
+            return;
+    }
+    const src = sourceAppPath();
+    copyAppBundle(src, dest);
+    const verify = codesignVerify(dest);
+    if (!verify.ok) {
+        throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
+            'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
+    }
+    const assess = spctlAssess(dest);
+    if (!assess.ok) {
+        // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
+        // installs and CI runners commonly fail this check. The ACL semantics
+        // we care about depend on codesign, not spctl.
+        process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
+    }
+}
+/**
+ * Return the absolute path to the helper executable. If the installed bundle
+ * is missing, performs a lazy install first.
+ *
+ * Throws on non-darwin.
+ */
+export function getKeychainHelperPath() {
+    assertDarwin();
+    const exec = installedExecutablePath();
+    if (!fs.existsSync(exec)) {
+        ensureKeychainHelperInstalled();
+    }
+    return exec;
+}
+export function getKeychainHelperStatus() {
+    assertDarwin();
+    const destApp = installedAppPath();
+    let src = null;
+    try {
+        src = sourceAppPath();
+    }
+    catch { /* missing source is reported as null */ }
+    const installed = fs.existsSync(destApp);
+    if (!installed) {
+        return {
+            source: src,
+            destination: destApp,
+            installed: false,
+            codesignOk: false,
+            codesignOutput: 'not installed',
+            spctlOk: false,
+            spctlOutput: 'not installed',
+        };
+    }
+    const cs = codesignVerify(destApp);
+    const sp = spctlAssess(destApp);
+    return {
+        source: src,
+        destination: destApp,
+        installed: true,
+        codesignOk: cs.ok,
+        codesignOutput: cs.output || 'ok',
+        spctlOk: sp.ok,
+        spctlOutput: sp.output || 'ok',
+    };
+}

package/dist/lib/secrets/linux.js

@@ -143,16 +143,16 @@ export function listSecretToolItems(prefix) {
 }
 /** KeychainBackend implementation for Linux using secret-tool */
 export const linuxBackend = {
-    has(item, _sync) {
+    has(item) {
         return hasSecretToolToken(item);
     },
-    get(item, _sync) {
+    get(item) {
         return getSecretToolToken(item);
     },
-    set(item, value, _sync) {
+    set(item, value) {
         setSecretToolToken(item, value);
     },
-    delete(item, _sync) {
+    delete(item) {
         return deleteSecretToolToken(item);
     },
     list(prefix) {

package/dist/lib/secrets/sync.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Remote sync client for secrets bundles.
+ *
+ * Replaces the previous "leave it to iCloud Keychain" model with explicit
+ * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
+ * encrypted client-side with AES-256-GCM under a key derived from a
+ * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
+ * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ */
+import { type SecretsBundle } from './bundles.js';
+export declare const MIN_PASSPHRASE_LEN = 12;
+/** Envelope for an encrypted bundle. All byte fields are base64. */
+export interface EncryptedEnvelope {
+    v: 1;
+    kdf: 'pbkdf2-sha256';
+    iter: number;
+    salt: string;
+    iv: string;
+    ct: string;
+    tag: string;
+}
+interface RemoteBundleSummary {
+    name: string;
+    updated_at: string;
+}
+/** Encrypt a JSON-serializable payload with a passphrase. */
+export declare function encryptBlob(plaintext: string, passphrase: string): EncryptedEnvelope;
+/** Decrypt an envelope. Throws on bad passphrase (auth tag mismatch). */
+export declare function decryptBlob(envelope: EncryptedEnvelope, passphrase: string): string;
+/** The plaintext we serialize before encrypting: bundle metadata + secret values. */
+export interface BundleSnapshot {
+    bundle: SecretsBundle;
+    /** keychain shortId -> plaintext value. Only present for keychain: refs. */
+    secrets: Record<string, string>;
+}
+/** Options for pushBundle. */
+export interface PushOptions {
+    passphrase: string;
+}
+/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+export declare function pushBundle(name: string, opts: PushOptions): Promise<{
+    updated_at: string;
+}>;
+/** Options for pullBundle. */
+export interface PullOptions {
+    passphrase: string;
+    /** When true, overwrite an existing local bundle. */
+    force?: boolean;
+}
+/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+export declare function pullBundle(name: string, opts: PullOptions): Promise<SecretsBundle>;
+/** Delete a bundle on the remote. */
+export declare function deleteRemoteBundle(name: string): Promise<boolean>;
+/** List bundles currently stored on api.prix.dev for this user. */
+export declare function listRemoteBundles(): Promise<RemoteBundleSummary[]>;
+export {};

package/dist/lib/secrets/sync.js

@@ -0,0 +1,180 @@
+/**
+ * Remote sync client for secrets bundles.
+ *
+ * Replaces the previous "leave it to iCloud Keychain" model with explicit
+ * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
+ * encrypted client-side with AES-256-GCM under a key derived from a
+ * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
+ * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { readBundle, writeBundle, keychainItemsForBundle, validateBundleName, } from './bundles.js';
+const PROXY_BASE = 'https://api.prix.dev';
+const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
+// PBKDF2 cost. 600k SHA-256 iters matches OWASP 2023+ guidance and keeps a
+// passphrase prompt under a second on the hardware the CLI targets.
+const PBKDF2_ITER = 600_000;
+export const MIN_PASSPHRASE_LEN = 12;
+const KEY_LEN = 32;
+const SALT_LEN = 16;
+const IV_LEN = 12;
+function readRushToken() {
+    if (!fs.existsSync(USER_YAML)) {
+        throw new Error('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(USER_YAML, 'utf-8');
+    const data = yaml.parse(raw);
+    const token = data?.session?.access_token;
+    if (!token) {
+        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return token;
+}
+async function api(method, endpoint, body) {
+    const token = readRushToken();
+    const url = endpoint.startsWith('http') ? endpoint : `${PROXY_BASE}${endpoint}`;
+    return fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+}
+function deriveKey(passphrase, salt) {
+    return crypto.pbkdf2Sync(passphrase, salt, PBKDF2_ITER, KEY_LEN, 'sha256');
+}
+/** Encrypt a JSON-serializable payload with a passphrase. */
+export function encryptBlob(plaintext, passphrase) {
+    if (!passphrase || passphrase.length < MIN_PASSPHRASE_LEN) {
+        throw new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`);
+    }
+    const salt = crypto.randomBytes(SALT_LEN);
+    const iv = crypto.randomBytes(IV_LEN);
+    const key = deriveKey(passphrase, salt);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+        v: 1,
+        kdf: 'pbkdf2-sha256',
+        iter: PBKDF2_ITER,
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        ct: ct.toString('base64'),
+        tag: tag.toString('base64'),
+    };
+}
+/** Decrypt an envelope. Throws on bad passphrase (auth tag mismatch). */
+export function decryptBlob(envelope, passphrase) {
+    if (envelope.v !== 1 || envelope.kdf !== 'pbkdf2-sha256') {
+        throw new Error(`Unsupported envelope version (v${envelope.v}, kdf=${envelope.kdf}).`);
+    }
+    const salt = Buffer.from(envelope.salt, 'base64');
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const ct = Buffer.from(envelope.ct, 'base64');
+    const tag = Buffer.from(envelope.tag, 'base64');
+    const key = deriveKey(passphrase, salt);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf-8');
+    }
+    catch {
+        throw new Error('Decryption failed — wrong passphrase or corrupt blob.');
+    }
+}
+function snapshotBundle(name) {
+    const bundle = readBundle(name);
+    const secrets = {};
+    for (const { key, item } of keychainItemsForBundle(bundle)) {
+        if (!hasKeychainToken(item)) {
+            throw new Error(`Bundle '${name}' key '${key}': keychain item '${item}' missing — cannot push incomplete bundle.`);
+        }
+        const raw = bundle.vars[key];
+        if (typeof raw !== 'string' || !raw.startsWith('keychain:'))
+            continue;
+        const shortId = raw.slice('keychain:'.length);
+        secrets[shortId] = getKeychainToken(item);
+    }
+    return { bundle, secrets };
+}
+function restoreSnapshot(snap) {
+    const bundle = snap.bundle;
+    validateBundleName(bundle.name);
+    for (const [shortId, value] of Object.entries(snap.secrets)) {
+        const item = secretsKeychainItem(bundle.name, shortId);
+        setKeychainToken(item, value);
+    }
+    writeBundle(bundle);
+}
+/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+export async function pushBundle(name, opts) {
+    validateBundleName(name);
+    const snap = snapshotBundle(name);
+    const envelope = encryptBlob(JSON.stringify(snap), opts.passphrase);
+    const updated_at = new Date().toISOString();
+    const payload = { envelope, updated_at };
+    const res = await api('PUT', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`, payload);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Push failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    return { updated_at };
+}
+/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+export async function pullBundle(name, opts) {
+    validateBundleName(name);
+    const res = await api('GET', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
+    if (res.status === 404) {
+        throw new Error(`Remote bundle '${name}' not found on api.prix.dev.`);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Pull failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    const data = await res.json();
+    const plaintext = decryptBlob(data.envelope, opts.passphrase);
+    const snap = JSON.parse(plaintext);
+    if (!snap || !snap.bundle || snap.bundle.name !== name) {
+        throw new Error(`Decrypted payload for '${name}' is malformed (bundle name mismatch).`);
+    }
+    // existence check is the caller's responsibility; we trust opts.force.
+    if (!opts.force) {
+        const { bundleExists } = await import('./bundles.js');
+        if (bundleExists(name)) {
+            throw new Error(`Local bundle '${name}' already exists. Re-run with --force to overwrite.`);
+        }
+    }
+    restoreSnapshot(snap);
+    return snap.bundle;
+}
+/** Delete a bundle on the remote. */
+export async function deleteRemoteBundle(name) {
+    validateBundleName(name);
+    const res = await api('DELETE', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
+    if (res.status === 404)
+        return false;
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Delete failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    return true;
+}
+/** List bundles currently stored on api.prix.dev for this user. */
+export async function listRemoteBundles() {
+    const res = await api('GET', BUNDLE_ENDPOINT);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`List failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    const data = await res.json();
+    return data.bundles ?? [];
+}

package/dist/lib/session/render.js

@@ -806,15 +806,15 @@ export function renderConversationMarkdown(events, opts = {}) {
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user') {
-                parts.push(`## User\n\n${event.content ?? ''}`);
+                parts.push(`## User\n\n${sanitize(event.content ?? '')}`);
             }
             else if (event.role === 'assistant') {
-                parts.push(`## Assistant\n\n${event.content ?? ''}`);
+                parts.push(`## Assistant\n\n${sanitize(event.content ?? '')}`);
             }
         }
         else if (event.type === 'thinking') {
             if (event.content)
-                parts.push(`### Thinking\n\n${event.content}`);
+                parts.push(`### Thinking\n\n${sanitize(event.content)}`);
         }
         else if (event.type === 'tool_use') {
             const tool = event.tool || 'unknown';
@@ -837,7 +837,7 @@ export function renderConversationMarkdown(events, opts = {}) {
             }
         }
         else if (event.type === 'error') {
-            parts.push(`### Error\n\n${event.content || event.tool || 'Unknown error'}`);
+            parts.push(`### Error\n\n${event.content ? sanitize(event.content) : (event.tool || 'Unknown error')}`);
         }
     }
     return parts.join('\n\n');

package/dist/lib/session/types.d.ts

@@ -37,7 +37,7 @@ export interface SessionEvent {
 export interface TeamOrigin {
     /** Teammate name if set, otherwise first 8 chars of the agent UUID. */
     handle?: string;
-    /** Agent mode: 'plan', 'edit', or 'full'. */
+    /** Agent mode: 'plan', 'edit', 'auto', or 'skip' ('full' accepted as legacy alias for 'skip'). */
     mode?: string;
 }
 /** Lightweight metadata for a discovered session, used in listings and pickers. */

package/dist/lib/shims.d.ts

@@ -59,8 +59,11 @@ export interface ConflictInfo {
  *         instead of hardcoding `.${agent}`. Backwards-compatible for every
  *         existing agent (their configDir is `~/.{agent}`); enables nested
  *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
+ *   v15 — remove foreground resource sync / rules refresh from launch shims.
+ *         Version homes are reconciled by agents-cli management commands; the
+ *         shim hot path only resolves a version and execs the agent binary.
  */
-export declare const SHIM_SCHEMA_VERSION = 14;
+export declare const SHIM_SCHEMA_VERSION = 15;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -183,8 +183,11 @@ async function promptConflictStrategy(conflictInfos) {
  *         instead of hardcoding `.${agent}`. Backwards-compatible for every
  *         existing agent (their configDir is `~/.{agent}`); enables nested
  *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
+ *   v15 — remove foreground resource sync / rules refresh from launch shims.
+ *         Version homes are reconciled by agents-cli management commands; the
+ *         shim hot path only resolves a version and execs the agent binary.
  */
-export const SHIM_SCHEMA_VERSION = 14;
+export const SHIM_SCHEMA_VERSION = 15;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -242,18 +245,6 @@ export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
 export GROK_HOME="$VERSION_DIR/home/.grok"
 `
                     : '';
-    // Agents that don't natively resolve @-imports in their rules file need
-    // agents-cli to recompile when the user edits a rule/preset file. The
-    // check is fast (sha256 of ~8 small files) and skips the recompile when
-    // sources haven't changed.
-    const refreshRulesCall = !agentConfig.capabilities.rulesImports
-        ? `
-# Recompile rules if any rule/preset source has changed since last sync.
-# Fast-path check (~10-20ms) when nothing changed; full recompile only on
-# actual diff. Non-blocking failure — if the refresh errors, we still launch.
-"$AGENTS_BIN" refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
-`
-        : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -307,22 +298,6 @@ resolve_default_version() {
   fi
 }
 
-# Find project-scoped .agents directory (stop at agents.yaml or .git)
-find_project_agents_dir() {
-  local dir="$PWD"
-  while [ "$dir" != "/" ]; do
-    if [ -d "$dir/.agents" ]; then
-      echo "$dir/.agents"
-      return 0
-    fi
-    if [ -f "$dir/agents.yaml" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
-      break
-    fi
-    dir=$(dirname "$dir")
-  done
-  return 1
-}
-
 # Find the latest installed version by numeric component comparison.
 # Handles both semver (2.1.138) and date-based (2026.5.7) version strings.
 find_latest_installed() {
@@ -474,12 +449,7 @@ if [ ! -x "$BINARY" ]; then
   fi
 fi
 
-# Sync project-scoped resources into version home if a project .agents/ is present
-PROJECT_AGENTS_DIR=$(find_project_agents_dir)
-if [ -n "$PROJECT_AGENTS_DIR" ]; then
-  "$AGENTS_BIN" sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
-fi
-${refreshRulesCall}${managedEnv}
+${managedEnv}
 
 exec "$BINARY"${launchArgs} "$@"
 `;

package/dist/lib/state.d.ts

@@ -107,6 +107,10 @@ export declare function getRunsDir(): string;
 export declare function getVersionsDir(): string;
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export declare function getShimsDir(): string;
+/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
+export declare function getHookShimsDir(): string;
+/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
+export declare function getHookCacheDir(): string;
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export declare function getBinDir(): string;
 /** Path to config backups (~/.agents/.history/backups/). */
@@ -191,7 +195,16 @@ export declare function getEnabledExtraRepos(): Array<{
 export declare function ensureAgentsDir(): void;
 /** Return an empty Meta object used when no agents.yaml exists yet. */
 export declare function createDefaultMeta(): Meta;
-/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
+/**
+ * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
+ *
+ * Cache invariants:
+ * - Cache key is the mtime of the user agents.yaml.
+ * - `writeMetaUnlocked` clears the cache; in-process callers always see fresh state.
+ * - If the file is mutated by ANOTHER process while we hold a stale cache, the
+ *   mtime check below catches it on the next read (assuming the mtime advanced).
+ * - The cache stores the merged system+user meta; both files' mtimes contribute.
+ */
 export declare function readMeta(): Meta;
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export declare function writeMeta(meta: Meta): void;

package/dist/lib/state.js

@@ -64,6 +64,8 @@ const BACKUPS_DIR = path.join(HISTORY_DIR, 'backups');
 const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
 // Cache bucket (regenerable).
 const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
+const HOOK_SHIMS_DIR = path.join(SHIMS_DIR, 'hooks');
+const HOOK_CACHE_DIR = path.join(CACHE_DIR, 'state', 'hooks');
 const BIN_DIR = path.join(CACHE_DIR, 'bin');
 const PACKAGES_DIR = path.join(CACHE_DIR, 'packages');
 // Plugins are user-authored resources, alongside skills/, commands/, hooks/.
@@ -265,6 +267,10 @@ export function getRunsDir() { return RUNS_DIR; }
 export function getVersionsDir() { return VERSIONS_DIR; }
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export function getShimsDir() { return SHIMS_DIR; }
+/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
+export function getHookShimsDir() { return HOOK_SHIMS_DIR; }
+/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
+export function getHookCacheDir() { return HOOK_CACHE_DIR; }
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export function getBinDir() { return BIN_DIR; }
 /** Path to config backups (~/.agents/.history/backups/). */
@@ -413,6 +419,24 @@ export function createDefaultMeta() {
 }
 let metaCache = null;
 let metaLockDepth = 0;
+/** Return mtimeMs for a file path, or 0 if the file is absent or unreadable. */
+function safeMtimeMs(filePath) {
+    try {
+        return fs.statSync(filePath).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Compute the combined cache stamp for the user + system agents.yaml files. */
+function currentMetaStamp() {
+    return safeMtimeMs(META_FILE) + safeMtimeMs(SYSTEM_META_FILE) * 1e-3;
+}
+/** Memoize a parsed Meta against the current file mtimes. */
+function rememberMeta(meta) {
+    metaCache = { mtime: currentMetaStamp(), meta };
+    return meta;
+}
 function withMetaLock(fn) {
     ensureAgentsDir();
     if (metaLockDepth > 0) {
@@ -483,9 +507,29 @@ function migrateSystemMetaToUser() {
         // Best-effort; proceed with fresh state if it fails.
     }
 }
-/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
+/**
+ * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
+ *
+ * Cache invariants:
+ * - Cache key is the mtime of the user agents.yaml.
+ * - `writeMetaUnlocked` clears the cache; in-process callers always see fresh state.
+ * - If the file is mutated by ANOTHER process while we hold a stale cache, the
+ *   mtime check below catches it on the next read (assuming the mtime advanced).
+ * - The cache stores the merged system+user meta; both files' mtimes contribute.
+ */
 export function readMeta() {
     ensureAgentsDir();
+    // Fast path: serve from cache when both source files are byte-identical to
+    // what we last parsed. Reduces N readMeta calls per CLI invocation to ~2 stat
+    // syscalls plus an in-memory object spread.
+    if (metaCache) {
+        const userMtime = safeMtimeMs(META_FILE);
+        const systemMtime = safeMtimeMs(SYSTEM_META_FILE);
+        const stamp = userMtime + systemMtime * 1e-3;
+        if (stamp === metaCache.mtime) {
+            return metaCache.meta;
+        }
+    }
     // NOTE: agents.yaml migration from ~/.agents-system/ to ~/.agents/ is handled
     // exclusively by runMigration() in migrate.ts, called from postinstall and
     // from a one-shot bootstrap step in src/index.ts. Calling it here would
@@ -515,7 +559,7 @@ export function readMeta() {
                 fs.unlinkSync(oldMetaFile);
             }
             catch { /* non-critical */ }
-            return meta;
+            return rememberMeta(meta);
         }
         catch {
             /* meta.yaml migration failed */
@@ -557,15 +601,15 @@ export function readMeta() {
         }
         if (applyRegistrySeeds(meta)) {
             writeMeta(meta);
-            return meta;
+            return rememberMeta(meta);
         }
-        return meta;
+        return rememberMeta(meta);
     }
     const meta = createDefaultMeta();
     if (applyRegistrySeeds(meta)) {
         writeMeta(meta);
     }
-    return meta;
+    return rememberMeta(meta);
 }
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {