dsh-permission-rules 0.2.0 → 0.4.0

package/lib/types/runtime.js

@@ -4,15 +4,17 @@
  * `tools/pre-execute` listener that turns a first-match hit into a
  * deny/ask decision (and NEVER short-circuits on allow or passthrough),
  * the `permissionRules/decision` audit event, the `/rules` session command
- * (`list | reload | decisions [n] | test <tool> <json>`), and
- * Chokidar-driven reloads. Every registration is an effect.
+ * (`list | reload | decisions [n] | test [flags] <tool> <json>`), and
+ * Chokidar-driven reloads (effective rule files plus candidate watches on
+ * expected-but-absent files, so mid-session creation is adopted). Every
+ * registration is an effect.
  * @module dsh-permission-rules/runtime
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import chokidar from 'chokidar';
 import { resolveConfig } from "./config.js";
-import { compileRules, compileRulesChain, describeRule, findUnreachableRules, matchRules, parseRulesDocument, RuleError } from "./rules.js";
+import { compileRules, compileRulesChain, describeRule, findUnreachableRules, matchRules, normalizeWorkspacePath, parseRulesDocument, PLATFORMS, RuleError } from "./rules.js";
 import { DESCRIBE_TOKENS, UI_PROSE } from "./prose.js";
 export const name = 'permission-rules';
 /** Services required before the plugin mounts. */
@@ -26,7 +28,7 @@ export class PermissionRulesRuntime {
     config;
     /** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
     byCwd = new Map();
-    /** Live watchers per rule-file path, with the cwds each serves. */
+    /** Live watchers per watched path (rule file or candidate ancestor directory), with the cwds each serves. */
     watchers = new Map();
     /** Debounce timers per rule-file path. */
     timers = new Map();
@@ -108,6 +110,17 @@ export class PermissionRulesRuntime {
             throw error instanceof RuleError ? error : new RuleError(`cannot load ${sources.join(', ')}: ${message}`);
         }
     }
