@phnx-labs/agents-cli 1.20.61 → 1.20.63

package/dist/lib/hosts/dispatch.js

@@ -16,6 +16,7 @@ import { remoteShellFor } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
+import { wrapHostCommandWithCredentials } from './credentials.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -91,6 +92,64 @@ export function terminateDispatchedTask(task) {
     terminateRemoteLaunch(task);
     updateTask(task.id, terminalPatch(143));
 }
+/**
+ * Build the remote shell used by {@link stopDispatchedTask}. Exported for
+ * unit tests — the keep-log / no-clobber contract lives in this script.
+ *
+ * Protocol (printed to stdout for the local caller):
+ * - `SIGNALED`  — process group was live; SIGTERM/KILL applied; wrote 143
+ * - `ALREADY` + code — group gone; adopted existing `.exit` (never overwrite)
+ * - `GONE` — group gone and no `.exit`; write 143 as the local stop outcome
+ * Exit 1 if the group is still alive after TERM/KILL (can't stop it).
+ */
+export function buildStopRemoteCommand(pid, remoteExit) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        throw new Error(`Invalid remote task pid: ${pid}`);
+    }
+    // Only force-write 143 when we actually signaled a live group (or nothing
+    // left a code). Never `echo 143` over a real completed-run exit code.
+    return (`if kill -TERM -- -${pid} 2>/dev/null; then ` +
+        `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
+        `echo 143 > ${remoteExit}; echo SIGNALED; ` +
+        `elif kill -0 -- -${pid} 2>/dev/null; then ` +
+        `exit 1; ` +
+        `else ` +
+        `code=$(cat ${remoteExit} 2>/dev/null | tr -d '[:space:]'); ` +
+        `if [ -n "$code" ]; then echo "ALREADY $code"; ` +
+        `else echo 143 > ${remoteExit}; echo GONE; fi; ` +
+        `fi`);
+}
+/**
+ * Stop a running host task from the origin machine (`agents hosts stop <id>`).
+ *
+ * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
+ * persist), this keeps the remote log so `agents hosts logs <id>` still works,
+ * writes a terminal `.exit` marker only when we actually stopped a live group
+ * (or no code existed), and never clobbers a real completed-run exit code.
+ */
+export function stopDispatchedTask(task) {
+    if (task.status !== 'running') {
+        throw new Error(`Task ${task.id} is already ${task.status}`);
+    }
+    if (!task.pid) {
+        throw new Error(`Cannot stop remote task ${task.id}: launch returned no PID.`);
+    }
+    const command = buildStopRemoteCommand(task.pid, task.remoteExit);
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    if (result.code !== 0) {
+        throw new Error(`Failed to stop remote task ${task.id} on ${task.host}: ` +
+            `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
+    }
+    const line = result.stdout.trim().split('\n').pop() ?? '';
+    let code = 143;
+    if (line.startsWith('ALREADY ')) {
+        const parsed = parseInt(line.slice('ALREADY '.length), 10);
+        if (Number.isFinite(parsed))
+            code = parsed;
+    }
+    // SIGNALED / GONE / ALREADY all end with a terminal local record.
+    return updateTask(task.id, terminalPatch(code)) ?? { ...task, ...terminalPatch(code) };
+}
 /**
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
@@ -117,7 +176,10 @@ async function launchDetached(host, target, opts) {
     // Inner command run under a login shell so PATH resolves `agents`.
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    let inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    if (opts.copyCreds) {
+        inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
+    }
     // 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)}`;
@@ -268,7 +330,10 @@ export async function runInteractiveOnHost(host, opts) {
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    const remoteCmd = `${cwd}${invocation}`;
+    let remoteCmd = `${cwd}${invocation}`;
+    if (opts.copyCreds) {
+        remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
+    }
     return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
@@ -288,6 +353,7 @@ export async function dispatchToHost(host, opts) {
         // On resume the remote session keeps its existing id; record that id so the
         // task stays mapped to the same session.
         sessionId: opts.resume ?? opts.sessionId,
+        copyCreds: opts.copyCreds,
     });
 }
 /**

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

@@ -1,10 +1,8 @@
 /**
  * Generic `--host` passthrough — the single choke point that runs an allowlisted
- * `agents <command>` on a remote host instead of locally, so read-only and
- * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
- * and the team lifecycle (`teams …`) all gain remote support with no per-command
- * code. Called once from `index.ts` before commander parses; returns `true` when
- * it handled the invocation (the local command must then NOT run).
+ * `agents <command>` on a remote host instead of locally. Called once from
+ * `index.ts` before commander parses; returns `true` when it handled the
+ * invocation (the local command must then NOT run).
  *
  * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
  * choke point already used everywhere, and it gives auth + encryption + host-key
@@ -12,17 +10,22 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run`, `sessions`, and `feed` are deliberately absent from the table below:
- * they own richer `--host` handling in their own command actions (detached run
- * dispatch or multi-host fan-out) and must fall through to it.
+ * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * fall through to their local actions. Everything else either routes via this
+ * table or, when `--host`/`--device` is present, exits with a clear
+ * "not supported" message — never commander's raw `unknown option`.
  */
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
  * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command isn't in the
