@phnx-labs/agents-cli 1.20.12 → 1.20.13

package/dist/lib/agents.js

@@ -90,41 +90,44 @@ function findInPath(command) {
     return null;
 }
 /** Grok-specific binary resolution.
- * Grok does not live in node_modules/.bin. Its versioned binaries live in
- * ~/.grok/downloads/ with names like `grok-0.1.218-macos-aarch64`.
- * We still use the agents-cli version dir for *config isolation* via GROK_HOME.
+ * Grok does not live in node_modules/.bin. Its versioned binaries live in each
+ * managed version home under `.grok/downloads/`, so detection must not follow
+ * the host ~/.grok config symlink.
  */
 function resolveGrokBinary(version) {
-    const grokDownloads = path.join(HOME, '.grok', 'downloads');
-    if (!fs.existsSync(grokDownloads))
-        return null;
-    const entries = fs.readdirSync(grokDownloads);
-    // Prefer exact version match in filename
     if (version && version !== 'latest') {
-        const match = entries.find((e) => e.includes(version) && e.startsWith('grok-'));
-        if (match)
-            return path.join(grokDownloads, match);
-    }
-    // Fallback: the "current" symlink or the plain `grok-*` without version in name
-    const current = entries.find((e) => e === 'grok' || e.startsWith('grok-') && !e.match(/grok-\d/));
-    if (current)
-        return path.join(grokDownloads, current);
-    // Last resort: newest file by mtime
+        const binaryPath = getBinaryPath('grok', version);
+        if (fs.existsSync(binaryPath))
+            return binaryPath;
+        return null;
+    }
+    const resolvedVersion = resolveVersion('grok', process.cwd());
+    if (resolvedVersion) {
+        const binaryPath = getBinaryPath('grok', resolvedVersion);
+        if (fs.existsSync(binaryPath))
+            return binaryPath;
+    }
+    const grokVersionsDir = path.join(getVersionsDir(), 'grok');
+    if (!fs.existsSync(grokVersionsDir))
+        return null;
     let latest = null;
     let latestMtime = 0;
