@phnx-labs/agents-cli 1.20.3 → 1.20.5

package/dist/lib/commands.d.ts

@@ -13,7 +13,28 @@ export type CommandScope = 'user' | 'project';
 export interface CommandMetadata {
     name: string;
     description: string;
+    /** When set, sync only to these agents (aliases resolved at parse time). */
+    agents?: AgentId[];
+    /** Minimum agent CLI version (inclusive) for this command. */
+    since?: string;
+    /** Exclusive upper bound on agent CLI version for this command. */
+    until?: string;
 }
+export type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
+export type CommandApplyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CommandApplyFailReason;
+    need?: string;
+};
+/**
+ * Whether a slash command should sync to the given agent@version. Checks
+ * frontmatter `agents` / `since` / `until` after the agent-level commands
+ * (or commands-as-skills) capability gate.
+ */
+export declare function commandAppliesTo(agent: AgentId, version: string, metadata: Pick<CommandMetadata, 'agents' | 'since' | 'until'> | null | undefined): CommandApplyResult;
+export declare function explainCommandSkip(agent: AgentId, version: string, commandName: string, result: CommandApplyResult): string;
 /** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
@@ -35,6 +56,8 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
+/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
+export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
 /** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
 /** Find the source path for a command in a repository. */
@@ -59,6 +82,8 @@ export interface VersionCommandDiff {
     toAdd: string[];
     toUpdate: string[];
     matched: string[];
+    /** Installed but excluded by frontmatter agents/since/until — safe to remove. */
+    toRemove: string[];
     orphans: string[];
 }
 /**
@@ -72,6 +97,8 @@ export declare function diffVersionCommands(agent: AgentId, version: string): Ve
 export declare function installCommandToVersion(agent: AgentId, version: string, commandName: string, method?: 'symlink' | 'copy'): {
     success: boolean;
     error?: string;
+    skipped?: boolean;
+    skipReason?: string;
 };
 /**
  * Remove a single command from a specific version home.
@@ -112,7 +139,7 @@ export declare function installCommandCentrally(sourcePath: string, commandName:
     warnings?: string[];
 };
 /**
- * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralCommands(): string[];

package/dist/lib/commands.js

@@ -9,13 +9,78 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
+import { AGENTS, ensureCommandsDir, agentConfigDirName, resolveAgentName } from './agents.js';
+import { capableAgents, isCapable, supports } from './capabilities.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
-/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-function parseCommandMetadata(filePath) {
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
+    const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0;
+        const bVal = bParts[i] || 0;
+        if (aVal !== bVal)
+            return aVal - bVal;
+    }
+    return 0;
+}
+function parseAgentsField(raw) {
+    if (raw == null)
+        return undefined;
+    const tokens = Array.isArray(raw)
+        ? raw
+        : typeof raw === 'string'
+            ? raw.split(/[,\s]+/)
+            : [];
+    const out = [];
+    for (const token of tokens) {
+        const id = resolveAgentName(String(token).trim());
+        if (id && !out.includes(id))
+            out.push(id);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Whether a slash command should sync to the given agent@version. Checks
+ * frontmatter `agents` / `since` / `until` after the agent-level commands
+ * (or commands-as-skills) capability gate.
+ */
+export function commandAppliesTo(agent, version, metadata) {
+    if (!supports(agent, 'commands', version).ok && !shouldInstallCommandAsSkill(agent, version)) {
+        return { ok: false, reason: 'unsupported' };
+    }
+    if (metadata?.agents?.length && !metadata.agents.includes(agent)) {
+        return { ok: false, reason: 'agent_excluded' };
+    }
+    if (metadata?.since && compareVersions(version, metadata.since) < 0) {
+        return { ok: false, reason: 'too_old', need: `>= ${metadata.since}` };
+    }
+    if (metadata?.until && compareVersions(version, metadata.until) >= 0) {
+        return { ok: false, reason: 'too_new', need: `< ${metadata.until}` };
+    }
+    return { ok: true };
+}
+export function explainCommandSkip(agent, version, commandName, result) {
+    if (result.ok)
+        return '';
+    const tag = `${agent}@${version}`;
+    switch (result.reason) {
+        case 'unsupported':
+            return `${tag}: /${commandName} not supported for this agent version`;
+        case 'agent_excluded':
+            return `${tag}: /${commandName} excluded by command frontmatter agents list`;
+        case 'too_old':
+            return `${tag}: /${commandName} requires ${result.need}`;
+        case 'too_new':
+            return `${tag}: /${commandName} requires ${result.need}`;
+        default:
+            return `${tag}: /${commandName} skipped`;
+    }
+}
+/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
+export function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
@@ -31,6 +96,9 @@ function parseCommandMetadata(filePath) {
                 return {
                     name: parsed.name || '',
                     description: parsed.description || '',
+                    agents: parseAgentsField(parsed.agents),
+                    since: typeof parsed.since === 'string' ? parsed.since : undefined,
+                    until: typeof parsed.until === 'string' ? parsed.until : undefined,
                 };
             }
         }