- * table, or the target is this very machine.
+ * `false` (run locally) when neither flag is present, the command owns its own
+ * host handling, the target is this very machine, or placement flags need the
+ * local action. Returns `true` after printing a clear error when the flag is
+ * present on a command that is neither routable nor self-handling — so the user
+ * never sees commander's raw `unknown option '--host'`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.

package/dist/lib/hosts/passthrough.js

@@ -1,10 +1,8 @@
 /**
  * Generic `--host` passthrough — the single choke point that runs an allowlisted
- * `agents <command>` on a remote host instead of locally, so read-only and
- * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
- * and the team lifecycle (`teams …`) all gain remote support with no per-command
- * code. Called once from `index.ts` before commander parses; returns `true` when
- * it handled the invocation (the local command must then NOT run).
+ * `agents <command>` on a remote host instead of locally. Called once from
+ * `index.ts` before commander parses; returns `true` when it handled the
+ * invocation (the local command must then NOT run).
  *
  * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
  * choke point already used everywhere, and it gives auth + encryption + host-key
@@ -12,9 +10,11 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run`, `sessions`, and `feed` are deliberately absent from the table below:
- * they own richer `--host` handling in their own command actions (detached run
- * dispatch or multi-host fan-out) and must fall through to it.
+ * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * fall through to their local actions. Everything else either routes via this
+ * table or, when `--host`/`--device` is present, exits with a clear
+ * "not supported" message — never commander's raw `unknown option`.
  */
 import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
@@ -24,19 +24,90 @@ import { dispatchAgentsCommand } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
+/**
+ * First-class groups that run transparently on a remote via SSH when
+ * `--host`/`--device` is present. Keep both canonical names and aliases
+ * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
+ *
+ * Prefer adding here over per-command SSH code — this is the single choke point.
+ */
 const REMOTE_PASSTHROUGH = {
+    // status / inspect
     view: {},
+    inspect: {},
+    doctor: {},
+    status: {},
+    check: {},
+    list: {},
     usage: {},
     cost: {},
     output: {},
-    doctor: {},
-    inspect: {},
-    list: {},
+    budget: {},
+    // config / resources
     sync: { nonInteractive: ['--yes'] },
+    pull: {},
+    push: {},
+    repo: {},
+    repos: {},
+    plugins: {},
+    skills: {},
+    hooks: {},
+    commands: {},
+    rules: {},
+    memory: {},
+    permissions: {},
+    perms: {},
+    mcp: {},
+    cli: {},
+    subagents: {},
+    workflows: {},
+    packages: {},
+    models: {},
+    profiles: {},
+    defaults: {},
+    alias: {},
+    // lifecycle
     teams: {},
     message: {},
     routines: {},
+    jobs: {},
+    cron: {},
+    // misc remote-sensible
+    prune: {},
+    trash: {},
+    restore: {},
+    worktree: {},
+    events: {},
+    audit: {},
+    lock: {},
+    feedback: {},
+    wallet: {},
+    daemon: {},
+    pty: {},
+    tmux: {},
+    watchdog: {},
+    factory: {},
+    browser: {},
+    versions: {},
 };
