@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/permissions.js

@@ -1,12 +1,3 @@
-/**
- * Permission management for AI coding agents.
- *
- * Provides a canonical permission format (PermissionSet with allow/deny rules)
- * and converters to/from each agent's native format (Claude settings.json,
- * OpenCode opencode.jsonc, Codex config.toml + .rules). Handles discovery,
- * installation, removal, and merging of permission groups stored in
- * ~/.agents/permissions/groups/.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -17,9 +8,6 @@ import { safeJoin } from './paths.js';
 import { agentConfigDirName } from './agents.js';
 import { supports } from './capabilities.js';
 import { updateGeminiSettings } from './gemini-settings.js';
-// The canonical<->native tool vocabularies live in the registry, which also owns
-// the reverse projections — so the serializers below and the readers there can
-// never disagree about what `fs_read` or `developer__shell` means.
 import { ANTIGRAVITY_ACTION_BY_TOOL, CANONICAL_TO_OPENCLAW_TOOL, CODEX_RULES_FILENAME, stripJsonComments, GROK_TOOL_BY_CANONICAL, PERMISSION_TARGETS, readCanonicalPermissions, } from './permissions-registry.js';
 export { CODEX_RULES_FILENAME };
 const HOME = os.homedir();
@@ -80,20 +68,12 @@ export function containsBroadGrants(rules) {
         return null;
     return { broad, reason: Array.from(reasons).join('; ') };
 }
-/**
- * Convert canonical deny rules to Codex Starlark .rules format.
- * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
- *
- * Inverse: `toCanonical` for `PERMISSION_TARGETS.codex` reads
- * `.codex/rules/agents-deny.rules` back into `Bash(<parts>:*)`.
- */
 export function convertDenyToCodexRules(deny) {
     const rules = [];
     for (const perm of deny) {
         const parsed = parseCanonicalPattern(perm);
         if (!parsed || parsed.tool !== 'bash')
             continue;
-        // Pattern format: "command arg1 arg2:*" or "command:*"
         const command = parsed.pattern.replace(/:?\*$/, '').trim();
         if (!command)
             continue;
@@ -105,12 +85,6 @@ export function convertDenyToCodexRules(deny) {
         return null;
     return `# Auto-generated by agents-cli from deny permission groups.\n# Do not edit manually — re-run "agents use" to regenerate.\n\n${rules.join('\n\n')}\n`;
 }
-/**
- * Write `.codex/rules/agents-deny.rules` to match `deny`, or delete it when
- * the current set has nothing to forbid. The reader (PHNX-2703) now surfaces
- * this file, so a later apply with an empty deny must not leave a stale
- * forbid behind — `agents permissions list codex` would keep reporting it.
- */
 function syncCodexDenyRules(configDir, deny) {
     const rulesPath = path.join(configDir, 'rules', CODEX_RULES_FILENAME);
     const rulesContent = deny && deny.length > 0 ? convertDenyToCodexRules(deny) : null;
@@ -123,18 +97,12 @@ function syncCodexDenyRules(configDir, deny) {
         fs.unlinkSync(rulesPath);
     }
 }
-/**
- * Ensure central permissions directory exists.
- */
 function ensurePermissionsDir() {
     const groupsDir = path.join(getUserPermissionsDir(), 'groups');
     if (!fs.existsSync(groupsDir)) {
         fs.mkdirSync(groupsDir, { recursive: true });
     }
 }
-/**
- * Parse a permission set from a YAML file.
- */
 export function parsePermissionSet(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
@@ -157,12 +125,8 @@ export function parsePermissionSet(filePath) {
         return null;
     }
 }
-/**
- * Discover permission sets from a repository.
- */
 export function discoverPermissionsFromRepo(repoPath) {
     const results = [];
-    // Look for permissions in common locations
     const searchPaths = [
         path.join(repoPath, 'permissions'),
         path.join(repoPath, 'agent-permissions'),
@@ -190,19 +154,13 @@ export function discoverPermissionsFromRepo(repoPath) {
             }
         }
         catch {
-            // Skip inaccessible directories
         }
     }
     return results;
 }
-/**
- * Discover permission groups from ~/.agents/permissions/groups/.
- * Returns groups with their rule counts.
- */
 export function discoverPermissionGroups() {
     const seen = new Set();
     const groups = [];
-    // Search user dir first, then system (user wins on name collision)
     for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
         const groupsDir = path.join(baseDir, 'groups');
         if (!fs.existsSync(groupsDir))
@@ -225,27 +183,19 @@ export function discoverPermissionGroups() {
                     const matches = content.match(/^\s*-\s*"/gm);
                     ruleCount = matches ? matches.length : 0;
                 }
-                catch { /* Skip files we can't read */ }
+                catch { }
                 groups.push({ name, ruleCount, path: filePath });
             }
         }
-        catch { /* Skip inaccessible directory */ }
+        catch { }
     }
     return groups.sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * Get total rule count across all permission groups.
