dsh-permission-rules 0.2.0 → 0.4.0

package/src/runtime.ts

@@ -4,8 +4,10 @@
  * `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
  */
 
@@ -17,7 +19,7 @@ import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands
 import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
 import { resolveConfig } from './config.ts'
 import type { Config, ResolvedConfig } from './config.ts'
-import { compileRules, compileRulesChain, describeRule, findUnreachableRules, matchRules, parseRulesDocument, RuleError } from './rules.ts'
+import { compileRules, compileRulesChain, describeRule, findUnreachableRules, matchRules, normalizeWorkspacePath, parseRulesDocument, PLATFORMS, RuleError } from './rules.ts'
 import type { CompileOptions, CompiledRuleset, MatchContext, RuleHit } from './rules.ts'
 import { DESCRIBE_TOKENS, UI_PROSE } from './prose.ts'
 import type { UiProse } from './prose.ts'
@@ -41,6 +43,13 @@ interface LoadedRules {
   readonly failed?: true
 }
 
+/** One live watcher: rule-file watchers key by the file path; candidate watchers key by an ancestor directory and map each cwd to the absent file they are waiting for. */
+interface WatcherEntry {
+  readonly cwds: Set<string>
+  readonly close: () => void
+  readonly candidates?: Map<string, string>
+}
+
 /**
  * State and behavior. One instance per plugin mount; disposals are owned by
  * the watcher/timer effects registered in {@link apply}.
@@ -49,8 +58,8 @@ export class PermissionRulesRuntime {
   /** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
   private readonly byCwd = new Map<string, LoadedRules>()
 
-  /** Live watchers per rule-file path, with the cwds each serves. */
-  private readonly watchers = new Map<string, { readonly cwds: Set<string>; readonly close: () => void }>()
+  /** Live watchers per watched path (rule file or candidate ancestor directory), with the cwds each serves. */
+  private readonly watchers = new Map<string, WatcherEntry>()
 
   /** Debounce timers per rule-file path. */
   private readonly timers = new Map<string, ReturnType<typeof setTimeout>>()
@@ -132,6 +141,18 @@ export class PermissionRulesRuntime {
     }
   }
 
+  /**
+   * 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.
+   */
+  private cacheKey(cwd: string): string {
+    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
@@ -143,26 +164,27 @@ export class PermissionRulesRuntime {
    * @returns the loaded rules.
    */
   rulesFor(cwd: string): LoadedRules {
-    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: unknown) {
       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
     }
   }
@@ -175,31 +197,45 @@ export class PermissionRulesRuntime {
    * @param cwd - the workspace root.
    */
   reload(cwd: string): void {
-    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: unknown) {
       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 })
+      if (previous !== undefined) 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. */
-  private matchContext(): 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.
+   */
+  private matchContext(exec?: ToolExecution): MatchContext {
+    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.
@@ -207,12 +243,18 @@ export class PermissionRulesRuntime {
   async preExecute(exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision> {
     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: DecisionOutcome = hit.rule.action
     this.audit(exec, loaded, hit, outcome)
     if (outcome === 'deny') return { kind: 'deny', reason: hit.rule.reason }
@@ -225,15 +267,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: ToolExecution, loaded: LoadedRules, hit: RuleHit | undefined, outcome: DecisionOutcome): void {
+  audit(exec: ToolExecution, loaded: LoadedRules, hit: RuleHit | undefined, outcome: DecisionOutcome, dryRun = false): void {
     if (this.config.audit === 'hits' && hit === undefined) return
     const agent = exec.agent
     if (agent === undefined) return
@@ -244,7 +289,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 as const } : {},
       }, { ignorable: true })
     } catch (error: unknown) {
       this.ctx.logger.warn(`permission-rules: audit append failed: ${String(error)}`)
@@ -254,8 +301,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.
@@ -269,12 +317,13 @@ export class PermissionRulesRuntime {
     if (verb === 'reload') {
       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()) }
       let count = 10
@@ -286,31 +335,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: unknown
-      try {
-        args = jsonText.length > 0 ? JSON.parse(jsonText) : {}
-      } catch {
-        return { kind: 'error', text: prose.testBadJson(jsonText) }
-      }
-      let loaded: LoadedRules
-      try {
-        loaded = this.rulesFor(cwd)
-      } catch (error: unknown) {
-        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 !== '') return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) }
+    if (verb !== '' && verb !== 'list') return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) }
     let loaded: LoadedRules
     try {
       loaded = this.rulesFor(cwd)
@@ -322,17 +349,102 @@ export class PermissionRulesRuntime {
       lines.push(prose.noRules(cwd, this.config.fallbackPath !== undefined ? prose.fallbackMissing : ''))
     } 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)))
     }
     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.
+   */
+  private testCommand(raw: string, verbRaw: string, invocation: CommandInvocation, sessionCwd: string, prose: UiProse): CommandResult {
+    let rest = raw.length > verbRaw.length ? raw.slice(verbRaw.length).trim() : ''
+    const envOverrides: Record<string, string> = {}
+    const agentSelectors: string[] = []
+    let testCwd: string | undefined
+    let testPlatform: string | undefined
+    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: unknown
+    try {
+      args = jsonText.length > 0 ? JSON.parse(jsonText) : {}
+    } catch {
+      return { kind: 'error', text: prose.testBadJson(jsonText) }
+    }
+    const evalCwd = testCwd ?? sessionCwd
+    let loaded: LoadedRules
+    try {
+      loaded = this.rulesFor(evalCwd)
+    } catch (error: unknown) {
+      return { kind: 'error', text: error instanceof Error ? error.message : String(error) }
+    }
+    const context: MatchContext = {
+      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. */
+  private displaySource(source: string, cwd: string): string {
+    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. */
   private decisionsCommand(invocation: CommandInvocation, count: number, prose: UiProse): CommandResult {
     const decisions = invocation.agent.session.events.filter(event => event.type === 'permissionRules/decision')
@@ -341,7 +453,7 @@ export class PermissionRulesRuntime {
     const lines = [prose.decisionsHeader(shown.length, decisions.length)]
     for (const event of shown) {
       const data = event.data as AuditDecision
-      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') }
   }
@@ -417,18 +529,99 @@ 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.
    */
   private reconcileWatch(cwd: string, sources: readonly string[]): void {
-    if (sources.length === 0) return
     for (const [watchedSource, entry] of this.watchers) {
-      if (!sources.includes(watchedSource)) entry.cwds.delete(cwd)
+      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.
+   */
+  private candidateSources(cwd: string): string[] {
+    const candidates: string[] = [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.
+   */
+  private attachCandidateWatch(cwd: string, candidate: string): void {
+    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 = (): void => 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: unknown) => {
+      this.ctx.logger.warn(`permission-rules: watcher error on ${dir}: ${String(error)}`)
+    })
+    this.watchers.set(dir, {
+      cwds,
+      candidates,
+      close: () => {
+        void watcher.close().catch((error: unknown) => {
+          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). */
+  private deepestExistingDir(dir: string): string {
+    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. */
@@ -457,7 +650,10 @@ export class PermissionRulesRuntime {
     const oldest = this.byCwd.keys().next().value
     if (oldest === undefined) return
     this.byCwd.delete(oldest)
-    for (const entry of this.watchers.values()) entry.cwds.delete(oldest)
+    for (const entry of this.watchers.values()) {
+      entry.cwds.delete(oldest)
+      entry.candidates?.delete(oldest)
+    }
     this.pruneWatchers()
   }
 
@@ -471,13 +667,24 @@ export class PermissionRulesRuntime {
     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.
+   */
   private scheduleReload(source: string): void {
     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 ?? []) this.reload(cwd)
+      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)
   }
@@ -498,7 +705,53 @@ export function apply(ctx: Context, config: Config): void {
   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: ToolExecution['agent']): string[] {
+  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: string): { token: string; rest: string } | undefined {
+  let i = 0
+  while (i < text.length && /\s/.test(text[i] as string)) i += 1
+  if (i >= text.length) return undefined
+  const quote = text[i] as string
+  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] as string)) end += 1
+  return { token: text.slice(i, end), rest: text.slice(end) }
+}