+    /**
+     * Canonical per-workspace cache key: the resolved root, case-folded on
+     * Windows so differently-spelled paths to the same workspace share one
+     * cache entry and one watcher set instead of doubling both.
+     * @param cwd - the session's absolute workspace root.
+     * @returns the canonical key.
+     */
+    cacheKey(cwd) {
+        const resolved = resolve(cwd);
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    }
     /**
      * The rules in effect for one cwd, loading on first use. Under
      * `badFilePolicy: 'fail'` a bad initial load throws on EVERY use (the
@@ -119,27 +132,28 @@ export class PermissionRulesRuntime {
      * @returns the loaded rules.
      */
     rulesFor(cwd) {
-        const existing = this.byCwd.get(cwd);
+        const key = this.cacheKey(cwd);
+        const existing = this.byCwd.get(key);
         if (existing !== undefined) {
             if (existing.failed === true) {
                 throw new RuleError(existing.lastError ?? `rule load failed for ${cwd}`);
             }
-            this.byCwd.delete(cwd);
-            this.byCwd.set(cwd, existing);
+            this.byCwd.delete(key);
+            this.byCwd.set(key, existing);
             return existing;
         }
-        this.evictIfFull(cwd);
+        this.evictIfFull(key);
         try {
             const loaded = this.load(cwd);
-            this.byCwd.set(cwd, loaded);
-            this.reconcileWatch(cwd, loaded.sources);
+            this.byCwd.set(key, loaded);
+            this.reconcileWatch(key, loaded.sources);
             return loaded;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             const sources = this.resolveSources(cwd);
-            this.byCwd.set(cwd, { cwd, sources, compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
-            this.reconcileWatch(cwd, sources);
+            this.byCwd.set(key, { cwd, sources, compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
+            this.reconcileWatch(key, sources);
             throw error;
         }
     }
@@ -151,32 +165,45 @@ export class PermissionRulesRuntime {
      * @param cwd - the workspace root.
      */
     reload(cwd) {
-        const previous = this.byCwd.get(cwd);
+        const key = this.cacheKey(cwd);
+        const previous = this.byCwd.get(key);
         try {
             const loaded = this.load(cwd);
-            this.byCwd.set(cwd, loaded);
-            this.reconcileWatch(cwd, loaded.sources);
+            this.byCwd.set(key, loaded);
+            this.reconcileWatch(key, loaded.sources);
             this.ctx.logger.info(`permission-rules: reloaded ${loaded.compiled.rules.length} rule(s) from ${loaded.sources.join(', ') || '(empty rule set)'} for ${cwd}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             this.ctx.logger.warn(`permission-rules: reload failed for ${cwd}: ${message} (keeping previous rules)`);
             if (previous !== undefined)
-                this.byCwd.set(cwd, { ...previous, lastError: message });
-            else
-                this.byCwd.set(cwd, { cwd, sources: this.resolveSources(cwd), compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
+                this.byCwd.set(key, { ...previous, lastError: message });
+            else {
+                const sources = this.resolveSources(cwd);
+                this.byCwd.set(key, { cwd, sources, compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
+                this.reconcileWatch(key, sources);
+            }
         }
     }
-    /** The match context `when` conditions evaluate against. */
-    matchContext() {
-        return { platform: process.platform, env: process.env };
+    /**
+     * The match context `when`/`agents` conditions evaluate against: host
+     * facts plus the caller's agent-identity candidates derived from the
+     * session header (`main` for top-level sessions, `subagent` for
+     * subagent children, `preset:<name>` when a preset composed the agent).
+     * @param exec - the pending call whose caller supplies the identity.
+     */
+    matchContext(exec) {
+        return { platform: process.platform, env: process.env, agents: agentCandidates(exec?.agent) };
     }
     /**
      * The `tools/pre-execute` listener. A deny/ask hit returns the decision
      * (first match wins, short-circuiting downstream listeners); an allow hit
      * and a passthrough MUST delegate via `next()` so later listeners keep
-     * their say. Audit is appended once the final outcome is known, so the
-     * recorded `outcome` matches what the waterfall settled on.
+     * their say. Under `enforce: false` (dry-run) a deny/ask hit also
+     * delegates — the record keeps the would-be action with `dryRun: true`
+     * and the actual downstream outcome. Audit is appended once the final
+     * outcome is known, so the recorded `outcome` matches what the waterfall
+     * settled on.
      * @param exec - the pending call (name, parsed arguments, caller agent).
      * @param next - the downstream chain.
      * @returns the pre-execute decision.
@@ -184,12 +211,18 @@ export class PermissionRulesRuntime {
     async preExecute(exec, next) {
         const cwd = exec.agent?.session.header.cwd ?? process.cwd();
         const loaded = this.rulesFor(cwd);
-        const hit = matchRules(loaded.compiled, exec.name, exec.arguments, cwd, this.matchContext());
+        const hit = matchRules(loaded.compiled, exec.name, exec.arguments, cwd, this.matchContext(exec));
         if (hit === undefined || hit.rule.action === 'allow') {
             const decision = await next();
             this.audit(exec, loaded, hit, decision.kind);
             return decision;
         }
+        if (!this.config.enforce) {
+            // Dry-run: match the rule, log what it WOULD do, and delegate.
+            const decision = await next();
+            this.audit(exec, loaded, hit, decision.kind, true);
+            return decision;
+        }
         const outcome = hit.rule.action;
         this.audit(exec, loaded, hit, outcome);
         if (outcome === 'deny')
@@ -202,15 +235,18 @@ export class PermissionRulesRuntime {
      * envelope's `ignorable: true` marker so any harness build can load the
      * log (readers that do not know the type skip the audit record instead of
      * refusing the session). `source` names the matched rule's file, or the
-     * nearest effective file on a passthrough. Agentless calls have no
-     * session to audit; append failures are contained so an audit hiccup can
-     * never change a permission decision.
+     * nearest effective file on a passthrough; `cwd` names the workspace the
+     * rules were resolved for; `dryRun` marks would-be deny/ask hits under
+     * `enforce: false`. Agentless calls have no session to audit; append
+     * failures are contained so an audit hiccup can never change a
+     * permission decision.
      * @param exec - the pending call.
      * @param loaded - the rules in effect.
      * @param hit - the first matching rule, or undefined for passthrough.
      * @param outcome - the final pre-execute decision.
+     * @param dryRun - mark the record as a would-be decision (dry-run mode).
      */
-    audit(exec, loaded, hit, outcome) {
+    audit(exec, loaded, hit, outcome, dryRun = false) {
         if (this.config.audit === 'hits' && hit === undefined)
             return;
         const agent = exec.agent;
@@ -224,7 +260,9 @@ export class PermissionRulesRuntime {
                 source: hit === undefined ? (loaded.sources[0] ?? '') : (loaded.sources[hit.rule.sourceIndex] ?? ''),
                 action: hit === undefined ? 'passthrough' : hit.rule.action,
                 outcome,
+                cwd: loaded.cwd,
                 ...hit !== undefined ? { ruleIndex: hit.ruleIndex, reason: hit.rule.reason } : {},
+                ...dryRun ? { dryRun: true } : {},
             }, { ignorable: true });
         }
         catch (error) {
@@ -234,8 +272,9 @@ export class PermissionRulesRuntime {
     /**
      * Execute the `/rules` command: bare `/rules` lists the active rules and
      * their sources; `/rules reload` re-reads the chain; `/rules decisions
-     * [n]` shows the session's audit trail; `/rules test <tool> <json>`
-     * dry-evaluates the rules against a hypothetical call. Command output
+     * [n]` shows the session's audit trail; `/rules test [flags] <tool>
+     * <json>` dry-evaluates the rules against a hypothetical call (flags
+     * override the workspace, host env, and agent identity). Command output
      * stays in the UI — nothing here is injected into the model context.
      * @param invocation - the received command invocation.
      * @returns the command result shown to the user.
@@ -250,13 +289,15 @@ export class PermissionRulesRuntime {
             if (rest.length > 0)
                 return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
             this.reload(cwd);
-            const reloaded = this.byCwd.get(cwd);
+            const reloaded = this.byCwd.get(this.cacheKey(cwd));
             if (reloaded?.lastError !== undefined)
                 return { kind: 'error', text: prose.reloadFailed(reloaded.lastError) };
             const rules = reloaded?.compiled.rules ?? [];
             const source = reloaded === undefined || reloaded.sources.length === 0 ? prose.emptySource : reloaded.sources.join(', ');
             return { kind: 'success', text: prose.reloaded(rules.length, source) };
         }
+        if (verb === 'list' && rest.length > 0)
+            return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
         if (verb === 'decisions') {
             if (rest.length > 1)
                 return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
@@ -270,34 +311,9 @@ export class PermissionRulesRuntime {
             return this.decisionsCommand(invocation, count, prose);
         }
         if (verb === 'test') {
-            const verbText = verbRaw ?? '';
-            const restLine = raw.length > verbText.length ? raw.slice(verbText.length).trim() : '';
-            const match = /^(\S+)\s*(.*)$/s.exec(restLine);
-            const tool = match?.[1];
-            const jsonText = match?.[2] ?? '';
-            if (tool === undefined || tool.length === 0)
-                return { kind: 'error', text: prose.testUsage };
-            let args;
-            try {
-                args = jsonText.length > 0 ? JSON.parse(jsonText) : {};
-            }
-            catch {
-                return { kind: 'error', text: prose.testBadJson(jsonText) };
-            }
-            let loaded;
-            try {
-                loaded = this.rulesFor(cwd);
-            }
-            catch (error) {
-                return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
-            }
-            const hit = matchRules(loaded.compiled, tool, args, cwd, this.matchContext());
-            return {
-                kind: 'success',
-                text: hit === undefined ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason),
-            };
+            return this.testCommand(raw, verbRaw ?? '', invocation, cwd, prose);
         }
-        if (verb !== '')
+        if (verb !== '' && verb !== 'list')
             return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
         let loaded;
         try {
@@ -312,7 +328,8 @@ export class PermissionRulesRuntime {
         }
         else {
             lines.push(prose.rulesHeader(loaded.compiled.rules.length, loaded.sources, cwd));
-            lines.push(...loaded.compiled.rules.map(rule => describeRule(rule, DESCRIBE_TOKENS[this.config.language])));
+            const multiSource = loaded.sources.length > 1;
+            lines.push(...loaded.compiled.rules.map(rule => describeRule(rule, DESCRIBE_TOKENS[this.config.language], multiSource ? this.displaySource(loaded.sources[rule.sourceIndex] ?? '', cwd) : undefined)));
             const unreachable = findUnreachableRules(loaded.compiled);
             if (unreachable.length > 0)
                 lines.push(prose.unreachableWarning(unreachable.map(index => index + 1)));
@@ -320,9 +337,101 @@ export class PermissionRulesRuntime {
         if (loaded.lastError !== undefined) {
             lines.push(prose.lastReloadWarning(loaded.lastError));
         }
+        if (!this.config.enforce) {
+            lines.push(prose.dryRunNotice);
+        }
         lines.push(prose.usage);
         return { kind: 'success', text: lines.join('\n') };
     }
+    /**
+     * Execute `/rules test` with optional leading flags: `--cwd <dir>`
+     * evaluates against that workspace (rule discovery AND path
+     * normalization), `--env KEY=VALUE` (repeatable) overrides host env for
+     * `when.env` matching, `--agent <selector>` (repeatable) supplies
+     * agent-identity candidates for the `agents` dimension, and
+     * `--platform <name>` overrides the host platform for `when.platform`.
+     * The JSON argument tail is kept verbatim, so quoted JSON survives
+     * unchanged.
+     * @param raw - the full raw command input.
+     * @param verbRaw - the verb as typed.
+     * @param invocation - the received command invocation (session agent).
+     * @param sessionCwd - the session's workspace root.
+     * @param prose - localized output vocabulary.
+     * @returns the dry-evaluation result.
+     */
+    testCommand(raw, verbRaw, invocation, sessionCwd, prose) {
+        let rest = raw.length > verbRaw.length ? raw.slice(verbRaw.length).trim() : '';
+        const envOverrides = {};
+        const agentSelectors = [];
+        let testCwd;
+        let testPlatform;
+        let parsed = nextToken(rest);
+        while (parsed !== undefined && parsed.token.startsWith('--')) {
+            const flag = parsed.token;
+            const value = nextToken(parsed.rest);
+            if (value === undefined || value.token.startsWith('--')) {
+                return { kind: 'error', text: prose.testBadFlag(flag) };
+            }
+            if (flag === '--cwd') {
+                testCwd = isAbsolute(value.token) ? value.token : resolve(sessionCwd, value.token);
+            }
+            else if (flag === '--env') {
+                const equals = value.token.indexOf('=');
+                if (equals <= 0)
+                    return { kind: 'error', text: prose.testBadFlag(`${flag} ${value.token}`) };
+                envOverrides[value.token.slice(0, equals)] = value.token.slice(equals + 1);
+            }
+            else if (flag === '--agent') {
+                agentSelectors.push(value.token);
+            }
+            else if (flag === '--platform') {
+                if (!PLATFORMS.includes(value.token))
+                    return { kind: 'error', text: prose.testBadPlatform(value.token) };
+                testPlatform = value.token;
+            }
+            else {
+                return { kind: 'error', text: prose.testUnknownFlag(flag) };
+            }
+            rest = value.rest;
+            parsed = nextToken(rest);
+        }
+        const tool = parsed?.token;
+        const jsonText = parsed === undefined ? '' : parsed.rest.trim();
+        if (tool === undefined || tool.length === 0)
+            return { kind: 'error', text: prose.testUsage };
+        let args;
+        try {
+            args = jsonText.length > 0 ? JSON.parse(jsonText) : {};
+        }
+        catch {
+            return { kind: 'error', text: prose.testBadJson(jsonText) };
+        }
+        const evalCwd = testCwd ?? sessionCwd;
+        let loaded;
+        try {
+            loaded = this.rulesFor(evalCwd);
+        }
+        catch (error) {
+            return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
+        }
+        const context = {
+            platform: testPlatform ?? process.platform,
+            env: Object.keys(envOverrides).length === 0 ? process.env : { ...process.env, ...envOverrides },
+            agents: agentSelectors.length > 0 ? agentSelectors : agentCandidates(invocation.agent),
+        };
+        const hit = matchRules(loaded.compiled, tool, args, evalCwd, context);
+        return {
+            kind: 'success',
+            text: hit === undefined ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason),
+        };
+    }
+    /** Render one rule-file source for per-rule attribution: workspace-relative when inside the cwd, raw otherwise. */
+    displaySource(source, cwd) {
+        if (source.length === 0)
+            return '';
+        const relative = normalizeWorkspacePath(cwd, source, this.config.caseInsensitivePaths);
+        return relative.length > 0 ? relative : source;
+    }
     /** Render the session's `permissionRules/decision` audit trail, newest last. */
     decisionsCommand(invocation, count, prose) {
         const decisions = invocation.agent.session.events.filter(event => event.type === 'permissionRules/decision');
@@ -332,7 +441,7 @@ export class PermissionRulesRuntime {
         const lines = [prose.decisionsHeader(shown.length, decisions.length)];
         for (const event of shown) {
             const data = event.data;
-            lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason));
+            lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason, data.dryRun === true, data.outcome));
         }
         return { kind: 'success', text: lines.join('\n') };
     }
@@ -406,21 +515,102 @@ export class PermissionRulesRuntime {
      * Rebind `cwd` to its current rule-source chain. When a concrete source
      * left the chain (deleted file, fallback switch), detach the workspace
      * from watchers serving other sources and close the ones left empty, so
-     * long-running hosts cannot accumulate stale watchers. An empty chain (no
-     * rule file in effect) keeps the previous watchers alive: they own the
-     * "file recreated → adopted" signal, and the workspace-cache bound keeps
-     * the set of such watchers finite.
+     * long-running hosts cannot accumulate stale watchers. Expected-but-absent
+     * rule files (the project file when it is not effective, and a configured
+     * fallback that does not exist) are covered by candidate watchers on
+     * their deepest existing ancestor directory, so a file created
+     * mid-session is adopted without a manual `/rules reload`. With
+     * `searchUp`, only the immediate cwd-level candidate is watched —
+     * deeper ancestors are discovered on the next load.
      */
     reconcileWatch(cwd, sources) {
-        if (sources.length === 0)
-            return;
         for (const [watchedSource, entry] of this.watchers) {
-            if (!sources.includes(watchedSource))
+            if (!sources.includes(watchedSource)) {
                 entry.cwds.delete(cwd);
+                entry.candidates?.delete(cwd);
+            }
         }
         this.pruneWatchers();
         for (const source of sources)
             this.attachWatch(cwd, source);
+        for (const candidate of this.candidateSources(cwd)) {
+            if (sources.includes(candidate) || existsSync(candidate))
+                continue;
+            this.attachCandidateWatch(cwd, candidate);
+        }
+    }
+    /**
+     * The rule-file paths a workspace COULD be served by: the project file
+     * (an absolute `rulesFile`, or `<cwd>/<rulesFile>` — the immediate level
+     * only under `searchUp`) plus the configured fallback.
+     */
+    candidateSources(cwd) {
+        const candidates = [isAbsolute(this.config.rulesFile) ? this.config.rulesFile : join(cwd, this.config.rulesFile)];
+        const fallback = this.config.fallbackPath;
+        if (fallback !== undefined)
+            candidates.push(isAbsolute(fallback) ? fallback : resolve(fallback));
+        return candidates;
+    }
+    /**
+     * Watch one expected-but-absent rule file through its deepest existing
+     * ancestor directory. Chokidar cannot reliably watch a missing path when
+     * its parent is also missing, but directory watching is dependable; every
+     * relevant event re-checks existence and only triggers a reload once the
+     * candidate actually appeared, so unrelated workspace activity while the
+     * file is absent costs a stat, not a reload.
+     */
+    attachCandidateWatch(cwd, candidate) {
+        if (!this.config.watch)
+            return;
+        const dir = this.deepestExistingDir(dirname(candidate));
+        const existing = this.watchers.get(dir);
+        if (existing !== undefined) {
+            existing.cwds.add(cwd);
+            existing.candidates?.set(cwd, candidate);
+            return;
+        }
+        const cwds = new Set([cwd]);
+        const candidates = new Map([[cwd, candidate]]);
+        const watcher = chokidar.watch(dir, { persistent: true, ignoreInitial: true });
+        const onEvent = () => this.scheduleReload(dir);
+        watcher.on('add', onEvent);
+        watcher.on('addDir', onEvent);
+        watcher.on('change', onEvent);
+        watcher.on('unlink', onEvent);
+        watcher.on('unlinkDir', onEvent);
+        watcher.on('error', (error) => {
+            this.ctx.logger.warn(`permission-rules: watcher error on ${dir}: ${String(error)}`);
+        });
+        this.watchers.set(dir, {
+            cwds,
+            candidates,
+            close: () => {
+                void watcher.close().catch((error) => {
+                    this.ctx.logger.warn(`permission-rules: failed to close watcher on ${dir}: ${String(error)}`);
+                });
+            },
+        });
+        this.ctx.effect(() => () => {
+            this.watchers.get(dir)?.close();
+            this.watchers.delete(dir);
+            const timer = this.timers.get(dir);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                this.timers.delete(dir);
+            }
+        });
+    }
+    /** The deepest existing ancestor directory of `dir` (candidate watchers target directories, never missing files). */
+    deepestExistingDir(dir) {
+        let current = dir;
+        for (;;) {
+            if (existsSync(current))
+                return current;
+            const parent = dirname(current);
+            if (parent === current)
+                return current;
+            current = parent;
+        }
     }
     /** Close and drop watchers whose workspace sets are empty, clearing their debounce timers. */
     pruneWatchers() {
@@ -450,8 +640,10 @@ export class PermissionRulesRuntime {
         if (oldest === undefined)
             return;
         this.byCwd.delete(oldest);
-        for (const entry of this.watchers.values())
+        for (const entry of this.watchers.values()) {
             entry.cwds.delete(oldest);
+            entry.candidates?.delete(oldest);
+        }
         this.pruneWatchers();
     }
     /** Number of live watchers, for observability and tests. */
@@ -462,15 +654,27 @@ export class PermissionRulesRuntime {
     pendingReloadCount() {
         return this.timers.size;
     }
-    /** Debounce watch events into one reload per stability window. */
+    /**
+     * Debounce watch events into one reload per stability window. A
+     * candidate (directory) watcher only reloads a cwd once its expected
+     * file actually exists — unrelated events while the file is absent are
+     * dropped before any re-read.
+     */
     scheduleReload(source) {
         const existing = this.timers.get(source);
         if (existing !== undefined)
             clearTimeout(existing);
         const timer = setTimeout(() => {
             this.timers.delete(source);
-            for (const cwd of this.watchers.get(source)?.cwds ?? [])
+            const entry = this.watchers.get(source);
+            if (entry === undefined)
+                return;
+            for (const cwd of entry.cwds) {
+                const candidate = entry.candidates?.get(cwd);
+                if (candidate !== undefined && !existsSync(candidate))
+                    continue;
                 this.reload(cwd);
+            }
         }, this.config.watchStabilityThresholdMs);
         this.timers.set(source, timer);
     }
@@ -490,8 +694,59 @@ export function apply(ctx, config) {
     ctx.commands.register({
         name: 'rules',
         description: 'list, reload, audit, or dry-test the active permission rules for this workspace',
-        input: { hint: '[reload | decisions [n] | test <tool> <json-args>]' },
+        input: { hint: '[list | reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] [--platform <name>] <tool> <json-args>]' },
         handler: invocation => runtime.command(invocation),
     });
 }
+/**
+ * Identity candidates for the `agents` match dimension, derived from the
+ * caller agent's session header: `main` for top-level sessions, `subagent`
+ * for subagent children (`header.origin === 'subagent'`), and
+ * `preset:<name>` when a preset composed the agent. No agent (or an
+ * unidentifiable one) yields no candidates, so agent-scoped rules fail
+ * closed instead of matching an unknown caller.
+ * @param agent - the calling agent, when the call has one.
+ * @returns the candidate strings, in a stable order.
+ */
+function agentCandidates(agent) {
+    if (agent === undefined)
+        return [];
+    const header = agent.session.header;
+    const candidates = [header.origin === 'subagent' ? 'subagent' : 'main'];
+    if (typeof header.agentPreset === 'string' && header.agentPreset.length > 0)
+        candidates.push(`preset:${header.agentPreset}`);
+    return candidates;
+}
+/**
+ * Pull the next whitespace-delimited argument from a command tail,
+ * honoring single/double quotes (with backslash escapes) so JSON blobs and
+ * paths with spaces survive. The remainder is returned verbatim — the JSON
+ * argument tail of `/rules test` is never re-tokenized.
+ * @param text - the remaining command tail.
+ * @returns the token plus the untouched remainder, or undefined when only
+ *   whitespace remains.
+ */
+function nextToken(text) {
+    let i = 0;
+    while (i < text.length && /\s/.test(text[i]))
+        i += 1;
+    if (i >= text.length)
+        return undefined;
+    const quote = text[i];
+    if (quote === '"' || quote === "'") {
+        let end = i + 1;
+        while (end < text.length && text[end] !== quote) {
+            if (text[end] === '\\')
+                end += 1;
+            end += 1;
+        }
+        if (end >= text.length)
+            return { token: text.slice(i + 1), rest: '' };
+        return { token: text.slice(i + 1, end), rest: text.slice(end + 1) };
+    }
+    let end = i;
+    while (end < text.length && !/\s/.test(text[end]))
+        end += 1;
+    return { token: text.slice(i, end), rest: text.slice(end) };
+}
 //# sourceMappingURL=runtime.js.map