@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/computer-rpc.d.ts

@@ -15,6 +15,9 @@ export declare function resolveLogPath(): string;
 export declare function resolvePolicyPath(): string;
 export declare function loadComputerAllowList(): string[];
 export declare function writeComputerPolicy(allowedBundleIds: string[]): void;
+export declare function resolvePeersPath(): string;
+export declare function loadDefaultPeers(): string[];
+export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
 export declare function openComputerClient(): ComputerClient;

package/dist/lib/computer-rpc.js

@@ -110,6 +110,59 @@ export function writeComputerPolicy(allowedBundleIds) {
     const policy = { allow: allowedBundleIds };
     fs.writeFileSync(resolvePolicyPath(), JSON.stringify(policy, null, 2), { mode: 0o600 });
 }
+// Peer-auth (F5): the helper reads a list of executable paths it will
+// accept connections from. Anything else — `nc`, `/usr/bin/python3`, a
+// random electron app — gets the socket closed before its first RPC.
+// File mirrors computer-policy.json: JSON, mode 0600, missing/unparseable
+// means deny-everything.
+export function resolvePeersPath() {
+    return path.join(getHelpersDir(), 'computer-peers.json');
+}
+// Default peer set: this exact `agents` CLI binary plus Rush.app if it's
+// installed. realpath() the symlink chain so we record the on-disk path
+// the helper will see via proc_pidpath, not the shim path.
+//
+// Why path-based instead of codesign-team-id? The agents CLI is unsigned
+// today (npm distribution), and even if we sign Rush.app the team-id
+// check would need a separate roundtrip. Path is concrete and fast; the
+// daemon already runs as the user so anyone who can swap a binary at
+// these paths can do worse via other means.
+export function loadDefaultPeers() {
+    const out = new Set();
+    const add = (p) => {
+        try {
+            out.add(fs.realpathSync(p));
+        }
+        catch {
+            out.add(p);
+        }
+    };
+    // The Node executable currently running the CLI. This is what
+    // proc_pidpath() will report when the CLI calls into the daemon.
+    if (process.execPath)
+        add(process.execPath);
+    // Rush.app — the consumer Electron client. Both the helper-binary and
+    // the main app binary are possible callers depending on how Rush wires
+    // the RPC client.
+    const rushCandidates = [
+        '/Applications/Rush.app/Contents/MacOS/Rush',
+        '/Applications/Rush.app/Contents/MacOS/Electron',
+    ];
+    for (const p of rushCandidates) {
+        if (fs.existsSync(p))
+            add(p);
+    }
+    return [...out].sort();
+}
+// Write the peer-auth allow list. Same mode 0600 + atomic-ish semantics
+// as the policy file. The daemon picks it up at startup and on SIGHUP.
+export function writeComputerPeers(allowedExecPaths) {
+    const dir = getHelpersDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(resolvePeersPath(), JSON.stringify({ allow: allowedExecPaths }, null, 2), { mode: 0o600 });
+}
 // Resolve the helper executable inside the dist .app bundle. Used by the
 // stdio fallback and by install-helper to find the source bundle.
 export function resolveHelperExec() {

package/dist/lib/daemon.js

@@ -14,6 +14,7 @@ import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
+import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 const PID_FILE = 'daemon.pid';
@@ -178,6 +179,25 @@ export async function runDaemon() {
     for (const job of scheduled) {
         log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
     }
+    // Backlog detection: any enabled recurring job whose most-recent expected
+    // fire is older than its most-recent recorded run is overdue. Happens when
+    // the laptop was off or the daemon crashed through a scheduled fire.
+    // We log it and pop a native notification — the user can review with
+    // `agents routines list` and run them with `agents routines catchup`.
+    try {
+        const overdue = detectOverdueJobs();
+        if (overdue.length > 0) {
+            log('WARN', `${overdue.length} routine(s) overdue:`);
+            for (const job of overdue) {
+                const last = job.lastRanAt ? job.lastRanAt.toISOString() : 'never';
+                log('WARN', `  ${job.name} -- expected ${job.expectedAt.toISOString()}, last ran ${last}`);
+            }
+            notifyOverdue(overdue);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Overdue detection failed: ${err.message}`);
+    }
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH

package/dist/lib/events.d.ts

@@ -32,7 +32,8 @@ export interface EventPayload {
     args?: string[];
     input?: string;
     output?: string;
-    prompt?: string;
+    prompt_length?: number;
+    prompt_sha256?: string;
     durationMs?: number;
     startupMs?: number;
     exitCode?: number;
@@ -42,6 +43,19 @@ export interface EventPayload {
     [key: string]: unknown;
 }
 export type EventRecord = EventMeta & EventPayload;
+/**
+ * Replace a prompt string with length + short SHA so we can correlate runs
+ * without persisting the raw text. Returns the fields to spread into a payload.
+ */
+export declare function redactPrompt(prompt: string | null | undefined): {
+    prompt_length?: number;
+    prompt_sha256?: string;
+};
+/**
+ * Mask argv entries that look like tokens or secret paths. Preserves structure
+ * for debugging but drops the sensitive substring.
+ */
+export declare function redactArgs(args: string[] | undefined): string[] | undefined;
 /**
  * Truncate a string to maxLength, adding ellipsis if truncated.
  * Returns undefined for null/undefined input.
@@ -124,7 +138,7 @@ export declare function emitError(err: Error | string, payload?: EventPayload):
  * Remove log files older than the retention period.
  * Called lazily on emit or explicitly via CLI.
  *
- * @param retentionDays - Number of days to keep (default 30)
+ * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
  * @returns Number of files removed
  */
 export declare function rotate(retentionDays?: number): number;

package/dist/lib/events.js

@@ -14,11 +14,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { createHash } from 'node:crypto';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Logs live under the cache bucket — they're regenerable telemetry.
 const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
 /** Default retention period in days. */
-const DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
 /** Environment variable to disable event logging. */
@@ -68,6 +69,36 @@ function ensureLogsDir() {
         }
     }
 }
+// ─── Redaction ────────────────────────────────────────────────────────────────
+/**
+ * Replace a prompt string with length + short SHA so we can correlate runs
+ * without persisting the raw text. Returns the fields to spread into a payload.
+ */
+export function redactPrompt(prompt) {
+    if (prompt == null)
+        return {};
+    return {
+        prompt_length: prompt.length,
+        prompt_sha256: createHash('sha256').update(prompt).digest('hex').slice(0, 16),
+    };
+}
+const TOKEN_LIKE = /(sk_(?:live|test)_|pk_(?:live|test)_|ghp_|gho_|ghu_|ghs_|xox[bpars]-|AKIA|ASIA|AIza|Bearer\s+|eyJ[A-Za-z0-9_-]+\.)/i;
+const SECRET_PATH = /\/(secrets|credentials|\.env|user\.yaml)\b/i;
+/**
+ * Mask argv entries that look like tokens or secret paths. Preserves structure
+ * for debugging but drops the sensitive substring.
+ */
+export function redactArgs(args) {
+    if (!args)
+        return undefined;
+    return args.map(a => {
+        if (typeof a !== 'string')
+            return a;
+        if (TOKEN_LIKE.test(a) || SECRET_PATH.test(a))
+            return '[REDACTED]';
+        return a;
+    });
+}
 // ─── Truncation ───────────────────────────────────────────────────────────────
 /**
  * Truncate a string to maxLength, adding ellipsis if truncated.
@@ -324,7 +355,7 @@ export function emitError(err, payload = {}) {
  * Remove log files older than the retention period.
  * Called lazily on emit or explicitly via CLI.
  *
- * @param retentionDays - Number of days to keep (default 30)
+ * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
  * @returns Number of files removed
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {

package/dist/lib/exec.d.ts

@@ -1,6 +1,28 @@
-import type { AgentId } from './types.js';
-/** Agent execution modes controlling tool access and autonomy level. */
-export type ExecMode = 'plan' | 'edit' | 'full' | 'auto';
+import type { AgentId, Mode } from './types.js';
+/**
+ * Agent execution modes. Canonical name `skip` (dangerously skip permissions);
+ * `full` is accepted as a permanent silent alias via normalizeMode().
+ */
+export type ExecMode = Mode;
+/**
+ * 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 declare function normalizeMode(input: string | null | undefined): Mode;
+/**
+ * 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 declare function resolveMode(agent: AgentId, requested: Mode): Mode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
@@ -27,26 +49,33 @@ export interface ExecOptions {
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**
  * Build the process environment for an agent invocation.
- * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
- * other agent's env var so it doesn't leak into unrelated invocations.
+ * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
+ * for GitHub Copilot; strips the other agents' env vars so they don't leak
+ * into unrelated invocations.
  */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
-/** Describes how to translate ExecOptions into CLI arguments for a specific agent. */
+/**
+ * Describes how to translate ExecOptions into CLI arguments for a specific agent.
+ *
+ * `modeFlags` only declares modes this agent natively supports. Keys must agree
+ * with AGENTS[agent].capabilities.modes — resolveMode() routes a request to a
+ * supported mode (or throws), then buildExecCommand looks up the flags here.
+ */
 export interface AgentCommandTemplate {
     base: string[];
     promptFlag: 'positional' | string;
-    modeFlags: {
-        plan: string[];
-        edit: string[];
-        full: string[];
-        auto?: string[];
-    };
+    modeFlags: Partial<Record<Mode, string[]>>;
     jsonFlags?: string[];
     modelFlag?: string;
     printFlags?: string[];
     verboseFlag?: string;
 }
-/** 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 declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];

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. */
@@ -35,11 +77,12 @@ export function parseExecEnv(entries) {
 }
 /**
  * Build the process environment for an agent invocation.
- * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
- * other agent's env var so it doesn't leak into unrelated invocations.
+ * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
+ * for GitHub Copilot; strips the other agents' env vars so they don't leak
+ * 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
@@ -56,6 +99,7 @@ export function buildExecEnv(options) {
             result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
         }
         delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     else if (options.agent === 'codex') {
         const cwd = options.cwd || process.cwd();
@@ -67,17 +111,39 @@ export function buildExecEnv(options) {
             result.CODEX_HOME = path.join(getVersionHomePath('codex', version), '.codex');
         }
         delete result.CLAUDE_CONFIG_DIR;
+        delete result.COPILOT_HOME;
+    }
+    else if (options.agent === 'copilot') {
+        // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
+        // mcp-config.json, sessions, logs). Pin it at the per-version home so
+        // version switches isolate MCP servers, auth, and session history.
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('copilot', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('copilot', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.COPILOT_HOME = path.join(getVersionHomePath('copilot', version), '.copilot');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
     }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     return {
         ...result,
         ...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'],
@@ -85,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',
@@ -97,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',
@@ -108,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',
@@ -119,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',
@@ -132,7 +202,6 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--agent', 'plan'],
             edit: ['--agent', 'build'],
-            full: ['--agent', 'build'],
         },
         jsonFlags: ['--format', 'json'],
         modelFlag: '--model',
@@ -143,19 +212,32 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'plan'],
             edit: ['--mode', 'edit'],
-            full: ['--mode', 'full'],
+            skip: ['--mode', 'full'],
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
+    // GitHub Copilot CLI (`@github/copilot`, GA 2026-02-25). Flags verified
+    // 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
+    // needs --allow-all-tools so headless runs don't stall on prompts.
     copilot: {
         base: ['copilot'],
-        promptFlag: 'positional',
+        promptFlag: '-p',
         modeFlags: {
-            plan: [],
-            edit: [],
-            full: [],
+            plan: ['--mode', 'plan'],
+            edit: ['--allow-all-tools'],
+            auto: ['--autopilot'],
+            skip: ['--allow-all'],
         },
+        jsonFlags: ['--output-format', 'json'],
         modelFlag: '--model',
     },
     amp: {
@@ -164,7 +246,6 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'plan'],
             edit: ['--mode', 'edit'],
-            full: ['--mode', 'edit'],
         },
         modelFlag: '--model',
     },
@@ -172,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',
     },
@@ -182,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: {
@@ -193,27 +272,33 @@ export const AGENT_COMMANDS = {
         modeFlags: {
             plan: ['--mode', 'architect'],
             edit: ['--mode', 'code'],
-            full: ['--mode', 'code'],
         },
         modelFlag: '--model',
     },
+    // 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
+    // adding `jsonFlags` here.
     antigravity: {
         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: [],
+            skip: ['--dangerously-skip-permissions'],
         },
+        printFlags: ['--print'],
         modelFlag: '--model',
     },
     grok: {
         base: ['grok'],
         promptFlag: '-p',
         modeFlags: {
-            plan: [],
+            // grok --help lists `--permission-mode plan`; the TUI defaults to ask.
+            plan: ['--permission-mode', 'plan'],
             edit: [],
-            full: [],
+            skip: ['--always-approve'],
         },
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',
@@ -248,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
@@ -335,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;