+/**
+ * Commands that register and interpret `--host`/`--device` themselves — must
+ * fall through to local commander even when the flag is present. Do not add
+ * these to {@link REMOTE_PASSTHROUGH}.
+ */
+const OWN_HOST_COMMANDS = new Set([
+    'run',
+    'exec', // deprecated alias of run
+    'sessions',
+    'feed',
+    'computer',
+    'secrets',
+    'logs',
+    'hosts',
+    'ssh',
+    'devices',
+    'fleet', // alias of devices
+]);
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
@@ -83,15 +154,26 @@ async function resolveTargetHost(name, any) {
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
  * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command isn't in the
- * table, or the target is this very machine.
+ * `false` (run locally) when neither flag is present, the command owns its own
+ * host handling, the target is this very machine, or placement flags need the
+ * local action. Returns `true` after printing a clear error when the flag is
+ * present on a command that is neither routable nor self-handling — so the user
+ * never sees commander's raw `unknown option '--host'`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export async function maybeRunOnHost(command, allArgs) {
-    const spec = REMOTE_PASSTHROUGH[command];
-    if (!spec)
+    const hostFlag = flagValue(allArgs, 'host', 'H');
+    const deviceFlag = flagValue(allArgs, 'device');
+    const hostName = hostFlag ?? deviceFlag;
+    if (!hostName)
+        return false;
+    // Commands with their own richer --host semantics must reach local commander
+    // BEFORE any single-target conflict gate. sessions/feed merge --host and
+    // --device into a multi-host list; rejecting "conflicting" pairs would break
+    // `agents sessions --host a --device b` / `agents feed --host a --device b`.
+    if (OWN_HOST_COMMANDS.has(command))
         return false;
     // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
     // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
@@ -107,16 +189,6 @@ export async function maybeRunOnHost(command, allArgs) {
             return false;
         }
     }
-    // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
-    // device registry is the source of truth for machine identity. Reject a
-    // conflicting pair rather than silently preferring one — same rule as run.
-    const hostFlag = flagValue(allArgs, 'host', 'H');
-    const deviceFlag = flagValue(allArgs, 'device');
-    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
-        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
-        process.exitCode = 1;
-        return true;
-    }
     // `--hosts` is always a generic fleet flag — bail for every command so the
     // local aggregator handles it. `--devices` is fan-out on most commands but
     // a placement flag on `routines` (which devices may run the routine), so
@@ -125,14 +197,32 @@ export async function maybeRunOnHost(command, allArgs) {
         return false;
     if (allArgs.includes('--devices') && command !== 'routines')
         return false;
-    const hostName = hostFlag ?? deviceFlag;
-    if (!hostName)
-        return false;
+    const spec = REMOTE_PASSTHROUGH[command];
+    if (!spec) {
+        // Flag was accepted (no raw commander "unknown option") but this group has
+        // no remote semantics — say so clearly instead of falling through.
+        console.error(chalk.red(`\`agents ${command}\` does not support --host/--device (no remote interpretation).`) +
+            chalk.gray(' Run without the flag, or use a host-routable group (repos, view, sync, teams, doctor, …).'));
+        process.exitCode = 1;
+        return true;
+    }
+    // Single-target remote path only: reject a conflicting --host/--device pair
+    // rather than silently preferring one (same rule as `agents run`).
+    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
+        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
+        process.exitCode = 1;
+        return true;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // `machineId()` is the same self-identifier the device registry and session
     // sync use (lowercased short hostname); compare case-insensitively.
-    if (hostName.toLowerCase() === machineId())
+    // Strip the routing flags from process.argv so the local command never sees
+    // an unregistered `--host`/`--device` and dies with "unknown option".
+    if (hostName.toLowerCase() === machineId()) {
+        const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
+        process.argv = [process.argv[0], process.argv[1], ...stripped];
         return false;
+    }
     const remoteCwd = flagValue(allArgs, 'remote-cwd');
     const any = allArgs.includes('--any');
     let host;

package/dist/lib/mailbox-gc.js

@@ -9,7 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getMailboxRootDir } from './state.js';
-import { mailboxDir, isValidMailboxId, readMessage, } from './mailbox.js';
+import { mailboxDir, isValidMailboxId, readMessage, sweepExpired, } from './mailbox.js';
 import { listBlocks, removeBlock } from './feed.js';
 const DEFAULT_MAX_CONSUMED_AGE_MINUTES = 24 * 60;
 function consumedAgeMinutes(file, now) {
@@ -134,21 +134,9 @@ export function gcMailbox(activeBoxIds, options = {}) {
             }
         }
         else {
-            // Live box: lazy expiry is handled by drain/peek, but sweep here for GC metrics.
-            // We still need to read expired messages; reuse readMessage directly to avoid
-            // importing sweepExpired and duplicating logic.
-            for (const sub of ['inbox', 'processing']) {
-                const dir = path.join(boxDir, sub);
-                for (const file of jsonFiles(dir)) {
-                    const msg = readMessage(path.join(dir, file));
-                    if (msg && msg.expiresAt) {
-                        const ts = Date.parse(msg.expiresAt);
-                        if (!Number.isNaN(ts) && ts <= now.getTime()) {
-                            result.messagesDroppedExpired++;
-                        }
-                    }
-                }
-            }
+            // Live box: archive expired messages (same path as drain/peek) so GC does
+            // not leave expired files in inbox/processing while only bumping metrics.
+            result.messagesDroppedExpired += sweepExpired(boxDir, name, now);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
         }
     }