@@ -126,10 +194,22 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
             warnings: validation.warnings,
         };
     }
+    const pinnedVersion = resolveVersion(agentId, process.cwd());
+    if (pinnedVersion) {
+        const gate = commandAppliesTo(agentId, pinnedVersion, metadata);
+        if (!gate.ok) {
+            return {
+                path: '',
+                method: 'copy',
+                error: explainCommandSkip(agentId, pinnedVersion, commandName, gate),
+                warnings: validation.warnings,
+            };
+        }
+    }
     const agent = AGENTS[agentId];
     ensureCommandsDir(agentId);
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     fs.mkdirSync(commandsDir, { recursive: true });
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
@@ -157,14 +237,14 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
  */
 export function getVersionCommandsDir(agent, version) {
     const home = getVersionHomePath(agent, version);
-    return path.join(home, `.${agent}`, AGENTS[agent].commandsSubdir);
+    return path.join(home, agentConfigDirName(agent), AGENTS[agent].commandsSubdir);
 }
 /**
  * List command names (without extension) installed in a specific version home.
  */
 export function listCommandsInVersionHome(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return listCommandSkillsInVersion(agentDir);
     }
@@ -186,7 +266,7 @@ function versionCommandMatches(agent, version, commandName) {
     if (!fs.existsSync(sourcePath))
         return false;
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return commandSkillMatches(agentDir, commandName, sourcePath);
     }
@@ -217,8 +297,13 @@ export function diffVersionCommands(agent, version) {
     const toAdd = [];
     const toUpdate = [];
     const matched = [];
+    const toRemove = [];
     const orphans = [];
     for (const name of central) {
+        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+        const metadata = parseCommandMetadata(sourcePath);
+        if (!commandAppliesTo(agent, version, metadata).ok)
+            continue;
         if (!installed.has(name)) {
             toAdd.push(name);
         }
@@ -230,10 +315,25 @@ export function diffVersionCommands(agent, version) {
         }
     }
     for (const name of installed) {
-        if (!central.has(name))
+        if (!central.has(name)) {
             orphans.push(name);
+            continue;
+        }
+        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+        const metadata = parseCommandMetadata(sourcePath);
+        if (!commandAppliesTo(agent, version, metadata).ok) {
+            toRemove.push(name);
+        }
     }
-    return { agent, version, toAdd: toAdd.sort(), toUpdate: toUpdate.sort(), matched, orphans: orphans.sort() };
+    return {
+        agent,
+        version,
+        toAdd: toAdd.sort(),
+        toUpdate: toUpdate.sort(),
+        matched,
+        toRemove: toRemove.sort(),
+        orphans: orphans.sort(),
+    };
 }
 /**
  * Install a single command from central into a specific version home.
@@ -244,8 +344,13 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
     if (!fs.existsSync(sourcePath)) {
         return { success: false, error: `Command '${commandName}' not found in central` };
     }
+    const metadata = parseCommandMetadata(sourcePath);
+    const gate = commandAppliesTo(agent, version, metadata);
+    if (!gate.ok) {
+        return { success: true, skipped: true, skipReason: explainCommandSkip(agent, version, commandName, gate) };
+    }
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return installCommandSkillToVersion(agentDir, commandName, sourcePath, [
             getSkillsDir(),
@@ -283,7 +388,7 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
  */
 export function removeCommandFromVersion(agent, version, commandName) {
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return removeCommandSkillFromVersion(agentDir, commandName);
     }
