@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/events.js

@@ -16,9 +16,25 @@ import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { parseSshConnection } from './session/provenance.js';
+import { getLogsDir } from './state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
-// Logs live under the cache bucket — they're regenerable telemetry.
-const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry. Route
+// through state's canonical home anchor (HOME override → os.homedir()) rather
+// than a bare os.homedir(): on Windows os.homedir() reads USERPROFILE and
+// ignores a HOME override, so a test (or any caller) that redirects HOME would
+// have its events silently written to the real profile instead. state.getLogsDir()
+// honors the HOME override on every platform while falling back to os.homedir()
+// (== USERPROFILE on Windows) in production where HOME is unset.
+//
+// Resolved lazily + memoized: importing this module must NOT call getLogsDir()
+// at eval time. events.ts is pulled in transitively (skills/versions/exec/
+// runner), and several tests mock './state.js' with partial factories that omit
+// getLogsDir — an eager call would crash those on import. Deferring to first use
+// keeps a bare import side-effect-free while staying a one-time resolution.
+let _logsDir;
+function logsDir() {
+    return (_logsDir ??= getLogsDir());
+}
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
@@ -54,16 +70,16 @@ function getLogFilePath(date = new Date()) {
     const yyyy = date.getFullYear();
     const mm = String(date.getMonth() + 1).padStart(2, '0');
     const dd = String(date.getDate()).padStart(2, '0');
-    return path.join(LOGS_DIR, `events-${yyyy}-${mm}-${dd}.jsonl`);
+    return path.join(logsDir(), `events-${yyyy}-${mm}-${dd}.jsonl`);
 }
 function ensureLogsDir() {
-    if (!fs.existsSync(LOGS_DIR)) {
-        fs.mkdirSync(LOGS_DIR, { recursive: true, mode: DIR_MODE });
+    if (!fs.existsSync(logsDir())) {
+        fs.mkdirSync(logsDir(), { recursive: true, mode: DIR_MODE });
     }
     else {
         // Ensure permissions are correct on existing dir
         try {
-            fs.chmodSync(LOGS_DIR, DIR_MODE);
+            fs.chmodSync(logsDir(), DIR_MODE);
         }
         catch {
             // May fail if not owner
@@ -395,10 +411,10 @@ export function emitError(err, payload = {}) {
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
     try {
-        if (!fs.existsSync(LOGS_DIR))
+        if (!fs.existsSync(logsDir()))
             return 0;
         const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(LOGS_DIR).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        const files = fs.readdirSync(logsDir()).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
         let removed = 0;
         for (const file of files) {
             const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
@@ -407,7 +423,7 @@ export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
             const [, yyyy, mm, dd] = match;
             const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
             if (fileDate.getTime() < cutoff) {
-                fs.unlinkSync(path.join(LOGS_DIR, file));
+                fs.unlinkSync(path.join(logsDir(), file));
                 removed++;
             }
         }
@@ -439,9 +455,9 @@ export function maybeRotate() {
 export function query(options) {
     const { startDate, endDate = new Date(), eventTypes, agent, command, module, limit } = options;
     const results = [];
-    if (!fs.existsSync(LOGS_DIR))
+    if (!fs.existsSync(logsDir()))
         return results;
-    const files = fs.readdirSync(LOGS_DIR)
+    const files = fs.readdirSync(logsDir())
         .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
         .sort()
         .reverse();
@@ -467,7 +483,7 @@ export function query(options) {
             continue;
         if (endDay && fileDate > endDay)
             continue;
-        const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
+        const content = fs.readFileSync(path.join(logsDir(), file), 'utf-8');
         const lines = content.trim().split('\n').filter(Boolean);
         for (const line of lines.reverse()) {
             try {
@@ -528,4 +544,6 @@ export function getTimingStats(label, options = {}) {
     };
 }
 // ─── Exports ──────────────────────────────────────────────────────────────────
-export const LOGS_PATH = LOGS_DIR;
+export function getLogsPath() {
+    return logsDir();
+}

package/dist/lib/exec.d.ts

@@ -230,6 +230,12 @@ export interface FallbackEntry {
     agent: AgentId;
     /** Optional pinned version (e.g. '0.116.0'). When set, takes precedence over the active default. */
     version?: string;
+    /**
+     * Env vars merged over options.env for THIS attempt only. Used by profiles
+     * with `fallback_model` to swap the model env key (e.g. ANTHROPIC_MODEL) on
+     * a same-agent retry without touching auth or base URL.
+     */
+    envOverride?: Record<string, string>;
 }
 /** ExecOptions extended with a fallback chain for rate-limit cascading. */
 export interface FallbackOptions extends ExecOptions {
@@ -237,6 +243,17 @@ export interface FallbackOptions extends ExecOptions {
     fallback: FallbackEntry[];
     /** Fallback requires a prompt -- chain handoff doesn't apply to interactive sessions. */
     prompt: string;
+    /**
+     * Optional out-param the caller reads AFTER the call to learn which chain
+     * entry actually executed — updated to each entry as it is attempted, so on
+     * return it holds the agent+version whose exit code is returned. Lets the
+     * audit log record the fallback that really ran, not always the primary
+     * (issue #347).
+     */
+    dispatchSink?: {
+        agent?: AgentId;
+        version?: string;
+    };
 }
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped

package/dist/lib/exec.js

@@ -16,7 +16,9 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
-import { writePidSessionEntry } from './session/pid-registry.js';
+import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { mailboxDir, isValidMailboxId } from './mailbox.js';
+import { composeWin32CommandLine } from './platform/index.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -182,6 +184,14 @@ export function buildExecEnv(options) {
             : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
         if (version) {
             result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
+            // A managed pin lives in a per-version dir; Claude Code's own background
+            // auto-updater would rewrite that pinned binary in place (and has left it
+            // half-swapped and broken). Disable it so a pin stays a pin. Honor an
+            // explicit user value — from process.env (already in result) or from
+            // options.env (spread over result below).
+            if (result.DISABLE_AUTOUPDATER === undefined) {
+                result.DISABLE_AUTOUPDATER = '1';
+            }
         }
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
@@ -237,6 +247,14 @@ export function buildExecEnv(options) {
         delete result.COPILOT_HOME;
         delete result.KIMI_CODE_HOME;
     }
+    // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
+    // knows which box to drain and inject mid-run. Keyed by the session id — the
+    // same id the writer resolves via mailboxIdForActiveSession(). A loop run
+    // overrides this to its run-level box via options.env (spread below), so all
+    // iterations share one inbox.
+    if (options.sessionId && isValidMailboxId(options.sessionId)) {
+        result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
+    }
     return {
         ...result,
         ...options.env,
@@ -472,11 +490,12 @@ export function buildExecCommand(options) {
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
     //
-    // On Windows the shims dir holds a `.cmd` companion next to the bash alias
-    // (see createVersionedAlias); prefer it so spawn() can launch it (the bash
-    // script is not directly executable by cmd.exe). When no shim exists on disk
-    // we fall back to the bare versioned name, which spawnAgent() resolves via
-    // PATH (+ PATHEXT/shell on Windows).
+    // On Windows the alias is materialized as a `.cmd` only (see
+    // createVersionedAlias — a bash alias next to it would shadow the `.cmd` in
+    // cmd.exe/PowerShell name resolution); the extensionless existsSync branch
+    // below still matches a legacy install's bash alias. When no shim exists on
+    // disk we fall back to the bare versioned name, which spawnAgent() resolves
+    // via PATH (+ PATHEXT/shell on Windows).
     if (options.version && cmd.length > 0) {
         const versionedName = `${cmd[0]}@${options.version}`;
         const absPath = path.join(getShimsDir(), versionedName);
@@ -672,7 +691,14 @@ export function resolveShimSpawn(platform, binary, extraArgs) {
         // Use win32 path semantics regardless of the host running this (the platform
         // is the parameter, not process.platform) so `C:\...` reads as absolute.
         const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
-        return { command: binary, args: extraArgs, shell: useShell };
+        if (useShell) {
+            // DEP0190-safe: hand cmd.exe ONE fully-quoted command line with an EMPTY
+            // args array, so Node never concatenates `extraArgs` (which carry the
+            // user's raw prompt/flags) into the shell line unescaped — that concat is
+            // both the deprecation and a command-injection surface.
+            return { command: composeWin32CommandLine(binary, extraArgs), args: [], shell: true };
+        }
+        return { command: binary, args: extraArgs, shell: false };
     }
     return { command: binary, args: extraArgs, shell: false };
 }
@@ -705,6 +731,21 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
+        // Record the launch so `ag sessions --active` can attribute the agent
+        // process to its cwd (and exact session when the caller passed
+        // --session-id). Vital on Windows, where there is no lsof to recover a
+        // foreign process's cwd. On the shell path this pid is the cmd.exe
+        // wrapper, not the agent binary — the active scan resolves that by
+        // walking the candidate's ancestors (readAncestorSessionEntry).
+        if (child.pid) {
+            writePidSessionEntry({
+                pid: child.pid,
+                agent,
+                sessionId: extractSessionIdArg(rawArgs),
+                cwd,
+                startedAtMs: Date.now(),
+            });
+        }
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
             process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);
@@ -772,9 +813,15 @@ async function spawnAgent(options) {
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', tapStdout ? 'pipe' : 'inherit', 'pipe'];
         // On Windows, .cmd batch wrappers (npm-installed CLIs) require shell:true
-        // whether addressed by name or absolute path.
+        // whether addressed by name or absolute path. On that shell path, compose a
+        // single fully-quoted command line and pass an EMPTY args array (see
+        // composeWin32CommandLine) so Node never concatenates the args array — which
+        // carries the user's prompt — into the cmd.exe line unescaped (DEP0190 +
+        // command injection).
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
-        const child = spawn(executable, args, {
+        const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
+        const spawnArgs = useShell ? [] : args;
+        const child = spawn(spawnCommand, spawnArgs, {
             cwd: options.cwd || process.cwd(),
             stdio,
             env: buildExecEnv(options),
@@ -1016,9 +1063,20 @@ export async function runWithFallback(options) {
         }
     }
     for (let i = 0; i < chain.length; i++) {
-        const { agent, version } = chain[i];
+        const { agent, version, envOverride } = chain[i];
+        // Record the entry we're about to attempt so the caller (audit log) sees the
+        // agent+version that actually ran, even after a rate-limit handoff.
+        if (options.dispatchSink) {
+            options.dispatchSink.agent = agent;
+            options.dispatchSink.version = version;
+        }
         const pinnedSessionId = agent === 'claude' ? randomUUID() : undefined;
-        const prompt = prevAgent
+        // Same-host retry (same agent+version as previous entry — used by profile
+        // `fallback_model` swaps) keeps the original prompt: the model changed,
+        // not the CLI, so a `/continue` handoff prompt would be misleading.
+        const prev = i > 0 ? chain[i - 1] : undefined;
+        const sameHostRetry = !!prev && prev.agent === agent && prev.version === version;
+        const prompt = prevAgent && !sameHostRetry
             ? buildFallbackPrompt(prevAgent, prevSessionId, agent, options.prompt)
             : options.prompt;
         const execOpts = {
@@ -1026,12 +1084,18 @@ export async function runWithFallback(options) {
             agent,
             version,
             prompt,
+            env: envOverride ? { ...(options.env ?? {}), ...envOverride } : options.env,
             sessionId: pinnedSessionId ?? (i === 0 ? options.sessionId : undefined),
         };
         const label = version ? `${agent}@${version}` : agent;
+        const modelSwapNote = sameHostRetry && envOverride
+            ? ` (retry with ${Object.entries(envOverride).map(([k, v]) => `${k}=${v}`).join(', ')})`
+            : '';
         const banner = i === 0
             ? `[agents] running ${label}`
-            : `[agents] fallback → ${label}`;
+            : sameHostRetry
+                ? `[agents] retry → ${label}${modelSwapNote}`
+                : `[agents] fallback → ${label}`;
         process.stderr.write(`${banner}${pinnedSessionId ? ` (session ${pinnedSessionId.slice(0, 8)})` : ''}\n`);
         let result;
         try {
@@ -1054,7 +1118,9 @@ export async function runWithFallback(options) {
         }
         const next = chain[i + 1];
         const nextLabel = next.version ? `${next.agent}@${next.version}` : next.agent;
-        process.stderr.write(`[agents] ${label} hit rate limit. Handing off to ${nextLabel}...\n`);
+        const nextSameHost = next.agent === agent && next.version === version;
+        const handoffVerb = nextSameHost ? 'Retrying on same host' : 'Handing off';
+        process.stderr.write(`[agents] ${label} hit rate limit. ${handoffVerb} to ${nextLabel}...\n`);
         prevAgent = agent;
         prevSessionId = pinnedSessionId;
     }

package/dist/lib/git.d.ts

@@ -112,6 +112,11 @@ export declare function isSystemRepoOrigin(dir: string): Promise<boolean>;
  * Check if repo has uncommitted changes (including untracked files).
  */
 export declare function hasLocalChanges(dir: string): Promise<boolean>;
+/**
+ * Render an absolute path in ~-relative form with forward slashes, matching the
+ * way the rest of the CLI prints home-anchored paths (e.g. `~/.agents/.system`).
+ */
+export declare function displayHomePath(dir: string): string;
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
@@ -121,6 +126,28 @@ export declare function pullRepo(dir: string): Promise<{
     commit: string;
     error?: string;
 }>;
+/**
+ * Rebase a repo onto its remote, optionally pushing local commits back up.
+ *
+ * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
+ *   1. Refuse if the working tree is dirty (commit or discard first).
+ *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
+ *      merge, so a local commit lands cleanly on top of upstream with no merge
+ *      bubble.
+ *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *
+ * The branch is read from the repo's current HEAD (falls back to `main`) rather
+ * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
+ * of the npm-shipped upstream.
+ */
+export declare function syncRepoGit(dir: string, opts: {
+    push: boolean;
+}): Promise<{
+    success: boolean;
+    commit: string;
+    pushed: boolean;
+    error?: string;
+}>;
 /**
  * Get git status for sync display.
  * Returns files categorized by their status relative to HEAD.

package/dist/lib/git.js

@@ -7,6 +7,7 @@
  */
 import simpleGit from 'simple-git';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
 import { getPackageLocalPath } from './state.js';
@@ -494,6 +495,15 @@ export async function hasLocalChanges(dir) {
         return false;
     }
 }
+/**
+ * Render an absolute path in ~-relative form with forward slashes, matching the
+ * way the rest of the CLI prints home-anchored paths (e.g. `~/.agents/.system`).
+ */
+export function displayHomePath(dir) {
+    const home = os.homedir();
+    const rel = dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+    return rel.replace(/\\/g, '/');
+}
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
@@ -506,7 +516,7 @@ export async function pullRepo(dir) {
             return {
                 success: false,
                 commit: '',
-                error: 'Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ~/.agents && git status',
+                error: `Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
             };
         }
         await git.fetch();
@@ -522,6 +532,51 @@ export async function pullRepo(dir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/**
+ * Rebase a repo onto its remote, optionally pushing local commits back up.
+ *
+ * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
+ *   1. Refuse if the working tree is dirty (commit or discard first).
+ *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
+ *      merge, so a local commit lands cleanly on top of upstream with no merge
+ *      bubble.
+ *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *
+ * The branch is read from the repo's current HEAD (falls back to `main`) rather
+ * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
+ * of the npm-shipped upstream.
+ */
+export async function syncRepoGit(dir, opts) {
+    try {
+        if (!isGitRepo(dir)) {
+            return { success: false, commit: '', pushed: false, error: `Not a git repo: ${dir}` };
+        }
+        const git = simpleGit(dir);
+        const status = await git.status();
+        if (!status.isClean()) {
+            return {
+                success: false,
+                commit: '',
+                pushed: false,
+                error: `Working tree has uncommitted changes. Commit or discard them first.\n\n  cd ${dir} && git status`,
+            };
+        }
+        const branch = status.current || 'main';
+        await git.fetch('origin');
+        await git.pull('origin', branch, { '--rebase': 'true' });
+        installGithooksSymlinks(dir);
+        let pushed = false;
+        if (opts.push) {
+            await git.push('origin', branch);
+            pushed = true;
+        }
+        const log = await git.log({ maxCount: 1 });
+        return { success: true, commit: log.latest?.hash.slice(0, 8) || 'unknown', pushed };
+    }
+    catch (err) {
+        return { success: false, commit: '', pushed: false, error: err.message };
+    }
+}
 /** Compute the sync status of a git repo, optionally scoped to a subdirectory. */
 export async function getGitSyncStatus(dir, subdir) {
     if (!isGitRepo(dir)) {

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

@@ -7,6 +7,12 @@ import type { HookCache, HookCacheConfig } from '../types.js';
 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;
+/**
+ * Reject hook names that could escape the shims directory when interpolated
+ * into a filename. Mirrors the containment gate on hook script resolution in
+ * hooks.ts (`resolveContainedHookPath`).
+ */
+export declare function isValidHookShimName(name: string): boolean;
 /** Absolute path of the generated shim for a hook name. */
 export declare function getHookShimPath(name: string): string;
 /**

package/dist/lib/hooks/cache.js

@@ -70,9 +70,35 @@ export function parseDuration(d) {
         return value * 60;
     return value;
 }
+/**
+ * Reject hook names that could escape the shims directory when interpolated
+ * into a filename. Mirrors the containment gate on hook script resolution in
+ * hooks.ts (`resolveContainedHookPath`).
+ */
+export function isValidHookShimName(name) {
+    return (!!name &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.startsWith('-') &&
+        !/[\/\\\x00]/.test(name) &&
+        name.length <= 255);
+}
+/** Resolve shimsDir + `${name}.sh` and assert the result stays inside shimsDir. */
+function resolveContainedHookShimPath(shimsDir, name) {
+    if (!isValidHookShimName(name)) {
+        throw new Error(`Invalid hook shim name: ${name}`);
+    }
+    const resolvedRoot = path.resolve(shimsDir);
+    const candidate = path.join(shimsDir, `${name}.sh`);
+    const resolved = path.resolve(candidate);
+    if (!resolved.startsWith(resolvedRoot + path.sep)) {
+        throw new Error(`Invalid hook shim name: ${name}`);
+    }
+    return resolved;
+}
 /** Absolute path of the generated shim for a hook name. */
 export function getHookShimPath(name) {
-    return path.join(getHookShimsDir(), `${name}.sh`);
+    return resolveContainedHookShimPath(getHookShimsDir(), name);
 }
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
@@ -82,7 +108,7 @@ 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 shimPath = resolveContainedHookShimPath(shimsDir, args.name);
     const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
@@ -105,9 +131,10 @@ export function generateHookShim(args) {
     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).
+ * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
+ * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
+ * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
+ * stub — which exits non-zero without running — doesn't silently break caching.
  */
 function renderShim(name, scriptPath, cache, paths) {
     const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
@@ -133,12 +160,25 @@ KEY_MODE=${q(key)}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR"
 
+# Resolve a real Python. On Windows, bare python3 is often a Microsoft Store
+# app-execution alias stub that prints to stderr and exits non-zero (0 bytes on
+# stdout) -- command -v finds it but it cannot run, which silently empties the
+# hash + mtime primitives below and makes EVERY call a cache miss (the hook
+# re-runs every time). Probe by executing, not by lookup, and fall back to python.
+PY=""
+for _cand in python3 python; do
+  if command -v "$_cand" >/dev/null 2>&1 && "$_cand" -c 'import sys' >/dev/null 2>&1; then
+    PY="$_cand"; break
+  fi
+done
+[ -z "$PY" ] && PY=python3
+
 # 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])'; }
+sha1_12() { "$PY" -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
@@ -146,14 +186,14 @@ sha1_12() { python3 -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().
 cache_suffix=""
 case "$KEY_MODE" in
   per-cwd)
-    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -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
+    sid_val="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -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
@@ -173,7 +213,7 @@ 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))'; }
+now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
 START_NS=$(now_ns)
 
 CACHE_STATUS=miss
@@ -181,10 +221,10 @@ CACHE_AGE=-1
 EXIT=0
 
 if [ -f "$CACHE_FILE" ]; then
-  # python3 is already a hard dep (used for now_ns) and gives portable mtime
+  # $PY is already resolved (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=$("$PY" -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))
@@ -231,8 +271,10 @@ exit "$EXIT"
  * hook is renamed/deleted or has its `cache:` field removed.
  */
 export function removeHookShim(name, shimsDir) {
+    if (!isValidHookShimName(name))
+        return;
     const dir = shimsDir ?? getHookShimsDir();
-    const shimPath = path.join(dir, `${name}.sh`);
+    const shimPath = resolveContainedHookShimPath(dir, name);
     if (fs.existsSync(shimPath)) {
         try {
             fs.unlinkSync(shimPath);

package/dist/lib/hooks.d.ts

@@ -8,6 +8,19 @@
  * and syncing them across version switches.
  */
 export declare function resolveHookScriptPath(script: string): string | null;
+/**
+ * Convert an absolute path under HOME to a portable ~/... form with forward
+ * slashes. Hook commands stored this way work on both macOS and Windows:
+ * absolute Windows paths break in bash because backslashes are stripped as
+ * escape characters, whereas ~/... paths expand correctly via the ~/.claude
+ * symlink/junction on both platforms.
+ *
+ * `home` and `sep` are injectable so the Windows behavior (backslash sep,
+ * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
+ * simulate Windows. With the defaults this is byte-identical to reading
+ * os.homedir()/path.sep at the call site.
+ */
+export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
@@ -165,3 +178,17 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
     registered: string[];
     errors: string[];
 };
+/**
+ * Prune every Claude-family (`settings.json`) hook entry whose command lives
+ * under a removed version's home
+ * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
+ *
+ * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
+ * the hook entries other version homes registered against it — dead hooks that
+ * error on every tool call ("No such file or directory") until the next sync.
+ * This clears them from a remaining version's settings immediately. Only the
+ * removed version's entries are touched; the current version's entries, system
+ * hooks, and the user's own custom hooks are left intact. Returns the number of
+ * entries removed.
+ */
+export declare function pruneVersionHomeHookEntriesFromSettings(settingsPath: string, agent: AgentId, removedVersion: string): number;