package/dist/lib/migrate.d.ts

@@ -44,6 +44,18 @@ export declare function foldLegacySystemRepo(): void;
  * drive a fixture tree without touching the user's ~/.agents.
  */
 export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
+/**
+ * Fold the legacy GLOBAL browser captures root
+ * (`~/.agents/.cache/browser/sessions/<task>/`) into the new PER-PROFILE layout
+ * (`~/.agents/.cache/browser/<profile>/sessions/<task>/`), so each profile is one
+ * self-contained tree and the new `browser sessions` listing finds old captures.
+ *
+ * Attribution: a legacy `sessions/<task>` dir is owned by whichever profile's
+ * `tasks.json` still lists that task name. Tasks no profile claims (the profile
+ * was deleted, or tasks.json was cleared) move under a `_legacy` pseudo-profile so
+ * nothing is lost. Idempotent — once the global `sessions/` root is gone it no-ops.
+ */
+export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): void;
 /**
  * Repair self-referential agent binary symlinks.
  *

package/dist/lib/migrate.js

@@ -359,6 +359,56 @@ function foldUserHooksYamlIntoAgentsYaml() {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Fold the legacy GLOBAL browser captures root
+ * (`~/.agents/.cache/browser/sessions/<task>/`) into the new PER-PROFILE layout
+ * (`~/.agents/.cache/browser/<profile>/sessions/<task>/`), so each profile is one
+ * self-contained tree and the new `browser sessions` listing finds old captures.
+ *
+ * Attribution: a legacy `sessions/<task>` dir is owned by whichever profile's
+ * `tasks.json` still lists that task name. Tasks no profile claims (the profile
+ * was deleted, or tasks.json was cleared) move under a `_legacy` pseudo-profile so
+ * nothing is lost. Idempotent — once the global `sessions/` root is gone it no-ops.
+ */
+export function foldBrowserSessionsIntoProfiles(browserDir = path.join(CACHE_DIR, 'browser')) {
+    const legacySessionsDir = path.join(browserDir, 'sessions');
+    let taskDirs;
+    try {
+        taskDirs = fs.readdirSync(legacySessionsDir, { withFileTypes: true });
+    }
+    catch {
+        return; // no legacy global sessions/ root — already folded or never existed
+    }
+    // Map task name -> owning profile from every profile's tasks.json (first wins).
+    const taskOwner = new Map();
+    let profileDirs = [];
+    try {
+        profileDirs = fs.readdirSync(browserDir, { withFileTypes: true });
+    }
+    catch { /* browserDir vanished mid-run */ }
+    for (const p of profileDirs) {
+        if (!p.isDirectory() || p.name === 'sessions' || p.name === '_legacy')
+            continue;
+        try {
+            const state = JSON.parse(fs.readFileSync(path.join(browserDir, p.name, 'tasks.json'), 'utf-8'));
+            for (const taskName of Object.keys(state)) {
+                if (!taskOwner.has(taskName))
+                    taskOwner.set(taskName, p.name);
+            }
+        }
+        catch { /* missing or invalid tasks.json */ }
+    }
+    for (const taskEntry of taskDirs) {
+        if (!taskEntry.isDirectory())
+            continue;
+        const owner = taskOwner.get(taskEntry.name) ?? '_legacy';
+        // A capture dir can hold a nested recordings/ subdir and may collide with a
+        // dest that already has newer captures — moveDirOnce merges (skip-existing),
+        // moveFileOnce would EISDIR on unlink and silently strand the captures.
+        moveDirOnce(path.join(legacySessionsDir, taskEntry.name), path.join(browserDir, owner, 'sessions', taskEntry.name));
+    }
+    rmEmptyDirTree(legacySessionsDir);
+}
 /**
  * Fold ~/.agents/browser/profiles/*.yaml into ~/.agents/agents.yaml under a
  * `browser:` key, then delete the profiles directory. Single user file to sync.
@@ -1582,7 +1632,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata
@@ -1966,6 +2016,10 @@ export async function runMigration() {
     // migrateRuntimeToCache so any legacy plugins/ still at the user-root from
     // very-old layouts have already been handled.
     migratePluginsBackToUserRoot();
+    // Browser captures: fold the legacy global browser/sessions/<task> root into the
+    // per-profile browser/<profile>/sessions/<task> layout. After the cache moves so
+    // the browser dir is at its canonical .cache location.
+    foldBrowserSessionsIntoProfiles();
     // System-repo sweep: move every remaining operational dir into its canonical
     // user-bucket location, then drop known-dead artifacts and warn about
     // anything we don't recognize. Order: durable (sessions/teams/trash/repos/

package/dist/lib/permissions.d.ts

@@ -122,6 +122,21 @@ export declare function convertToDroidFormat(set: PermissionSet): {
     commandAllowlist: string[];
     commandDenylist: string[];
 };
+/**
+ * Convert canonical permission set to OpenClaw's `tools.alsoAllow`/`tools.deny`.
+ *
+ * OpenClaw's allowlist is tool-level only, so ONLY blanket (whole-tool) rules
+ * map — a rule is blanket iff it's a bare tool with no parens (`Bash`), it's in
+ * BLANKET_BASH_FORMS, or its pattern is `*`/`**` (`Read(**)`, `Write(*)`).
+ * Sub-command/path/domain rules (`Bash(git:*)`, `Write(secrets/**)`,
+ * `WebFetch(domain:x)`) are SKIPPED — coarse-mapping a specific deny to a whole
+ * tool would wrongly gate every use of that tool. Output arrays are deduped and
+ * sorted for deterministic writes/tests.
+ */
+export declare function convertToOpenClawFormat(set: PermissionSet): {
+    alsoAllow: string[];
+    deny: string[];
+};
 /**
  * Convert canonical permission set to Antigravity format.
  * Antigravity reads ~/.gemini/antigravity-cli/settings.json with

package/dist/lib/permissions.js

@@ -560,6 +560,60 @@ export function convertToDroidFormat(set) {
         commandDenylist: commands(set.deny ?? []),
     };
 }
+/**
+ * Canonical tool -> OpenClaw tool id. OpenClaw gates at TOOL granularity only
+ * (no sub-command/path/domain patterns), so only these whole-tool ids exist.
+ * Any canonical tool not in this map is unsupported and skipped.
+ */
+const CANONICAL_TO_OPENCLAW_TOOL = {
+    bash: 'exec',
+    read: 'read',
+    write: 'write',
+    edit: 'write',
+    webfetch: 'web_fetch',
+    websearch: 'web_search',
+};
+/**
+ * Convert canonical permission set to OpenClaw's `tools.alsoAllow`/`tools.deny`.
+ *
+ * OpenClaw's allowlist is tool-level only, so ONLY blanket (whole-tool) rules
+ * map — a rule is blanket iff it's a bare tool with no parens (`Bash`), it's in
+ * BLANKET_BASH_FORMS, or its pattern is `*`/`**` (`Read(**)`, `Write(*)`).
+ * Sub-command/path/domain rules (`Bash(git:*)`, `Write(secrets/**)`,
+ * `WebFetch(domain:x)`) are SKIPPED — coarse-mapping a specific deny to a whole
+ * tool would wrongly gate every use of that tool. Output arrays are deduped and
+ * sorted for deterministic writes/tests.
+ */
+export function convertToOpenClawFormat(set) {
+    const map = (permissions) => {
+        const tools = new Set();
+        for (const perm of permissions) {
+            // Bare tool name with no parens (e.g. "Bash", "Read") is a blanket grant;
+            // parseCanonicalPattern requires parens, so handle it first.
+            const bare = perm.match(/^(\w+)$/);
+            if (bare) {
+                const id = CANONICAL_TO_OPENCLAW_TOOL[bare[1].toLowerCase()];
+                if (id)
+                    tools.add(id);
+                continue;
+            }
+            const parsed = parseCanonicalPattern(perm);
+            if (!parsed)
+                continue;
+            const isBlanket = BLANKET_BASH_FORMS.has(perm) || parsed.pattern === '*' || parsed.pattern === '**';
+            if (!isBlanket)
+                continue;
+            const id = CANONICAL_TO_OPENCLAW_TOOL[parsed.tool];
+            if (id)
+                tools.add(id);
+        }
+        return Array.from(tools).sort();
+    };
+    return {
+        alsoAllow: map(set.allow),
+        deny: map(set.deny ?? []),
+    };
+}
 /**
  * Convert canonical permission set to Antigravity format.
  * Antigravity reads ~/.gemini/antigravity-cli/settings.json with
@@ -1570,6 +1624,51 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'openclaw') {
+            // OpenClaw's allowlist lives in ~/.openclaw/openclaw.json under `tools`.
+            // Only blanket tool-level rules map (see convertToOpenClawFormat). We
+            // read-modify-write to preserve all other keys (mcp, exec, agents, …) and
+            // never touch `tools.allow` (the absolute allowlist that replaces defaults).
+            const configPath = path.join(versionHome, '.openclaw', 'openclaw.json');
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            const converted = convertToOpenClawFormat(set);
+            const existingTools = (typeof config.tools === 'object' && config.tools !== null && !Array.isArray(config.tools))
+                ? config.tools
+                : {};
+            let alsoAllow;
+            let deny;
+            if (merge) {
+                const existingAllow = Array.isArray(existingTools.alsoAllow) ? existingTools.alsoAllow : [];
+                const existingDeny = Array.isArray(existingTools.deny) ? existingTools.deny : [];
+                alsoAllow = Array.from(new Set([...existingAllow, ...converted.alsoAllow]));
+                deny = Array.from(new Set([...existingDeny, ...converted.deny]));
+            }
+            else {
+                alsoAllow = converted.alsoAllow;
+                deny = converted.deny;
+            }
+            // Set or delete each key: avoid writing empty arrays (churn). On a
+            // non-merge replace with nothing to write, delete the stale key.
+            const tools = { ...existingTools };
+            if (alsoAllow.length > 0)
+                tools.alsoAllow = alsoAllow;
+            else
+                delete tools.alsoAllow;
+            if (deny.length > 0)
+                tools.deny = deny;
+            else
+                delete tools.deny;
+            if (Object.keys(tools).length > 0)
+                config.tools = tools;
+            else
+                delete config.tools;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            return { success: true };
+        }
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
     catch (err) {

package/dist/lib/plugins.d.ts

@@ -211,6 +211,26 @@ export declare function goosePluginsDir(versionHome: string): string;
 export declare function installGoosePlugin(plugin: DiscoveredPlugin, versionHome: string): boolean;
 export declare function isGoosePluginInstalled(pluginName: string, versionHome: string): boolean;
 export declare function removeGoosePlugin(pluginName: string, versionHome: string): boolean;
+/**
+ * Hermes (Nous Research) loads plugins from a flat `$HOME/.hermes/plugins/<name>/`
+ * directory holding a `plugin.yaml` manifest — NOT the Claude marketplace layout.
+ * Under agents-cli version isolation HOME is the version home, so we install to:
+ *   {versionHome}/.hermes/plugins/<name>/
+ * A plugin does not load until its name is added to `plugins.enabled` (a YAML
+ * array) in `{versionHome}/.hermes/config.yaml`; a deny-list `plugins.disabled`
+ * wins on conflict, so agents-cli only manages the `enabled` allowlist and never
+ * touches `disabled` (user-owned).
+ */
+export declare function hermesPluginsDir(versionHome: string): string;
+/**
+ * Add or remove a plugin name in `plugins.enabled` within ~/.hermes/config.yaml,
+ * preserving every other key (read → mutate → write). Never touches
+ * `plugins.disabled`. No-op (no rewrite) when the desired state already holds.
+ */
+export declare function setHermesPluginEnabled(pluginName: string, versionHome: string, enabled: boolean): void;
+export declare function installHermesPlugin(plugin: DiscoveredPlugin, versionHome: string, enable: boolean): boolean;
+export declare function isHermesPluginInstalled(pluginName: string, versionHome: string): boolean;
+export declare function removeHermesPlugin(pluginName: string, versionHome: string): boolean;
 /**
  * Check if a plugin is synced to a version. True when the plugin lives at the
  * native marketplace install path. Legacy dual-dash entries are not counted —