@miphamai/cli 0.83.0 → 0.84.0

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

package/src/core/rule-engine.ts

@@ -1,8 +1,8 @@
 import type { ExperienceRule } from '../agent/experience-rules.js'
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { MANAGED_RULES } from './crsi-managed-rules'
+import { miphamHome } from './paths.ts'
 
 export interface ToolRule {
   id: string
@@ -62,7 +62,7 @@ export class ExperienceRuleEngine {
   private rules: ToolRule[]
   private storePath: string
 
-  constructor(storeDir: string = join(homedir(), '.mipham', 'rule-engine')) {
+  constructor(storeDir: string = miphamHome('rule-engine')) {
     this.rules = [...BUILTIN_RULES, ...MANAGED_RULES].map((r) => ({ ...r }))
     this.storePath = join(storeDir, 'rules.json')
     this.load()

package/src/core/rules-loader.ts

@@ -21,6 +21,7 @@ import { readdirSync, readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { globToRegexSource } from './credential-masker/matcher'
 import { findWorktreeMarker } from './paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
 interface RuleFile {
   name: string
@@ -49,9 +50,9 @@ export class RulesLoader {
   private projectRulesDir: string | null
 
   constructor(cwd: string) {
-    this.rulesDir = join(cwd, '.mipham', 'rules')
+    this.rulesDir = join(cwd, MIPHAM_DIR, 'rules')
     const marker = findWorktreeMarker(cwd)
-    const projectRulesDir = marker ? join(marker.root, '.mipham', 'rules') : null
+    const projectRulesDir = marker ? join(marker.root, MIPHAM_DIR, 'rules') : null
     this.projectRulesDir = projectRulesDir === this.rulesDir ? null : projectRulesDir
   }
 

package/src/core/session-log.ts

@@ -1,9 +1,9 @@
 import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import type { Message, ToolUseContent, ToolResultContent, ToolResult } from '../shared/types'
 import type { CheckerDecision } from './post-flight-checker'
+import { miphamHome } from './paths.ts'
 
 export type SessionEvent =
   | {
@@ -115,8 +115,7 @@ export function deriveMessages(events: SessionEvent[]): Message[] {
   return out
 }
 
-const HOME = homedir()
-const LOG_DIR = join(HOME, '.mipham', 'sessions')
+const LOG_DIR = miphamHome('sessions')
 
 /** 将会话名消毒为安全文件名（与 SessionStore 共用；防路径穿越）。 */
 export function sanitizeSessionName(name: string): string {

package/src/core/session-store.ts

@@ -8,11 +8,11 @@ import {
   existsSync,
   statSync,
 } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import type { Message } from '../shared/types'
 import { sanitizeSessionName, SessionLog, deriveMessages, messageToEvents } from './session-log'
+import { miphamHome } from './paths.ts'
 
 export interface SessionMetadata {
   name: string
@@ -29,8 +29,7 @@ export interface StoredSession {
   messages: Message[]
 }
 
-const HOME = homedir()
-const SESSIONS_DIR = join(HOME, '.mipham', 'sessions')
+const SESSIONS_DIR = miphamHome('sessions')
 const INDEX_FILE = join(SESSIONS_DIR, '.index.json')
 const SUMMARIES_DIR = join(SESSIONS_DIR, '.summaries')
 

package/src/core/workspace-trust.ts

@@ -1,9 +1,10 @@
 import { readFileSync, existsSync, mkdirSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
-import { homedir } from 'node:os'
 import { atomicWriteFileSync } from '../shared/atomic-write'
+import { miphamHome } from './paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const TRUST_STORE_PATH = join(MIPHAM_HOME, 'trusted-workspaces.json')
 
 export interface TrustedWorkspaces {
@@ -198,7 +199,7 @@ export function resetWorkspaceTrust(): void {
  */
 export function warnProjectHooksSkipped(cwd: string): void {
   process.stderr.write(
-    `⚠️  Workspace not trusted: skipped hooks from ${join(cwd, '.mipham', 'settings.json')}\n` +
+    `⚠️  Workspace not trusted: skipped hooks from ${join(cwd, MIPHAM_DIR, 'settings.json')}\n` +
       `    (hooks run commands — repository-controlled). Trust this directory in an interactive\n` +
       `    session to enable them.\n`,
   )

package/src/daemon/database.ts

@@ -1,7 +1,6 @@
 // apps/cli/src/daemon/database.ts
 import { Database } from 'bun:sqlite'
 import { readdirSync, readFileSync, existsSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type {
   DaemonSession,
@@ -12,6 +11,7 @@ import type {
   CreateSessionInput,
   SessionStatus,
 } from './types'
+import { miphamHome } from '../core/paths.ts'
 
 export class DaemonDatabase {
   private db: Database
@@ -340,7 +340,7 @@ export class DaemonDatabase {
   // ── Migration ──────────────────────────────────────────────
 
   migrateFromJsonl(): number {
-    const sessionsDir = join(homedir(), '.mipham', 'sessions')
+    const sessionsDir = miphamHome('sessions')
 
     if (!existsSync(sessionsDir)) return 0
 

package/src/daemon/index.ts

@@ -8,7 +8,6 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs'
 import { createServer as createNetServer } from 'node:net'
-import { homedir } from 'node:os'
 import type { Server } from 'bun'
 import { DaemonDatabase } from './database'
 import { SessionManager } from './session-manager'
@@ -32,9 +31,9 @@ import type { WecomConfig } from './wecom/types.js'
 import { parseDingtalkEnv } from './dingtalk/env.js'
 import type { DingtalkConfig } from './dingtalk/types.js'
 import { loadConfig } from '../config/loader'
+import { miphamHome } from '../core/paths.ts'
 
-const HOME = homedir()
-const MIPHAM_HOME = join(HOME, '.mipham')
+const MIPHAM_HOME = miphamHome()
 const DB_PATH = join(MIPHAM_HOME, 'daemon.db')
 const TOKEN_PATH = join(MIPHAM_HOME, 'daemon.token')
 const PID_FILE = join(MIPHAM_HOME, 'daemon.pid')

package/src/daemon/launch.ts

@@ -13,13 +13,13 @@
 
 import { spawn, type SpawnOptions } from 'node:child_process'
 import { closeSync, mkdirSync, openSync, readFileSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { miphamHome } from '../core/paths.ts'
 
 /** argv sentinel that re-enters this program as a daemon. Not user-facing. */
 export const DAEMON_ENTRY = '__daemon'
 
-const DEFAULT_LOG_FILE = join(homedir(), '.mipham', 'daemon.log')
+const DEFAULT_LOG_FILE = miphamHome('daemon.log')
 
 /**
  * argv prefix that re-runs *this* program.