@miphamai/cli 0.83.0 → 0.84.0

package/src/config/preferences.ts

@@ -6,11 +6,10 @@
  * NOT for secrets — this file is plain JSON, not encrypted.
  */
 import { readFileSync, existsSync, mkdirSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { atomicWriteFileSync } from '../shared/atomic-write'
+import { miphamHome } from '../core/paths.ts'
 
-const PREFS_PATH = join(homedir(), '.mipham', 'preferences.json')
+const PREFS_PATH = miphamHome('preferences.json')
 
 function readPrefs(): Record<string, string> {
   try {
@@ -26,7 +25,7 @@ function readPrefs(): Record<string, string> {
 
 function writePrefs(prefs: Record<string, string>): void {
   try {
-    const dir = join(homedir(), '.mipham')
+    const dir = miphamHome()
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
     // 原子写：裸 writeFileSync 原地截断，崩在写中途就留下一份不可解析的文件，
     // 而 readPrefs 把不可解析吞成「空」⇒ **全部**偏好静默消失（不是丢一项）。

package/src/core/auto-memory.ts

@@ -18,8 +18,7 @@ import type { EffectivenessTracker } from '../agent/effectiveness-tracker.js'
 import type { ErrorSignatureDB } from './error-signature-db.js'
 import type { CrsiProvenanceBridge } from '../agent/crsi-provenance-bridge.js'
 import { getMetrics } from './metrics'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
+import { miphamHome } from './paths.ts'
 
 // ── Types ──
 
@@ -74,7 +73,7 @@ export interface TurnReflection {
 
 // ── Constants ──
 
-const DEFAULT_MEMORY_DIR = join(homedir(), '.mipham', 'memory')
+const DEFAULT_MEMORY_DIR = miphamHome('memory')
 
 /** Minimum number of similar failures before a CRSI rule is generated. */
 const CRSI_RULE_THRESHOLD = 2

package/src/core/constitution-loader.ts

@@ -14,8 +14,7 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
+import { miphamHome } from './paths.ts'
 import alignmentVocabulary from './alignment-vocabulary.json' with { type: 'json' }
 
 // ── Types ──
@@ -76,7 +75,7 @@ export class ConstitutionLoader {
   private cached: MiphamConstitution | null = null
 
   constructor(customPath?: string) {
-    this.path = customPath || join(homedir(), '.mipham', 'ai-guardrails.yml')
+    this.path = customPath || miphamHome('ai-guardrails.yml')
   }
 
   /**
@@ -102,7 +101,7 @@ export class ConstitutionLoader {
     // Write the default constitution to disk for visibility
     this.cached = DEFAULT_CONSTITUTION
     try {
-      const dir = join(homedir(), '.mipham')
+      const dir = miphamHome()
       if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
       writeFileSync(this.path, this.serializeToYaml(DEFAULT_CONSTITUTION), 'utf-8')
     } catch {

package/src/core/crsi-producer.ts

@@ -15,7 +15,7 @@ import type { MetaRule } from './meta-rule-engine'
 import type { Llm } from '../providers/llm'
 import { readdirSync, appendFileSync, readFileSync, existsSync, mkdirSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
+import { miphamHome } from './paths.ts'
 
 /** 教训文件（相对仓库根）。预建，沙箱只能改已存在文件。 */
 export const LESSONS_FILE = 'apps/cli/crsi-lessons.md'
@@ -514,7 +514,7 @@ export interface ProseProposalRecord {
 }
 
 function proseLedgerFile(): string {
-  return join(homedir(), '.mipham', 'crsi', 'prose-proposals.jsonl')
+  return miphamHome('crsi', 'prose-proposals.jsonl')
 }
 
 /** 该信号是否已生成过散文提议。 */
@@ -537,7 +537,7 @@ export function hasProposedProse(id: string): boolean {
 /** 追加一条散文提议记录（append-only，非关键——失败不影响提议本身）。 */
 export function appendProseProposal(record: ProseProposalRecord): void {
   try {
-    mkdirSync(join(homedir(), '.mipham', 'crsi'), { recursive: true })
+    mkdirSync(miphamHome('crsi'), { recursive: true })
     appendFileSync(proseLedgerFile(), JSON.stringify(record) + '\n', 'utf-8')
   } catch {
     // ledger 非关键，失败不影响提议本身

package/src/core/crsi-sandbox.ts

@@ -17,9 +17,10 @@
 import { execSync } from 'node:child_process'
 import { mkdirSync, rmSync, existsSync, writeFileSync, readFileSync, readdirSync } from 'node:fs'
 import { join, resolve, sep, posix } from 'node:path'
-import { tmpdir, homedir } from 'node:os'
+import { tmpdir } from 'node:os'
 import { randomUUID } from 'node:crypto'
 import { LESSONS_FILE, MANAGED_RULES_FILE } from './crsi-producer'
+import { miphamHome } from './paths.ts'
 
 // ── Types ──
 
@@ -86,7 +87,7 @@ export interface CrsiSessionReport {
 
 const WORKTREE_PREFIX = 'crsi-sandbox-'
 const TEST_TIMEOUT_MS = 120_000 // 2 minutes
-const REPORT_DIR = join(homedir(), '.mipham', 'crsi-sandbox')
+const REPORT_DIR = miphamHome('crsi-sandbox')
 
 /**
  * 自改进的「不可变基础」（immutable base）——按语义角色三类。

package/src/core/dream-engine.ts

@@ -35,7 +35,7 @@ import {
   statSync,
 } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
+import { miphamHome } from './paths.ts'
 
 // ── Types ──
 
@@ -78,7 +78,7 @@ interface MemoryFile {
 
 // ── Constants ──
 
-const DEFAULT_MEMORY_DIR = join(homedir(), '.mipham', 'memory')
+const DEFAULT_MEMORY_DIR = miphamHome('memory')
 const STALE_DAYS = 30
 const SIMILARITY_THRESHOLD = 0.65
 

package/src/core/engine.ts

@@ -11,6 +11,7 @@ import type { ChatRequest } from '../providers/registry'
 import type { Llm } from '../providers/llm'
 import { ContextManager } from './context'
 import { PermissionSystem } from './permission'
+import type { ApprovalDecision } from './permission'
 import type { HookEngine } from './hooks'
 import type { ArtifactServer } from '../artifacts/server'
 import type { AgentRegistry } from '../agent/agent-registry'
@@ -701,7 +702,7 @@ export class QueryEngine {
     const toolCallRecords: ToolCallRecord[] = []
     for (const toolUse of toolUses) {
       const toolStart = Date.now()
-      const result = await this.executeTool(toolUse.name, toolUse.input)
+      const result = await this.executeTool(toolUse.name, toolUse.input, signal)
       yield {
         type: 'tool_result',
         tool_use_id: toolUse.id,
@@ -1041,7 +1042,7 @@ export class QueryEngine {
 
       // Execute tools and feed results back to the model for the next turn
       for (const toolUse of toolUses) {
-        const result = await this.executeTool(toolUse.name, toolUse.input)
+        const result = await this.executeTool(toolUse.name, toolUse.input, signal)
         lastActivity = Date.now()
         yield {
           type: 'tool_result',
@@ -1068,7 +1069,11 @@ export class QueryEngine {
     // Max turns reached — safety limit, stop gracefully
   }
 
-  private async executeTool(name: string, params: Record<string, unknown>): Promise<ToolResult> {
+  private async executeTool(
+    name: string,
+    params: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<ToolResult> {
     getMetrics().toolCalls.inc({ tool_name: name })
     const tool = this.tools.get(name)
     if (!tool) {
@@ -1080,12 +1085,20 @@ export class QueryEngine {
       return { success: false, content: '', error: `Unknown tool: ${name}${hint}` }
     }
 
-    // Security: check permission before executing
-    if (this.permission.needsApproval(tool, params)) {
+    // Security: check permission before executing.
+    //
+    // `resolveApproval` answers the same question `needsApproval` did for every mode
+    // except `auto`, where it additionally lets the classifier rule on a call the
+    // static chain could only refuse. It is deliberately a superset — the earlier
+    // `needsApproval(...)` check would have been a *second* gate, and a second gate
+    // is how a call refused here gets allowed there. The signal is the caller's, so
+    // an interrupt cancels a ruling in flight (the classifier denies on abort).
+    const decision = await this.permission.resolveApproval(tool, params, { signal })
+    if (decision.level === 'ask') {
       // P1-4: Increment consecutive block counter; if limit exceeded,
       // tell the model to move on instead of retrying.
       const limitExceeded = this.permission.incrementBlockCounter()
-      const baseError = this.buildDenialError(name, tool, params)
+      const baseError = this.buildDenialError(name, tool, params, decision)
       const moveOnHint = limitExceeded
         ? '\n(Consecutive block limit reached. Please try a different approach or ask the user for guidance.)'
         : ''
@@ -1451,12 +1464,31 @@ export class QueryEngine {
   /**
    * Build a rich permission-denial error naming the mode (level), the setting
    * (rule/level) that caused the denial, and the correct fix (#52).
+   *
+   * The `decision` comes from `resolveApproval` and is used rather than re-derived:
+   * `explainDenial` can only describe the *static* chain, so for a classifier
+   * refusal it would report the underlying `mode-baseline`/`tool-default` and tell
+   * the model to switch modes — advice that changes nothing, because the refusal is
+   * the classifier's, not the mode's. The parameter is optional so the static path
+   * keeps working unchanged where no decision is at hand.
    */
   private buildDenialError(
     name: string,
     tool: ToolDefinition,
     params: Record<string, unknown>,
+    decision?: ApprovalDecision,
   ): string {
+    if (decision?.source === 'classifier' && decision.denialReason === 'classifier-deny') {
+      // Two different facts, and the model acts differently on each: a policy
+      // refusal is final, while an unreachable/unreadable classifier means the call
+      // was *held back* and a retry is appropriate. Telling it "denied" for the
+      // second makes it abandon work that was never actually judged.
+      const reason = decision.classifierReason ?? ''
+      return decision.retryable
+        ? t('errors.tool_denied_classifier_unavailable', { name, reason })
+        : t('errors.tool_denied_classifier', { name, reason })
+    }
+
     const { reason, rulePattern } = this.permission.explainDenial(tool, params)
     const mode = this.permission.getMode()
     switch (reason) {

package/src/core/error-signature-db.ts

@@ -16,8 +16,8 @@
 
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { randomUUID } from 'node:crypto'
+import { miphamHome } from './paths.ts'
 
 // ── Types ──
 
@@ -61,7 +61,7 @@ export interface ErrorSignatureStats {
 
 // ── Constants ──
 
-const DEFAULT_STORE_DIR = join(homedir(), '.mipham', 'sis')
+const DEFAULT_STORE_DIR = miphamHome('sis')
 const STORE_FILE = 'error-signatures.json'
 const MIN_SUCCESS_RATE = 0.5 // below this → degraded
 const RETIREMENT_RATE = 0.2 // below this and > 90 days old → retired

package/src/core/eval-harness.ts

@@ -12,7 +12,7 @@
  */
 
 import { join } from 'node:path'
-import { tmpdir, homedir } from 'node:os'
+import { tmpdir } from 'node:os'
 import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'node:fs'
 import { ExperienceRuleEngine } from './rule-engine'
 import { ConstitutionLoader, DEFAULT_CONSTITUTION } from './constitution-loader'
@@ -37,6 +37,7 @@ import {
 import type { CrsiSignal } from './crsi-producer'
 import { predictionHit } from './improvement-track'
 import { loadBehaviorTasks, judgeBehaviorTask } from './behavior-tasks'
+import { miphamHome } from './paths.ts'
 
 // ── Types ──
 
@@ -95,7 +96,7 @@ export function regressedAnchors(results: EvalResult[]): string[] {
 
 // ── Rewards log (path A Phase 1: 奖励信号持久化) ──
 
-const SCORES_FILE = join(homedir(), '.mipham', 'crsi', 'eval-scores.jsonl')
+const SCORES_FILE = miphamHome('crsi', 'eval-scores.jsonl')
 
 /** 落盘的契约粒度投影 —— 只要 id/passed/role（EvalResult 的 description/detail 不落盘）。 */
 export interface ContractResultRecord {
@@ -117,7 +118,7 @@ export function appendEvalScore(
   report: { score: number; passed: number; total: number; results?: EvalResult[] },
 ): void {
   try {
-    mkdirSync(join(homedir(), '.mipham', 'crsi'), { recursive: true })
+    mkdirSync(miphamHome('crsi'), { recursive: true })
     appendFileSync(
       SCORES_FILE,
       JSON.stringify({

package/src/core/improvement-track.ts

@@ -1,10 +1,9 @@
 // CRSI 改进轨：噪声自适应改进判定 + 台账 + pending verdict 闸。
 // A1 不破：verdict / minEffect / 改进率全是确定性算术（均值/标准差/阈值/Wilson），无 LLM 裁判。
 import { readFileSync, existsSync, mkdirSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { atomicWriteFileSync } from '../shared/atomic-write'
 import type { SkillDeltaSample } from './task-performance'
+import { miphamHome } from './paths.ts'
 
 export type ImprovementVerdict = 'improved' | 'regressed' | 'inconclusive'
 
@@ -181,12 +180,12 @@ export function formatCostLine(report: ImprovementReport): string | null {
 // ── 台账 ──
 
 export function improvementPath(): string {
-  return join(homedir(), '.mipham', 'crsi', 'improvements.jsonl')
+  return miphamHome('crsi', 'improvements.jsonl')
 }
 
 export function appendImprovement(record: ImprovementRecord): void {
   const file = improvementPath()
-  mkdirSync(join(homedir(), '.mipham', 'crsi'), { recursive: true })
+  mkdirSync(miphamHome('crsi'), { recursive: true })
   // 原子激活（④）：整账本读-改-写 + temp 文件 rename（见 shared/atomic-write），读者要么见旧要么见新。
   // 非原子的 appendFileSync 写中途崩溃会留撕裂行，readImprovements 会 JSON.parse 抛错。
   const existing = readImprovements()
@@ -214,7 +213,7 @@ export function readImprovements(): ImprovementRecord[] {
 // （temp+rename，见 shared/atomic-write），替代易失内存变量（进程重启即丢、无 manifest）。
 
 export function pendingVerdictPath(): string {
-  return join(homedir(), '.mipham', 'crsi', 'pending-verdict.json')
+  return miphamHome('crsi', 'pending-verdict.json')
 }
 
 export function setPendingVerdict(v: ImprovementVerdict | null): void {
@@ -223,7 +222,7 @@ export function setPendingVerdict(v: ImprovementVerdict | null): void {
     rmSync(file, { force: true }) // 原子清除（unlink 原子）
     return
   }
-  mkdirSync(join(homedir(), '.mipham', 'crsi'), { recursive: true })
+  mkdirSync(miphamHome('crsi'), { recursive: true })
   atomicWriteFileSync(file, JSON.stringify({ verdict: v, timestamp: new Date().toISOString() }))
 }
 

package/src/core/instructions.ts

@@ -1,6 +1,5 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { join, resolve, relative, sep, isAbsolute } from 'node:path'
-import { homedir } from 'node:os'
 import { execSync } from 'node:child_process'
 import { parse as parseYaml } from 'yaml'
 import type { InstructionFile } from '../shared/index.ts'
@@ -11,6 +10,7 @@ import {
   buildCrsiLessonsBlock,
   type CrsiLessonSummary,
 } from './crsi-producer'
+import { miphamHome } from './paths.ts'
 
 export interface FrontmatterResult {
   data: Record<string, unknown>
@@ -127,8 +127,7 @@ export class InstructionsLoader {
     })
 
     // Tier 3: 用户层 ~/.mipham/USER.md
-    const home = homedir()
-    this.tryLoad(join(home, '.mipham', 'USER.md'), 'user')
+    this.tryLoad(miphamHome('USER.md'), 'user')
 
     // CRSI 教训召回：读 crsi-lessons.md 提取精华，注入系统提示（只写不读 → 写后召回）
     this.crsiLessonSummaries = this.loadCrsiLessons(root)
@@ -327,12 +326,21 @@ Never omit it or present the work as purely human-authored.`)
    * Tells the model its current permission level and what to expect.
    */
   private buildPermissionContext(mode: string): string {
+    // Hand-written map, and a missing key is **silent**: the `if (!description)`
+    // below returns `''`, so the system prompt would simply say nothing about
+    // permissions rather than warn. Every `PermissionMode` member needs a line.
+    // `auto`'s text has to describe a gate the model cannot see: it is told
+    // "a classifier rules on each of your calls" rather than "you are
+    // unrestricted", because a model that believes it has blanket permission
+    // stops explaining what it is about to do — which is exactly the input the
+    // classifier needs.
     const modeDescriptions: Record<string, string> = {
       default:
         'You are in **default** mode. Tools marked as requiring approval will be blocked. Use Read/Grep/Glob for exploration.',
       acceptEdits:
         'You are in **acceptEdits** mode. File reads and edits are allowed; Bash requires approval.',
       plan: 'You are in **plan** mode. Only Read/Grep/Glob are allowed — no file modifications or command execution.',
+      auto: 'You are in **auto** mode. A classifier reviews each tool call before it runs and blocks calls that are destructive, that act on instructions found in files or tool output, or that touch credentials. Approved calls run; blocked ones return a denial with the reason. Prefer explaining the intent of a call when it is unusual.',
       bypassPermissions:
         'You are in **bypassPermissions** mode. All tools are allowed. Use this power responsibly.',
     }
@@ -340,7 +348,23 @@ Never omit it or present the work as purely human-authored.`)
     const description = modeDescriptions[mode]
     if (!description) return ''
 
-    return `## Permission Context\n\n${description}\n\nWhen a tool is denied, do NOT retry it or any other approval-gated tool — Bash, WebSearch, network, and Workflow are all blocked in this mode. If the task genuinely needs a blocked tool, STOP retrying and ask the user to switch to bypassPermissions (Shift+Tab) or add an allow rule (/permissions), then wait for the user's answer.`
+    // What actually lifts a denial is not the same in `auto`. There the refusal is a
+    // ruling on one exact call, and a repeat of that same call is answered from the
+    // classifier cache rather than re-judged — so "retry after explaining yourself" is
+    // advice that cannot work, and telling the model to switch modes is advice that is
+    // never needed. The two levers that do work are named instead.
+    const escape =
+      mode === 'auto'
+        ? ' In **auto** mode the refusal is a ruling on that exact call: an allow rule (`/permissions allow`) lifts it, and so does changing the call so it no longer trips the rule — repeating the identical call returns the same ruling.'
+        : ''
+
+    // The tail used to name `bypassPermissions` as the Shift+Tab destination. That
+    // was true while the wheel carried it and became false the moment `auto`
+    // replaced it — and this string is *advice the model repeats to the user*, so
+    // staying stale makes it promise a keypress that does nothing. `bypassPermissions`
+    // is still reachable, but only by naming it in config; saying so is what keeps
+    // the model from offering it as a way out.
+    return `## Permission Context\n\n${description}\n\nWhen a tool is denied, do NOT retry it or any other approval-gated tool — Bash, WebSearch, network, and Workflow are all blocked in this mode.${escape} If the task genuinely needs a blocked tool, STOP retrying and ask the user to switch modes with Shift+Tab or add an allow rule (/permissions), then wait for the user's answer. Note that Shift+Tab's wheel does not reach bypassPermissions — that mode is set in config, so do not offer it as a keypress.`
   }
 
   list(): InstructionFile[] {

package/src/core/memory/memory-loader.ts

@@ -1,9 +1,8 @@
-import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { MemoryManager } from './memory-manager'
 import type { MemoryManager as MemoryManagerType } from './memory-manager'
+import { miphamHome } from '../paths.ts'
 
-const MEMORY_DIR = join(homedir(), '.mipham', 'memory')
+const MEMORY_DIR = miphamHome('memory')
 
 let instance: MemoryManagerType | null = null
 

package/src/core/paths.ts

@@ -1,5 +1,10 @@
 /**
- * 项目内数据目录的路径单一真源。
+ * 数据目录的路径单一真源 —— **项目内** `.mipham/` 与**用户级** `~/.mipham`。
+ *
+ * 目录名 `.mipham` 曾在 `src/` 里散落成几十处各自独立的字面量：用户级写
+ * `join(homedir(), '.mipham', …)`、项目内写 `join(cwd, '.mipham', …)`，两级的根
+ * 因此都没人守。现在字面量只剩 `shared/constants.ts` 的 `MIPHAM_DIR` 一处 ——
+ * 用户级一律经 `miphamHome()`，项目内一律经 `join(<dir>, MIPHAM_DIR, …)`。
  *
  * 写入一律落在 `.mipham/`（我们自己的目录）；`.claude/` 只保留**只读兼容** ——
  * 早期版本把 worktree 建在 `.claude/worktrees/` 下，那些工作树今天仍要可列举、
@@ -120,3 +125,18 @@ export function workflowScriptDirs(cwd: string): string[] {
     join(homedir(), LEGACY_CLAUDE_DIR, 'workflows'),
   ]
 }
+
+/* ── 用户级数据根 ──────────────────────────────────────────────────────── */
+
+/**
+ * 用户级数据根目录 `~/.mipham`，后可接任意子路径。
+ *
+ * `homedir()` 在**调用时**求值，与改造前的调用点语义一致 —— 调用点若在模块作用域，
+ * 本函数也在那时求值。这不是可有可无的细节：`config/loader.ts` 的 `MIPHAM_HOME` 正是
+ * 模块作用域捕获的，测试靠 `vi.mock('node:os')` + `vi.hoisted` 抢在 import 之前装
+ * mock 才拦得住它（见 `test/telemetry/index.test.ts` 顶部那条注释）。故本函数**不得**
+ * 改成在别处预先算好再传进来 —— 那会把「调用时求值」换成「导入时求值」。
+ */
+export function miphamHome(...segments: string[]): string {
+  return join(homedir(), MIPHAM_DIR, ...segments)
+}

package/src/core/permission-audit.ts

@@ -0,0 +1,120 @@
+/**
+ * 分类器裁决的本地台账 —— `~/.mipham/permission-audit.jsonl`。
+ *
+ * **为什么需要它。** 设计文档 §3.7（决策 5）与风险 8 记着同一条：子代理与后台是
+ * **无人值守**的（后台 / worktree / daemon 共用 `sub-agent.ts` 那条路径），而那道闸门
+ * 只有**拒绝**的通知路径 —— **放行是无声的**。`source: 'classifier'` 在
+ * `resolveApproval()` 里被造出来，随后只在**拒绝**分支上被两个闸门读走
+ * （`engine.ts` / `sub-agent.ts` 的 `decision.source === 'classifier'` 都嵌在拒绝那一支），
+ * 放行那一支的这个字段直接丢掉：没有会话日志事件、没有 metrics 计数器、也没有 hook 事件。
+ * 于是「`auto` 档到底批过什么」在本机没有任何一处读得出来。
+ *
+ * **为什么记在 `resolveApproval()` 里。** 那里是裁决的**出生地**，也是唯一一个天然覆盖
+ * 全部闸门的点：今天两个（`engine.ts` / `sub-agent.ts`），将来第三个也自动在内。反过来把
+ * 记录挂在两个闸门上，就是本仓库反复出现的那族缺陷的形状 —— 两条路径只接一条。更要紧的是
+ * 第二条理由：**子代理根本没有 `SessionLog`**（`SubAgent` 的构造函数里没有这个参数），
+ * 所以「走会话日志事件」这条更整齐的路在子代理那里无路可走，除非给它新拉一条日志管线。
+ * 这是相对原计划的一处**偏离**：原计划写的是会话日志事件，实测后改为这里的**模块级台账**
+ * （session-log 的 `checker/decision` 是同类先例，但那条先例只覆盖引擎，覆盖不到子代理）。
+ *
+ * **记什么、不记什么。** 只记「哪次调用、谁裁的、裁成什么、为什么」—— **绝不记工具入参**。
+ * 入参里会有文件正文、命令行、凭据片段。分类器的 `reason` 是模型生成的一句话，可能复述
+ * 入参，但它落在本机 0600 的文件里、不上网。这**不构成新的暴露面**：同一次调用在会话日志里
+ * 本来就以全量入参 + 全量结果的形式落盘了（`session-log.ts` 的「model-visible means logged」），
+ * 台账严格更少；子代理那条路径虽然没有会话日志，但仍是本机 0600、不经网络。
+ * **边界（是取舍，不是遗漏）**：没有入参 ⇒ 「`auto` 放行了哪一条 Bash」只能从 `reason` 里读，
+ * 读不到命令原文。要还原到那一层请去会话日志（引擎路径有，子代理路径没有）。
+ *
+ * **一条裁决 = 一行，不是一次执行 = 一行。** 记录写在分类器**真的被咨询**的那两处；
+ * `classifierCache` 命中**不写** —— 那时分类器根本没被问到（`resolveApproval()` 在调用它
+ * 之前就从缓存返回了），写一行等于声称有一个没人做过的裁决。反过来读：台账回答的是
+ * 「分类器裁过什么」，不是「某条命令跑了几次」；执行次数要问 gate 侧的指标或会话日志。
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { PermissionLevel, PermissionMode } from '../shared/index.ts'
+import type { PermissionDenialReason } from './permission'
+import { miphamHome } from './paths.ts'
+
+/** 一条分类器裁决。 */
+export interface ClassifierRulingRecord {
+  /** ISO 时间戳。 */
+  at: string
+  /** 裁决时的档位。今天只可能是 `'auto'`，写上它是为了让记录自证而不是靠读者推断。 */
+  mode: PermissionMode
+  tool: string
+  /** **分类器说了什么。** */
+  verdict: 'allow' | 'deny'
+  /**
+   * **这一支最终落定的档位。** 分类器放行后仍可能是 `'ask'` —— 放行走的是
+   * `allowRuleDecision()`，组织级 `maxAllowedMode` 会在那里封顶（`resolveApproval` 第 4 步）。
+   * 那种记录读作「分类器同意、上限否决」，`verdict` 与 `level` 两个字段合起来才说得清。
+   */
+  level: PermissionLevel
+  /** 分类器自己的一句话理由（模型生成 —— 见文件头「记什么」）。缺省不写该键。 */
+  reason?: string
+  /** 仅拒绝：`true` ⇒ 引擎故障拿住，**不是策略决定**，重试是对的。缺省不写该键。 */
+  retryable?: boolean
+  /** 仅拒绝：拒绝的类别（策略拒绝是 `'classifier-deny'`）。缺省不写该键。 */
+  denialReason?: PermissionDenialReason
+}
+
+/**
+ * 台账路径。**每次现算**，不存模块级常量 —— 测试对 `node:os` 的 `homedir` mock
+ * （全局 `vitest.setup.ts` 与文件级 `vi.mock` 两种）都因此一定生效，且不必依赖
+ * import 求值与 mock hoisting 的先后。`eval-harness.ts` 用模块级常量也能成立，
+ * 但那是「恰好也对」，这里不复制那个形状。
+ */
+export function permissionAuditPath(): string {
+  return miphamHome('permission-audit.jsonl')
+}
+
+/** 整个进程只说一次 —— 见 `recordClassifierRuling` 的失败分支。 */
+let warnedOnce = false
+
+/**
+ * 追加一条裁决。**永不抛。**
+ *
+ * 一次台账写失败不该掀翻一次工具调用（可用性优先），但**也不能静默地失败** ——
+ * 这个模块存在的全部意义就是消掉「无声」，若写不进去还一声不响，等于把无声又装了回来。
+ * 折中是：调用方看不到异常，第一次失败往 stderr 说一句，之后不再重复。stderr 是本仓库
+ * 既有的告警通道（`hooks.ts` / `workspace-trust.ts` 同形）。
+ */
+export function recordClassifierRuling(record: Omit<ClassifierRulingRecord, 'at'>): void {
+  try {
+    const file = permissionAuditPath()
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...record }) + '\n', {
+      encoding: 'utf-8',
+      // 只在创建时生效；已存在的文件不会被改权限。
+      mode: 0o600,
+    })
+  } catch (err) {
+    if (!warnedOnce) {
+      warnedOnce = true
+      process.stderr.write(
+        `⚠️  分类器台账写不进去（之后不再重复报告）: ${err instanceof Error ? err.message : String(err)}\n`,
+      )
+    }
+  }
+}
+
+/**
+ * 读回全部裁决。**撕裂行只跳过那一行** —— 写到一半进程被杀会留半行 JSON，
+ * 读侧不能因此整份报废（`improvement-track.ts` 的同形处理）。
+ */
+export function readClassifierRulings(): ClassifierRulingRecord[] {
+  const file = permissionAuditPath()
+  if (!existsSync(file)) return []
+  return readFileSync(file, 'utf-8')
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line) as ClassifierRulingRecord]
+      } catch {
+        return []
+      }
+    })
+}