@phnx-labs/agents-cli 1.20.57 → 1.20.58

package/dist/lib/daemon.js

@@ -674,8 +674,7 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
     fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
 }
 /** Generate a macOS launchd plist for auto-starting the daemon. */
-export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken()) {
-    const agentsBin = getAgentsBinPath();
+export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const logPath = getLogPath();
     const oauthEntry = oauthToken
@@ -704,7 +703,7 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin</string>${oauthEntry}
+    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>${oauthEntry}
   </dict>
 </dict>
 </plist>`;
@@ -714,8 +713,7 @@ function systemdExecArg(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
-export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken()) {
-    const agentsBin = getAgentsBinPath();
+export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
     const oauthLine = oauthToken
@@ -730,7 +728,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=10
-Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin${oauthLine}
+Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin${oauthLine}
 
 [Install]
 WantedBy=default.target`;
@@ -802,7 +800,7 @@ function readServiceManagerPid(platform = os.platform()) {
     return null;
 }
 /** Start the daemon via launchd, systemd, or as a detached process. */
-export function startDaemon() {
+export function startDaemon(agentsBin) {
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };
@@ -814,7 +812,7 @@ export function startDaemon() {
         return { pid, method: 'already-starting' };
     }
     try {
-        return startDaemonLocked();
+        return startDaemonLocked(agentsBin ?? getAgentsBinPath());
     }
     finally {
         releaseLock();
@@ -838,7 +836,7 @@ export function ensureDaemonStarted() {
         return null;
     }
 }
-function startDaemonLocked() {
+function startDaemonLocked(agentsBin) {
     const platform = os.platform();
     if (platform === 'darwin') {
         try {
@@ -849,7 +847,7 @@ function startDaemonLocked() {
             }
             // The plist may embed a long-lived OAuth token in EnvironmentVariables;
             // create owner-only atomically (no world-readable window before chmod).
-            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist());
+            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist(undefined, agentsBin));
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -867,7 +865,7 @@ function startDaemonLocked() {
         catch {
             // load threw — fall through to detached spawn
         }
-        return startDetached();
+        return startDetached({ agentsBin });
     }
     if (platform === 'linux') {
         try {
@@ -877,7 +875,7 @@ function startDaemonLocked() {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
             // May embed a long-lived OAuth token in an Environment= line; owner-only.
-            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit());
+            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit(undefined, agentsBin));
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
@@ -890,9 +888,9 @@ function startDaemonLocked() {
         catch {
             // start threw — fall through to detached spawn
         }
-        return startDetached();
+        return startDetached({ agentsBin });
     }
-    return startDetached();
+    return startDetached({ agentsBin });
 }
 /**
  * Environment for the detached daemon fallback. The launchd/systemd paths
@@ -925,18 +923,68 @@ export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readD
  * Going through `process.execPath` means a real PE/binary is spawned with
  * `detached: true` and no console, so nothing signals the daemon after launch.
  *
- * When the entry isn't a JS file (e.g. a native launcher resolved via
- * `which agents`), run it directly — it owns its own runtime resolution.
+ * When the entry isn't a Node script (e.g. a native compiled launcher), run it
+ * directly — it owns its own runtime resolution.
  */
 export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     const { warnings } = validateDaemonBinary(agentsBin);
     for (const w of warnings)
         process.stderr.write(`[agents] ${w}\n`);
-    if (/\.(c|m)?js$/.test(agentsBin)) {
+    if (isNodeScriptEntry(agentsBin)) {
         return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
     }
     return { command: agentsBin, args: ['daemon', '_run'] };
 }
+/**
+ * A daemon entry must be launched through the Node runtime when it is a Node
+ * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose
+ * shebang names `node`. Package installs link `bin/agents` to a `dist/index.js`
+ * (a symlink) or drop an extension-less `#!/usr/bin/env node` shim, so an
+ * extension check alone misses them and they get run directly. Executing such an
+ * entry then relies on the shebang resolving `node` off the daemon's PATH — and
+ * when that PATH points at a pruned nvm version (or an ancient system node), the
+ * daemon crash-loops at import (`node:util` has no `styleText` on Node 18). A
+ * real compiled binary (Mach-O/ELF/PE) has no `#!node` shebang, so it takes the
+ * direct branch and owns its own runtime resolution.
+ */
+function isNodeScriptEntry(agentsBin) {
+    let resolved = agentsBin;
+    try {
+        resolved = fs.realpathSync(agentsBin);
+    }
+    catch {
+        // Unresolvable (e.g. a template path that does not exist on this box): fall
+        // back to the extension check on the path as given.
+    }
+    if (/\.(c|m)?js$/.test(resolved))
+        return true;
+    try {
+        const fd = fs.openSync(resolved, 'r');
+        try {
+            const buf = Buffer.alloc(128);
+            const n = fs.readSync(fd, buf, 0, 128, 0);
+            const firstLine = buf.toString('utf-8', 0, n).split('\n', 1)[0];
+            return firstLine.startsWith('#!') && /\bnode\b/.test(firstLine);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The directory of the Node runtime that generated this service manifest, kept
+ * first on the daemon's PATH. Both the shim's shebang and any child routine
+ * process then resolve the exact Node that installed the service — never an
+ * ancient system node or a pruned nvm version. Replaces the old hardcoded
+ * `~/.nvm/versions/node/v24.0.0/bin`, which went stale the moment that patch
+ * release was upgraded away and bricked the daemon fleet-wide.
+ */
+function daemonNodeBinDir() {
+    return path.dirname(process.execPath);
+}
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.
  *

package/dist/lib/git.d.ts

@@ -107,6 +107,15 @@ export declare function isGitRepo(dir: string): boolean;
  * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
  */
 export declare function getGitRoot(dir: string): Promise<string>;
+/**
+ * Return the absolute path to the **main** working-tree root for `dir`.
+ *
+ * Unlike {@link getGitRoot}, this stays correct when `dir` is inside a *linked*
+ * worktree: `--show-toplevel` there returns the worktree's own path, but the
+ * common git dir (`--git-common-dir`) always points at the primary repo's
+ * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ */
+export declare function getMainRepoRoot(dir: string): Promise<string>;
 /**
  * Initialize a git repo in an existing directory.
  */

package/dist/lib/git.js

@@ -427,6 +427,18 @@ export async function getGitRoot(dir) {
     const root = await simpleGit(dir).revparse(['--show-toplevel']);
     return root.trim();
 }
+/**
+ * Return the absolute path to the **main** working-tree root for `dir`.
+ *
+ * Unlike {@link getGitRoot}, this stays correct when `dir` is inside a *linked*
+ * worktree: `--show-toplevel` there returns the worktree's own path, but the
+ * common git dir (`--git-common-dir`) always points at the primary repo's
+ * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ */
+export async function getMainRepoRoot(dir) {
+    const common = await simpleGit(dir).raw(['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    return path.dirname(common.trim());
+}
 /**
  * Initialize a git repo in an existing directory.
  */

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

@@ -10,11 +10,32 @@
  */
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * 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.
+ */
+export declare function remoteCdPrefix(remoteCwd?: string): string;
+/**
+ * Launch a detached login-shell command in its own Unix session/process group.
+ *
+ * Node is already a hard requirement for a host that can run `agents`. Its
+ * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
+ * a non-interactive shell where the background wrapper can remain in the SSH
+ * shell's process group. Returning the group leader PID makes `kill(-pid)` a
+ * reliable whole-tree operation for both normal stops and rollback cleanup.
+ */
+export declare function buildDetachedLaunchCommand(inner: string): string;
 export interface DispatchResult {
     task: HostTask;
     /** Exit code when followed; undefined when detached (--no-follow). */
     exitCode?: number;
 }
+/** Terminate a detached dispatch that its caller could not persist locally. */
+export declare function terminateDispatchedTask(task: HostTask): void;
 export interface DispatchOptions {
     agent: string;
     prompt: string;

package/dist/lib/hosts/dispatch.js

@@ -20,6 +20,77 @@ import { followHostTask } from './progress.js';
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
+/**
+ * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
+ * remainder (no leading slash), else null. Callers that want a local-home
+ * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
+ * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
+ * `--remote-cwd` is left literal and so is never re-rooted here.
+ */
+function homeRemainder(p) {
+    if (p === '~' || p === '$HOME')
+        return '';
+    if (p.startsWith('~/'))
+        return p.slice(2);
+    if (p.startsWith('$HOME/'))
+        return p.slice(6);
+    return null;
+}
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * 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.
+ */
+export function remoteCdPrefix(remoteCwd) {
+    if (!remoteCwd)
+        return '';
+    const rest = homeRemainder(remoteCwd);
+    if (rest === '')
+        return 'cd "$HOME" && ';
+    if (rest !== null)
+        return `cd "$HOME"/${shellQuote(rest)} && `;
+    return `cd ${shellQuote(remoteCwd)} && `;
+}
+/**
+ * Launch a detached login-shell command in its own Unix session/process group.
+ *
+ * Node is already a hard requirement for a host that can run `agents`. Its
+ * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
+ * a non-interactive shell where the background wrapper can remain in the SSH
+ * shell's process group. Returning the group leader PID makes `kill(-pid)` a
+ * reliable whole-tree operation for both normal stops and rollback cleanup.
+ */
+export function buildDetachedLaunchCommand(inner) {
+    const nodeScript = [
+        "const { spawn } = require('node:child_process');",
+        `const child = spawn('/bin/bash', ['-lc', ${JSON.stringify(inner)}], { detached: true, stdio: 'ignore' });`,
+        "child.once('error', error => { console.error(error.message); process.exitCode = 1; });",
+        "child.once('spawn', () => { console.log(child.pid); child.unref(); });",
+    ].join(' ');
+    return `bash -lc ${shellQuote(`node -e ${shellQuote(nodeScript)}`)}`;
+}
+function terminateRemoteLaunch(task) {
+    if (!task.pid)
+        throw new Error(`Cannot terminate remote task ${task.id}: launch returned no PID.`);
+    const pid = task.pid;
+    const command = `if kill -TERM -- -${pid} 2>/dev/null; then ` +
+        `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
+        `elif kill -0 -- -${pid} 2>/dev/null; then exit 1; fi; ` +
+        `rm -f ${task.remoteLog} ${task.remoteExit}`;
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    if (result.code !== 0) {
+        throw new Error(`Failed to terminate remote task ${task.id} on ${task.host}: ` +
+            `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
+    }
+}
+/** Terminate a detached dispatch that its caller could not persist locally. */
+export function terminateDispatchedTask(task) {
+    terminateRemoteLaunch(task);
+    updateTask(task.id, terminalPatch(143));
+}
 /**
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
@@ -45,10 +116,11 @@ async function launchDetached(host, target, opts) {
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
     // Inner command run under a login shell so PATH resolves `agents`.
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
-    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const cwd = remoteCdPrefix(opts.remoteCwd);
     const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
-    // Outer: ensure dir, launch detached under bash -lc, print the PID.
-    const launch = `mkdir -p ${REMOTE_DIR}; nohup bash -lc ${shellQuote(inner)} >/dev/null 2>&1 & echo $!`;
+    // Outer: ensure dir, launch the login-shell wrapper as a new process-group
+    // leader, and print that leader PID.
+    const launch = `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
     const res = sshExec(target, launch, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
@@ -68,7 +140,18 @@ async function launchDetached(host, target, opts) {
         status: 'running',
         createdAt: new Date().toISOString(),
     };
-    saveTask(task);
+    try {
+        saveTask(task);
+    }
+    catch (err) {
+        try {
+            terminateRemoteLaunch(task);
+        }
+        catch (cleanupErr) {
+            throw new Error(`Failed to persist remote task ${task.id}; cleanup also failed: ${cleanupErr.message}`, { cause: err });
+        }
+        throw err;
+    }
     if (opts.follow === false) {
         return { task };
     }
@@ -146,7 +229,7 @@ export async function runInteractiveOnHost(host, opts) {
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
-    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const cwd = remoteCdPrefix(opts.remoteCwd);
     const remoteCmd = `${cwd}${invocation}`;
     return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
 }

package/dist/lib/permissions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, OpenCodePermissions, CodexPermissions } from './types.js';
+import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, CursorPermissions, OpenCodePermissions, CodexPermissions } from './types.js';
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 export type ParsedRules = PermissionSet;
@@ -99,6 +99,11 @@ export declare function removePermissionSet(name: string): {
  * Claude uses: { permissions: { allow: ["Bash(*)", "Read(**)"], deny: [] } }
  */
 export declare function convertToClaudeFormat(set: PermissionSet): ClaudePermissions;
+/**
+ * Convert canonical permission set to Cursor CLI format
+ * (`~/.cursor/cli-config.json` permissions.allow/deny).
+ */
+export declare function convertToCursorFormat(set: PermissionSet): CursorPermissions;
 /**
  * Convert canonical permission set to Gemini format.
  * Gemini reads tool allow-lists from settings.json under `tools.allowed`.
@@ -152,6 +157,19 @@ export type KimiRule = {
     decision: 'allow' | 'deny';
     pattern: string;
 };
+export type KiroRule = {
+    capability: string;
+    effect: 'allow' | 'deny';
+    match?: string[];
+    exclude?: string[];
+};
+/**
+ * Convert canonical permissions to Kiro CLI v3 capability rules.
+ * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
+ */
+export declare function convertToKiroFormat(set: PermissionSet): {
+    rules: KiroRule[];
+};
 /**
  * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
  * Kimi (`~/.kimi-code/config.toml`) reads rules of the form

package/dist/lib/permissions.js

@@ -440,6 +440,37 @@ export function convertToClaudeFormat(set) {
     }
     return { permissions };
 }
+/**
+ * Map a canonical rule to Cursor CLI syntax.
+ * Cursor uses Shell(...) instead of Bash(...); other tools keep TitleCase names.
+ * https://cursor.com/docs/cli/reference/permissions
+ */
+function canonicalToCursorRule(perm) {
+    if (perm === 'Bash' || perm.startsWith('Bash(')) {
+        return perm.replace(/^Bash/, 'Shell');
+    }
+    // Canonical WebSearch maps to WebFetch family for network allow.
+    if (perm.startsWith('WebSearch(')) {
+        return perm.replace(/^WebSearch/, 'WebFetch');
+    }
+    // Cursor has no Edit prefix — file writes use Write(...).
+    if (perm === 'Edit' || perm.startsWith('Edit(')) {
+        return perm.replace(/^Edit/, 'Write');
+    }
+    return perm;
+}
+/**
+ * Convert canonical permission set to Cursor CLI format
+ * (`~/.cursor/cli-config.json` permissions.allow/deny).
+ */
+export function convertToCursorFormat(set) {
+    return {
+        permissions: {
+            allow: set.allow.map(canonicalToCursorRule),
+            deny: (set.deny ?? []).map(canonicalToCursorRule),
+        },
+    };
+}
 /**
  * Parse canonical permission pattern to extract tool and pattern.
  * "Bash(git *)" -> { tool: "bash", pattern: "git *" }
@@ -592,6 +623,57 @@ function canonicalToGrokRule(perm, action) {
     }
     return { action, tool, pattern };
 }
+/**
+ * Convert canonical permissions to Kiro CLI v3 capability rules.
+ * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
+ */
+export function convertToKiroFormat(set) {
+    const rules = [];
+    for (const perm of set.allow) {
+        const rule = canonicalToKiroRule(perm, 'allow');
+        if (rule)
+            rules.push(rule);
+    }
+    for (const perm of set.deny ?? []) {
+        const rule = canonicalToKiroRule(perm, 'deny');
+        if (rule)
+            rules.push(rule);
+    }
+    return { rules };
+}
+function canonicalToKiroRule(perm, effect) {
+    if (BLANKET_BASH_FORMS.has(perm)) {
+        return { capability: 'shell', effect };
+    }
+    const parsed = parseCanonicalPreserveCase(perm);
+    const capability = KIRO_CAPABILITY_BY_TOOL[parsed.tool.toLowerCase()];
+    if (!capability)
+        return null;
+    if (parsed.pattern === null || parsed.pattern === '*' || parsed.pattern === '**') {
+        return { capability, effect };
+    }
+    const lowerTool = parsed.tool.toLowerCase();
+    const pattern = lowerTool === 'bash'
+        ? normalizeBashPattern(parsed.pattern)
+        : (lowerTool === 'webfetch' || lowerTool === 'websearch') && parsed.pattern.startsWith('domain:')
+            ? parsed.pattern.slice('domain:'.length)
+            : parsed.pattern;
+    return { capability, effect, match: [pattern] };
+}
+const KIRO_CAPABILITY_BY_TOOL = {
+    bash: 'shell',
+    read: 'fs_read',
+    grep: 'fs_read',
+    glob: 'fs_read',
+    write: 'fs_write',
+    edit: 'fs_write',
+    notebookedit: 'fs_write',
+    webfetch: 'web_fetch',
+    websearch: 'web_search',
+    mcp: 'mcp',
+    subagent: 'subagent',
+    skill: 'skill',
+};
 /**
  * Parse a canonical permission string preserving the tool's original casing.
  * `parseCanonicalPattern` lowercases the tool name, which is fine for Grok
@@ -1258,6 +1340,61 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'cursor') {
+            // Cursor CLI permissions live in ~/.cursor/cli-config.json
+            const configPath = path.join(configDir, 'cli-config.json');
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch { /* start fresh */ }
+            }
+            const converted = convertToCursorFormat(set);
+            if (merge && config.permissions && typeof config.permissions === 'object') {
+                const existing = config.permissions;
+                const allow = new Set([...(existing.allow || []), ...converted.permissions.allow]);
+                const deny = new Set([...(existing.deny || []), ...converted.permissions.deny]);
+                config.permissions = { allow: [...allow], deny: [...deny] };
+            }
+            else {
+                config.permissions = converted.permissions;
+            }
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            return { success: true };
+        }
+        if (agentId === 'kiro') {
+            const permissionsPath = path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
+            let config = {};
+            if (fs.existsSync(permissionsPath)) {
+                const parsed = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    config = parsed;
+                }
+            }
+            const newRules = convertToKiroFormat(set).rules;
+            if (merge) {
+                const existingRules = Array.isArray(config.rules) ? config.rules : [];
+                const seen = new Set();
+                config.rules = [...existingRules, ...newRules].filter((rule) => {
+                    if (!rule || typeof rule !== 'object' || Array.isArray(rule))
+                        return false;
+                    const record = rule;
+                    const key = `${String(record.effect)}|${String(record.capability)}|${JSON.stringify(record.match ?? [])}|${JSON.stringify(record.exclude ?? [])}`;
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+            }
+            else {
+                config.rules = newRules;
+            }
+            fs.mkdirSync(path.dirname(permissionsPath), { recursive: true });
+            fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
+            return { success: true };
+        }
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
     catch (err) {

package/dist/lib/project-root.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Projects-root resolution for the `agents run --project <slug>` shorthand.
+ *
+ * Projects follow a predictable layout — `<root>/<repo>` (e.g.
+ * `~/src/github.com/<user>/<repo>`), with git worktrees under
+ * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
+ * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
+ * so later runs resolve a bare slug from anywhere. It is stored home-relative
+ * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
+ * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--host` run
+ * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
+ * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
+ */
+/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
+export declare function toHomeRelative(abs: string): string;
+/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
+export declare function expandLocalHome(p: string): string;
+/**
+ * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
+ * under the LOCAL home (which the local shell already expanded from `~`) becomes
+ * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
+ * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
+ * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
+ * it is a literal remote path by contract.
+ */
+export declare function toRemotePortable(p: string): string;
+/** The configured projects root (home-relative or absolute), or undefined when unset. */
+export declare function getProjectRoot(): string | undefined;
+/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
+export declare function setProjectRoot(rootPath: string): string;
+/**
+ * Infer the projects root from `cwd`: the directory ABOVE the git repo root
+ * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
+ * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
+ */
+export declare function inferProjectRoot(cwd: string): Promise<string | undefined>;
+/**
+ * Resolve the projects root, auto-inferring and caching on first use. Throws an
+ * actionable error when it is neither configured nor inferrable from `cwd`.
+ */
+export declare function ensureProjectRoot(cwd: string): Promise<string>;
+export interface ProjectRef {
+    slug: string;
+    worktree?: string;
+}
+/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
+export declare function parseProjectRef(ref: string): ProjectRef;
+/**
+ * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
+ * slug/worktree layout is unit-testable. `forRemote` keeps the path
+ * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
+ * against the local home into an absolute path.
+ */
+export declare function buildProjectPath(root: string, ref: string, forRemote: boolean): string;
+/**
+ * Resolve a `--project` ref to a working directory, inferring/caching the root.
+ *
+ * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
+ * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
+ * absolute local path and verifies it exists (so a mistyped slug fails loudly).
+ */
+export declare function resolveProjectRef(ref: string, opts: {
+    forRemote: boolean;
+    cwd?: string;
+}): Promise<string>;