@miphamai/cli 0.81.8 → 0.82.0

package/src/shared/arg-validation.ts

@@ -29,7 +29,42 @@ const KNOWN_COMMANDS = [
   'help',
 ]
 
-const KNOWN_FLAGS = ['--version', '-v', '-V', '--help', '-h', '--dump-config', '--safe-mode']
+const KNOWN_FLAGS = [
+  '--version',
+  '-v',
+  '-V',
+  '--help',
+  '-h',
+  '--dump-config',
+  '--safe-mode',
+  '--resume',
+]
+
+/**
+ * Flags that consume the **next** argument as their value. That value is not a
+ * command, so it must not go through the unknown-command check: with
+ * `mipham --resume "my session"` the old scan found the first token that didn't
+ * start with `-`, concluded the user had typed a command, and reported
+ * `Unknown command: mipham my session` — blaming the session name and never
+ * mentioning `--resume`, the one argument that was actually wrong.
+ */
+const VALUE_FLAGS = ['--resume']
+
+/**
+ * The first token that would be read as a command, skipping flags and the values
+ * of value-taking flags. `null` when there is none.
+ */
+function firstPositional(args: string[]): string | null {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (arg.startsWith('-')) {
+      if (VALUE_FLAGS.includes(arg)) i++ // its value is not a command
+      continue
+    }
+    return arg
+  }
+  return null
+}
 
 /** Levenshtein edit distance between two strings. */
 function levenshtein(a: string, b: string): number {
@@ -64,7 +99,7 @@ function closest(target: string, candidates: string[], maxDist = 3): string[] {
  * command is present, instead of falling through to the interactive CLI.
  */
 export function detectUnknownArgument(args: string[]): UnknownArgument | null {
-  const firstArg = args.find((a) => !a.startsWith('-'))
+  const firstArg = firstPositional(args)
   if (firstArg && !KNOWN_COMMANDS.includes(firstArg)) {
     return { kind: 'command', arg: firstArg, suggestions: closest(firstArg, KNOWN_COMMANDS) }
   }

package/src/shared/package-info.ts

@@ -9,7 +9,7 @@
 export const PACKAGE_NAME = '@miphamai/cli' as const
 
 /** 当前发布版本 */
-export const PACKAGE_VERSION = '0.81.8' as const
+export const PACKAGE_VERSION = '0.82.0' as const
 
 /** npm install 全局安装命令 */
 export const NPM_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}` as const

package/src/shared/sanitize.ts

@@ -10,14 +10,39 @@
  * to ASCII equivalents for permission checks.
  */
 
-const DANGEROUS_UNICODE = /[​‌‍‎‏‪‫‬‭‮⁠⁦⁧⁨⁩]/g
+/**
+ * Invisible/formatting code points that can hide content.
+ *
+ * Written as `\u{…}` escapes (hence the `u` flag) so the set is *auditable*: the
+ * same list spelled as literal characters is unreviewable in a diff, which is how
+ * the tag block (U+E0000–E007F) went missing while every neighbouring family was
+ * already covered.
+ *
+ * Deliberately **not** included — variation selectors (U+FE00–FE0F):
+ * - they are load-bearing in emoji (e.g. U+2764 U+FE0F), so stripping them
+ *   visibly changes text;
+ * - `sanitizeParams` feeds `tool.execute` (`tools/validation.ts`), so the strip is
+ *   applied to what tools *write to disk*, not only to what gets pattern-matched.
+ *   Adding them here would silently rewrite file contents.
+ *
+ * The tag block (U+E0000–E007F) *is* included: it is invisible in itself, and the
+ * only sequences that use it (subdivision flags, e.g. U+1F3F4 + a tag run) degrade
+ * to the bare black flag — which renders the same.
+ */
+const DANGEROUS_UNICODE =
+  /[\u{061C}\u{115F}-\u{1160}\u{180E}\u{200B}-\u{200F}\u{202A}-\u{202E}\u{2060}\u{2066}-\u{2069}\u{3164}\u{FEFF}\u{FFA0}\u{E0000}-\u{E007F}]/gu
 
 /**
  * Strip dangerous invisible Unicode characters from a string.
  * - Zero-width: U+200B (ZWSP), U+200C (ZWNJ), U+200D (ZWJ), U+200E/F (LTR/RTL marks)
- * - Bidi controls: U+202A-E, U+2066-9
+ * - Bidi controls: U+202A-E, U+2066-9, U+061C (Arabic letter mark)
  * - Word joiner: U+2060
  * - BOM: U+FEFF
+ * - Invisible fillers: U+115F/1160 (Hangul choseong/jungseong), U+3164 (Hangul),
+ *   U+FFA0 (halfwidth Hangul), U+180E (Mongolian vowel separator)
+ * - Tag characters: U+E0000-E007F (deprecated, invisible, hide arbitrary text)
+ *
+ * See `DANGEROUS_UNICODE` for which *adjacent* families are left in place, and why.
  */
 export function stripDangerousUnicode(input: string): string {
   if (!input) return input

package/src/shared/types.ts

@@ -276,6 +276,14 @@ export interface HookDefinition {
 
 export interface HookContext {
   event: HookEvent
+  /**
+   * The workspace this invocation is for.
+   *
+   * Stamped by `HookEngine` from its own cwd; hooks read it out of stdin and run
+   * in it. It is the *session's* cwd, which is not `process.cwd()` in the daemon
+   * (many sessions, one process).
+   */
+  cwd?: string
   toolName?: string
   toolInput?: Record<string, unknown>
   toolResult?: ToolResult

package/src/shared/update.ts

@@ -26,10 +26,20 @@ const REGISTRIES = [
 export interface UpdateCheck {
   /** Current installed version */
   current: string
-  /** Latest version on npm */
+  /** Latest version on npm — only meaningful when `checked` is true */
   latest: string
   /** Whether an update is available */
   available: boolean
+  /**
+   * Whether the registry was actually reached.
+   *
+   * `false` means `latest`/`available` carry **no information**: the check
+   * failed and `latest` is just `current`. Without this field the two states
+   * are the same value — "we asked, you're current" and "we couldn't ask" both
+   * read as `available: false`, which is how `/upgrade` came to print
+   * "Already up to date" while offline.
+   */
+  checked: boolean
 }
 
 /**
@@ -101,15 +111,19 @@ export function checkForUpdates(): UpdateCheck {
   const current = getCurrentVersion()
   let latest = current
   let available = false
+  let checked = false
 
   try {
     latest = fetchLatestVersion()
     available = compareVersions(latest, current) > 0
+    checked = true
   } catch {
-    // If we can't reach npm, treat as up-to-date (don't alarm the user)
+    // Registry unreachable — stay quiet rather than alarm, but do **not** claim
+    // we are current: `checked: false` is what lets `/upgrade` say "couldn't
+    // check" instead of "Already up to date".
   }
 
-  return { current, latest, available }
+  return { current, latest, available, checked }
 }
 
 /**
@@ -222,13 +236,16 @@ export async function checkForUpdatesAsync(): Promise<UpdateCheck> {
   const current: string = PACKAGE_VERSION
   let latest: string = current
   let available = false
+  let checked = false
   try {
     latest = await fetchLatestVersionAsync()
     available = compareVersions(latest, current) > 0
+    checked = true
   } catch {
-    // offline → treat as up-to-date (don't alarm the user)
+    // offline → don't alarm the user, but don't report `available: false` as if
+    // it were an answer either (`checked` is what keeps the two apart)
   }
-  return { current, latest, available }
+  return { current, latest, available, checked }
 }
 
 /**

package/src/tools/agent/agent.ts

@@ -88,6 +88,9 @@ export const agentTool: ToolDefinition = {
         type: agentType,
         agentDef,
         runInBackground,
+        // Hand the caller's services down: the sub-agent keeps running the same
+        // skills/agents/artifacts, and only the fields it owns are overridden.
+        toolContext: ctx,
       })
 
       // If background execution, also register in the task system for Task tool integration

package/src/tools/exec/bash.ts

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
 import type { ToolDefinition, CredentialMaskingConfig } from '../../shared/index.ts'
 import { sanitizeCommand } from '../../shared/sanitize.ts'
 import { DANGEROUS_GIT_PATTERNS } from './git.ts'
@@ -363,7 +364,22 @@ export function createBashTool(credentialConfig?: CredentialMaskingConfig): Tool
     },
     async execute(params, ctx) {
       const command = params.command as string
-      const timeout = Math.min((params.timeout as number) || 120_000, 600_000)
+      const requestedTimeout = params.timeout as number | undefined
+      // A negative timeout is not "no timeout". `Math.min(-1 || 120_000, 600_000)` is `-1`,
+      // and `setTimeout(fn, -1)` is clamped to **1 ms** — so the command is group-killed on
+      // the spot and reported as a bare `Exit code 137` (measured with real bun). Node does
+      // warn, but only on stderr, where the model never sees it. Refuse rather than silently
+      // reinterpret; `0`, `NaN` and `undefined` already fall back to the default via `||`.
+      if (typeof requestedTimeout === 'number' && requestedTimeout < 0) {
+        return {
+          success: false,
+          content: '',
+          error:
+            `timeout must not be negative (got ${requestedTimeout}ms). ` +
+            `Omit it for the 120000ms default.`,
+        }
+      }
+      const timeout = Math.min(requestedTimeout || 120_000, 600_000)
 
       // P0-4: Worktree isolation — block cd escape attempts
       // 标记取自 core/paths.ts：新目录与历史 .claude/worktrees/ 都认，
@@ -401,15 +417,42 @@ export function createBashTool(credentialConfig?: CredentialMaskingConfig): Tool
           stdout: 'pipe',
           stderr: 'pipe',
           env: spawnEnv,
+          // Own process group. Required for the group kill below to reach
+          // grandchildren — and for it to target *our* group at all: without
+          // this the child inherits the parent's pgid, so `kill(-pid)` aims at
+          // the wrong group and fails (or, worse, hits the parent's).
+          detached: true,
         })
 
-        const timer = setTimeout(() => proc.kill(), timeout)
-        const rawOutput = await new Response(proc.stdout).text()
+        // Start reading at once — a child that fills the pipe buffer blocks on
+        // write and would then never exit — but do **not** await here: if a
+        // descendant inherits the pipe and outlives the shell, EOF never comes,
+        // and awaiting this before `exited` is what hung the call for good.
+        const stdoutRead = new Response(proc.stdout).text()
+        const stderrRead = new Response(proc.stderr).text()
+
+        // Remember whether we were the ones who killed it: the exit code is 137 and
+        // stderr is empty either way, so the model cannot tell a timeout from the
+        // command's own failure (measured with real bun — both are `Exit code 137: `).
+        let timedOut = false
+        const timer = setTimeout(() => {
+          timedOut = true
+          killProcessGroup(proc.pid)
+        }, timeout)
         const exitCode = await proc.exited
         clearTimeout(timer)
 
+        // The shell is gone, so only a pipe-holding descendant can still be
+        // holding these up. Released by the group kill, at most once.
+        let released = false
+        const release = () => {
+          if (released) return
+          released = true
+          killProcessGroup(proc.pid)
+        }
+        const rawOutput = await settlePipe(stdoutRead, release)
         // Read stderr for violation detection and error reporting
-        const rawStderr = await new Response(proc.stderr).text()
+        const rawStderr = await settlePipe(stderrRead, release)
 
         // ── Credential masking: scrub output ──
         let output = rawOutput
@@ -450,7 +493,9 @@ export function createBashTool(credentialConfig?: CredentialMaskingConfig): Tool
           return {
             success: false,
             content: errorContent,
-            error: `Exit code ${exitCode}: ${stderr.slice(0, 1_000)}`,
+            error: timedOut
+              ? `Command timed out after ${timeout}ms (killed): ${stderr.slice(0, 1_000)}`
+              : `Exit code ${exitCode}: ${stderr.slice(0, 1_000)}`,
           }
         }
 
@@ -460,16 +505,71 @@ export function createBashTool(credentialConfig?: CredentialMaskingConfig): Tool
         }
         return { success: true, content: successContent }
       } catch (err) {
+        // A missing `cwd` and a missing `bash` both surface as the *same*
+        // `ENOENT: no such file or directory, posix_spawn 'bash'` (measured), which reads
+        // as "bash is not installed" and points the model at the wrong root cause. The cwd
+        // is the one we can actually check — so check it, and only claim it when it is
+        // genuinely absent, or a truly missing bash would get relabelled as a bad cwd.
+        const code = (err as NodeJS.ErrnoException | undefined)?.code
         return {
           success: false,
           content: '',
-          error: `Command failed: ${String(err)}`,
+          error:
+            code === 'ENOENT' && !existsSync(ctx.cwd)
+              ? `Working directory does not exist: ${ctx.cwd}`
+              : `Command failed: ${String(err)}`,
         }
       }
     },
   }
 }
 
+/** Grace given to a descendant still holding the output pipe after the shell itself has exited. */
+const PIPE_GRACE_MS = 1_000
+
+/**
+ * Kill a whole process group. `proc.kill()` reaches only the direct child, so a
+ * `bash -c` that spawned its own children leaves them orphaned and unnotified.
+ * The negative pid addresses the group led by that pid, which exists only when
+ * the child was spawned `detached` — verified on this host: without it the
+ * child's pgid is the *parent's* group, and this call fails with ESRCH rather
+ * than reaching the grandchildren.
+ */
+export function killProcessGroup(pid: number | undefined): void {
+  if (pid === undefined || pid <= 0) return
+  try {
+    process.kill(-pid, 'SIGKILL')
+  } catch (err: unknown) {
+    // ESRCH: the group is already gone, which is the normal case when the
+    // command finished on its own. Anything else means a group kill isn't
+    // available here, so fall back to the direct child.
+    if ((err as NodeJS.ErrnoException).code === 'ESRCH') return
+    try {
+      process.kill(pid, 'SIGKILL')
+    } catch {
+      // Already gone.
+    }
+  }
+}
+
+/**
+ * Await an already-started pipe read, but not forever. A descendant that
+ * inherited the pipe keeps EOF from arriving, and that read is what used to
+ * hang the call after the command itself had finished. Once the grace expires,
+ * take the group down — which closes the pipe — and finish the read.
+ */
+async function settlePipe<T>(read: Promise<T>, release: () => void): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const stalled = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), PIPE_GRACE_MS)
+  })
+  const winner = await Promise.race([read, stalled])
+  clearTimeout(timer)
+  if (winner !== null) return winner
+  release()
+  return read
+}
+
 export const bashToolService: Service = {
   inject: ['credentials'],
   apply(ctx) {

package/src/tools/exec/enter-worktree.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from '../../shared/index.ts'
-import { worktreeRoot } from '../../core/paths.ts'
+import { listsWorktree, worktreeRoot } from '../../core/paths.ts'
 
 export const enterWorktreeTool: ToolDefinition = {
   name: 'EnterWorktree',
@@ -95,7 +95,7 @@ export const enterWorktreeTool: ToolDefinition = {
         stderr: 'pipe',
       })
       const existingWorktrees = await new Response(checkProc.stdout).text()
-      if (existingWorktrees.includes(worktreePath)) {
+      if (listsWorktree(existingWorktrees, worktreePath)) {
         return {
           success: true,
           content:
@@ -126,8 +126,14 @@ export const enterWorktreeTool: ToolDefinition = {
 
       // Create worktree with new branch
       const branchName = `worktree/${name}`
+      // `--` ends git's option parsing. `baseRef` comes from the model and is
+      // otherwise unvalidated, so without it a ref spelled `--force` is read as
+      // an *option*: measured on this machine, `git worktree add -b b <path>
+      // --force` succeeds, while a bogus ref in that same slot is `fatal:
+      // invalid reference`. After `--` git reads it as a ref and rejects
+      // nonsense, which is what a bad base ref should do.
       const proc = Bun.spawn(
-        ['git', 'worktree', 'add', '-b', branchName, worktreePath, resolvedBaseRef],
+        ['git', 'worktree', 'add', '-b', branchName, worktreePath, '--', resolvedBaseRef],
         { cwd, stdout: 'pipe', stderr: 'pipe' },
       )
       const _stdout = await new Response(proc.stdout).text()

package/src/tools/exec/exit-worktree.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from '../../shared/index.ts'
-import { worktreeRoots } from '../../core/paths.ts'
+import { listsWorktree, worktreeRoots } from '../../core/paths.ts'
 
 export const exitWorktreeTool: ToolDefinition = {
   name: 'ExitWorktree',
@@ -39,7 +39,10 @@ export const exitWorktreeTool: ToolDefinition = {
     // Validate the path is under a worktree root（新目录优先，兼容历史 .claude/）
     const cwd = ctx.cwd
     const { resolve } = await import('node:path')
-    const resolvedPath = resolve(worktreePath)
+    // 基数必须是 `cwd`（= ctx.cwd）：下面每一个 `Bun.spawn` 都带 `cwd: ctx.cwd`，
+    // 单参数 `resolve()` 却拿 `process.cwd()` 当归宿 —— 相对路径于是「校验的是 A、
+    // 执行的是 B」。两者在 daemon（ctx.cwd 是会话工作区、不是进程启动目录）下分叉。
+    const resolvedPath = resolve(cwd, worktreePath)
     const roots = worktreeRoots(cwd).map((root) => resolve(root))
     const inWorktree = roots.some(
       (root) => resolvedPath === root || resolvedPath.startsWith(root + '/'),
@@ -64,7 +67,7 @@ export const exitWorktreeTool: ToolDefinition = {
       })
       const listOutput = await new Response(listProc.stdout).text()
 
-      if (!listOutput.includes(worktreePath)) {
+      if (!listsWorktree(listOutput, resolvedPath)) {
         return {
           success: false,
           content: '',

package/src/tools/exec/git.ts

@@ -3,6 +3,9 @@ import type { ToolDefinition } from '../../shared/index.ts'
 import { findWorktreeMarker } from '../../core/paths.ts'
 import { isWithin } from '../../security/path.ts'
 
+/** Generous enough for a clone or fetch, short enough to bound a hung git. */
+const GIT_TIMEOUT_MS = 120_000
+
 // P0-4 (v2.1.222 alignment): Regex-based word-boundary patterns replace
 // fragile substring matching. Each pattern describes what it blocks.
 export const DANGEROUS_GIT_PATTERNS: Array<{ pattern: RegExp; description: string }> = [
@@ -90,6 +93,60 @@ function isOutsideWorktree(command: string, cwd: string): string | null {
   return null
 }
 
+/**
+ * Git options whose value is a program git will execute. The regex list above
+ * covers command execution reached through config keys; these are the ones it
+ * does not name at all, and each was confirmed to run an arbitrary local
+ * program: `ls-remote --upload-pack=/tmp/x.sh <path>`, `push --receive-pack=…`,
+ * and `--exec-path=<dir>` followed by a planted `<dir>/git-<subcommand>`.
+ */
+const PROGRAM_EXECUTING_OPTIONS = ['--upload-pack', '--receive-pack', '--exec-path']
+
+/** Config keys whose value git runs as a program. */
+const PROGRAM_EXECUTING_CONFIG_KEY =
+  /^(?:core\.(?:sshCommand|pager|askpass|editor)|alias\.|credential\.helper)/i
+
+/**
+ * Find an argv entry that makes git execute a program the caller named.
+ *
+ * This runs on the parsed argv rather than the raw command string. The regex
+ * list above is organised by *spelling*, so it has to anticipate every way the
+ * text can be written — `" -c " + "core.pager=…" ` written with quotes between
+ * the two halves never matches it, yet git receives the same two tokens. argv
+ * is what git actually gets, so it has no such gap.
+ */
+export function findProgramExecutingArg(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!
+
+    for (const opt of PROGRAM_EXECUTING_OPTIONS) {
+      // `--upload-pack=<exec>` and `--upload-pack <exec>` are both accepted.
+      if (arg === opt) return `${arg} ${argv[i + 1] ?? ''}`
+      if (arg.startsWith(`${opt}=`)) return arg
+    }
+
+    // `-c<key>=<value>` / `--config=<key>=<value>`. `--config=…` is checked
+    // first so `/^-c[^-]/` cannot swallow it.
+    const attached = arg.startsWith('--config=')
+      ? arg.slice('--config='.length)
+      : /^-c[^-]/.test(arg)
+        ? arg.slice(2)
+        : null
+    if (attached !== null && PROGRAM_EXECUTING_CONFIG_KEY.test(attached)) return arg
+
+    // `-c <key>=<value>` / `--config <key>=<value>`. A bare `-c` also means
+    // "reuse this commit" for `git commit`, but that value never contains `=`,
+    // so the config read cannot swallow it.
+    if ((arg === '-c' || arg === '--config') && i + 1 < argv.length) {
+      const next = argv[i + 1]!
+      if (next.includes('=') && PROGRAM_EXECUTING_CONFIG_KEY.test(next)) {
+        return `${arg} ${next}`
+      }
+    }
+  }
+  return null
+}
+
 /**
  * Split a git command string into argv tokens, honoring shell-style quoting
  * (single quotes, double quotes, and backslash escapes). Unlike a naive
@@ -183,14 +240,32 @@ export const gitTool: ToolDefinition = {
       }
     }
 
+    // Git runs without an approval prompt (`permission: 'auto'`), so an option
+    // that names a program to execute is a code-execution path Bash would have
+    // had to ask for. Checked on argv, which is what git is handed below.
+    const argv = splitCommand(command)
+    const execArg = findProgramExecutingArg(argv)
+    if (execArg) {
+      return {
+        success: false,
+        content: '',
+        error: `Dangerous git option blocked: "${execArg}" makes git run an arbitrary program. Run manually if intended.`,
+      }
+    }
+
     try {
-      const proc = Bun.spawn(['git', ...splitCommand(command)], {
+      const proc = Bun.spawn(['git', ...argv], {
         cwd: ctx.cwd,
         stdout: 'pipe',
         stderr: 'pipe',
       })
+
+      // Bounded like Bash: a git command that blocks on a pager, a credential
+      // prompt, or an unreachable remote would otherwise hang the turn forever.
+      const timer = setTimeout(() => proc.kill(), GIT_TIMEOUT_MS)
       const output = await new Response(proc.stdout).text()
       const exitCode = await proc.exited
+      clearTimeout(timer)
 
       if (exitCode !== 0) {
         const stderr = await new Response(proc.stderr).text()

package/src/tools/file/glob.ts

@@ -6,6 +6,10 @@ import { toolKey } from '../seam'
 import { withValidation } from '../validation'
 import { maskGlobOutput } from '../../core/credential-masker'
 
+/** 结果上限：超过则显式截断并附标记（不能静默丢内容——模型会误以为看全了，
+ *  与 Grep 的 `truncateGrepOutput` 同一约定）。 */
+const GLOB_MAX_RESULTS = 500
+
 export function createGlobTool(credentialConfig?: CredentialMaskingConfig): ToolDefinition {
   return {
     name: 'Glob',
@@ -25,12 +29,24 @@ export function createGlobTool(credentialConfig?: CredentialMaskingConfig): Tool
       const basePath = resolveSafe(ctx.cwd, (params.path as string) || '.')
       const glob = new Glob(pattern)
       const results: string[] = []
+      let truncated = false
       for await (const file of glob.scan({ cwd: basePath, absolute: true })) {
+        if (results.length >= GLOB_MAX_RESULTS) {
+          // 只有真的还有第 501 个匹配时才叫截断 —— 恰好 500 个匹配是完整结果。
+          truncated = true
+          break
+        }
         results.push(file)
-        if (results.length >= 500) break
       }
-      const content = results.join('\n') || '(no matches)'
-      return { success: true, content: maskGlobOutput(content, credentialConfig) }
+      // 先掩码正文、再拼注解：`maskGlobOutput` 是**逐行当路径**去比对的
+      // （每行都过 `matchCredentialFile`），注解不是路径，不该喂给它。
+      const content = maskGlobOutput(results.join('\n') || '(no matches)', credentialConfig)
+      return {
+        success: true,
+        content: truncated
+          ? `${content}\n\n... (truncated at ${GLOB_MAX_RESULTS} matches — narrow the pattern or "path")`
+          : content,
+      }
     },
   }
 }

package/src/tools/file/grep.ts

@@ -54,6 +54,27 @@ export function isTopLevelScope(searchPath: string, home = homedir()): boolean {
   return searchPath === home || searchPath === parse(searchPath).root
 }
 
+/** 把未知异常变成一句可读的原因（`code` 才是可操作的部分：ENOENT / EAGAIN）。 */
+function describeError(err: unknown): string {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code
+    return typeof code === 'string' ? `${code}: ${err.message}` : err.message
+  }
+  return String(err)
+}
+
+/**
+ * 只有「rg 不在 PATH」才该回退到 `find`。别的异常（EAGAIN / EPERM / spawn
+ * 失败）说明 rg 装了却起不来 —— 那不是回退能解决的问题，再起一个 find 只会
+ * 换来第二个失败，而错误信息里的「去装 ripgrep」会把排查方向整条带偏。
+ */
+function isMissingBinary(err: unknown): boolean {
+  if (!(err instanceof Error)) return false
+  if ((err as { code?: unknown }).code === 'ENOENT') return true
+  // 有些抛出方只给句子不给 code。
+  return /ENOENT|not found|no such file or directory/i.test(err.message)
+}
+
 export function createGrepTool(credentialConfig?: CredentialMaskingConfig): ToolDefinition {
   return {
     name: 'Grep',
@@ -139,7 +160,14 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
             'rg error (exit 2) — likely permission denied on a large/protected tree. ' +
             'Narrow scope with "path" (project directory) and "include".',
         }
-      } catch {
+      } catch (err) {
+        if (!isMissingBinary(err)) {
+          return {
+            success: false,
+            content: '',
+            error: `ripgrep failed: ${describeError(err)}`,
+          }
+        }
         // rg not installed → fall through to grep (find + grep fallback)
       }
 
@@ -197,11 +225,13 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
             (stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : '') +
             '. Install ripgrep: brew install ripgrep',
         }
-      } catch {
+      } catch (err) {
+        // 这里回退自己起不来 —— 报回退的真实原因，别再断言「rg 没装」
+        // （走到这一步的路径本来就有「rg 没装」和「装了但起不来」两种）。
         return {
           success: false,
           content: '',
-          error: 'grep failed. Install ripgrep: brew install ripgrep',
+          error: `Search failed to start: ${describeError(err)}`,
         }
       }
     },

package/src/tools/index.ts

@@ -31,13 +31,21 @@ import { listAgentsTool } from './agent/list-agents'
 import { computerUseTool } from './computer/computer-use'
 import { scheduleWakeupTool } from './scheduling/schedule-wakeup.js'
 import { cronCreateTool, cronDeleteTool, cronListTool } from './scheduling/cron.js'
-import { DISABLED_CREDENTIAL_MASKING_CONFIG } from '../config/defaults'
+import { loadUserCredentialMaskingConfig } from '../config/loader'
 
 function defaultVajraContext(): Context {
   const ctx = new Context()
-  // 掩码中立默认：无参调用（daemon/workflow）保持 Read/Bash 挂载，但不启用掩码，
-  // 对齐 pre-seam 行为（那些路径从不调用 setter）。显式开启掩码走 index.tsx 的加载配置。
-  ctx.provide('credentials', DISABLED_CREDENTIAL_MASKING_CONFIG)
+  // Fail-closed 默认：无参调用（daemon / workflow）拿到的是**用户级**掩码策略，
+  // 且配置读不出来时留下的是默认值（掩码开），不是一块关掉的掩码。
+  //
+  // 原先给的是 DISABLED 配置，理由是「对齐 pre-seam 行为」—— 但掩码是安全控制，
+  // 「没配置就关掉」是把默认值的方向定反了：daemon 里 Read/Bash/Grep/Glob 的
+  // 掩码整套失效，子进程继承完整 process.env、输出不擦洗。
+  //
+  // 只取用户级、不取项目级：注册表是 daemon 进程级的一个实例而会话 cwd 各不相同
+  // （见 `loadUserCredentialMaskingConfig` 的注释），把某个项目的段套上去等于让它溢到
+  // 别的会话。交互式 CLI 走 index.tsx 自己的 ctx（含项目级），不经过这里。
+  ctx.provide('credentials', loadUserCredentialMaskingConfig())
   return ctx
 }