@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/lib/exec.js

@@ -17,7 +17,7 @@ import { isTierToken, resolveTier } from './model-tiers.js';
 import { createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
-import { getShimsDir, getHistoryDir } from './state.js';
+import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
@@ -86,7 +86,7 @@ export function headlessPlanStallCommand(args) {
  *   (every agent supports edit-like behavior as its default).
  * - `plan` on an agent without a read-only mode degrades to the agent's
  *   safest native mode (`capabilities.modes[0]`, typically `edit`). Agents
- *   like antigravity/cursor/kiro have no plan flag; hard-failing made
+ *   like antigravity/kiro have no plan flag; hard-failing made
  *   multi-agent scripts (`--mode plan` for everyone) unusable and diverged
  *   from `agents teams add`, which already defaults to `edit`. Callers that
  *   care (the `agents run` CLI) must surface a warning when requested ≠
@@ -106,7 +106,7 @@ export function resolveMode(agent, requested) {
     }
     if (requested === 'plan') {
         // No read-only mode on this agent. modes[0] is the declared safest mode
-        // (edit for antigravity/cursor/kiro/…). Prefer that over hard-fail so
+        // (edit for antigravity/kiro/…). Prefer that over hard-fail so
         // uniform multi-agent `--mode plan` dispatches still run.
         return supported[0];
     }
@@ -121,8 +121,8 @@ export function resolveMode(agent, requested) {
  * `--prompt` + `--plan`, and grok's `--permission-mode plan` silently stalls at
  * its ExitPlanMode gate. For those agents, a headless plan request degrades to
  * `auto` (kimi -p auto-runs; grok maps auto→edit via resolveMode) with a visible
- * one-line stderr warning, mirroring the graceful plan→edit degrade cursor and
- * antigravity get for having no plan flag at all. Interactive runs are never
+ * one-line stderr warning, mirroring the graceful plan→edit degrade antigravity
+ * and kiro get for having no plan flag at all. Interactive runs are never
  * downgraded. This is the single source of truth shared by buildExecCommand
  * (agents run / teams) and the routine runner.
  */
@@ -142,12 +142,8 @@ export function resolveHeadlessMode(agent, requested, interactive, warningContex
     if (mode !== requested) {
         const subject = warningContext ? `${warningContext}: ` : '';
         if (requested === 'plan') {
-            const limitation = agent === 'cursor'
-                ? "cursor's read-only plan mode is not enabled in this build"
-                : `${agent} has no read-only 'plan' mode`;
-            warn(`[agents] ${subject}${limitation}; ` +
-                `running '${mode}' (writable) instead${agent === 'cursor' ? ' (RUSH-2101)' : ''}. ` +
-                `Pass --mode ${mode} to silence this.\n`);
+            warn(`[agents] ${subject}${agent} has no read-only 'plan' mode; ` +
+                `running '${mode}' (writable) instead. Pass --mode ${mode} to silence this.\n`);
         }
         else {
             warn(`[agents] ${subject}${agent} has no '${requested}' mode; using '${mode}'.\n`);
@@ -362,6 +358,28 @@ export function buildExecEnv(options) {
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
     }
+    else if (options.agent === 'muse') {
+        // Muse has no MUSE_CONFIG_DIR. Config is XDG-based:
+        //   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+        //   $XDG_DATA_HOME/muse    (sessions, plugins)
+        // Pin both into the version home so multi-version isolation matches
+        // Claude's CLAUDE_CONFIG_DIR / Codex's CODEX_HOME, and so Muse never
+        // resolves through the adopt-time ~/.config/muse symlink (SymlinkOrReparse).
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('muse', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('muse', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            const versionHome = getVersionHomePath('muse', version);
+            result.XDG_CONFIG_HOME = path.join(versionHome, '.config');
+            result.XDG_DATA_HOME = path.join(versionHome, '.local', 'share');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
+    }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
@@ -472,6 +490,7 @@ export const AGENT_COMMANDS = {
         base: ['cursor-agent'],
         promptFlag: '-p',
         modeFlags: {
+            plan: ['--plan'],
             edit: [],
             skip: ['-f'],
         },
@@ -665,6 +684,23 @@ export const AGENT_COMMANDS = {
         // `resume` subcommand — special-cased in buildExecCommand.
         resume: { flag: '--session-id' },
     },
+    // Warp Agent CLI (`oz agent run`). Headless is `-p/--prompt "<task>"`; JSON is
+    // the global `--output-format json`. Autonomy comes from the selected agent
+    // profile (`--profile`), not a per-run permission flag, so the single `edit`
+    // mode maps to no flags (mirrors hermes). `--model` overrides the base model
+    // (`oz model list`). No `resume`: Oz's `oz agent run --conversation <id>`
+    // continues a SERVER-SIDE conversation by id, and warp is not session-tracked
+    // (absent from SESSION_AGENTS), so agents-cli has no local id to resume from —
+    // declaring it would make nativeResume(warp) true against an unreachable path.
+    warp: {
+        base: ['oz', 'agent', 'run'],
+        promptFlag: '-p',
+        modeFlags: {
+            edit: [],
+        },
+        jsonFlags: ['--output-format', 'json'],
+        modelFlag: '--model',
+    },
 };
 /**
  * Whether `agent` has a native resume form (Tier 1). Derived solely from the
@@ -1167,13 +1203,53 @@ export function shouldWrapInTmux(ctx) {
  * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
+    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
+    // envFile: source the values instead of inlining them, so no VALUE ever lands
+    // in the pane's argv. `exec env K=V …` put every resolved secret into the
+    // process table, readable by any process of this user — on one fleet box six
+    // live processes carried the secrets-store master passphrase, which decrypts
+    // every file-backed bundle including the Claude OAuth tokens (RUSH-2100).
+    // `set -a` exports what the file assigns; the file is unlinked before `exec`,
+    // so it exists only for the sourcing itself. A missing file aborts the pane
+    // rather than silently launching with a half-built env.
+    if (opts.envFile) {
+        const f = shellQuote(opts.envFile);
+        // Remove the file whether or not sourcing succeeds — a bare `. f || exit 1`
+        // strands the plaintext env (incl. the secrets-store master passphrase) on
+        // disk on any source failure, worse than the argv leak this replaces
+        // (RUSH-2100). Capture the source rc, unlink, then honor it.
+        return `set -a; . ${f}; __agents_rc=$?; set +a; rm -f ${f}; [ "$__agents_rc" -eq 0 ] || exit 1; exec ${agentCmd}`;
+    }
     const envPrefix = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
         .map(([k, v]) => `${k}=${opts.redactEnvValues ? '<redacted>' : shellQuote(String(v))}`)
         .join(' ');
-    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
 }
+/**
+ * Serialize the pane env to a shell-sourceable file, created 0600 and exclusively
+ * (`wx`) so it can never adopt a pre-existing file's mode or content.
+ *
+ * EVERY key goes in the file, not a curated "secret-bearing" subset: a denylist
+ * has to be updated for each new credential and is wrong the moment someone
+ * forgets, whereas routing all of it through the file makes the guarantee hold by
+ * construction. Keys are filtered to valid shell identifiers for the same reason
+ * `env` needed it — an exported function (`BASH_FUNC_x%%`) is not assignable.
+ */
+export function writeTmuxEnvFile(env, filePath) {
+    const body = Object.entries(env)
+        .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
+        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .join('\n');
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, 'wx', 0o600);
+    try {
+        fs.writeSync(fd, `${body}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
  * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
@@ -1231,15 +1307,32 @@ async function runInTmux(options, executable, args) {
     // SessionStart learns some harness IDs only after launch. Carry the wrapper
     // name into that hook so it can bind both identities durably.
     const execEnv = { ...buildExecEnv(options), AGENT_TMUX_SESSION_NAME: name };
-    // Launch with the real env (secret VALUES materialized into the pane); persist
-    // only a value-redacted copy in SessionMeta.cmd so resolved secrets never hit
-    // disk via the informational cmd field (RUSH-1758).
-    const cmd = buildTmuxAgentCommand(executable, args, execEnv);
+    // The pane sources its env from a 0600 file it unlinks before exec, so no
+    // resolved secret VALUE reaches the process table (RUSH-2100). SessionMeta.cmd
+    // keeps the value-redacted inline form — the human-readable record of what ran,
+    // which never carried real values anyway (RUSH-1758).
+    const envFile = path.join(getRuntimeStateDir(), 'tmux-env', `${name}-${randomUUID().slice(0, 8)}.env`);
+    writeTmuxEnvFile(execEnv, envFile);
+    const cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
     if (options.sessionId)
         labels.sessionId = options.sessionId;
-    const meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
+    // Only a launched pane sources-and-unlinks the env file. If createSession
+    // throws, the pane never runs, so the resolved secrets (incl. the master
+    // passphrase) would linger on disk — remove it on that failure path
+    // (RUSH-2100). On success the detached pane owns the unlink.
+    let meta;
+    try {
+        meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
+    }
+    catch (err) {
+        try {
+            fs.rmSync(envFile, { force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
     const pane = meta.pane;
     if (options.sessionId)
         writeSessionAliasRecord(options.sessionId, name);
@@ -1317,7 +1410,7 @@ async function runInTmux(options, executable, args) {
     };
     // The agent could exit before we attach (fast failure). Don't attach to an
     // already-dead pane — surface its output + status directly and tear down.
-    const before = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (before.dead) {
         // F2 (RUSH-2185 / EXEC-23a): for interactive runs, ALWAYS recap — a clean
         // exit-0 before attach means the harness has no interactive REPL and the
@@ -1343,7 +1436,7 @@ async function runInTmux(options, executable, args) {
             return false;
         }
     };
-    const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (after.dead) {
         // Nonzero exit after attach → the agent crashed rather than the user
         // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).

package/dist/lib/feed-outcome.d.ts

@@ -89,6 +89,9 @@ export interface SessionOutcomeHint {
     worktreeSlug?: string | null;
     branch?: string | null;
     project?: string | null;
+    host?: string | null;
+    origin?: 'cli' | 'routine' | null;
+    routineName?: string | null;
 }
 /**
  * Overlay session meta onto a block when the block itself is missing ticket/PR/

package/dist/lib/feed-outcome.js

@@ -152,21 +152,22 @@ export function groupBlocksByOutcome(blocks) {
     const groups = [];
     for (const { outcome, blocks: members } of byKey.values()) {
         const mailboxes = new Set(members.map((b) => b.mailboxId));
-        let open = 0;
-        let answered = 0;
-        let parked = 0;
+        const states = new Map();
         for (const b of members) {
-            if (b.parkedAt)
-                parked += 1;
-            else if (b.answer || b.defaultedAt || b.continuedAt)
-                answered += 1;
-            else
-                open += 1;
+            const next = b.parkedAt
+                ? 'parked'
+                : b.answer || b.defaultedAt || b.continuedAt ? 'answered' : 'open';
+            const current = states.get(b.mailboxId);
+            // One agent occupies one state. Its most actionable block wins.
+            if (!current || next === 'open' || (next === 'parked' && current === 'answered')) {
+                states.set(b.mailboxId, next);
+            }
         }
+        const count = (state) => [...states.values()].filter((value) => value === state).length;
         groups.push({
             outcome,
             blocks: members,
-            counts: { agents: mailboxes.size, open, answered, parked },
+            counts: { agents: mailboxes.size, open: count('open'), answered: count('answered'), parked: count('parked') },
         });
     }
     groups.sort((a, b) => {
@@ -222,6 +223,13 @@ export function enrichBlockFromSession(block, hint) {
         next.worktreeSlug = hint.worktreeSlug;
     if (!next.project && hint.project)
         next.project = hint.project;
+    if (hint.host && hint.host !== 'terminal' && next.runtime === 'terminal')
+        next.runtime = hint.host;
+    if (hint.origin === 'routine') {
+        next.origin = 'routine';
+        if (hint.routineName)
+            next.routineName = hint.routineName;
+    }
     return next;
 }
 /**

package/dist/lib/feed.d.ts

@@ -36,6 +36,10 @@ export interface OpenBlock {
     mailboxId: string;
     host: string;
     runtime: string;
+    /** Indexed launch origin, added at read time when the live session is known. */
+    origin?: 'cli' | 'routine';
+    /** Routine definition name when origin is `routine`. */
+    routineName?: string;
     /** Project/repo name this block belongs to (derived from cwd, worktree-aware). */
     project?: string;
     ts: string;

package/dist/lib/hooks/cache.js

@@ -463,6 +463,9 @@ except Exception: pass' 2>/dev/null || true)"
     ;;
 esac
 CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
+# Failure sentinel: touched on bg-refresh failure; mtime drives the backoff window.
+FAIL_FILE="$CACHE_FILE.fail"
+BACKOFF_SEC=60
 
 # Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
 now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
@@ -491,9 +494,38 @@ if [ "$CACHE_STATUS" = miss ]; then
     # Stale-while-revalidate: serve stale immediately, refresh in detached child.
     cat "$CACHE_FILE"
     CACHE_STATUS=stale-prefetch
-    tmp="$CACHE_FILE.new.$$"
-    ( printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null && mv -f "$tmp" "$CACHE_FILE" || rm -f "$tmp" ) >/dev/null 2>&1 &
-    disown 2>/dev/null || true
+    # Fix 2: backoff — skip bg refresh if last attempt failed within BACKOFF_SEC.
+    _in_backoff=0
+    if [ -f "$FAIL_FILE" ]; then
+      _fail_mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$FAIL_FILE" 2>/dev/null || echo 0)
+      _now_s=$(date +%s)
+      _fail_age=$((_now_s - \${_fail_mtime:-0}))
+      [ "$_fail_age" -lt "$BACKOFF_SEC" ] && _in_backoff=1
+    fi
+    if [ "$_in_backoff" -eq 0 ]; then
+      # Fix 1: lockdir — only one background refresh runs at a time.
+      LOCK_DIR="$CACHE_FILE.bg.lck"
+      if mkdir "$LOCK_DIR" 2>/dev/null; then
+        tmp="$CACHE_FILE.new.$$"
+        # Fix 3: background subshell captures and logs its own real exit code.
+        (
+          trap 'rm -rf "$LOCK_DIR"' EXIT
+          _bg_exit=0
+          if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null; then
+            mv -f "$tmp" "$CACHE_FILE" && rm -f "$FAIL_FILE"
+          else
+            _bg_exit=$?
+            rm -f "$tmp"
+            touch "$FAIL_FILE"
+          fi
+          _bg_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          _bg_log_file="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+          printf '{"ts":"%s","event":"hook.cache.refresh","hook":"%s","cache":"bg-refresh","exit":%d}\\n' \\
+            "$_bg_ts" "$HOOK_NAME" "$_bg_exit" >>"$_bg_log_file" 2>/dev/null || true
+        ) >/dev/null 2>&1 &
+        disown 2>/dev/null || true
+      fi
+    fi
   else
     # Synchronous fetch + cache.
     tmp="$CACHE_FILE.new.$$"
@@ -501,6 +533,7 @@ if [ "$CACHE_STATUS" = miss ]; then
       EXIT=0
       cat "$tmp"
       mv -f "$tmp" "$CACHE_FILE"
+      rm -f "$FAIL_FILE"
     else
       EXIT=$?
       rm -f "$tmp"

package/dist/lib/hooks.d.ts

@@ -73,6 +73,14 @@ export declare function hookExists(agentId: AgentId, hookName: string): boolean;
  * Compares both script file and data file (if present).
  */
 export declare function hookContentMatches(agentId: AgentId, hookName: string, sourceEntry: HookEntry): boolean;
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export declare function getHooksDirInHome(agentId: AgentId, home: string): string;
 export declare function listInstalledHooksWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledHook[];
@@ -99,7 +107,7 @@ export interface HookWiringIssue {
      *  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`. */
+    /** The command the harness-native config should reference under `event`. */
     command: string;
 }
 export interface HookWiringReport {
@@ -109,18 +117,22 @@ export interface HookWiringReport {
     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. */
+    /** Native hook config does not exist — nothing declared can be wired. */
     settingsMissing?: boolean;
-    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    /** Native hook config cannot be parsed — 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. */
+     *  native event group/entry should carry them in. */
     unwired: HookWiringIssue[];
+    /** Expected hooks that ARE referenced in native config (expected − unwired).
+     *  Empty whenever wiring cannot be verified (unsupported family, missing or
+     *  unparseable settings). */
+    wired: 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.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, 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

package/dist/lib/hooks.js

@@ -673,6 +673,20 @@ export function hookContentMatches(agentId, hookName, sourceEntry) {
         return false;
     }
 }
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export function getHooksDirInHome(agentId, home) {
+    const config = AGENTS[agentId];
+    const hooksDir = path.isAbsolute(config.hooksDir)
+        ? path.relative(config.configDir, config.hooksDir)
+        : config.hooksDir;
+    return path.join(home, agentConfigDirName(agentId), hooksDir);
+}
 export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), options) {
     const agent = AGENTS[agentId];
     if (!agent.supportsHooks) {
@@ -702,7 +716,7 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
     }
     // User-scoped hooks (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userDir = path.join(home, agentConfigDirName(agentId), agent.hooksDir);
+    const userDir = getHooksDirInHome(agentId, home);
     const userHooks = listHookEntriesFromDir(userDir);
     for (const hook of userHooks) {
         addHook(hook, 'user', agentId);
@@ -740,8 +754,7 @@ export async function installHooks(source, agents, options = {}) {
  * Path to the hooks dir of a specific version home (not the active one).
  */
 export function getVersionHooksDir(agent, version) {
-    const home = getVersionHomePath(agent, version);
-    return path.join(home, agentConfigDirName(agent), AGENTS[agent].hooksDir);
+    return getHooksDirInHome(agent, getVersionHomePath(agent, version));
 }
 /**
  * List hook entries in a specific version home.
@@ -749,20 +762,20 @@ export function getVersionHooksDir(agent, version) {
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
-// ─── wiring inspection (settings.json family: claude, droid) ──────────────────
+// ─── wiring inspection ────────────────────────────────────────────────────────
 /**
- * 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.
+ * Native hook-config families understood by this read-only inspector. Claude,
+ * Droid, and Muse share settings.json; Grok uses the same grouped event shape
+ * in hooks/hooks.json; Kimi stores one hook per [[hooks]] config.toml table.
+ * Other harnesses report unsupported rather than risk a false verdict.
  */
 const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
+const HOOKS_JSON_HOOK_FAMILY = ['grok'];
+const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
 /**
- * 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.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, 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
@@ -774,11 +787,18 @@ const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
  * 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: [] };
+    if (!AGENTS[agent].supportsHooks ||
+        (!SETTINGS_JSON_HOOK_FAMILY.includes(agent) &&
+            !HOOKS_JSON_HOOK_FAMILY.includes(agent) &&
+            !TOML_ARRAY_HOOK_FAMILY.includes(agent))) {
+        return { supported: false, unwired: [], wired: [] };
     }
     const versionHome = getVersionHomePath(agent, version);
-    const settingsPath = path.join(versionHome, agentConfigDirName(agent), 'settings.json');
+    const settingsPath = HOOKS_JSON_HOOK_FAMILY.includes(agent)
+        ? path.join(versionHome, '.grok', 'hooks', 'hooks.json')
+        : TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? path.join(versionHome, '.kimi-code', 'config.toml')
+            : 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
@@ -815,11 +835,17 @@ export function checkVersionHookWiring(agent, version) {
         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 });
+        for (const event of hookDef.events) {
+            if (HOOKS_JSON_HOOK_FAMILY.includes(agent)) {
+                const matcher = GROK_MATCHER_EVENTS.has(event)
+                    ? (GROK_MATCHER_ALIASES[hookDef.matcher || ''] ?? hookDef.matcher ?? '')
+                    : '';
+                expected.push({ name, event, matcher, command });
+            }
+            else {
+                expected.push({ name, event, matcher: hookDef.matcher || '', command });
+            }
+        }
     }
     if (!fs.existsSync(settingsPath)) {
         return {
@@ -828,11 +854,15 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsMissing: expected.length > 0,
             unwired: [],
+            wired: [],
         };
     }
     let config;
     try {
-        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const raw = fs.readFileSync(settingsPath, 'utf-8');
+        config = TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? TOML.parse(raw)
+            : JSON.parse(raw);
     }
     catch {
         return {
@@ -841,6 +871,7 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsUnparseable: true,
             unwired: [],
+            wired: [],
         };
     }
     // Command strings actually referenced, keyed by (event, matcher) — a hook wired
@@ -848,30 +879,49 @@ export function checkVersionHookWiring(agent, version) {
     // 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))
+    if (TOML_ARRAY_HOOK_FAMILY.includes(agent)) {
+        const hooks = Array.isArray(config.hooks) ? config.hooks : [];
+        for (const hook of hooks) {
+            if (typeof hook.event !== 'string' || typeof hook.command !== 'string')
                 continue;
-            const matcher = typeof group.matcher === 'string' ? group.matcher : '';
-            const key = groupKey(event, matcher);
+            const matcher = typeof hook.matcher === 'string' ? hook.matcher : '';
+            const key = groupKey(hook.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);
+            cmds.add(hook.command);
+        }
+    }
+    else {
+        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 };
+    const isWired = (entry) => wiredByGroup.get(groupKey(entry.event, entry.matcher))?.has(entry.command) ?? false;
+    const unwired = expected.filter((entry) => !isWired(entry));
+    const wired = expected.filter(isWired);
+    return { supported: true, settingsPath, expected: expected.length, unwired, wired };
 }
 /**
  * Check if a hook installed in a specific version matches central content.
@@ -1402,7 +1452,7 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
     const localHooksDir = !overrideRoots
-        ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
+        ? getHooksDirInHome(agentId, versionHome)
         : null;
     const resolveScript = (script) => {
         // Subrule-dir hooks declare an already-absolute script path. Use it

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

@@ -16,6 +16,7 @@
  * table or, when `--host`/`--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
+import { type Host } from './types.js';
 import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Per-command remote behaviour. Absence from this map = not host-routable here. */
@@ -60,4 +61,24 @@ export declare function runFleetPassthrough(command: string, allArgs: string[],
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export declare function maybeRunOnHost(command: string, allArgs: string[], opts?: FleetPassthroughOptions): Promise<boolean>;
+/**
+ * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
+ * return the exit code. The single place the SSH hop is built, so every remote
+ * `agents` invocation carries identical env semantics.
+ *
+ * Forwards actor provenance (`AGENTS_ACTOR`/`GIT_` vars) across the hop, merged UNDER
+ * `extraEnv` so a caller-supplied PATH still wins — without this the remote
+ * re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
+ * (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
+ * AGENTS_FLEET_REMOTE marks this as a fleet-dispatched run so the far side can
+ * gate consent-sensitive actions — the browser consent gate
+ * (lib/browser/remote-control.ts) reads it to allow/deny a cross-machine drive.
+ */
+export declare function streamAgentsOnHost(host: Host, forwardedArgs: string[], opts?: {
+    remoteCwd?: string;
+    interactive?: boolean;
+    extraEnv?: Record<string, string>;
+    remoteOs?: string;
+    target?: string;
+}): number;
 export {};