@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/git.js

@@ -11,7 +11,7 @@ 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, getDeviceMetaPath } from './state.js';
+import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
@@ -334,6 +334,34 @@ export async function getRepoCommit(repoPath) {
         return 'unknown';
     }
 }
+/** Read {@link RepoStateSnapshot} for `repoPath` using plumbing commands so the
+ *  result is stable across git versions and never mutates the tree. Returns null
+ *  when the path is not a git worktree. */
+export function readRepoState(repoPath) {
+    const runGit = (args) => {
+        try {
+            return execFileSync('git', ['-C', repoPath, ...args], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+            })
+                .toString()
+                .trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    // Gate on a real worktree first; `rev-parse --is-inside-work-tree` prints
+    // `true` only inside one, and returns non-zero (→ null) otherwise.
+    if (runGit(['rev-parse', '--is-inside-work-tree']) !== 'true')
+        return null;
+    const branchRaw = runGit(['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = branchRaw && branchRaw !== 'HEAD' ? branchRaw : null; // detached → null
+    const headRaw = runGit(['rev-parse', 'HEAD']);
+    const head = headRaw ? headRaw.slice(0, 8) : null;
+    const porcelain = runGit(['status', '--porcelain']);
+    const dirty = porcelain != null && porcelain.length > 0;
+    return { branch, head, dirty };
+}
 /**
  * Get the current GitHub username using gh CLI.
  * Returns null if gh is not installed or user is not authenticated.
@@ -775,47 +803,42 @@ export function displayHomePath(dir) {
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
-/**
- * Auto-commit the machine's OWN generated per-device meta file
- * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
- *
- * That file is committed + synced (so every machine can introspect every other
- * machine's pins), but each box rewrites its own copy whenever a pin changes —
- * leaving the tree perpetually dirty and wedging `agents repo pull` (which
- * refuses a dirty tree). This durably commits just that one path (explicit
- * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
- * untouched and still (correctly) block the pull. No-op when the meta path isn't
- * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
- * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
- */
-export async function commitOwnDeviceMeta(dir, metaAbs = getDeviceMetaPath()) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedMeta = path.resolve(metaAbs);
-    if (resolvedMeta !== resolvedDir && !resolvedMeta.startsWith(resolvedDir + path.sep)) {
-        return null; // meta lives outside this repo — not ours to commit here
-    }
-    const rel = path.relative(resolvedDir, resolvedMeta).split(path.sep).join('/');
-    try {
-        const git = simpleGit(dir);
-        const status = await git.status();
-        const dirty = status.files.some((f) => f.path === rel);
-        if (!dirty)
-            return null;
-        await git.add([rel]);
-        const machine = path.basename(path.dirname(resolvedMeta));
-        await git.commit(`chore(devices): snapshot ${machine} agent pins`, [rel]);
-        return rel;
-    }
-    catch {
-        return null; // best-effort — never let this block the pull path
-    }
-}
 export async function pullRepo(dir) {
     try {
         const git = simpleGit(dir);
-        // Commit this machine's own device-meta first so a per-machine pin change
-        // never wedges the pull. Genuine edits elsewhere still block below.
-        await commitOwnDeviceMeta(dir);
+        // A rebase left in progress by an earlier run must be reported as itself.
+        // Without this the dirty-tree guard below claims "Blocked by local changes",
+        // which is both wrong and actively harmful advice mid-rebase on a detached
+        // HEAD.
+        // Ask git where the state dirs live rather than assuming `<dir>/.git/` is a
+        // directory. In a worktree `.git` is a FILE containing `gitdir: <path>`, so
+        // path.join(dir, '.git', 'rebase-merge') can never exist and the check would
+        // silently never fire. `rev-parse --git-path` resolves both layouts.
+        const gitPath = async (name) => {
+            try {
+                const raw = (await git.raw(['rev-parse', '--git-path', name])).trim();
+                return path.isAbsolute(raw) ? raw : path.join(dir, raw);
+            }
+            catch {
+                return null;
+            }
+        };
+        const [rebaseMerge, rebaseApply] = await Promise.all([
+            gitPath('rebase-merge'),
+            gitPath('rebase-apply'),
+        ]);
+        const rebaseInProgress = (rebaseMerge !== null && fs.existsSync(rebaseMerge)) ||
+            (rebaseApply !== null && fs.existsSync(rebaseApply));
+        if (rebaseInProgress) {
+            return {
+                success: false,
+                commit: '',
+                error: `A previous rebase is still in progress — finish or abort it, then pull again.\n\n` +
+                    `  cd ${displayHomePath(dir)} && git status\n` +
+                    `  git rebase --continue   # after resolving\n` +
+                    `  git rebase --abort      # to discard the attempt`,
+            };
+        }
         const status = await git.status();
         if (!status.isClean()) {
             return {
@@ -825,12 +848,15 @@ export async function pullRepo(dir) {
             };
         }
         const branch = status.current || 'main';
-        await git.fetch('origin');
         // Resolve the upstream ref to fast-forward against. Prefer the local
         // branch's tracking config; otherwise ask origin for its default branch.
         let tracking = status.tracking;
         if (!tracking) {
+            // No tracking config: fetch origin so its HEAD is known, then ask which
+            // branch it points at. This path only ever concerns origin — a branch with
+            // no upstream has no other remote to consult.
             try {
+                await git.fetch('origin');
                 await git.raw(['remote', 'set-head', 'origin', '--auto']);
                 const sym = await git.raw(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
                 tracking = sym.trim();
@@ -839,6 +865,22 @@ export async function pullRepo(dir) {
                 tracking = `origin/${branch}`;
             }
         }
+        // Split the remote-tracking ref (<remote>/<branch>) into its parts and pull
+        // THOSE. Hardcoding 'origin' while comparing against `tracking` is how a
+        // branch tracking e.g. upstream/main silently 'succeeded': revparse saw a
+        // difference, the pull fetched origin/main (already current), and pullRepo
+        // returned success having moved nothing — the same "reported ok, pulled
+        // nothing" failure this change exists to remove. Branch names may contain
+        // slashes, so split on the FIRST separator only.
+        const sep = tracking.indexOf('/');
+        const remoteName = sep > 0 ? tracking.slice(0, sep) : 'origin';
+        const remoteBranch = sep > 0 ? tracking.slice(sep + 1) : branch;
+        // Bare fetch: updates every remote, so the revparse below sees a fresh ref
+        // whichever one the branch tracks. Deliberately argument-less — simple-git's
+        // fetchTask only forwards a remote when BOTH remote and branch are passed,
+        // so `fetch(remoteName)` would silently drop the argument and do exactly
+        // this anyway. Saying so beats an inert argument that reads as targeted.
+        await git.fetch();
         const localRef = await git.revparse(['HEAD']);
         const remoteRef = await git.revparse([tracking]).catch(() => null);
         if (!remoteRef) {
@@ -853,13 +895,29 @@ export async function pullRepo(dir) {
             };
         }
         try {
-            await git.merge(['--ff-only', tracking]);
+            // Rebase, not --ff-only. Fast-forward refuses ANY divergence, conflict or
+            // not, so a single local commit permanently wedged the pull with nothing
+            // actually in conflict. Matches syncRepoGit (below) and this function's doc.
+            //
+            // Pull the RESOLVED tracking ref, not `branch`: when the local branch has
+            // no tracking config the block above falls back to origin's default head,
+            // which may be named differently (local `main` vs origin `master`). Using
+            // `branch` there asks origin for a ref it does not have.
+            assertValidBranchName(remoteBranch);
+            await git.pull(remoteName, remoteBranch, { '--rebase': 'true' });
         }
-        catch {
+        catch (err) {
+            // Abort so the tree is restored, matching the atomicity --ff-only gave us.
+            // Without this a conflict leaves the repo detached, mid-rebase, with
+            // conflict markers written into live config (this repo is ~/.agents —
+            // agents.yaml and AGENTS.md are in it), and every later pull misreports
+            // the cause. `agents sync` reaches this path unattended across the fleet,
+            // so a wedged checkout would be worse than the bug this fixes.
+            await git.raw(['rebase', '--abort']).catch(() => { });
             return {
                 success: false,
                 commit: '',
-                error: `Blocked by local commits. Push or reset them before pulling.\n\n  cd ${displayHomePath(dir)} && git log --oneline HEAD...${tracking}`,
+                error: `Rebase onto ${tracking} hit a conflict — the pull was rolled back, nothing changed.\n\nResolve the divergence, then pull again:\n\n  cd ${displayHomePath(dir)} && git log --oneline HEAD...${tracking}\n\n${err.message}`,
             };
         }
         installGithooksSymlinks(dir);
@@ -1113,3 +1171,40 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
+/**
+ * How many commits `dir`'s checked-out branch is behind its upstream, read from
+ * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the
+ * dir is not a git repo, has no upstream configured, or git errors.
+ *
+ * Used by `agents doctor` to flag a source layer (`~/.agents`, `~/.agents/.system`)
+ * that is reconciled against stale truth. Staleness relative to origin is a
+ * background auto-pull concern; this surfaces the same fact synchronously in the
+ * per-version verdict.
+ */
+export function commitsBehindUpstream(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    const run = (args) => {
+        try {
+            return execFileSync('git', ['-C', dir, ...args], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                encoding: 'utf8',
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    // Name of the upstream ref (e.g. `origin/main`) for the human-readable message.
+    const branch = run(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    if (!branch)
+        return null;
+    // `--count HEAD..@{upstream}` = commits on upstream not yet in HEAD = behind.
+    const raw = run(['rev-list', '--count', 'HEAD..@{upstream}']);
+    if (raw === null)
+        return null;
+    const behind = parseInt(raw, 10);
+    if (!Number.isFinite(behind))
+        return null;
+    return { behind, branch };
+}

package/dist/lib/hooks.d.ts

@@ -59,6 +59,48 @@ export declare function getVersionHooksDir(agent: AgentId, version: string): str
  * List hook entries in a specific version home.
  */
 export declare function listHooksInVersionHome(agent: AgentId, version: string): HookEntry[];
+export interface HookWiringIssue {
+    /** Hook name (script basename minus extension). */
+    name: string;
+    /** Native lifecycle event the hook should be wired to (Stop, PreToolUse, …). */
+    event: string;
+    /** Matcher group the hook belongs to under `event` (`''` = the catch-all
+     *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
+     *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
+    matcher: string;
+    /** The command settings.json should reference for this hook under `event`. */
+    command: string;
+}
+export interface HookWiringReport {
+    /** Whether this agent's hook config format is understood by the inspector. */
+    supported: boolean;
+    /** Absolute path of the settings file inspected (when supported). */
+    settingsPath?: string;
+    /** Number of hooks the manifest says should be wired for this version. */
+    expected?: number;
+    /** settings.json does not exist — nothing declared can be wired. */
+    settingsMissing?: boolean;
+    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    settingsUnparseable?: boolean;
+    /** Hooks whose file is present/resolvable but that are NOT referenced in the
+     *  event array settings.json should carry them in. */
+    unwired: HookWiringIssue[];
+}
+/**
+ * Verify that every hook the manifest says should be wired for a (claude|droid)
+ * version is actually REFERENCED in that version's native settings.json — not
+ * merely present as a file on disk.
+ *
+ * `agents doctor` compares hook FILES against source (see diffHooks in
+ * doctor-diff.ts) but never checks the wiring, so a hook whose script is
+ * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
+ * array reads as "ok" while it never fires. This closes that blind spot.
+ *
+ * Read-only by construction: it mirrors registerHooksForClaude's command
+ * resolution WITHOUT the shim-generation / chmod side effects that
+ * resolveHookCommand performs, so it never mutates the version home.
+ */
+export declare function checkVersionHookWiring(agent: AgentId, version: string): HookWiringReport;
 export interface VersionHookDiff {
     agent: AgentId;
     version: string;

package/dist/lib/hooks.js

@@ -13,9 +13,8 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-import { AGENTS, agentConfigDirName } from './agents.js';
+import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
-import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
 import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
@@ -148,7 +147,7 @@ function isStaleSiblingVersionCommand(command, current) {
     return id !== null && id.agent === current.agent && id.version !== current.version;
 }
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
-import { generateHookShim, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
+import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
@@ -488,6 +487,130 @@ export function getVersionHooksDir(agent, version) {
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
+// ─── wiring inspection (settings.json family: claude, droid) ──────────────────
+/**
+ * Agents whose hooks register through {@link registerHooksForClaude} — a native
+ * settings.json shaped `hooks[event] = [{ matcher, hooks: [{ command }] }]`, with
+ * no event renaming. These are the only agents this read-only wiring inspector
+ * understands; every other harness uses a divergent config format and/or event
+ * map (Gemini/Antigravity settings.json variants, Codex config.toml, the OpenCode
+ * plugin, …), so it reports them unsupported rather than risk a false verdict.
+ */
+const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid'];
+/**
+ * Verify that every hook the manifest says should be wired for a (claude|droid)
+ * version is actually REFERENCED in that version's native settings.json — not
+ * merely present as a file on disk.
+ *
+ * `agents doctor` compares hook FILES against source (see diffHooks in
+ * doctor-diff.ts) but never checks the wiring, so a hook whose script is
+ * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
+ * array reads as "ok" while it never fires. This closes that blind spot.
+ *
+ * Read-only by construction: it mirrors registerHooksForClaude's command
+ * resolution WITHOUT the shim-generation / chmod side effects that
+ * resolveHookCommand performs, so it never mutates the version home.
+ */
+export function checkVersionHookWiring(agent, version) {
+    if (!AGENTS[agent].supportsHooks || !SETTINGS_JSON_HOOK_FAMILY.includes(agent)) {
+        return { supported: false, unwired: [] };
+    }
+    const versionHome = getVersionHomePath(agent, version);
+    const settingsPath = path.join(versionHome, agentConfigDirName(agent), 'settings.json');
+    const localHooksDir = getVersionHooksDir(agent, version);
+    // Resolve ONLY to a script that was actually synced for THIS agent+version: the
+    // copy in the version home hooks dir, or an absolute subrule-dir path (those are
+    // registered in place, never copied). Deliberately NO central-source fallback —
+    // sync wires `selectHookManifest(parseHookManifest(), hooksToSync)` where
+    // hooksToSync is the per-agent selected set (versions.ts), so a hook the manifest
+    // declares but that was never synced into THIS version home (e.g. a claude-scoped
+    // hook viewed for droid) must not be expected here. A missing-but-declared hook
+    // is a FILE gap that diffHooks reports as `missing`, not a wiring gap.
+    // No ensureExecutable — that chmods, and this path must not touch disk.
+    const resolveScript = (script) => {
+        if (path.isAbsolute(script) && fs.existsSync(script))
+            return script;
+        return resolveContainedHookPath(localHooksDir, script);
+    };
+    // Read-only mirror of resolveHookCommand — same command string, no shim write.
+    const expectedCommand = (name, hookDef) => {
+        const scriptPath = resolveScript(hookDef.script);
+        if (!scriptPath)
+            return null;
+        if (!isValidHookShimName(name))
+            return null;
+        const cache = parseCacheConfig(hookDef.cache);
+        const hasMatches = hookDef.matches != null && Object.keys(hookDef.matches).length > 0;
+        if (!cache && !hasMatches)
+            return toPortableCommand(scriptPath);
+        return toPortableCommand(getHookShimPath(name));
+    };
+    const manifest = parseHookManifest({ warn: false });
+    const expected = [];
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const command = expectedCommand(name, hookDef);
+        if (!command)
+            continue; // script unresolved — a file gap, reported by diffHooks
+        // Mirror registerHooksForClaude: a hook registers under the matcher group
+        // `hookDef.matcher || ''` for each of its events.
+        const matcher = hookDef.matcher || '';
+        for (const event of hookDef.events)
+            expected.push({ name, event, matcher, command });
+    }
+    if (!fs.existsSync(settingsPath)) {
+        return {
+            supported: true,
+            settingsPath,
+            expected: expected.length,
+            settingsMissing: expected.length > 0,
+            unwired: [],
+        };
+    }
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return {
+            supported: true,
+            settingsPath,
+            expected: expected.length,
+            settingsUnparseable: true,
+            unwired: [],
+        };
+    }
+    // Command strings actually referenced, keyed by (event, matcher) — a hook wired
+    // under the WRONG matcher group must NOT read as wired, so scope by matcher and
+    // not just by event.
+    const wiredByGroup = new Map();
+    const groupKey = (event, matcher) => `${event}\n${matcher}`;
+    const hooks = config.hooks && typeof config.hooks === 'object'
+        ? config.hooks
+        : {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!group || !Array.isArray(group.hooks))
+                continue;
+            const matcher = typeof group.matcher === 'string' ? group.matcher : '';
+            const key = groupKey(event, matcher);
+            let cmds = wiredByGroup.get(key);
+            if (!cmds) {
+                cmds = new Set();
+                wiredByGroup.set(key, cmds);
+            }
+            for (const h of group.hooks) {
+                if (h && typeof h.command === 'string')
+                    cmds.add(h.command);
+            }
+        }
+    }
+    const unwired = expected.filter((e) => !wiredByGroup.get(groupKey(e.event, e.matcher))?.has(e.command));
+    return { supported: true, settingsPath, expected: expected.length, unwired };
+}
 /**
  * Check if a hook installed in a specific version matches central content.
  */
@@ -936,6 +1059,9 @@ function sweepOrphanShims(manifest) {
     }
 }
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
+    if (isAgentHardDeprecated(agentId)) {
+        return { registered: [], errors: [] };
+    }
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
         if (agentId === 'opencode') {
@@ -995,9 +1121,6 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'codex') {
         return registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes);
     }
-    if (agentId === 'gemini') {
-        return registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes);
-    }
     if (agentId === 'antigravity') {
         return registerHooksForAntigravity(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -1183,16 +1306,6 @@ const ANTIGRAVITY_EVENT_MAP = {
     Stop: 'on_loop_stop',
     OnError: 'on_error',
 };
-/**
- * Gemini has no native UserPromptSubmit event — map it to BeforeAgent,
- * the closest lifecycle phase that fires before the model sees the prompt.
- * Note: gemini's BeforeAgent can only APPEND via additionalContext — it
- * cannot replace the prompt. The hook script branches on caller to emit
- * the correct protocol.
- */
-const GEMINI_EVENT_MAP = {
-    UserPromptSubmit: 'BeforeAgent',
-};
 function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, configDirName = '.claude') {
     const registered = [];
     const errors = [];
@@ -1387,12 +1500,17 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         if (resolved)
             currentManifestPaths.add(resolved);
     }
+    // Identity of the version home being synced. Codex stores hooks in a shared
+    // hooks.json per CODEX_HOME, but agents-cli registers version-scoped command
+    // paths; without this, old version entries keep firing after upgrades.
+    const currentVh = versionHomeIdentity(versionHome);
     // Remove stale entries from all event groups
     for (const eventGroups of Object.values(hooksFile.hooks)) {
         for (const group of eventGroups) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
+            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+                !isStaleSiblingVersionCommand(h.command, currentVh));
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
@@ -1436,7 +1554,8 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
                 group.hooks = [];
             }
             const existingIdx = group.hooks.findIndex((h) => h.command === commandPath);
-            const hookEntry = { type: 'command', command: commandPath, timeout };
+            const eventTimeout = event === 'SessionEnd' ? Math.min(timeout, 3) : timeout;
+            const hookEntry = { type: 'command', command: commandPath, timeout: eventTimeout };
             if (existingIdx >= 0) {
                 group.hooks[existingIdx] = hookEntry;
             }
@@ -1529,81 +1648,6 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     }
     return { registered, errors };
 }
-function registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes) {
-    const registered = [];
-    const errors = [];
-    const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
-    try {
-        updateGeminiSettings(settingsPath, (config) => {
-            setGeminiAutoUpdateDisabled(config);
-            if (!config.hooks || typeof config.hooks !== 'object') {
-                config.hooks = {};
-            }
-            const hooks = config.hooks;
-            const currentManifestPaths = new Set();
-            for (const [hookName, hookDef] of Object.entries(manifest)) {
-                if (!hookDef.events || hookDef.events.length === 0)
-                    continue;
-                const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
-                if (resolved)
-                    currentManifestPaths.add(resolved);
-            }
-            for (const eventEntries of Object.values(hooks)) {
-                if (!Array.isArray(eventEntries))
-                    continue;
-                for (const group of eventEntries) {
-                    if (!group.hooks)
-                        continue;
-                    group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
-                }
-            }
-            for (const [event, eventEntries] of Object.entries(hooks)) {
-                if (!Array.isArray(eventEntries))
-                    continue;
-                hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
-            }
-            for (const [name, hookDef] of Object.entries(manifest)) {
-                if (!hookDef.events || hookDef.events.length === 0)
-                    continue;
-                const commandPath = resolveHookCommand(name, hookDef, resolveScript);
-                if (!commandPath) {
-                    errors.push(`${name}: script not found in user or system hooks dir`);
-                    continue;
-                }
-                const timeoutMs = (hookDef.timeout || 600) * 1000;
-                for (const event of hookDef.events) {
-                    const geminiEvent = GEMINI_EVENT_MAP[event] ?? event;
-                    if (!hooks[geminiEvent]) {
-                        hooks[geminiEvent] = [];
-                    }
-                    const eventEntries = hooks[geminiEvent];
-                    const matcher = hookDef.matcher || '';
-                    let matcherGroup = eventEntries.find((e) => (e.matcher || '') === matcher);
-                    if (!matcherGroup) {
-                        matcherGroup = { matcher, hooks: [] };
-                        eventEntries.push(matcherGroup);
-                    }
-                    if (!matcherGroup.hooks) {
-                        matcherGroup.hooks = [];
-                    }
-                    const existingIdx = matcherGroup.hooks.findIndex((h) => h.command === commandPath);
-                    const hookEntry = { name, type: 'command', command: commandPath, timeout: timeoutMs };
-                    if (existingIdx >= 0) {
-                        matcherGroup.hooks[existingIdx] = hookEntry;
-                    }
-                    else {
-                        matcherGroup.hooks.push(hookEntry);
-                    }
-                    registered.push(`${name} -> ${geminiEvent}`);
-                }
-            }
-        });
-    }
-    catch (err) {
-        errors.push(`Failed to write gemini settings.json: ${err.message}`);
-    }
-    return { registered, errors };
-}
 /**
  * Register hooks into antigravity's (agy) settings.json. Unlike gemini, agy uses
  * a flat per-event array of `{ command }` entries (no matcher groups). Events

package/dist/lib/hosts/dispatch.d.ts

@@ -11,6 +11,18 @@
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd`.
+ *
+ * Without this a `--host` run lands in the remote `$HOME`, so an agent launched
+ * from a repo starts with no project context and the user has to `cd` by hand.
+ * Only a cwd under the LOCAL home is mirrored — that is the part with a
+ * meaningful remote analogue (`~/src/x` re-roots onto the remote home). A path
+ * outside home returns undefined: `/opt/thing` on this box says nothing about
+ * the target's filesystem, so the run keeps the remote home.
+ */
+export declare function deriveMirroredCwd(localCwd: string): string | undefined;
 /**
  * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
  *
@@ -18,8 +30,19 @@ import { type HostCredentials } from './credentials.js';
  * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
  * for that segment — the remote login shell expands it — and shell-quote the
  * remainder. Any other path (absolute or relative) is quoted verbatim.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
  */
-export declare function remoteCdPrefix(remoteCwd?: string): string;
+export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
+    mirror?: boolean;
+}): string;
 /**
  * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
  * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
@@ -103,6 +126,8 @@ export interface DispatchOptions {
     /** Native-CLI passthrough (everything after `--`), appended last. */
     passthroughArgs?: string[];
     remoteCwd?: string;
+    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
+    mirrorCwd?: boolean;
     /**
      * Force the remote run's NEW session to use this exact id (Claude only, via
      * `agents run --session-id`). Captured on the task record so the run is
@@ -165,6 +190,8 @@ export interface InteractiveDispatchOptions {
     /** Route through the Agent Client Protocol. */
     acp?: boolean;
     remoteCwd?: string;
+    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
+    mirrorCwd?: boolean;
     sessionId?: string;
     name?: string;
     resume?: string;