@miphamai/cli 0.83.0 → 0.85.0

package/src/config/loader.ts

@@ -8,7 +8,6 @@ import {
   chmodSync,
 } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { atomicWriteFileSync } from '../shared/atomic-write'
 import type {
@@ -29,8 +28,10 @@ import {
 } from './defaults'
 import { getCredentialKey, encryptApiKey, decryptApiKey, ENC_PREFIX } from './credential-crypto'
 import type { SettingsHooks } from '../core/hooks-config'
+import { miphamHome } from '../core/paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const BACKUP_PREFIX = 'config.backup-'
 
 /**
@@ -212,7 +213,7 @@ export function tryRestoreFromBackup(configPath: string): boolean {
 function loadMcpJson(cwd: string): McpServerConfig[] {
   const servers: McpServerConfig[] = []
   const searchPaths = [
-    join(cwd, '.mipham', 'mcp.json'),
+    join(cwd, MIPHAM_DIR, 'mcp.json'),
     join(cwd, '.mcp.json'),
     join(MIPHAM_HOME, 'mcp.json'),
   ]
@@ -294,7 +295,7 @@ export function loadSettingsJson(
 
   const searchPaths: Array<{ path: string; readHooks: boolean; isProject?: boolean }> = [
     {
-      path: join(cwd, '.mipham', 'settings.json'),
+      path: join(cwd, MIPHAM_DIR, 'settings.json'),
       readHooks: options.includeProjectHooks ?? false,
       isProject: true,
     },
@@ -366,7 +367,7 @@ export type SettingsScope = 'project' | 'user'
 export function settingsPathFor(scope: SettingsScope, cwd: string = process.cwd()): string {
   return scope === 'user'
     ? join(MIPHAM_HOME, 'settings.json')
-    : join(cwd, '.mipham', 'settings.json')
+    : join(cwd, MIPHAM_DIR, 'settings.json')
 }
 
 /**
@@ -442,7 +443,7 @@ export function removeSettingsRule(
 }
 
 export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let config = { ...DEFAULT_CONFIG }
@@ -629,7 +630,7 @@ function mergeCredentialMaskingFile(
 export function loadCredentialMaskingConfig(cwd: string = process.cwd()): CredentialMaskingConfig {
   let merged = { ...DEFAULT_CREDENTIAL_MASKING_CONFIG }
   merged = mergeCredentialMaskingFile(merged, join(MIPHAM_HOME, 'config.yml'), true)
-  merged = mergeCredentialMaskingFile(merged, join(cwd, '.mipham', 'config.yml'), false)
+  merged = mergeCredentialMaskingFile(merged, join(cwd, MIPHAM_DIR, 'config.yml'), false)
   return merged
 }
 
@@ -655,7 +656,7 @@ export function loadUserCredentialMaskingConfig(): CredentialMaskingConfig {
  * Load background agent configuration from config sources.
  */
 export function loadBackgroundAgentConfig(cwd: string = process.cwd()): BackgroundAgentConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let merged = { ...DEFAULT_BACKGROUND_AGENT_CONFIG }
@@ -688,7 +689,7 @@ export function loadBackgroundAgentConfig(cwd: string = process.cwd()): Backgrou
  * Merges project-level over user-level. Returns defaults if no section present.
  */
 export function loadCrossSessionConfig(cwd: string = process.cwd()): CrossSessionConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let merged = { ...DEFAULT_CROSS_SESSION_CONFIG }
@@ -751,7 +752,7 @@ function decryptProviderApiKeys(providers: ProviderConfig[] | undefined): void {
  */
 export function getProviderApiKey(providerId: string, cwd: string = process.cwd()): string | null {
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
-  const projectConfigPath = join(cwd, '.mipham', 'config.yml')
+  const projectConfigPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const configPath = existsSync(userConfigPath) ? userConfigPath : projectConfigPath
 
   try {

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)
+}