- */
 export function getTotalPermissionRuleCount() {
     const groups = discoverPermissionGroups();
     return groups.reduce((sum, g) => sum + g.ruleCount, 0);
 }
-/** Env var that selects which set recipe to apply at sync time. */
 export const PERMISSION_PRESET_ENV_VAR = 'AGENTS_PERMISSION_PRESET';
-/**
- * Read a permission preset recipe by name from ~/.agents/permissions/presets/.
- * Returns null if the recipe file is missing or malformed.
- */
 export function readPermissionPresetRecipe(name) {
     const presetsDir = path.join(getPermissionsDir(), 'presets');
     for (const ext of ['.yaml', '.yml']) {
@@ -271,26 +221,14 @@ export function readPermissionPresetRecipe(name) {
     }
     return null;
 }
-/**
- * Return the active permission preset name from AGENTS_PERMISSION_PRESET env var,
- * or null if unset. Caller decides the default behavior when null.
- */
 export function getActivePermissionPresetName() {
     const v = process.env[PERMISSION_PRESET_ENV_VAR];
     return v && v.trim() ? v.trim() : null;
 }
-/**
- * Build a PermissionSet from selected groups.
- * Concatenates allow/deny rules from each group.
- *
- * Uses line-by-line regex extraction instead of YAML parsing because
- * permission files often contain unescaped nested quotes that break YAML.
- */
 export function buildPermissionsFromGroups(groupNames) {
     const allAllow = [];
     const allDeny = [];
     for (const groupName of groupNames) {
-        // Search user dir first, then system dir
         let filePath = null;
         for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
             const groupsDir = path.join(baseDir, 'groups');
@@ -308,14 +246,6 @@ export function buildPermissionsFromGroups(groupNames) {
             continue;
         try {
             const content = fs.readFileSync(filePath, 'utf-8');
-            // Extract rules using line-by-line regex (more robust than YAML parsing)
-            // Matches lines like: - "Bash(git *)" or   - "WebFetch(domain:example.com)"
-            // Handles nested quotes that break YAML parsers.
-            // Split on CRLF or LF: git checks group yaml out with CRLF on Windows
-            // (core.autocrlf), and a plain split('\n') leaves a trailing '\r' so the
-            // closing-quote anchor `"$` never matches — extracting ZERO rules, which
-            // wrote an empty permission set and left `agents sync` unable to
-            // reconcile permissions on Windows forever (PHNX-3187).
             const lines = content.split(/\r?\n/);
             let section = null;
             for (const line of lines) {
@@ -324,13 +254,9 @@ export function buildPermissionsFromGroups(groupNames) {
                     section = sectionMatch[1];
                     continue;
                 }
-                // Match: optional whitespace, dash, whitespace, quote, content, quote
-                // Use greedy match to capture everything between first and last quote
                 const match = line.match(/^\s*-\s*"(.+)"$/);
                 if (match) {
                     const rule = match[1];
-                    // 99-deny group rules go to deny, others follow their YAML section.
-                    // Legacy group files used bare lists with no section; keep those as allow.
                     if (section === 'deny' || groupName === '99-deny' || groupName.includes('-deny')) {
                         allDeny.push(rule);
                     }
@@ -341,7 +267,6 @@ export function buildPermissionsFromGroups(groupNames) {
             }
         }
         catch {
-            // Skip files we can't read
         }
     }
     return {
@@ -351,11 +276,6 @@ export function buildPermissionsFromGroups(groupNames) {
         deny: allDeny.length > 0 ? allDeny : undefined,
     };
 }
-/**
- * List installed permission sets from central storage.
- * User dir takes precedence; system entries are surfaced when user has no
- * same-named override.
- */
 export function listInstalledPermissions() {
     ensureAgentsDir();
     const seen = new Set();
@@ -382,14 +302,10 @@ export function listInstalledPermissions() {
             }
         }
         catch {
-            // Skip inaccessible directory
         }
     }
     return results;
 }
-/**
- * Get a specific permission set by name. Searches user groups/ dir first, then system groups/.
- */
 function getPermissionSet(name) {
     for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
         const dir = path.join(baseDir, 'groups');
@@ -405,9 +321,6 @@ function getPermissionSet(name) {
     }
     return null;
 }
-/**
- * Install a permission set to user-level central storage.
- */
 export function installPermissionSet(sourcePath, name) {
     ensurePermissionsDir();
     const set = parsePermissionSet(sourcePath);
@@ -423,10 +336,6 @@ export function installPermissionSet(sourcePath, name) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Remove a permission set from user-level central storage. System-shipped
- * sets are intentionally not deletable from user commands.
- */
 export function removePermissionSet(name) {
     const groupsDir = path.join(getUserPermissionsDir(), 'groups');
     for (const ext of ['.yml', '.yaml']) {
@@ -443,26 +352,12 @@ export function removePermissionSet(name) {
     }
     return { success: false, error: `Permission set '${name}' not found` };
 }
-// ============================================================================
-// Agent-specific converters
-// ============================================================================
-/**
- * Map a canonical rule to Claude settings.json syntax.
- * Claude's file-permission checks only match Edit(path) rules — an Edit rule
- * covers every file-editing tool (Write, Edit, NotebookEdit) — and Claude
- * warns at startup about unmatched Write(path) rules. Canonical Write(path)
- * stays for other agents' converters; for Claude it is emitted as Edit(path).
- */
 function canonicalToClaudeRule(perm) {
     if (perm.startsWith('Write(')) {
         return perm.replace(/^Write/, 'Edit');
     }
     return perm;
 }
-/**
- * Convert canonical permission set to Claude format.
- * Claude uses: { permissions: { allow: ["Bash(*)", "Read(**)"], deny: [] } }
- */
 export function convertToClaudeFormat(set) {
     const permissions = {
         allow: [...new Set(set.allow.map(canonicalToClaudeRule))],
@@ -473,29 +368,18 @@ 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: {
@@ -504,24 +388,13 @@ export function convertToCursorFormat(set) {
         },
     };
 }
-/**
- * Parse canonical permission pattern to extract tool and pattern.
- * "Bash(git *)" -> { tool: "bash", pattern: "git *" }
- * "Read(**)" -> { tool: "read", pattern: "**" }
- */
 function parseCanonicalPattern(permission) {
     const match = permission.match(/^(\w+)\((.+)\)$/);
     if (!match)
         return null;
     return { tool: match[1].toLowerCase(), pattern: match[2] };
 }
-/** Blanket-Bash canonical forms that mean "allow any bash command". */
 const BLANKET_BASH_FORMS = new Set(['Bash', 'Bash(*)', 'Bash(**)']);
-/**
- * Strip Claude's `:*` subcommand-wildcard suffix and return a space-glob form.
- * "mq:*" -> "mq *", "git status" -> "git status", "*" -> "*".
- * Used by serializers whose native pattern grammar uses ` *` instead of `:*`.
- */
 function normalizeBashPattern(pattern) {
     if (pattern === '*' || pattern === '**')
         return '*';
@@ -612,7 +485,6 @@ export function convertToCopilotFormat(set, location) {
         },
     };
 }
-/** Convert canonical Bash rules into Droid's command arrays. */
 export function convertToDroidFormat(set) {
     const commands = (permissions) => {
         const result = new Set();
@@ -632,23 +504,10 @@ export function convertToDroidFormat(set) {
         commandDenylist: commands(set.deny ?? []),
     };
 }
-/**
- * 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()];
@@ -692,18 +551,6 @@ export function convertToHermesFormat(set) {
         approvals: { deny: commands(set.deny ?? []) },
     };
 }
-/**
- * Convert canonical permission set to Antigravity format.
- * Antigravity reads ~/.gemini/antigravity-cli/settings.json with
- *   { permissions: { allow: [...], deny: [...] } }
- * where each entry is action-namespaced: command(...), read_file(...),
- * write_file(...), read_url(...), mcp(...).
- * Bash maps to `command`, Read to `read_file`, Write to `write_file`,
- * WebFetch to `read_url`. Other canonical tools are skipped.
- * Note: Antigravity matches `command(npm install)` as an exact string,
- * not a prefix — `Bash(npm:*)` becomes `command(npm *)` which is a glob
- * but Antigravity upstream has a known exact-match bug for some forms.
- */
 export function convertToAntigravityFormat(set) {
     const allow = serializeAntigravityEntries(set.allow);
     const deny = set.deny ? serializeAntigravityEntries(set.deny) : [];
@@ -737,14 +584,6 @@ function serializeAntigravityEntries(perms) {
     }
     return Array.from(out);
 }
-/**
- * Convert canonical permission set to Grok format.
- * Grok reads ~/.grok/config.toml with
- *   [permission]
- *   rules = [ { action = "allow", tool = "bash", pattern = "git *" }, ... ]
- * Tool names are lowercase: bash, read, edit, grep, mcptool, webfetch.
- * Canonical Write maps to Grok's `edit` tool.
- */
 export function convertToGrokFormat(set) {
     const rules = [];
     for (const perm of set.allow) {
@@ -763,15 +602,6 @@ export function convertToGrokFormat(set) {
 }
 function canonicalToGrokRule(perm, action) {
     if (BLANKET_BASH_FORMS.has(perm)) {
-        // Grok's `*` is a SINGLE-LEVEL wildcard, so a `pattern: '*'` bash rule does
-        // NOT auto-approve a multi-token command like `ssh host cmd` or `scp a b`
-        // (PHNX-3294 — verified: two boxes carrying the identical `pattern="*"` rule
-        // differed only by `[ui].permission_mode`, and only the always-approve box
-        // ran ssh without prompting). Grok's documented "bare prefix matches all
-        // invocations" idiom is a rule with NO `pattern` key — the true allow-all
-        // shell form, matching how kimi (bare `Bash`), droid (`*`) and claude
-        // express a blanket Bash grant. This reads back as `Bash(*)` via the
-        // registry's pattern-less path, so the round-trip is unchanged.
         return { action, tool: 'bash' };
     }
     const parsed = parseCanonicalPattern(perm);
@@ -786,34 +616,12 @@ function canonicalToGrokRule(perm, action) {
     }
     return { action, tool, pattern };
 }
-/**
- * Parse a canonical permission string preserving the tool's original casing.
- * `parseCanonicalPattern` lowercases the tool name, which is fine for Grok
- * (lowercase tool vocabulary) but wrong for Kimi, whose tool names are
- * capitalized (`Bash`, `Read`, `Grep`). Bare tool names (no parens, e.g.
- * `Read` or an MCP id like `mcp__server__tool`) return `pattern: null`.
- */
 function parseCanonicalPreserveCase(perm) {
     const m = perm.match(/^([\w-]+)\((.*)\)$/);
     if (m)
         return { tool: m[1], pattern: m[2] };
     return { tool: perm, pattern: null };
 }
-/**
- * Translate a canonical Bash arg-glob (`cmd:*`) into the Kimi pattern(s) that
- * actually match that command's invocations.
- *
- * Kimi matches Bash arg-globs with picomatch, where `*` does NOT cross `/` and a
- * `**` only globstars when it is its own path segment (`*​/**`, `**​/`). A plain
- * `cmd*` therefore matches `git status -s` but NOT `git push origin feat/x` or
- * `cat dir/file` — any argument containing a slash falls through to a prompt
- * (verified interactively against kimi 0.12.1). We emit TWO patterns so the
- * command auto-approves whether its args contain a slash or not:
- *   - `cmd*`     — no-slash args (and the bare command; `*` is zero-or-more).
- *   - `cmd*​/**` — args with a path: `*` consumes up to the first `/`, then the
- *                 bounded globstar crosses the remaining slashes.
- * "git push:*" -> ["git push*", "git push*​/**"].
- */
 function kimiBashPatterns(pattern) {
     if (pattern === '*' || pattern === '**')
         return ['*'];
@@ -821,7 +629,6 @@ function kimiBashPatterns(pattern) {
         const prefix = pattern.slice(0, -2);
         return [`${prefix}*`, `${prefix}*/**`];
     }
-    // Exact command (no `:*`, e.g. `env`, `pwd`, `true`) — no path args expected.
     return [pattern];
 }
 function canonicalToKimiRules(perm, decision) {
@@ -829,8 +636,6 @@ function canonicalToKimiRules(perm, decision) {
         return [{ decision, pattern: 'Bash' }];
     }
     const { tool, pattern } = parseCanonicalPreserveCase(perm);
-    // Bare tool name (no parens) — name-only match. Covers `Read`, `Grep`, and
-    // MCP tool ids, which Kimi can only match by name anyway.
     if (pattern === null) {
         return [{ decision, pattern: tool }];
     }
@@ -840,28 +645,11 @@ function canonicalToKimiRules(perm, decision) {
             pattern: p === '*' ? 'Bash' : `Bash(${p})`,
         }));
     }
-    // Non-Bash built-ins (Read/Write/Edit/Grep/Glob/WebFetch...) share Kimi's
-    // capitalized tool vocabulary, so pass the tool+pattern through. A `**`/`*`
-    // glob means "any" — collapse to a name-only rule.
     if (pattern === '*' || pattern === '**') {
         return [{ decision, pattern: tool }];
     }
     return [{ decision, pattern: `${tool}(${pattern})` }];
 }
-/**
- * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
- * Kimi (`~/.kimi-code/config.toml`) reads rules of the form
- *   [[permission.rules]]
- *   decision = "allow"
- *   pattern  = "Bash(git status*)"
- * Tool names are capitalized and the Bash arg-glob uses a trailing `*` (no
- * Claude `:*` separator). Without this conversion the canonical strings match
- * nothing in Kimi's engine and every tool call falls through to a prompt.
- *
- * Each `:*` Bash rule expands to TWO patterns (`cmd*` and `cmd*​/**`) so the
- * command auto-approves whether or not its arguments contain a slash — see
- * `kimiBashPatterns` for why Kimi's picomatch matcher needs both.
- */
 export function convertToKimiFormat(set) {
     const rules = [];
     for (const perm of set.allow) {
@@ -874,17 +662,10 @@ export function convertToKimiFormat(set) {
     }
     return { permission: { rules } };
 }
-/**
- * Convert canonical permission set to OpenCode format.
- * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
- */
 export function convertToOpenCodeFormat(set) {
     const bashPermissions = {};
-    // Process allow list
     for (const perm of set.allow) {
         if (BLANKET_BASH_FORMS.has(perm)) {
-            // Bare "Bash" has no parens so parseCanonicalPattern returns null;
-            // normalize all three blanket forms to "*".
             bashPermissions['*'] = 'allow';
             continue;
         }
@@ -893,7 +674,6 @@ export function convertToOpenCodeFormat(set) {
             bashPermissions[parsed.pattern] = 'allow';
         }
     }
-    // Process deny list
     if (set.deny) {
         for (const perm of set.deny) {
             const parsed = parseCanonicalPattern(perm);
@@ -908,18 +688,6 @@ export function convertToOpenCodeFormat(set) {
         },
     };
 }
-/**
- * Default extra writable roots for Codex's `workspace-write` sandbox: the
- * regenerable package/toolchain caches that build/test/install write OUTSIDE the
- * workspace (cargo registry, npm/bun/pnpm caches, GOPATH/GOCACHE, the OS cache
- * root, …). Without these, a sandboxed `cargo build` / `go build` / `npm install`
- * fails on its cache write, which is what pushes users to `--mode full` (YOLO).
- *
- * Credential dirs (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/.netrc`) are
- * deliberately EXCLUDED so the sandbox stays meaningful — this is far from
- * danger-full-access. Resolved per platform + home; each box regenerates its own
- * Codex config on sync, so the paths always match the box Codex runs on.
- */
 export function codexDefaultWritableRoots(home = HOME, platform = process.platform) {
     const shared = ['.cargo', '.rustup', '.npm', '.bun', 'go', '.deno', '.gradle', '.m2', '.gem'];
     const roots = shared.map((d) => path.join(home, d));
@@ -927,18 +695,10 @@ export function codexDefaultWritableRoots(home = HOME, platform = process.platfo
         roots.push(path.join(home, 'Library', 'Caches'), path.join(home, 'Library', 'pnpm'));
     }
     else {
-        // Linux/XDG: ~/.cache covers pip, uv, go-build, ms-playwright, etc.
         roots.push(path.join(home, '.cache'), path.join(home, '.local', 'share'), path.join(home, '.local', 'state'));
     }
     return roots;
 }
-/**
- * Merge Codex `[sandbox_workspace_write]` config, UNIONing `writable_roots` so a
- * baseline cache root never clobbers a root the user configured directly (a
- * plain object spread would overwrite the whole array), while merging scalar
- * keys (`network_access`) normally. Shared by the user- and version-scoped Codex
- * config writers so the two can't drift.
- */
 function mergeCodexSandboxWrite(existing, incoming) {
     const existingRoots = Array.isArray(existing?.writable_roots)
         ? existing.writable_roots
@@ -950,17 +710,8 @@ function mergeCodexSandboxWrite(existing, incoming) {
         ...(unionRoots.length > 0 ? { writable_roots: unionRoots } : {}),
     };
 }
-/**
- * Convert canonical permission set to Codex format.
- * Codex uses coarse-grained modes, so we infer the best fit.
- */
 export function convertToCodexFormat(set, cwd) {
     const result = {};
-    // Check for broad bash permissions -> suggest full-auto.
-    // Treat the bare blanket form "Bash" the same as "Bash(*)" / "Bash(**)";
-    // parseCanonicalPattern requires parens so "Bash" alone wouldn't match
-    // otherwise — the difference determines whether a pod runs unattended
-    // (approval_policy: 'never') or stalls on interactive approvals.
     const hasBroadBash = set.allow.some((p) => {
         if (BLANKET_BASH_FORMS.has(p))
             return true;
@@ -975,7 +726,6 @@ export function convertToCodexFormat(set, cwd) {
         result.approval_policy = 'on-request';
         result.sandbox_mode = 'workspace-write';
     }
-    // Check for network/web permissions
     const hasNetwork = set.allow.some((p) => {
         const parsed = parseCanonicalPattern(p);
         return parsed && (parsed.tool === 'websearch' || parsed.tool === 'webfetch');
@@ -985,23 +735,12 @@ export function convertToCodexFormat(set, cwd) {
             network_access: true,
         };
     }
-    // Baseline (unconditional): always grant the regenerable build/test/install
-    // caches as writable roots so `agents run codex` in workspace-write can build,
-    // test, and install without escalating to danger-full-access. Merged with
-    // network_access above when set; applyCodexPermissions unions these with any
-    // writable_roots the user configured directly.
     result.sandbox_workspace_write = {
         ...result.sandbox_workspace_write,
         writable_roots: codexDefaultWritableRoots(),
     };
     return result;
 }
-// ============================================================================
-// Read agent permissions from native configs
-// ============================================================================
-/**
- * Read Claude's current permissions from settings.json.
- */
 function readClaudePermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = scope === 'user'
@@ -1027,9 +766,6 @@ function readClaudePermissions(scope = 'user', cwd, options) {
         return null;
     }
 }
-/**
- * Read OpenCode's current permissions from opencode.jsonc.
- */
 function readOpenCodePermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = openCodeConfigPath(scope, cwd, home);
@@ -1052,9 +788,6 @@ function readOpenCodePermissions(scope = 'user', cwd, options) {
         return null;
     }
 }
-/**
- * Read Codex's current permissions from config.toml.
- */
 function readCodexPermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
     const configPath = scope === 'user'
@@ -1086,19 +819,6 @@ function readCodexPermissions(scope = 'user', cwd, options) {
         return null;
     }
 }
-/**
- * Read an agent's currently installed permissions.
- *
- * claude/opencode/codex return their NATIVE shape, because `agents permissions
- * list` renders those three specially — Codex especially, whose config records a
- * sandbox mode rather than a rule list, so its own fields say more than the
- * blanket grants that mode widens into.
- *
- * Every other allowlist-capable harness returns the canonical `PermissionSet`
- * that `PERMISSION_TARGETS` reads back. Before RUSH-2676 they returned `null`,
- * so permissions written for cursor, antigravity, grok, kimi, droid,
- * copilot, openclaw and hermes were reported as absent.
- */
 export function readAgentPermissions(agentId, scope = 'user', cwd, options) {
     switch (agentId) {
         case 'claude':
@@ -1111,23 +831,15 @@ export function readAgentPermissions(agentId, scope = 'user', cwd, options) {
             return readCanonicalPermissions(agentId, scope, cwd, options?.home);
     }
 }
-// ============================================================================
-// Apply permissions to agents
-// ============================================================================
-/**
- * Apply a permission set to Claude's settings.json.
- */
 export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
     const configDir = scope === 'user'
         ? path.join(HOME, '.claude')
         : path.join(cwd || process.cwd(), '.claude');
     const configPath = path.join(configDir, 'settings.json');
     try {
-        // Ensure directory exists
         if (!fs.existsSync(configDir)) {
             fs.mkdirSync(configDir, { recursive: true });
         }
-        // Read existing config
         let config = {};
         if (fs.existsSync(configPath)) {
             config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
@@ -1135,7 +847,6 @@ export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
         const newPermissions = convertToClaudeFormat(set);
         if (merge && config.permissions) {
             const existing = config.permissions;
-            // Rewrite stale Write(path) rules already installed in settings.json too.
             const mergedAllow = new Set([...(existing.allow || []).map(canonicalToClaudeRule), ...newPermissions.permissions.allow]);
             const mergedDeny = new Set([...(existing.deny || []).map(canonicalToClaudeRule), ...newPermissions.permissions.deny]);
             config.permissions = {
@@ -1153,12 +864,6 @@ export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Path OpenCode actually loads for global config:
- *   ~/.config/opencode/opencode.jsonc  (or .json)
- * Project: <cwd>/opencode.jsonc (or .json) at project root — not .opencode/.
- * See https://opencode.ai/docs/config/
- */
 export function openCodeConfigPath(scope, cwd, home = HOME) {
     if (scope === 'project') {
         const root = cwd || process.cwd();
@@ -1177,18 +882,13 @@ export function openCodeConfigPath(scope, cwd, home = HOME) {
     }
     return path.join(globalDir, 'opencode.jsonc');
 }
-/**
- * Apply a permission set to OpenCode's opencode.jsonc.
- */
 function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
     const configPath = openCodeConfigPath(scope, cwd);
     const configDir = path.dirname(configPath);
     try {
-        // Ensure directory exists
         if (!fs.existsSync(configDir)) {
             fs.mkdirSync(configDir, { recursive: true });
         }
-        // Read existing config
         let config = {};
         if (fs.existsSync(configPath)) {
             const content = stripJsonComments(fs.readFileSync(configPath, 'utf-8'));
@@ -1208,7 +908,6 @@ function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
         else {
             config.permission = newPermissions.permission;
         }
-        // Write without comments (they'll be lost)
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
         return { success: true };
     }
@@ -1216,27 +915,21 @@ function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Apply a permission set to Codex's config.toml.
- */
 function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
     const configDir = scope === 'user'
         ? path.join(HOME, '.codex')
         : path.join(cwd || process.cwd(), '.codex');
     const configPath = path.join(configDir, 'config.toml');
     try {
-        // Ensure directory exists
         if (!fs.existsSync(configDir)) {
             fs.mkdirSync(configDir, { recursive: true });
         }
-        // Read existing config
         let config = {};
         if (fs.existsSync(configPath)) {
             const content = fs.readFileSync(configPath, 'utf-8');
             config = TOML.parse(content);
         }
         const newPermissions = convertToCodexFormat(set, cwd);
-        // Merge or replace
         if (newPermissions.approval_policy) {
             config.approval_policy = newPermissions.approval_policy;
         }
@@ -1245,8 +938,6 @@ function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
         }
         if (newPermissions.sandbox_workspace_write) {
             const existing = config.sandbox_workspace_write;
-            // merge=false is a deliberate full replace (drops any user-custom roots);
-            // production sync always passes merge=true, taking the union path.
             config.sandbox_workspace_write = merge
                 ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                 : newPermissions.sandbox_workspace_write;
@@ -1259,9 +950,6 @@ function applyCodexPermissions(set, scope = 'user', cwd, merge = true) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Apply a permission set to an agent (global config).
- */
 function applyPermissionsToAgent(agentId, set, scope = 'user', cwd, merge = true) {
     switch (agentId) {
         case 'claude':
@@ -1274,10 +962,6 @@ function applyPermissionsToAgent(agentId, set, scope = 'user', cwd, merge = true
             return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
 }
-/**
- * Apply a permission set to a specific version's home directory.
- * This writes to {versionHome}/.{agent}/settings.json (or equivalent).
- */
 export function applyPermissionsToVersion(agentId, set, versionHome, merge = true, cwd) {
     if (!supports(agentId, 'allowlist').ok) {
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
@@ -1294,7 +978,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             const newPermissions = convertToClaudeFormat(set);
             if (merge && config.permissions) {
                 const existing = config.permissions;
-                // Rewrite stale Write(path) rules already installed in settings.json too.
                 const mergedAllow = new Set([...(existing.allow || []).map(canonicalToClaudeRule), ...newPermissions.permissions.allow]);
                 const mergedDeny = new Set([...(existing.deny || []).map(canonicalToClaudeRule), ...newPermissions.permissions.deny]);
                 const mergedDirs = new Set([...(existing.additionalDirectories || []), ...(newPermissions.permissions.additionalDirectories || [])]);
@@ -1314,8 +997,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             return { success: true };
         }
         if (agentId === 'opencode') {
-            // OpenCode loads ~/.config/opencode/opencode.jsonc under the version home
-            // (HOME isolation), not ~/.opencode/opencode.jsonc.
             const configPath = openCodeConfigPath('user', undefined, versionHome);
             fs.mkdirSync(path.dirname(configPath), { recursive: true });
             let config = {};
@@ -1356,8 +1037,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             }
             if (newPermissions.sandbox_workspace_write) {
                 const existing = config.sandbox_workspace_write;
-                // merge=false is a deliberate full replace (drops any user-custom roots);
-                // production sync always passes merge=true, taking the union path.
                 config.sandbox_workspace_write = merge
                     ? mergeCodexSandboxWrite(existing, newPermissions.sandbox_workspace_write)
                     : newPermissions.sandbox_workspace_write;
@@ -1460,14 +1139,13 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             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 */ }
+                catch { }
             }
             const converted = convertToCursorFormat(set);
             if (merge && config.permissions && typeof config.permissions === 'object') {
@@ -1549,10 +1227,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             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)) {
@@ -1574,8 +1248,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
                 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;
@@ -1627,12 +1299,6 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
         return { success: false, error: err.message };
     }
 }
-// ============================================================================
-// Export canonical format from agent
-// ============================================================================
-/**
- * Convert Claude permissions back to canonical format.
- */
 export function claudeToCanonical(perms) {
     const result = {
         name: 'exported',
@@ -1644,9 +1310,6 @@ export function claudeToCanonical(perms) {
     }
     return result;
 }
-/**
- * Convert OpenCode permissions back to canonical format.
- */
 export function openCodeToCanonical(perms) {
     const allow = [];
     const deny = [];
@@ -1664,9 +1327,6 @@ export function openCodeToCanonical(perms) {
         deny: deny.length > 0 ? deny : undefined,
     };
 }
-/**
- * Convert Codex permissions back to canonical format (approximation).
- */
 export function codexToCanonical(perms) {
     const allow = [];
     if (perms.approval_policy === 'never' || perms.sandbox_mode === 'danger-full-access') {
@@ -1688,14 +1348,6 @@ export function codexToCanonical(perms) {
         allow,
     };
 }
-/**
- * Export permissions from a specific config file path to canonical format,
- * auto-detecting the harness from the path.
- *
- * Detection walks `PERMISSION_TARGETS` and matches each harness's own declared
- * filename + parent directory, so it covers all 13 rather than the three
- * hardcoded `.claude`/`.opencode`/`.codex` fragments it used to know about.
- */
 export function exportPermissionsFromPath(filePath) {
     if (!fs.existsSync(filePath))
         return null;
@@ -1704,18 +1356,11 @@ export function exportPermissionsFromPath(filePath) {
         return null;
     return PERMISSION_TARGETS[agentId].toCanonical(filePath);
 }
-/**
- * Which harness owns `filePath`, by comparing against the trailing path segments
- * each registry target declares. Longer (more specific) suffixes win, so
-  */
 export function detectPermissionAgentFromPath(filePath) {
     const normalized = path.resolve(filePath).split(path.sep).join('/');
     let best = null;
     for (const [agent, target] of Object.entries(PERMISSION_TARGETS)) {
         const agentId = agent;
-        // `altSuffixes` first: home()/project() may probe the filesystem to choose
-        // between accepted spellings, and with an empty root that probe resolves
-        // against process.cwd() -- so detection must not depend on it.
         const candidates = [
             ...(target.altSuffixes ?? []),
             target.home(''),
@@ -1733,9 +1378,6 @@ export function detectPermissionAgentFromPath(filePath) {
     }
     return best?.agentId ?? null;
 }
-/**
- * Save a permission set to central storage.
- */
 function savePermissionSet(set) {
     ensurePermissionsDir();
     const filePath = safeJoin(path.join(getUserPermissionsDir(), 'groups'), set.name + '.yml');
@@ -1753,11 +1395,7 @@ function savePermissionSet(set) {
         return { success: false, error: err.message };
     }
 }
-/** Name used for the default permission set in central storage. */
 const DEFAULT_PERMISSION_SET_NAME = 'default';
-/**
- * Get the default permission set from central storage.
- */
 export function getDefaultPermissionSet() {
     const existing = getPermissionSet(DEFAULT_PERMISSION_SET_NAME);
     if (existing) {
@@ -1770,10 +1408,6 @@ export function getDefaultPermissionSet() {
         deny: [],
     };
 }
-/**
- * Compute diff between existing and new permissions.
- * Returns { added, existing, removed } for both allow and deny rules.
- */
 export function computePermissionsDiff(existing, incoming) {
     const existingAllowSet = new Set(existing.allow);
     const existingDenySet = new Set(existing.deny || []);
@@ -1787,9 +1421,6 @@ export function computePermissionsDiff(existing, incoming) {
         deny: { added: denyAdded, existing: denyExisting },
     };
 }
-/**
- * Merge incoming permissions into existing, deduplicating.
- */
 export function mergePermissionSets(existing, incoming) {
     const allowSet = new Set([...existing.allow, ...incoming.allow]);
     const denySet = new Set([...(existing.deny || []), ...(incoming.deny || [])]);
@@ -1805,31 +1436,10 @@ export function mergePermissionSets(existing, incoming) {
     }
     return result;
 }
-/**
- * Save the default permission set.
- */
 export function saveDefaultPermissionSet(set) {
     set.name = DEFAULT_PERMISSION_SET_NAME;
     return savePermissionSet(set);
 }
-// ============================================================================
-// Content-drift check (agents doctor, PHNX-3504)
-// ============================================================================
-/**
- * Harnesses whose native permission file carries a per-rule allow/deny list the
- * writer emits verbatim, so `agents doctor` can verify a group's rules survived
- * into the version home rule-for-rule. The compare is done in the harness's OWN
- * native vocabulary (Cursor `Shell(...)`, Droid command arrays, …) — NOT
- * canonical — because every target's canonical round-trip is lossy
- * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
- * would false-diff a correctly-synced home.
- *
- * Every other allowlist harness (codex/grok/kimi/antigravity/hermes/copilot)
- * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
- * approval, or a split/merged pattern — with no faithful per-group provenance, so
- * doctor stays presence-only there and says so (`detail: 'format cannot verify
- * content'`) rather than faking `ok`.
- */
 export const PERMISSIONS_REPRESENTABLE = new Set([
     'claude',
     'opencode',
@@ -1848,7 +1458,6 @@ function readJsonFileSafe(filePath) {
         return null;
     }
 }
-/** allow/deny rule strings in `agent`'s NATIVE vocabulary from its version home. */
 function homeNativePermissionRules(agent, versionHome) {
     const target = PERMISSION_TARGETS[agent];
     if (!target)
@@ -1895,7 +1504,6 @@ function homeNativePermissionRules(agent, versionHome) {
             return null;
     }
 }
-/** allow/deny rule strings in `agent`'s NATIVE vocabulary the writer WOULD emit. */
 function expectedNativePermissionRules(agent, set) {
     switch (agent) {
         case 'claude': {
@@ -1930,23 +1538,12 @@ function expectedNativePermissionRules(agent, set) {
             return { allow: new Set(), deny: new Set() };
     }
 }
-/**
- * True when permission GROUP `groupName` is faithfully present in `agent`'s
- * version home — every rule the group renders into that harness's native format
- * is on disk. Only meaningful for {@link PERMISSIONS_REPRESENTABLE} agents (the
- * caller keeps the lossy harnesses presence-only); returns true for a lossy
- * harness or an empty/header group so the caller does not down-rank it.
- *
- * The expected rules are re-derived from the CURRENT source group every call
- * (never a stored hash), so a rule edited/added in the source group surfaces as
- * drift even though the group name is unchanged (PHNX-3504).
- */
 export function permissionsGroupMatches(agent, versionHome, groupName) {
     if (!PERMISSIONS_REPRESENTABLE.has(agent))
         return true;
     const expected = expectedNativePermissionRules(agent, buildPermissionsFromGroups([groupName]));
     if (expected.allow.size === 0 && expected.deny.size === 0)
-        return true; // header / empty group
+        return true;
     const home = homeNativePermissionRules(agent, versionHome);
     if (!home)
         return false;