-    for (const e of entries) {
-        if (!e.startsWith('grok-'))
+    for (const entry of fs.readdirSync(grokVersionsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const binaryPath = getBinaryPath('grok', entry.name);
+        if (!fs.existsSync(binaryPath))
             continue;
         try {
-            const stat = fs.statSync(path.join(grokDownloads, e));
+            const stat = fs.statSync(binaryPath);
             if (stat.mtimeMs > latestMtime) {
                 latestMtime = stat.mtimeMs;
-                latest = e;
+                latest = binaryPath;
             }
         }
         catch { }
     }
-    return latest ? path.join(grokDownloads, latest) : null;
+    return latest;
 }
 function splitCommandLine(command) {
     const args = [];
@@ -482,6 +485,44 @@ export const AGENTS = {
             rulesImports: false,
         },
     },
+    // Factory AI Droid CLI (`droid`) — agentic coding CLI from factory.ai.
+    // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
+    // Binary is NOT in node_modules/.bin — resolved via resolveDroidBinary().
+    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
+    // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
+    // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
+    // switch (no FACTORY_HOME env var exists). Headless: `droid exec "<prompt>"`
+    // with --auto low|medium|high, -o stream-json, -m <model>, -r <effort>.
+    droid: {
+        id: 'droid',
+        name: 'Droid',
+        color: 'yellowBright',
+        cliCommand: 'droid',
+        npmPackage: '',
+        installScript: 'curl -fsSL https://app.factory.ai/cli | sh',
+        configDir: path.join(HOME, '.factory'),
+        commandsDir: path.join(HOME, '.factory', 'commands'),
+        commandsSubdir: 'commands',
+        skillsDir: '', // no skills concept
+        hooksDir: 'hooks',
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        supportsHooks: false,
+        capabilities: {
+            hooks: false,
+            mcp: true,
+            allowlist: false,
+            skills: false,
+            commands: true,
+            plugins: false,
+            subagents: true,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            modes: ['plan', 'edit', 'auto', 'skip'],
+            rulesImports: false,
+        },
+    },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
@@ -1353,6 +1394,9 @@ export function getUserMcpConfigPath(agentId) {
         case 'grok':
             // grok mcp.json — exact field schema verified at first install
             return path.join(agent.configDir, 'mcp.json');
+        case 'droid':
+            // Factory AI Droid stores MCPs in ~/.factory/mcp.json
+            return path.join(agent.configDir, 'mcp.json');
         default:
             // Gemini and others use settings.json
             return path.join(agent.configDir, 'settings.json');
@@ -1387,6 +1431,8 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
             return path.join(home, '.grok', 'config.toml');
+        case 'droid':
+            return path.join(home, '.factory', 'mcp.json');
         default:
             return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
@@ -1423,6 +1469,8 @@ function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
             return path.join(cwd, '.grok', 'config.toml');
+        case 'droid':
+            return path.join(cwd, '.factory', 'mcp.json');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }

package/dist/lib/browser/ipc.d.ts

@@ -16,4 +16,11 @@ export declare class BrowserIPCServer {
     stop(): Promise<void>;
     private handleRequest;
 }
+/**
+ * Decide whether a running daemon is stale and must be restarted. A daemon
+ * is stale when it reports a concrete version that differs from this CLI's.
+ * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
+ * action reliably — don't churn it on that ambiguous signal.
+ */
+export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;

package/dist/lib/browser/ipc.js

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { IS_WINDOWS, ipcEndpoint } from '../platform/index.js';
 import { getHelpersDir } from '../state.js';
-import { startDaemon } from '../daemon.js';
+import { startDaemon, stopDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
 export class BrowserDaemonNotRunningError extends Error {
@@ -453,41 +453,51 @@ export class BrowserIPCServer {
         }
     }
 }
-let versionCheckedThisProcess = false;
+let versionReconciledThisProcess = false;
 /**
- * Check the daemon's version against ours and warn loudly when they
- * differ. Fires at most once per CLI process — successive calls in the
- * same `agents browser ...` invocation are cheap. The whole reason this
- * code exists: a launchd-managed registry daemon kept serving stale code
- * to a dev-build CLI for an entire session and nothing surfaced it.
+ * Decide whether a running daemon is stale and must be restarted. A daemon
+ * is stale when it reports a concrete version that differs from this CLI's.
+ * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
+ * action reliably — don't churn it on that ambiguous signal.
  */
-async function maybeWarnVersionMismatch() {
-    if (versionCheckedThisProcess)
+export function shouldRestartStaleDaemon(daemonVersion, clientVersion) {
+    if (!daemonVersion || daemonVersion === 'unknown')
+        return false;
+    return daemonVersion !== clientVersion;
+}
+/**
+ * Reconcile the running daemon's version with ours. If the daemon is serving
+ * stale code, stop and restart it so this request — and the rest of the
+ * session — runs the current build. Runs at most once per CLI process. The
+ * whole reason this exists: a launchd-managed daemon kept serving stale code
+ * to a dev-build CLI for an entire session and nothing surfaced it (#291).
+ */
+async function reconcileDaemonVersion(socketPath) {
+    if (versionReconciledThisProcess)
         return;
-    versionCheckedThisProcess = true;
+    versionReconciledThisProcess = true;
+    let daemon;
     try {
-        const resp = await sendRawIPCRequest({ action: 'version' });
-        const daemon = resp.version;
-        const client = getCliVersion();
-        if (!daemon || daemon === 'unknown' || daemon === client)
-            return;
-        process.stderr.write(`\nwarning: browser daemon is on ${daemon} but this CLI is on ${client}.\n` +
-            `         Run \`agents daemon restart\` to load the current code.\n\n`);
+        const resp = await sendRawIPCRequest({ action: 'version' }, { autoStartDaemon: false });
+        daemon = resp.version;
     }
     catch {
-        // daemon might be an older build that doesn't speak 'version' — that's
-        // itself a hint, but a noisy one. Stay silent on this path.
+        // Daemon unreachable or too old to speak 'version' — leave it alone.
+        return;
     }
+    const client = getCliVersion();
+    if (!shouldRestartStaleDaemon(daemon, client))
+        return;
+    process.stderr.write(`\nbrowser daemon was on ${daemon}, this CLI is on ${client} — restarting it to load current code.\n\n`);
+    stopDaemon();
+    startDaemon();
+    if (!(await isDaemonReachable())) {
+        await waitForSocket(socketPath, 6000);
+    }
+    await new Promise((r) => setTimeout(r, 300));
 }
 export async function sendIPCRequest(request, opts = {}) {
-    const result = await sendRawIPCRequest(request, opts);
-    // Run the version check after the user's request returns — keeps the
-    // critical path zero-overhead and ensures `start` doesn't get blocked
-    // on a daemon-restart warning that the user hasn't read yet.
-    if (request.action !== 'version') {
-        maybeWarnVersionMismatch().catch(() => { });
-    }
-    return result;
+    return sendRawIPCRequest(request, opts);
 }
 async function sendRawIPCRequest(request, opts = {}) {
     const socketPath = getSocketPath();
@@ -510,6 +520,12 @@ async function sendRawIPCRequest(request, opts = {}) {
         }
         await new Promise((r) => setTimeout(r, 300));
     }
+    // Before serving a real request, make sure the daemon isn't running stale
+    // code. Skips the internal `version` probe (avoids recursion) and callers
+    // that opt out of auto-start. No-ops once reconciled or when versions match.
+    if (request.action !== 'version' && autoStartDaemon) {
+        await reconcileDaemonVersion(socketPath);
+    }
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(endpoint);
         let buffer = '';

package/dist/lib/capabilities.js

@@ -24,7 +24,13 @@ function compareVersions(a, b) {
     return 0;
 }
 function getCapability(agent, cap) {
-    return AGENTS[agent].capabilities[cap];
+    // Guard against unknown agent ids (e.g. a caller passing "claude@2.1.168"
+    // instead of "claude"). Without this, AGENTS[agent] is undefined and the
+    // property access throws an opaque TypeError instead of reporting false.
+    const def = AGENTS[agent];
+    if (!def)
+        return false;
+    return def.capabilities[cap];
 }
 /**
  * True when the agent supports the capability on at least some version.

package/dist/lib/command-skills.d.ts

@@ -7,6 +7,7 @@ export declare function shouldInstallCommandAsSkill(agent: AgentId, version: str
 export declare function commandSkillName(commandName: string): string;
 export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
 export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;
+export declare function readSkillSourceCommandMarker(skillName: string, skillSourceDirs: Array<string | null | undefined>): string | null;
 export declare function installCommandSkillToVersion(agentDir: string, commandName: string, sourcePath: string, skillSourceDirs?: Array<string | null | undefined>): {
     success: boolean;
     skipped?: boolean;

package/dist/lib/command-skills.js

@@ -74,18 +74,34 @@ export function buildCommandSkillContent(commandName, sourcePath) {
         '',
     ].join('\n');
 }
-export function skillSourceExists(skillName, skillSourceDirs) {
-    return skillSourceDirs.some((dir) => {
+function findSkillSourceDir(skillName, skillSourceDirs) {
+    for (const dir of skillSourceDirs) {
         if (!dir)
-            return false;
+            continue;
         const candidate = path.join(dir, skillName);
-        return fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory();
-    });
+        if (fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function skillSourceExists(skillName, skillSourceDirs) {
+    return findSkillSourceDir(skillName, skillSourceDirs) !== null;
+}
+export function readSkillSourceCommandMarker(skillName, skillSourceDirs) {
+    const sourceDir = findSkillSourceDir(skillName, skillSourceDirs);
+    if (!sourceDir)
+        return null;
+    return readSkillCommandMarker(path.join(sourceDir, 'SKILL.md'));
 }
 export function installCommandSkillToVersion(agentDir, commandName, sourcePath, skillSourceDirs = []) {
     const skillName = commandSkillName(commandName);
-    if (skillSourceExists(skillName, skillSourceDirs)) {
-        return { success: false, skipped: true, error: `Skill '${skillName}' already exists` };
+    const existingSkillSource = findSkillSourceDir(skillName, skillSourceDirs);
+    if (existingSkillSource) {
+        const sourceMarker = readSkillCommandMarker(path.join(existingSkillSource, 'SKILL.md'));
+        if (sourceMarker !== commandName) {
+            return { success: true, skipped: true, error: `Skill '${skillName}' already exists` };
+        }
     }
     const skillsDir = safeJoin(agentDir, 'skills');
     const skillDir = safeJoin(skillsDir, skillName);

package/dist/lib/exec.d.ts

@@ -12,6 +12,29 @@ export type ExecMode = Mode;
  * boundary rather than silently picking a wrong code path.
  */
 export declare function normalizeMode(input: string | null | undefined): Mode;
+/**
+ * Detect the headless-plan stall footgun.
+ *
+ * A slash command (e.g. `/code:commit`) run headless under the IMPLICIT default
+ * `plan` mode hangs forever: plan is read-only, so the agent calls ExitPlanMode
+ * to start working, and in a headless run there is no TTY to approve it. The
+ * process just sits there. Callers use this to fail fast with a fix instead.
+ *
+ * Returns the offending command token (e.g. `/code:commit`) when the run should
+ * be blocked, else null. Guards are deliberately narrow:
+ *   - interactive runs / no prompt        -> not headless, never blocks
+ *   - explicit --mode (modeIsDefault false) -> respected; `--mode plan` is a
+ *     legitimate read-only command run and must not be blocked
+ *   - resolved mode is not `plan`          -> only plan stalls at ExitPlanMode
+ *   - prompt is not a slash command        -> natural-language read-only prompts
+ *     ("summarize commits") are a valid default-plan use and must not be blocked
+ */
+export declare function headlessPlanStallCommand(args: {
+    prompt: string | undefined;
+    interactive: boolean | undefined;
+    mode: string;
+    modeIsDefault: boolean;
+}): string | null;
 /**
  * Resolve a requested mode against an agent's capability table.
  *
@@ -45,11 +68,12 @@ export interface ExecOptions {
     version?: string;
     /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
-    /** Force interactive mode even when a prompt is provided. */
+    /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
     interactive?: boolean;
     mode: ExecMode;
     effort: ExecEffort;
     cwd?: string;
+    /** Force headless mode even when no prompt is provided (e.g. piping via stdin). */
     headless?: boolean;
     json?: boolean;
     model?: string;
@@ -59,6 +83,13 @@ export interface ExecOptions {
     verbose?: boolean;
     env?: Record<string, string>;
 }
+/**
+ * Resolve interactive vs headless. Explicit flags are definitive and win over
+ * inference: `--interactive` forces interactive, `--headless` forces headless.
+ * With neither flag, prompt presence decides (prompt -> headless, none -> interactive).
+ * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
+ */
+export declare function resolveInteractive(options: Pick<ExecOptions, 'interactive' | 'headless' | 'prompt'>): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**

package/dist/lib/exec.js

@@ -34,6 +34,36 @@ export function normalizeMode(input) {
         return v;
     throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as a deprecated alias for 'skip').`);
 }
+/**
+ * Detect the headless-plan stall footgun.
+ *
+ * A slash command (e.g. `/code:commit`) run headless under the IMPLICIT default
+ * `plan` mode hangs forever: plan is read-only, so the agent calls ExitPlanMode
+ * to start working, and in a headless run there is no TTY to approve it. The
+ * process just sits there. Callers use this to fail fast with a fix instead.
+ *
+ * Returns the offending command token (e.g. `/code:commit`) when the run should
+ * be blocked, else null. Guards are deliberately narrow:
+ *   - interactive runs / no prompt        -> not headless, never blocks
+ *   - explicit --mode (modeIsDefault false) -> respected; `--mode plan` is a
+ *     legitimate read-only command run and must not be blocked
+ *   - resolved mode is not `plan`          -> only plan stalls at ExitPlanMode
+ *   - prompt is not a slash command        -> natural-language read-only prompts
+ *     ("summarize commits") are a valid default-plan use and must not be blocked
+ */
+export function headlessPlanStallCommand(args) {
+    const { prompt, interactive, mode, modeIsDefault } = args;
+    if (interactive === true || prompt === undefined)
+        return null;
+    if (!modeIsDefault)
+        return null;
+    if (normalizeMode(mode) !== 'plan')
+        return null;
+    const trimmed = prompt.trimStart();
+    if (!trimmed.startsWith('/'))
+        return null;
+    return trimmed.split(/\s+/)[0];
+}
 /**
  * Resolve a requested mode against an agent's capability table.
  *
@@ -71,6 +101,19 @@ export function resolveMode(agent, requested) {
 export function defaultModeFor(agent) {
     return AGENTS[agent].capabilities.modes[0];
 }
+/**
+ * Resolve interactive vs headless. Explicit flags are definitive and win over
+ * inference: `--interactive` forces interactive, `--headless` forces headless.
+ * With neither flag, prompt presence decides (prompt -> headless, none -> interactive).
+ * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
+ */
+export function resolveInteractive(options) {
+    if (options.interactive === true)
+        return true;
+    if (options.headless === true)
+        return false;
+    return options.prompt === undefined;
+}
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -352,16 +395,40 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
+    // Factory AI Droid (`droid exec` for headless, `droid` for TUI). Flags from
+    // docs.factory.ai CLI reference: prompt is positional; --auto low|medium|high
+    // escalates autonomy (default is read-only); --skip-permissions-unsafe drops
+    // all guardrails; -o stream-json streams JSONL events; -m selects the model.
+    // The `exec` subcommand is dropped for interactive runs (see buildExecCommand).
+    droid: {
+        base: ['droid', 'exec'],
+        promptFlag: 'positional',
+        modeFlags: {
+            plan: [], // droid's default exec mode is read-only
+            edit: ['--auto', 'low'], // create/edit files, non-destructive
+            auto: ['--auto', 'high'], // full autonomy
+            skip: ['--skip-permissions-unsafe'],
+        },
+        jsonFlags: ['-o', 'stream-json'],
+        modelFlag: '-m',
+    },
 };
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
-    const interactive = options.interactive === true || options.prompt === undefined;
-    // For Codex, 'exec' is the headless subcommand -- drop it for interactive mode
-    // so we run 'codex' (TUI) instead of 'codex exec' (one-shot)
-    if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
-        cmd.splice(1, 1);
+    const interactive = resolveInteractive(options);
+    // For Codex and Droid, 'exec' is the headless subcommand; for OpenCode, 'run'
+    // is. Drop it for interactive mode so we launch the TUI (`codex` / `droid` /
+    // `opencode`, each agent's default command) instead of the one-shot headless
+    // subcommand ('codex exec' / 'droid exec' / 'opencode run').
+    if (interactive) {
+        if ((options.agent === 'codex' || options.agent === 'droid') && cmd[1] === 'exec') {
+            cmd.splice(1, 1);
+        }
+        else if (options.agent === 'opencode' && cmd[1] === 'run') {
+            cmd.splice(1, 1);
+        }
     }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
@@ -455,7 +522,12 @@ export function buildExecCommand(options) {
     // so the CLI launches its TUI. When --interactive is passed alongside a prompt
     // we still forward the prompt so the agent receives it as the first message.
     if (options.prompt !== undefined) {
-        if (template.promptFlag === 'positional') {
+        if (interactive && options.agent === 'opencode') {
+            // The OpenCode TUI takes an initial prompt via --prompt; a bare positional
+            // on the default command is parsed as a project path, not a message.
+            cmd.push('--prompt', options.prompt);
+        }
+        else if (template.promptFlag === 'positional') {
             cmd.push(options.prompt);
         }
         else {
@@ -526,7 +598,7 @@ async function spawnAgent(options) {
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
-    const interactive = options.interactive === true || options.prompt === undefined;
+    const interactive = resolveInteractive(options);
     maybeRotate();
     const timer = createTimer('agent.run', {
         agent: options.agent,

package/dist/lib/hooks.js

@@ -8,6 +8,7 @@
  * and syncing them across version switches.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
@@ -53,9 +54,41 @@ function getManagedHookPrefixes() {
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
     ];
 }
+/**
+ * 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.
+ */
+function toPortableCommand(absPath) {
+    const home = os.homedir();
+    const normalized = absPath.split(path.sep).join('/');
+    const homeNorm = home.split(path.sep).join('/');
+    if (normalized.startsWith(homeNorm + '/')) {
+        return '~/' + normalized.slice(homeNorm.length + 1);
+    }
+    return normalized;
+}
 function isManagedHookCommand(command, prefixes) {
+    // Expand ~/... so tilde-form portable commands can be matched against
+    // absolute managed prefixes.
+    let expanded = command;
+    if (command.startsWith('~/')) {
+        expanded = path.join(os.homedir(), command.slice(2));
+    }
+    // Resolve the directory through symlinks/junctions (e.g. ~/.claude on
+    // Windows is a junction to the versioned home dir where prefixes live).
+    // Resolve the dir, not the full path — the file may not exist after removal.
+    const dir = path.dirname(expanded);
+    let resolvedDir = dir;
+    try {
+        resolvedDir = fs.realpathSync(dir);
+    }
+    catch { /* absent or broken link */ }
+    const resolved = path.join(resolvedDir, path.basename(expanded));
     for (const prefix of prefixes) {
-        if (command.startsWith(prefix))
+        if (resolved.startsWith(prefix))
             return true;
     }
     return false;
@@ -80,9 +113,9 @@ function resolveHookCommand(name, hookDef, resolveScript) {
         // No caching opted in — make sure a previously generated shim from an
         // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
         removeHookShim(name);
-        return scriptPath;
+        return toPortableCommand(scriptPath);
     }
-    return generateHookShim({ name, scriptPath, cache });
+    return toPortableCommand(generateHookShim({ name, scriptPath, cache }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file
@@ -1253,8 +1286,7 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
         const cmd = typeof h.command === 'string' ? h.command : '';
         if (!cmd)
             return true;
-        const isManaged = managedPrefixes.some((p) => cmd.startsWith(p));
-        if (!isManaged)
+        if (!isManagedHookCommand(cmd, managedPrefixes))
             return true;
         return currentManifestPaths.has(cmd);
     });

package/dist/lib/mcp.js

@@ -338,6 +338,35 @@ function installMcpToKimiConfig(server, versionHome) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+/**
+ * Install MCP server to Factory AI Droid config (`~/.factory/mcp.json`).
+ * Droid uses the standard `mcpServers` JSON shape, same as Kimi/Claude.
+ */
+function installMcpToFactoryConfig(server, versionHome) {
+    const configPath = path.join(versionHome, '.factory', 'mcp.json');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        config.mcpServers = {};
+    }
+    const mcpServers = config.mcpServers;
+    if (server.config.transport === 'stdio') {
+        mcpServers[server.name] = {
+            command: server.config.command,
+            args: server.config.args || [],
+            env: server.config.env || {},
+        };
+    }
+    else {
+        mcpServers[server.name] = {
+            url: server.config.url,
+        };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
 function installMcpToOpenCodeConfig(server, versionHome) {
     const configPath = path.join(versionHome, '.opencode', 'opencode.jsonc');
     let config = {};
@@ -424,6 +453,10 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 installMcpToKimiConfig(server, versionHome);
                 applied.push(server.name);
             }
+            else if (agentId === 'droid') {
+                installMcpToFactoryConfig(server, versionHome);
+                applied.push(server.name);
+            }
         }
         catch (err) {
             const message = err.message;

package/dist/lib/models.js

@@ -772,5 +772,10 @@ export function buildReasoningFlags(agent, level) {
         const codexLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
         return ['-c', `model_reasoning_effort=${codexLevel}`];
     }
+    if (agent === 'droid') {
+        // Droid: `-r off|none|low|medium|high`. xhigh/max clamp to high.
+        const droidLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
+        return ['-r', droidLevel];
+    }
     return [];
 }

package/dist/lib/picker.d.ts

@@ -22,5 +22,7 @@ export interface PickerConfig<T> {
 export interface PickedItem<T> {
     item: T;
 }
+/** Clip a picker preview so the full prompt can fit in the terminal viewport. */
+export declare function limitPreviewHeight(preview: string, maxRows: number, width: number): string;
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;