@@ -309,9 +414,9 @@ export function removeCommandFromVersion(agent, version, commandName) {
  */
 export function iterCommandsCapableVersions(filter) {
     const pairs = [];
-    const agents = filter?.agent ? [filter.agent] : COMMANDS_CAPABLE_AGENTS;
+    const agents = filter?.agent ? [filter.agent] : capableAgents('commands');
     for (const agent of agents) {
-        if (!COMMANDS_CAPABLE_AGENTS.includes(agent))
+        if (!isCapable(agent, 'commands'))
             continue;
         const versions = listInstalledVersions(agent);
         for (const version of versions) {
@@ -326,7 +431,7 @@ export function iterCommandsCapableVersions(filter) {
 export function uninstallCommand(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
     if (fs.existsSync(targetPath)) {
@@ -339,7 +444,7 @@ export function uninstallCommand(agentId, commandName) {
 function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     if (!fs.existsSync(commandsDir)) {
         return [];
     }
@@ -355,7 +460,7 @@ function listInstalledCommands(agentId) {
 function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
     return fs.existsSync(targetPath);
@@ -373,7 +478,7 @@ function normalizeContent(content) {
 function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const installedPath = path.join(commandsDir, `${commandName}${ext}`);
     if (!fs.existsSync(installedPath) || !fs.existsSync(sourcePath)) {
@@ -455,7 +560,7 @@ export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), opt
     }
     // User-scoped commands (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userCommandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const userCommandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const userExts = [ext];
     const userCommands = listCommandsFromDir(userCommandsDir, userExts);
     for (const name of userCommands) {
@@ -509,7 +614,7 @@ export function installCommandCentrally(sourcePath, commandName) {
     }
 }
 /**
- * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralCommands() {

package/dist/lib/doctor-diff.js

@@ -21,7 +21,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS } from './agents.js';
+import { AGENTS, agentConfigDirName } from './agents.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
 import { markdownToToml } from './convert.js';
@@ -352,7 +352,7 @@ function expectedRuleContent(agent, name, sourcePath) {
 function diffRules(agent, version, cwd) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
-    const configDir = path.join(versionHome, `.${agent}`);
+    const configDir = path.join(versionHome, agentConfigDirName(agent));
     const sourcesByName = listRulesNames(cwd);
     // Files actually present in the version home.
     const homeFiles = new Set();

package/dist/lib/exec.d.ts

@@ -23,6 +23,20 @@ export declare function normalizeMode(input: string | null | undefined): Mode;
  * - `plan` on an agent without plan support throws the same way.
  */
 export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
+/**
+ * The mode an agent should run in when the caller has no preference.
+ *
+ * Returns the first entry in the agent's `capabilities.modes` table — the
+ * declaration order is the source of truth for "the safest mode this agent
+ * supports." Agents that include `plan` list it first; agents like
+ * antigravity that have no read-only mode list `edit` first.
+ *
+ * Use this when the user did not pass `--mode` explicitly. When the user
+ * *did* pass `--mode plan` and the agent doesn't support it, call
+ * `resolveMode` instead so the user sees a loud error rather than a silent
+ * elevation from read-only to writable.
+ */
+export declare function defaultModeFor(agent: AgentId): Mode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */

package/dist/lib/exec.js

@@ -6,6 +6,7 @@
  */
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
+import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
@@ -14,6 +15,7 @@ import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versio
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
+import { getShimsDir } from './state.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -53,6 +55,22 @@ export function resolveMode(agent, requested) {
     }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
 }
+/**
+ * The mode an agent should run in when the caller has no preference.
+ *
+ * Returns the first entry in the agent's `capabilities.modes` table — the
+ * declaration order is the source of truth for "the safest mode this agent
+ * supports." Agents that include `plan` list it first; agents like
+ * antigravity that have no read-only mode list `edit` first.
+ *
+ * Use this when the user did not pass `--mode` explicitly. When the user
+ * *did* pass `--mode plan` and the agent doesn't support it, call
+ * `resolveMode` instead so the user sees a loud error rather than a silent
+ * elevation from read-only to writable.
+ */
+export function defaultModeFor(agent) {
+    return AGENTS[agent].capabilities.modes[0];
+}
 /** 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. */
@@ -167,9 +185,9 @@ export const AGENT_COMMANDS = {
             // "workspace-write but no auto-approval" — closer to plan-as-restraint.
             // True read-only requires --sandbox read-only which we haven't wired.
             plan: ['--sandbox', 'workspace-write'],
-            edit: ['--sandbox', 'workspace-write', '--full-auto'],
-            // skip drops the sandbox entirely; --full-auto then approves anything.
-            skip: ['--full-auto'],
+            edit: ['--sandbox', 'workspace-write', '--dangerously-bypass-approvals-and-sandbox'],
+            // skip drops the sandbox entirely; --dangerously-bypass-approvals-and-sandbox then approves anything.
+            skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
         jsonFlags: ['--json'],
         modelFlag: '--model',
@@ -303,6 +321,17 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',
     },
+    kimi: {
+        base: ['kimi-code'],
+        promptFlag: '-p',
+        modeFlags: {
+            plan: [],
+            edit: [],
+            skip: [],
+        },
+        jsonFlags: [],
+        modelFlag: '--model',
+    },
 };
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
@@ -314,9 +343,14 @@ export function buildExecCommand(options) {
     if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
         cmd.splice(1, 1);
     }
-    // Use versioned alias if a specific version was requested (e.g., claude@2.1.98)
+    // 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 —
+    // on Linux installs where the shims dir isn't on PATH, spawning the bare
+    // versioned name fails with ENOENT even though `agents view` shows the agent.
     if (options.version && cmd.length > 0) {
-        cmd[0] = `${cmd[0]}@${options.version}`;
+        const versionedName = `${cmd[0]}@${options.version}`;
+        const absPath = path.join(getShimsDir(), versionedName);
+        cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
     // For codex, -c must come before 'exec' subcommand, so we insert at position 1

package/dist/lib/fuzzy.d.ts

@@ -4,11 +4,20 @@
  */
 /** Levenshtein edit distance between two strings. */
 export declare function levenshtein(a: string, b: string): number;
+/**
+ * Damerau-Levenshtein (optimal string alignment) distance.
+ * Counts a transposition of two adjacent characters as a single edit,
+ * so `cladue` -> `claude` is distance 1, matching the user's notion of
+ * "one misspelling."
+ */
+export declare function damerauLevenshtein(a: string, b: string): number;
 export interface FuzzyOptions {
     /** Absolute max edit distance allowed. */
     maxDistance?: number;
     /** Max ratio of distance to input length. If set, effective threshold = min(maxDistance, floor(len * maxRatio)). */
     maxRatio?: number;
+    /** Use Damerau-Levenshtein (transposition = 1 edit) instead of plain Levenshtein. */
+    damerau?: boolean;
 }
 /**
  * Fuzzy match an input string against a list of candidates.
@@ -20,9 +29,10 @@ export declare function fuzzyMatch<T extends string>(input: string, candidates:
  * Based on pairwise distance analysis of candidate pools.
  */
 export declare const FUZZY_PRESETS: {
-    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
+    /** Agents: 1 mistype (insertion/deletion/substitution/transposition). Damerau so `cladue`->`claude` is 1. */
     readonly agents: {
-        readonly maxDistance: 2;
+        readonly maxDistance: 1;
+        readonly damerau: true;
     };
     /** Modes: plan/edit/full all at dist=4, lenient */
     readonly modes: {

package/dist/lib/fuzzy.js

@@ -19,12 +19,36 @@ export function levenshtein(a, b) {
     }
     return dp[m][n];
 }
+/**
+ * Damerau-Levenshtein (optimal string alignment) distance.
+ * Counts a transposition of two adjacent characters as a single edit,
+ * so `cladue` -> `claude` is distance 1, matching the user's notion of
+ * "one misspelling."
+ */
+export function damerauLevenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[m][n];
+}
 /**
  * Fuzzy match an input string against a list of candidates.
  * Returns the single best match within tolerance, or null if no match or ambiguous.
  */
 export function fuzzyMatch(input, candidates, options = {}) {
-    const { maxDistance = 2, maxRatio } = options;
+    const { maxDistance = 2, maxRatio, damerau = false } = options;
     const lower = input.toLowerCase();
     // Reject inputs that are too short - they're too ambiguous
     if (lower.length < 3)
@@ -33,10 +57,11 @@ export function fuzzyMatch(input, candidates, options = {}) {
     const threshold = maxRatio
         ? Math.min(maxDistance, Math.floor(lower.length * maxRatio))
         : maxDistance;
+    const distance = damerau ? damerauLevenshtein : levenshtein;
     // Find all candidates within threshold (excluding exact matches)
     const matches = [];
     for (const candidate of candidates) {
-        const dist = levenshtein(lower, candidate.toLowerCase());
+        const dist = distance(lower, candidate.toLowerCase());
         if (dist > 0 && dist <= threshold) {
             matches.push({ candidate, dist });
         }
@@ -55,8 +80,8 @@ export function fuzzyMatch(input, candidates, options = {}) {
  * Based on pairwise distance analysis of candidate pools.
  */
 export const FUZZY_PRESETS = {
-    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
-    agents: { maxDistance: 2 },
+    /** Agents: 1 mistype (insertion/deletion/substitution/transposition). Damerau so `cladue`->`claude` is 1. */
+    agents: { maxDistance: 1, damerau: true },
     /** Modes: plan/edit/full all at dist=4, lenient */
     modes: { maxDistance: 2 },
     /** Efforts: high/xhigh at dist=1, must be strict */

package/dist/lib/git.js

@@ -32,7 +32,14 @@ function installGithooksSymlinks(repoDir) {
         if (fs.lstatSync(dest, { throwIfNoEntry: false })) {
             fs.rmSync(dest);
         }
-        fs.symlinkSync(target, dest);
+        try {
+            fs.symlinkSync(target, dest);
+        }
+        catch (err) {
+            // Windows requires Developer Mode or elevated privileges for symlinks; skip gracefully.
+            if (err.code !== 'EPERM')
+                throw err;
+        }
     }
 }
 /**

package/dist/lib/hooks.d.ts

@@ -110,12 +110,12 @@ export declare function installHooksCentrally(source: string): Promise<{
     errors: string[];
 }>;
 /**
- * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents/.system/hooks/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse hook manifests. Reads system hooks from ~/.agents-system/hooks.yaml
+ * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
  * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
  * A user entry with `enabled: false` disables the system-shipped hook of