@miphamai/cli 0.83.0 → 0.85.0

package/src/core/permission-config.ts

@@ -29,11 +29,11 @@ export function loadPermissionConfig(raw: Partial<PermissionConfig> = {}): Permi
  *
  * - `plan` is strictly the narrowest. It passes only Read/Grep/Glob and sends
  *   *everything* else to approval, while `default` passes every tool that
- *   declares `permission: 'auto'` — git, task, web-fetch, cron, memory, … So a
+ *   declares `permission: 'self'` — git, task, web-fetch, cron, memory, … So a
  *   cap of `'plan'` must not admit `default`, and `plan` belongs at the bottom.
  * - `acceptEdits` and `default` are **incomparable**: acceptEdits auto-approves
  *   Write/Edit and verification-only Bash that `default` asks about, while
- *   `default` auto-approves the non-file `'auto'` tools that acceptEdits asks
+ *   `default` auto-approves the non-file `'self'` tools that acceptEdits asks
  *   about. No total order is faithful there, so the ranking only needs to carry
  *   the relations the two consumers rely on.
  *
@@ -42,28 +42,97 @@ export function loadPermissionConfig(raw: Partial<PermissionConfig> = {}): Permi
  * 'plan'` admitted acceptEdits *and* default — the ceiling let through the wider
  * mode each time. The pairs are pinned by a probe in `test/core/permission.test.ts`
  * (P4) so the claim stays measured rather than asserted.
+ *
+ * `auto` sits between `acceptEdits` and `bypassPermissions` — the same rung Claude
+ * Code puts it on. It has to sit above `acceptEdits`, because at runtime the
+ * classifier may allow calls `acceptEdits` refuses (network, non-verification
+ * Bash), so a ceiling of `acceptEdits` must not admit it. Its own static baseline
+ * grants nothing at all, which is why the P4 width probe **excludes** it by name:
+ * measuring "who is narrower" on the static chain would otherwise call `auto` the
+ * narrowest mode of all and point the hierarchy's first slot at it.
+ *
+ * **Every member of `PermissionMode` must appear here.** A missing member makes
+ * `indexOf` return `-1`, and `getAllowedModes` then skips the whole ceiling
+ * (`if (capIdx >= 0)`) — the org-level cap goes silently inert, fail-open, with no
+ * warning anywhere. There is a compile-time-exhaustive coverage assertion for this
+ * in `test/core/permission.test.ts` (P4c); the ordering probe (P4) catches a wrong
+ * *order* but never a *missing* entry.
+ *
+ * **Inserting `auto` moved a fallback destination, on purpose and without a
+ * failure.** `clampMode` answers "the highest allowed mode at or below `desired`",
+ * so every mode gains a neighbour below it. A config that forbids
+ * `bypassPermissions` and then requests it now lands on `auto` — previously
+ * `acceptEdits`. Both readings satisfy the contract and `auto` is a strict subset
+ * of `bypassPermissions` at runtime (it gates each call), so the move narrows
+ * rather than escalates; but it *is* a change in what those configs do, and it is
+ * pinned in `test/core/permission.test.ts` and `test/daemon/permission.test.ts`
+ * rather than left to be discovered. **Until the classifier is wired, `auto`'s
+ * static baseline is `ask` throughout, so that landing means "every call
+ * refused"** — fail-closed, and honest, but not a behaviour to install by accident.
  */
 export const PERMISSION_MODE_HIERARCHY: PermissionMode[] = [
   'plan',
   'default',
   'acceptEdits',
+  'auto',
   'bypassPermissions',
 ]
 
 /**
- * Shift+Tab cycling order — deliberately **not** the permissiveness order above.
- * The cycle is UX (manual → accept edits → plan → bypass); only the hierarchy
- * answers "is this mode wider than that one". Keeping them separate is what lets
- * `forbiddenModes` drop an entry from the cycle without disturbing the ranking
- * that `clampMode` walks.
+ * Every **legal** mode — the full internal enumeration, and the base set that
+ * `forbiddenModes` / `maxAllowedMode` are applied to.
+ *
+ * Deliberately a separate array from `MODE_CYCLE`, and deliberately able to be a
+ * **superset** of it: `bypassPermissions` is reachable through config /
+ * `MIPHAM_DAEMON_PERMISSION` / settings without being something a user can
+ * Shift+Tab into. Claude Code arranges it the same way — its descriptor table
+ * lists `bypassPermissions` while its cycle array does not.
+ *
+ * **The two arrays must not be collapsed back into one.** `getAllowedModes`
+ * filters *this* array, never `MODE_CYCLE`. If it filtered the cycle, then the
+ * moment the cycle stops listing `bypassPermissions`, a config requesting it
+ * would be silently walked *down* to `acceptEdits` by `clampMode` — a quiet
+ * downgrade of a security-relevant setting, with every existing test still
+ * green. The fixed point is pinned by a probe in `test/core/permission.test.ts`
+ * (P4b).
+ *
+ * Order is insignificant to both consumers except in one place: `clampMode`'s
+ * last-resort fallback is `allowed[0]`, so `default` stays first.
  */
-export const MODE_CYCLE: PermissionMode[] = ['default', 'acceptEdits', 'plan', 'bypassPermissions']
+export const ALL_MODES: PermissionMode[] = [
+  'default',
+  'acceptEdits',
+  'plan',
+  'auto',
+  'bypassPermissions',
+]
+
+/**
+ * Shift+Tab cycling order — **what the user actually presses through**. Also
+ * deliberately **not** the permissiveness order above: the cycle is UX, and only
+ * the hierarchy answers "is this mode wider than that one". Keeping them
+ * separate is what lets `forbiddenModes` drop an entry from the cycle without
+ * disturbing the ranking that `clampMode` walks.
+ *
+ * The two arrays **differ**, and that is the whole reason both exist:
+ * `bypassPermissions` is a legal mode that no Shift+Tab reaches (asked for
+ * through config / `MIPHAM_DAEMON_PERMISSION` / settings, where the user named
+ * it explicitly), while `auto` is on the wheel. Collapsing them back into one
+ * would either drop a legal mode or advertise one the wheel cannot reach —
+ * **do not "simplify" one back into the other.**
+ *
+ * Both of those are load-bearing, so an off-wheel *current* mode is a real state
+ * (`permission: bypassPermissions` in config, then Shift+Tab). `nextMode` owns
+ * the rule for it — see there.
+ */
+export const MODE_CYCLE: PermissionMode[] = ['default', 'acceptEdits', 'plan', 'auto']
 
 /** 规范形 → 把别名与大小写归一到一个键上（键一律小写）。 */
 const MODE_ALIASES: Record<string, PermissionMode> = {
   default: 'default',
   plan: 'plan',
   acceptedits: 'acceptEdits',
+  auto: 'auto',
   bypasspermissions: 'bypassPermissions',
   bypass: 'bypassPermissions', // 遗留 3 档名（PermissionLevel 里的 'bypass'）
 }
@@ -71,7 +140,7 @@ const MODE_ALIASES: Record<string, PermissionMode> = {
 /** 认不出的配置一律按这一档收紧 —— 层级表首位即最严的一档（与 P4 同一真源）。 */
 const STRICTEST_MODE: PermissionMode = PERMISSION_MODE_HIERARCHY[0]!
 
-const VALID_MODE_LIST = 'default, plan, acceptEdits, bypassPermissions'
+const VALID_MODE_LIST = 'default, plan, acceptEdits, auto, bypassPermissions'
 
 /** 可读的类型名 —— 报错要说清「你给的是个字符串」，而不是只说 invalid。 */
 function describeValue(value: unknown): string {
@@ -173,9 +242,15 @@ export function normalizeRestrictions(raw: unknown): {
   return { restrictions, invalid }
 }
 
-/** Resolve which modes are actually permitted given the restrictions. */
+/**
+ * Resolve which modes are actually permitted given the restrictions.
+ *
+ * Filtered from `ALL_MODES` (the full legal set), **not** from `MODE_CYCLE` —
+ * see `ALL_MODES` for what filtering the cycle would silently do to
+ * `bypassPermissions`. `nextMode` re-intersects with the cycle afterwards.
+ */
 function getAllowedModes(restrictions?: PermissionRestrictions): PermissionMode[] {
-  let allowed = [...MODE_CYCLE]
+  let allowed = [...ALL_MODES]
 
   if (restrictions?.forbiddenModes && restrictions.forbiddenModes.length > 0) {
     const forbidden = new Set(restrictions.forbiddenModes)
@@ -218,11 +293,27 @@ export function nextMode(
   current: PermissionMode,
   restrictions?: PermissionRestrictions,
 ): PermissionMode {
+  // The user-facing cycle is `MODE_CYCLE`, narrowed by what the restrictions
+  // leave allowed — so reading the *cycle's* order (not `getAllowedModes`'
+  // order) is what keeps Shift+Tab on the same path once the two arrays
+  // diverge. An off-cycle mode (or one forbidden here) is not `indexOf`-able
+  // and falls through to `clampMode`.
   const allowed = getAllowedModes(restrictions)
-  const idx = allowed.indexOf(current)
+  const cycle = MODE_CYCLE.filter((m) => allowed.includes(m))
+  const idx = cycle.indexOf(current)
   if (idx === -1) {
-    // Current mode is not in the allowed set — clamp then find next
-    return clampMode(current, restrictions)
+    // `current` is off the cycle: legal-but-uncyclable (`bypassPermissions`) or
+    // forbidden by the restrictions. Reading "clamp then find next" as
+    // `return clampMode(current)` returns `current` itself in the first case —
+    // clamping an *allowed* mode is the identity — so Shift+Tab would do nothing
+    // and `nextMode` would hand back a mode the wheel cannot reach. Clamp *onto*
+    // the cycle, then advance from there; if that still lands off-cycle, take the
+    // cycle's first entry. That entry is `default`, which is not the narrowest mode
+    // on the wheel (`plan` is) — the wheel is not a permissiveness order — but the
+    // only off-wheel state reachable is `bypassPermissions`, so the fallback still
+    // steps away from wider rather than toward it.
+    const onCycle = cycle.indexOf(clampMode(current, restrictions))
+    return onCycle === -1 ? (cycle[0] ?? current) : cycle[(onCycle + 1) % cycle.length]!
   }
-  return allowed[(idx + 1) % allowed.length]!
+  return cycle[(idx + 1) % cycle.length]!
 }

package/src/core/permission.ts

@@ -12,8 +12,26 @@ import {
   nextMode,
   clampMode,
   normalizeRestrictions,
-  MODE_CYCLE,
+  ALL_MODES,
 } from './permission-config'
+import type { PermissionClassifier } from './permission-classifier'
+import { recordClassifierRuling } from './permission-audit'
+
+/**
+ * A tool that only reads: it cannot modify a file or run anything.
+ *
+ * Named and shared because two modes now depend on the same judgement — `plan`
+ * allows exactly these and nothing else, and `auto` lets them past the classifier.
+ * Two hand-written copies of this list are how the two modes would come to disagree
+ * about what "read-only" means, which is the shape of defect this file has already
+ * been bitten by more than once.
+ *
+ * The `category === 'file'` half is load-bearing rather than redundant: it keeps a
+ * future non-file tool that happens to be called `Read` out of the carve-out.
+ */
+function isReadOnlyTool(tool: ToolDefinition): boolean {
+  return tool.category === 'file' && ['Read', 'Grep', 'Glob'].includes(tool.name)
+}
 
 /**
  * Check if a Bash command is a "verification-only" command that should be
@@ -66,7 +84,32 @@ function isVerificationCommand(input: Record<string, unknown>): boolean {
   return verifyPatterns.some((p) => p.test(cmd))
 }
 
-const VALID_MODES: Set<string> = new Set<string>(MODE_CYCLE)
+/**
+ * Which `PermissionLevel` spellings the constructor accepts as an actual
+ * *mode*. Filtered from `ALL_MODES`, **not** `MODE_CYCLE`: `bypassPermissions`
+ * is a legal destination even though it is not part of the Shift+Tab cycle, and
+ * reading the cycle here would quietly demote it to the legacy-level fallback.
+ */
+const VALID_MODES: Set<string> = new Set<string>(ALL_MODES)
+
+/**
+ * Legacy 3-level spellings, still honoured — and still **silent**, because they
+ * are *mapped* rather than ignored: `'self'`/`'ask'` both meant "let each tool
+ * self-decide" (→ `'default'`), `'bypass'` → `'bypassPermissions'`.
+ *
+ * They predate `PermissionMode` and stay accepted so an old `config.yml` keeps
+ * working. They are also why `setDefaultLevel` cannot use `VALID_MODES` as its
+ * only test: a legacy spelling and a mode name must both count as *recognized*,
+ * while only a value that is neither gets a warning.
+ */
+const LEGACY_LEVEL_MODES: Record<string, PermissionMode> = {
+  self: 'default',
+  ask: 'default',
+  bypass: 'bypassPermissions',
+}
+
+/** Human-readable mode list for warnings — derived, so no message can hold a stale copy. */
+const MODE_LIST = ALL_MODES.join(', ')
 
 /**
  * Why a tool resolved to 'ask' — for rich denial errors (#52).
@@ -79,6 +122,51 @@ export type PermissionDenialReason =
   | 'mode-baseline' // mode-specific default (acceptEdits/plan) → ask
   | 'tool-default' // tool.permission === 'ask'
   | 'system-default' // no rule, no tool permission → fallback ask
+  | 'classifier-deny' // `auto` mode's classifier ruled against the call
+
+/**
+ * Which denial reasons `auto` mode's classifier is allowed to rule on — an
+ * **allowlist**, not a denylist, and the direction is the whole point.
+ *
+ * `deny-rule` and `ask-rule` are absent deliberately: those are decisions a human
+ * wrote down. Adding them here would silently turn the classifier into a universal
+ * bypass of every org-level rule — the one thing the mode must never be. A reason
+ * missing from this set therefore fails **closed** (the call stays `'ask'`), which
+ * is why the set is spelled as the reasons that are *permitted*, not the ones that
+ * are not.
+ *
+ * `legacy-rule` is absent for the same reason as the rules: it is an explicit
+ * per-tool decision from `setRule()`. `classifier-deny` is absent because it is not
+ * a *static* reason at all — `explainDenial()` never returns it.
+ */
+const CLASSIFIABLE: ReadonlySet<PermissionDenialReason> = new Set<PermissionDenialReason>([
+  'mode-baseline',
+  'tool-default',
+  'system-default',
+])
+
+/**
+ * What a tool call actually resolved to, after the classifier has had its say.
+ *
+ * `level` is what the caller acts on (`'ask'` ⇒ blocked). `source` records whether
+ * the decision was the static chain's or the classifier's, so a caller can word the
+ * denial correctly: telling a model "denied" when the classifier was merely
+ * unreachable makes it abandon the task, while the honest reading is "this did not
+ * run, a retry is appropriate".
+ */
+export interface ApprovalDecision {
+  level: PermissionLevel
+  source: 'static' | 'classifier'
+  /** Why it is `'ask'`. Present on every denial, from either source. */
+  denialReason?: PermissionDenialReason
+  /** The classifier's own one-line justification, when it ruled. */
+  classifierReason?: string
+  /**
+   * `true` ⇒ held back because the classifier could not be reached or its answer
+   * could not be read — **not** a policy decision, and worth retrying.
+   */
+  retryable?: boolean
+}
 
 export class PermissionSystem {
   private allowRules: PermissionRuleEntry[] = []
@@ -86,7 +174,9 @@ export class PermissionSystem {
   private askRules: PermissionRuleEntry[] = []
   /** Malformed `permissionRestrictions` entries from the last set/load — see below. */
   private restrictionWarnings: string[] = []
-  /** Legacy exact-name rules for backward compat (set via setRule with 'auto' level). */
+  /** Unrecognized `permission:` value from the last `setDefaultLevel` — third of the warning family. */
+  private levelWarnings: string[] = []
+  /** Legacy exact-name rules for backward compat (set via setRule with 'self' level). */
   private legacyRules = new Map<string, PermissionLevel>()
   /** Legacy default level from constructor when passed non-mode values like 'ask' or 'bypass'. */
   private legacyDefaultFallback: PermissionLevel | null = null
@@ -97,6 +187,19 @@ export class PermissionSystem {
   private checkCache = new Map<string, PermissionLevel>()
   private cacheMode: PermissionMode | null = null
 
+  /**
+   * Cache for classifier rulings, same key as `checkCache`. Only **terminal**
+   * rulings are stored — see `resolveApproval`.
+   */
+  private classifierCache = new Map<string, ApprovalDecision>()
+
+  /**
+   * The `auto`-mode classifier, when one was handed in. Absent is a legal state
+   * (every other mode ignores it, and `auto` without one fails closed), so nothing
+   * here assumes it exists.
+   */
+  private classifier: PermissionClassifier | undefined = undefined
+
   // ── Org-level restrictions (P0 security) ──
   private restrictions: PermissionRestrictions | undefined = undefined
 
@@ -107,9 +210,34 @@ export class PermissionSystem {
   /** Invalidate the permission cache (called on any rule/mode change). */
   private invalidateCache(): void {
     this.checkCache.clear()
+    this.classifierCache.clear()
     this.cacheMode = null
   }
 
+  /**
+   * Hand in the classifier that `auto` mode consults. Separating this from the
+   * constructor keeps the permission system free of provider/registry imports: the
+   * wiring site (the CLI entry, where the registry exists) builds the classifier and
+   * attaches it here. `undefined` removes it, which makes `auto` refuse every gated
+   * call again — fail-closed, not fail-open.
+   *
+   * The seam deliberately lives on the permission system rather than on the engine:
+   * an engine-side setter would be a new engine capability that the daemon would
+   * then have to match or be given a named exemption from
+   * (`test/integrity/daemon-capability-parity.test.ts`). The cost of that choice is
+   * stated where it matters: this guard therefore cannot see whether anyone ever
+   * calls this, which is why the wiring has its own source-side assertion.
+   */
+  setClassifier(classifier: PermissionClassifier | undefined): void {
+    this.classifier = classifier
+    this.invalidateCache()
+  }
+
+  /** Whether an `auto`-mode classifier is attached. For diagnostics, not decisions. */
+  hasClassifier(): boolean {
+    return this.classifier !== undefined
+  }
+
   constructor(modeOrLevel: PermissionLevel = 'default') {
     if (VALID_MODES.has(modeOrLevel)) {
       this.mode = modeOrLevel as PermissionMode
@@ -212,6 +340,23 @@ export class PermissionSystem {
       subPerm.deny(denyEntry.pattern)
     }
 
+    // The classifier travels with the `auto` mode, not with the agent: a sub-agent
+    // gets it exactly when its *resolved* mode is `auto`, and not otherwise. That
+    // makes the two natural ways in behave consistently — an agent that names `auto`
+    // explicitly, and one that inherits from a parent already sitting in `auto`
+    // (`resolveAgentMode` reads `inherit` as "the parent's mode"). Inheriting the
+    // label without the engine would be the worst of both: a sub-agent pinned to a
+    // mode whose only substance is a classifier it does not have, refusing every
+    // gated call with a message about a mode that is working fine for its parent.
+    //
+    // No sub-agent lands here by default: the default mode is `default`, so this is
+    // opt-in through the mode itself. What is *not* inherited is any allowance —
+    // `resolvedMode` is already clamped against the org restrictions above, so an
+    // org that caps the mode also removes the classifier.
+    if (resolvedMode === 'auto' && this.classifier) {
+      subPerm.setClassifier(this.classifier)
+    }
+
     return subPerm
   }
 
@@ -224,8 +369,13 @@ export class PermissionSystem {
     // Normalize aliases
     const normalized = agentMode === 'bypass' ? 'bypassPermissions' : agentMode
 
+    // Hand-written map, so a mode missing from it does not fail to compile: it
+    // falls to the `|| 'default'` below and the agent silently runs narrower than
+    // it asked for. `auto` therefore has to be added here *and* in
+    // `agent/types.ts`'s union — the type does not force either.
     const modeMap: Record<string, PermissionMode> = {
       bypassPermissions: 'bypassPermissions',
+      auto: 'auto',
       plan: 'plan',
       acceptEdits: 'acceptEdits',
       default: 'default',
@@ -296,7 +446,7 @@ export class PermissionSystem {
    * 1. Deny rules → block
    * 2. Ask rules → require approval
    * 3. Allow rules → permit
-   * 4. Legacy exact-name rules (backward compat — e.g. setRule('tool', 'auto'))
+   * 4. Legacy exact-name rules (backward compat — e.g. setRule('tool', 'self'))
    * 5. Mode baseline → mode-specific default (overrides tool.permission for explicit modes)
    * 6. Tool's own permission → tool-specific default (backward compat)
    * 7. Legacy constructor fallback (when constructed with 'ask'/'bypass')
@@ -309,7 +459,7 @@ export class PermissionSystem {
     }
 
     // ── Cache lookup (P2): reuse decision for same tool+mode+input ──
-    const cacheKey = tool.name + '|' + JSON.stringify(input, Object.keys(input).sort())
+    const cacheKey = this.cacheKey(tool, input)
     if (this.cacheMode === this.mode) {
       const cached = this.checkCache.get(cacheKey)
       if (cached !== undefined) return cached
@@ -419,6 +569,133 @@ export class PermissionSystem {
     return { reason: 'system-default' }
   }
 
+  /**
+   * Same key both caches use. Extracted rather than written twice: two copies of a
+   * cache key would drift, and a key that drifts is a cache that answers for the
+   * wrong call.
+   */
+  private cacheKey(tool: ToolDefinition, input: Record<string, unknown>): string {
+    return tool.name + '|' + JSON.stringify(input, Object.keys(input).sort())
+  }
+
+  /**
+   * Resolve a call to a decision, consulting `auto` mode's classifier when — and
+   * only when — the static chain answered `'ask'` for a reason a classifier is
+   * allowed to rule on.
+   *
+   * **The step order below is the security contract, not an implementation
+   * detail.** Each numbered step exists to close a specific way this could go
+   * wrong, and reordering them is how the mode would become a bypass:
+   *
+   * 1. `check()` first, untouched. Everything it decides *without* asking —
+   *    `bypassPermissions`, `acceptEdits`, `plan`, allow rules, tool defaults that
+   *    are not `'ask'` — is returned verbatim. This is the compatibility guarantee:
+   *    non-`'ask'` decisions are byte-for-byte what they were before this method
+   *    existed, and the classifier is never even consulted for them.
+   * 2. Only `'ask'` continues, and only for a reason in `CLASSIFIABLE`. A denial
+   *    caused by a deny rule, an ask rule, or a legacy exact-name rule stops here
+   *    and stays denied. Without this step the classifier would be a universal
+   *    bypass of every rule a human wrote.
+   * 3. `auto` without a classifier stops here too, still `'ask'` — fail-closed.
+   * 4. A ruling of "allow" is **not** returned as `'bypass'`. It is re-derived
+   *    through `allowRuleDecision()`, the same ceiling-aware path an allow *rule*
+   *    takes, so the classifier can never grant more than a rule could and an org's
+   *    `maxAllowedMode` caps it automatically.
+   *
+   * A refusal is always `'ask'` — never a new kind of denial. The classifier may
+   * only ever turn a blocked call into a running one; it cannot manufacture a
+   * denial the static chain did not already produce. Read the other way round: it
+   * can only *narrow* what runs, never widen the gate.
+   *
+   * Caching: rulings are cached on the same key as `check()`, but a ruling that came
+   * from an engine failure is **not** cached. Its own verdict says a retry is
+   * appropriate (`retryable`), and a cache would make that false by replaying the
+   * failure without asking anyone.
+   */
+  async resolveApproval(
+    tool: ToolDefinition,
+    input: Record<string, unknown>,
+    opts: { signal?: AbortSignal } = {},
+  ): Promise<ApprovalDecision> {
+    // 1. The static chain decides everything it can decide without asking.
+    const level = this.check(tool, input)
+    if (level !== 'ask') return { level, source: 'static' }
+
+    // 2. Why it is 'ask' — and may a classifier rule on that reason at all?
+    const { reason } = this.explainDenial(tool, input)
+    if (!CLASSIFIABLE.has(reason)) return { level: 'ask', source: 'static', denialReason: reason }
+
+    // 3. Only `auto` consults a classifier, and only if one was handed in.
+    if (!this.classifier || this.mode !== 'auto') {
+      return { level: 'ask', source: 'static', denialReason: reason }
+    }
+
+    const key = this.cacheKey(tool, input)
+    const cached = this.classifierCache.get(key)
+    if (cached) return cached
+
+    const verdict = await this.classifier.classify({
+      tool: tool.name,
+      input,
+      mode: this.mode,
+      reason,
+      signal: opts.signal,
+    })
+
+    if (verdict.allow) {
+      // 4. An allow is re-derived through the rule path, so the org ceiling applies.
+      const decision: ApprovalDecision = {
+        level: this.allowRuleDecision(tool, input),
+        source: 'classifier',
+        classifierReason: verdict.reason,
+      }
+      // Only cache a ruling that actually let the call through, or one the
+      // classifier refused on policy. (`allowRuleDecision` can still answer 'ask'
+      // under a ceiling — that is a terminal answer too, so it caches.)
+      this.classifierCache.set(key, decision)
+      return this.ruled(tool, decision, 'allow')
+    }
+
+    const decision: ApprovalDecision = {
+      level: 'ask',
+      source: 'classifier',
+      denialReason: 'classifier-deny',
+      classifierReason: verdict.reason,
+      retryable: verdict.retryable,
+    }
+    // A retryable failure is a statement that asking again is appropriate; caching
+    // it would contradict the field we just set.
+    if (!verdict.retryable) this.classifierCache.set(key, decision)
+    return this.ruled(tool, decision, 'deny')
+  }
+
+  /**
+   * 记一条裁决，再把**同一个对象**交回去：放行那一支此前是**无声**的，而无人值守的
+   * 子代理 + 无声放行是最坏的组合（`permission-audit.ts` 文件头有完整的来龙去脉）。
+   *
+   * 这个私有方法的存在方式就是那条不变量 —— 返回 `source: 'classifier'` 与落一条台账
+   * 在代码上**分不开**：两处都在这里出口，将来加第三条路也必须过这里。
+   *
+   * **缓存命中不在此列**（`resolveApproval` 在调用分类器之前就返回了）：那时分类器
+   * 根本没被咨询，写一行等于声称有一个没人做过的裁决。
+   */
+  private ruled(
+    tool: ToolDefinition,
+    decision: ApprovalDecision,
+    verdict: 'allow' | 'deny',
+  ): ApprovalDecision {
+    recordClassifierRuling({
+      mode: this.mode,
+      tool: tool.name,
+      verdict,
+      level: decision.level,
+      reason: decision.classifierReason,
+      retryable: decision.retryable,
+      denialReason: decision.denialReason,
+    })
+    return decision
+  }
+
   // ── Helpers ──
 
   private ruleMatches(
@@ -501,9 +778,40 @@ export class PermissionSystem {
 
       case 'plan':
         // Only reads, no writes or executes
-        return tool.category === 'file' && ['Read', 'Grep', 'Glob'].includes(tool.name)
-          ? 'bypass'
-          : 'ask'
+        return isReadOnlyTool(tool) ? 'bypass' : 'ask'
+
+      case 'auto':
+        // Reads stay free; everything else is handed to the classifier.
+        //
+        // The tempting one-liner is `return 'ask'` — every call ruled on, which is
+        // what a mode table reading `auto → classify` suggests. Measured against the
+        // actual registry, that one-liner is a broken mode: 20 of the 31 tools
+        // declare `permission: 'self'`, and the list includes **Read, Grep and
+        // Glob**. Gating those makes `auto` the only mode in the ladder that cannot
+        // read a file without an LLM round-trip — every other mode (including
+        // `plan`) allows reads unconditionally — and when the classifier is
+        // unreachable, fail-closed means the agent cannot even read. A gate that
+        // fails catastrophically on the most benign operation is not a conservative
+        // gate; it is a broken one.
+        //
+        // So reads are carved out using `plan`'s own definition of read-only rather
+        // than a second list, and everything else — `Bash`, `Write`, `Edit`, and the
+        // `self`-declared tools that can reach outside this machine (`Git`,
+        // `WebFetch`, `CronCreate`, `Task`, `Memory`, …) — reaches
+        // `resolveApproval`. That is the half the classifier is actually needed for,
+        // and leaving them to auto-approve would be the fail-open version of this
+        // mistake.
+        //
+        // Returning the sentinel `'mode-baseline'` instead would hand those tools to
+        // step 6 of `check()`, i.e. `tool.permission` — `'self'` for all 20, so they
+        // would auto-approve and the classifier would never see them. (20 is counted
+        // from `createToolRegistry()`, not from grep: the literal `permission: 'self'`
+        // also appears in prose comments.)
+        //
+        // This does not contradict "the classifier may only allow, never deny": the
+        // baseline is `'ask'` (what an un-configured Mipham already answers), and a
+        // classifier refusal merely *keeps* that `'ask'`.
+        return isReadOnlyTool(tool) ? 'bypass' : 'ask'
 
       case 'bypassPermissions':
         return 'bypass'
@@ -515,12 +823,47 @@ export class PermissionSystem {
 
   // ── Legacy compatibility ──
 
-  setDefaultLevel(level: PermissionLevel): void {
-    // Map legacy 3-level (auto/ask/bypass) to new 4-level mode.
-    // Legacy 'auto'/'ask' = "let each tool self-decide" → 'default'.
-    // Legacy 'bypass' → 'bypassPermissions'.
-    const newMode: PermissionMode = level === 'bypass' ? 'bypassPermissions' : 'default'
-    this.mode = clampMode(newMode, this.restrictions)
+  /**
+   * Set the default mode from a `permission:` config value. Accepts **both** the
+   * legacy 3-level spellings and any real mode name.
+   *
+   * This used to read `newMode = level === 'bypass' ? 'bypassPermissions' :
+   * 'default'` — i.e. it honoured exactly one string and sent everything else to
+   * `'default'`. Every mode name a user could write in `config.yml` therefore
+   * landed on `default` **silently**: `permission: plan` became a mode that
+   * auto-approves every tool declaring `permission: 'self'` (git, task,
+   * web-fetch, cron, memory, …), so the user believes they narrowed the gate
+   * while it moved the other way; `permission: bypassPermissions` and
+   * `permission: auto` did not do what they say either. No warning, no error,
+   * no way to tell — the same fail-open shape `normalizeRestrictions` was written
+   * to fix, arriving through a different door. Hence the same remedy: honour what
+   * is recognized, pin a safe fallback for what is not, and **say so** through
+   * `getInvalidPermissionMode()`.
+   *
+   * `VALID_MODES` is the discriminator, deliberately the same one the constructor
+   * uses — so a `permission:` value and a `new PermissionSystem(...)` argument
+   * cannot drift apart in which spellings they accept.
+   *
+   * The fallback for an unrecognized value stays `'default'`: the caller asked for
+   * a mode we cannot name, and `default` is the only mode that is not *wider* than
+   * a well-formed request (`plan` is narrower; the rest are comparable or wider).
+   * The org restrictions are applied last, so a clamped mode is what actually lands
+   * — `getMode()` reports the clamped value, never the requested one.
+   */
+  setDefaultLevel(level: PermissionLevel | PermissionMode): void {
+    const mode: PermissionMode | undefined = VALID_MODES.has(level)
+      ? (level as PermissionMode)
+      : LEGACY_LEVEL_MODES[level]
+
+    // Only a value that is neither a mode name nor a legacy spelling warns. The
+    // legacy ones are mapped, not dropped, so they have nothing to report.
+    this.levelWarnings = mode
+      ? []
+      : [
+          `permission "${String(level)}" is not a permission mode; valid: ${MODE_LIST} (legacy spellings also accepted: ${Object.keys(LEGACY_LEVEL_MODES).join(', ')}). Using "default".`,
+        ]
+
+    this.mode = clampMode(mode ?? 'default', this.restrictions)
     this.invalidateCache()
   }
 
@@ -529,7 +872,17 @@ export class PermissionSystem {
     if (this.legacyDefaultFallback) return this.legacyDefaultFallback
     if (this.mode === 'bypassPermissions') return 'bypass'
     if (this.mode === 'plan') return 'ask'
-    return 'auto'
+    return 'self'
+  }
+
+  /**
+   * Unrecognized `permission:` values from the last `setDefaultLevel`, one message
+   * each — third member of the warning family beside `getInvalidRules()` and
+   * `getInvalidRestrictions()`. Callers surface all three to stderr; a silent
+   * return here means the gate is not where the user's config says it is.
+   */
+  getInvalidPermissionMode(): string[] {
+    return this.levelWarnings
   }
 
   setRule(toolNameOrRule: string | PermissionRule, level?: PermissionLevel): void {
@@ -542,7 +895,7 @@ export class PermissionSystem {
         // Also sync to new-style arrays for listRules / new API consistency
         if (level === 'bypass') this.allow(toolName)
         else if (level === 'ask') this.ask(toolName)
-        // 'auto' is stored only in legacyRules (returns 'auto', not 'bypass')
+        // 'self' is stored only in legacyRules (returns 'self', not 'bypass')
       }
     } else {
       const rule = toolNameOrRule