@miphamai/cli 0.81.6 → 0.81.8

package/src/telemetry/redact.ts

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+
+/**
+ * Redaction for crash reports.
+ *
+ * Nothing in this module is reusable from the existing scrubbers: the four
+ * families in the repo (`credential-masker/`, `security/gate.ts`,
+ * `shared/sanitize.ts`, `skills/sanitizer.ts`) all match *credential shapes* —
+ * token prefixes, JWTs, `sk-ant-…`. None of them removes a user name out of a
+ * path. The only home→`~` helper is `ui/chat.tsx` `displayCwd()`, which is
+ * unexported, has zero call sites, and only ever looks at `process.cwd()` — it
+ * cannot touch a path inside an error object or a stack frame.
+ *
+ * So the guarantee below has to be carried by tests, not by reuse.
+ */
+
+/** Frames kept by default. `Error.stackTraceLimit` is 10; we allow headroom. */
+export const MAX_STACK_FRAMES = 15
+
+/** Marker substituted for the working directory — hides the project name. */
+const CWD_MARKER = '<cwd>'
+
+/** Marker substituted for the home directory. */
+const HOME_MARKER = '~'
+
+/**
+ * Marker substituted for the first directory segment under home.
+ *
+ * Home replacement alone still discloses the user's own naming: a frame in
+ * `~/acme-secret-merger-2026/src/a.ts` would render as exactly that. The
+ * data dictionary promises no project names, so the segment right after `~` is
+ * collapsed too. Structure and the frame's own file name survive — which is
+ * what makes a frame useful — but the user's label for a directory does not.
+ */
+const DIR_MARKER = '<dir>'
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Replace absolute home/cwd paths with their markers, anywhere in the string.
+ *
+ * Order matters and is not arbitrary: cwd is normally *inside* home, so
+ * replacing home first would leave `~/proj/src/a.ts` — which leaks the project
+ * directory name. Replacing cwd first yields `<cwd>/src/a.ts`, which does not.
+ * This ordering is asserted by a test.
+ *
+ * Paths that are neither under cwd nor under home are left alone. Those are
+ * system/package locations (e.g. `/usr/local/lib/node_modules/…`) that contain
+ * no user data, and keeping them is what makes a frame useful for debugging.
+ */
+export function redactText(input: string, cwd?: string): string {
+  let out = input
+
+  if (cwd && cwd.length > 1) {
+    out = out.replace(new RegExp(escapeRegExp(cwd), 'g'), CWD_MARKER)
+  }
+
+  let home = ''
+  try {
+    home = homedir()
+  } catch {
+    /* homedir() can throw when neither HOME nor the passwd entry resolves */
+  }
+  if (home && home.length > 1) {
+    out = out.replace(new RegExp(escapeRegExp(home), 'g'), HOME_MARKER)
+  }
+
+  // Collapse the first segment after `~` (both separators — Windows stacks use
+  // backslashes) so a user-chosen directory name is not disclosed. The matched
+  // separator is echoed back rather than normalised, so a Windows path does not
+  // come out with mixed separators.
+  out = out.replace(
+    /~([\\/])[^\\/\s:)]+/g,
+    (_match, sep: string) => `${HOME_MARKER}${sep}${DIR_MARKER}`,
+  )
+
+  return out
+}
+
+export interface RedactedStack {
+  /** Redacted frame lines, truncated to `maxFrames`. */
+  frames: string[]
+  /** Frame count *before* truncation — truncation loses data, this bounds the loss. */
+  frameCount: number
+}
+
+/**
+ * Extract and redact the frame lines of a V8 stack.
+ *
+ * The first line of a stack is `"TypeError: <message>"` — it is dropped
+ * outright, never redacted, because the message routinely embeds paths and user
+ * data. `crash.ts` sends only `hashMessage(error.message)` instead.
+ */
+export function redactStack(
+  stack: string,
+  opts: { cwd?: string; maxFrames?: number } = {},
+): RedactedStack {
+  const { cwd = process.cwd(), maxFrames = MAX_STACK_FRAMES } = opts
+
+  const frameLines = stack.split('\n').filter((line) => /^\s*at\s/.test(line))
+  const redacted = frameLines.map((line) => redactText(line.trim(), cwd))
+
+  return {
+    frames: redacted.slice(0, maxFrames),
+    frameCount: frameLines.length,
+  }
+}
+
+/**
+ * sha256 of the error message, first 16 hex chars.
+ *
+ * Only the digest is reportable. The plaintext message is not — same reason the
+ * stack's first line is dropped.
+ */
+export function hashMessage(message: string): string {
+  return createHash('sha256').update(message).digest('hex').slice(0, 16)
+}
+
+/** Runtime tag for the session payload, e.g. `bun@1.2` / `node@22`. */
+export function runtimeTag(): string {
+  const versions = process.versions as Record<string, string | undefined>
+  if (versions.bun) return `bun@${versions.bun}`
+  return `node@${(versions.node ?? '0').split('.')[0]}`
+}

package/src/telemetry/transport.ts

@@ -0,0 +1,81 @@
+import { fetchWithRetry } from '../providers/fetch-utils'
+import { ackQueue, readQueue, type QueuedEvent } from './queue'
+
+/**
+ * Upload queued events.
+ *
+ * Runs at *startup*, not at exit: `process.on('exit')` cannot await async work,
+ * so collecting and sending are decoupled — the session queue is written
+ * synchronously at exit and drained here on the next launch. Same shape as the
+ * existing startup update check (`shared/update.ts`), which is likewise
+ * fire-and-forget.
+ *
+ * Every failure is silent and leaves the event queued for the next attempt. A
+ * telemetry endpoint being unreachable must never be visible to the user.
+ */
+
+/** Per-request budget. Short: this runs alongside startup, not during it. */
+const REQUEST_TIMEOUT_MS = 10_000
+
+export interface FlushResult {
+  sent: number
+  failed: number
+}
+
+/**
+ * Drain the queue to `endpoint`.
+ *
+ * Returns without sending anything when the endpoint is empty — which is the
+ * shipped default, so an unconfigured install performs **zero** network calls.
+ */
+export async function flushQueue(
+  endpoint: string,
+  opts: { fetchImpl?: typeof fetch; events?: QueuedEvent[] } = {},
+): Promise<FlushResult> {
+  if (!endpoint) return { sent: 0, failed: 0 }
+
+  const events = opts.events ?? readQueue()
+  if (events.length === 0) return { sent: 0, failed: 0 }
+
+  const sent: string[] = []
+  let failed = 0
+
+  for (const event of events) {
+    try {
+      const response = await fetchWithRetry(
+        endpoint,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(event),
+        },
+        { timeout: REQUEST_TIMEOUT_MS, maxRetries: 2, baseDelay: 1000 },
+      )
+
+      // 4xx means we are sending something the endpoint will never accept —
+      // retrying forever would wedge the queue behind a permanently bad event.
+      // Drop it on the floor rather than block every later event.
+      if (response.ok || (response.status >= 400 && response.status < 500)) {
+        sent.push(event.id)
+      } else {
+        failed++
+      }
+    } catch {
+      failed++
+    }
+  }
+
+  ackQueue(sent)
+  return { sent: sent.length, failed }
+}
+
+/**
+ * Fire-and-forget startup flush. Never rejects, never blocks the caller, and
+ * never surfaces an error — the caller does not await it.
+ */
+export function flushQueueInBackground(endpoint: string): void {
+  if (!endpoint) return
+  void flushQueue(endpoint).catch(() => {
+    /* best-effort by design */
+  })
+}

package/src/tools/agent/workflow.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from '../../shared/index.ts'
 import { runWorkflow } from '../../workflow/runtime'
+import { workflowScriptDir } from '../../core/paths.ts'
 import type { QueryEngine } from '../../core/engine'
 
 export const workflowTool: ToolDefinition = {
@@ -108,10 +109,11 @@ export const workflowTool: ToolDefinition = {
       )
 
       // Persist last-run state for /workflow save
+      let persistWarning = ''
       try {
         const { existsSync, mkdirSync, writeFileSync } = await import('node:fs')
         const { join } = await import('node:path')
-        const workflowsDir = join(process.cwd(), '.claude', 'workflows')
+        const workflowsDir = workflowScriptDir(process.cwd())
         if (!existsSync(workflowsDir)) {
           mkdirSync(workflowsDir, { recursive: true })
         }
@@ -120,8 +122,13 @@ export const workflowTool: ToolDefinition = {
           JSON.stringify({ runId, script, timestamp: new Date().toISOString() }),
           'utf-8',
         )
-      } catch {
-        // best-effort — don't fail the workflow if state persistence fails
+      } catch (err) {
+        // Persistence stays best-effort — the workflow itself succeeded, so a
+        // disk error must not fail it. But it must not be *silent* either:
+        // swallowing this made the next `/workflow save` report "No recent
+        // workflow run found" while the script sat intact in
+        // ~/.mipham/workflows/<runId>/script.js.
+        persistWarning = `\n\n⚠️  Could not persist last-run state for /workflow save: ${String(err)}`
       }
 
       let content = `Workflow ${runId} completed.\n\n`
@@ -130,7 +137,7 @@ export const workflowTool: ToolDefinition = {
       }
       content += `Result:\n${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`
 
-      return { success: true, content }
+      return { success: true, content: content + persistWarning }
     } catch (err) {
       return {
         success: false,

package/src/tools/artifact/artifact.ts

@@ -1,7 +1,8 @@
 import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { ToolDefinition } from '../../shared/index.ts'
-import { ARTIFACTS_DIR, ARTIFACT_MAX_SIZE } from '../../shared/constants'
+import { ARTIFACT_MAX_SIZE } from '../../shared/constants'
+import { artifactsRoot } from '../../artifacts/paths'
 import { addToManifest, readManifest, archiveVersion } from '../../artifacts/manifest'
 
 const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
@@ -57,8 +58,10 @@ export const artifactTool: ToolDefinition = {
       }
     }
 
-    // Determine output paths
-    const baseDir = join(ctx.cwd, ARTIFACTS_DIR)
+    // Determine output paths — the server's root, the manifest's home and this
+    // directory are one and the same; computing it here is what made the URL a
+    // guaranteed 404 before.
+    const baseDir = artifactsRoot(ctx.cwd)
     const sessionDir = join(baseDir, ctx.sessionId)
     mkdirSync(sessionDir, { recursive: true })
 
@@ -100,7 +103,7 @@ export const artifactTool: ToolDefinition = {
     const prev = manifestPre.artifacts.find((a) => a.name === name && a.sessionId === ctx.sessionId)
     const versionCount = prev?.versionCount || (isUpdate ? 1 : undefined)
 
-    addToManifest(
+    const { quarantined } = addToManifest(
       baseDir,
       {
         name,
@@ -124,6 +127,12 @@ export const artifactTool: ToolDefinition = {
     const galleryUrl = port ? `http://localhost:${port}` : undefined
     const versionLine = archivedVersion ? `   Prev archived as: ${archivedVersion}` : ''
     const galleryLine = galleryUrl ? `Gallery: ${galleryUrl}` : ''
+    // The index was unreadable and got moved aside, so this publish started from
+    // nothing: say it here, or the user reads "saved" and never learns that the
+    // rest of the index is now a file next to it.
+    const warnLine = quarantined
+      ? `   ⚠️  Index was unreadable; previous index kept at ${quarantined}`
+      : ''
 
     return {
       success: true,
@@ -132,6 +141,7 @@ export const artifactTool: ToolDefinition = {
         `   URL:  ${url}`,
         `   Size: ${size.toLocaleString()} bytes`,
         versionLine,
+        warnLine,
         galleryLine,
         '',
         `Open in browser: /artifact open ${name}`,

package/src/tools/exec/bash.ts

@@ -1,7 +1,9 @@
+import { resolve } from 'node:path'
 import type { ToolDefinition, CredentialMaskingConfig } from '../../shared/index.ts'
 import { sanitizeCommand } from '../../shared/sanitize.ts'
 import { DANGEROUS_GIT_PATTERNS } from './git.ts'
-import { isUncOrDevicePath } from '../../security/path.ts'
+import { isUncOrDevicePath, isWithin } from '../../security/path.ts'
+import { findWorktreeMarker } from '../../core/paths.ts'
 import type { Service } from '../../vajra'
 import { toolKey } from '../seam'
 import { withValidation } from '../validation'
@@ -307,6 +309,36 @@ function parseErrorLocations(stderr: string): ErrorLocation[] {
   return unique.slice(0, 10)
 }
 
+/**
+ * 找出命令里第一个 `cd` 到工作区之外的**目标原样字符串**（供错误文案用）；
+ * 无逃逸返回 null。判定边界是 `worktreeRoot`（项目根），不是 `cwd` ——
+ * 既有行为即如此：`cd <项目内其它目录>` 放行（见 test/tools/exec.test.ts
+ * 「allows cd inside the project from a .mipham worktree」）。
+ *
+ * 此前三个缺陷，其中两个是活的绕过：
+ *  - 相对路径用字符串拼接而非 `resolve`：`cd ../../../..` 拼出来的串仍以
+ *    cwd 开头，于是被当成「在区内」放行 —— **活绕过**；
+ *  - `command.match(...)` 非全局，只看第一个 `cd`，`cd sub && cd /etc` 的
+ *    后半段完全不检查 —— **活绕过**；
+ *  - 归属判定用 `resolved.startsWith(cwd)` 字符串前缀比较，`/proj/w1-evil`
+ *    会被判成「在 /proj/w1 里」；它只被 root 那个析取项兜住才没显形，故一并
+ *    改成按路径分段比较的 `isWithin`。
+ */
+export function resolveWorktreeEscape(
+  cwd: string,
+  worktreeRoot: string,
+  command: string,
+): string | null {
+  const cdRe = /\bcd\s+(?:"([^"]+)"|'([^']+)'|([^\s;|&]+))/g
+  for (const m of command.matchAll(cdRe)) {
+    const target = m[1] ?? m[2] ?? m[3]
+    if (!target) continue
+    const resolved = resolve(cwd, target)
+    if (!isWithin(resolved, cwd) && !isWithin(resolved, worktreeRoot)) return target
+  }
+  return null
+}
+
 export function createBashTool(credentialConfig?: CredentialMaskingConfig): ToolDefinition {
   return {
     name: 'Bash',
@@ -334,26 +366,18 @@ export function createBashTool(credentialConfig?: CredentialMaskingConfig): Tool
       const timeout = Math.min((params.timeout as number) || 120_000, 600_000)
 
       // P0-4: Worktree isolation — block cd escape attempts
-      const WORKTREE_MARKER = '.claude/worktrees/'
-      if (ctx.cwd.includes(WORKTREE_MARKER)) {
-        const worktreeRoot = ctx.cwd.substring(0, ctx.cwd.indexOf(WORKTREE_MARKER))
-        // Detect cd to absolute paths outside the worktree
-        const cdEscapePattern = /\bcd\s+(?:"([^"]+)"|'([^']+)'|([^\s;|&]+))/
-        const cdMatch = command.match(cdEscapePattern)
-        if (cdMatch) {
-          const target = cdMatch[1] || cdMatch[2] || cdMatch[3] || ''
-          // Resolve relative to cwd
-          const resolved = target.startsWith('/')
-            ? target
-            : `${ctx.cwd}/${target}`.replace(/\/\.\//g, '/')
-          if (!resolved.startsWith(ctx.cwd) && !resolved.startsWith(worktreeRoot + '/')) {
-            return {
-              success: false,
-              content: '',
-              error:
-                `Worktree isolation: cannot cd outside worktree directory. ` +
-                `Attempted: ${target}. Use tools within the worktree only.`,
-            }
+      // 标记取自 core/paths.ts：新目录与历史 .claude/worktrees/ 都认，
+      // 隔离度只增不减（只认新前缀会让旧工作树失去保护）。
+      const worktreeMarker = findWorktreeMarker(ctx.cwd)
+      if (worktreeMarker) {
+        const escapeTarget = resolveWorktreeEscape(ctx.cwd, worktreeMarker.root, command)
+        if (escapeTarget !== null) {
+          return {
+            success: false,
+            content: '',
+            error:
+              `Worktree isolation: cannot cd outside worktree directory. ` +
+              `Attempted: ${escapeTarget}. Use tools within the worktree only.`,
           }
         }
       }

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

@@ -1,10 +1,11 @@
 import type { ToolDefinition } from '../../shared/index.ts'
+import { worktreeRoot } from '../../core/paths.ts'
 
 export const enterWorktreeTool: ToolDefinition = {
   name: 'EnterWorktree',
   description:
     'Create an isolated git worktree for parallel development. ' +
-    'Creates a new worktree at .claude/worktrees/<name> on its own branch. ' +
+    'Creates a new worktree at .mipham/worktrees/<name> on its own branch. ' +
     'Use this when you need to work on a separate task without affecting the main workspace. ' +
     'Pair with ExitWorktree to clean up when done.',
   category: 'exec',
@@ -56,10 +57,10 @@ export const enterWorktreeTool: ToolDefinition = {
 
     const cwd = ctx.cwd
     const { resolve } = await import('node:path')
-    const worktreePath = resolve(`${cwd}/.claude/worktrees/${name}`)
-    const allowedPrefix = resolve(`${cwd}/.claude/worktrees/`)
+    const worktreePath = resolve(worktreeRoot(cwd), name)
+    const allowedPrefix = resolve(worktreeRoot(cwd))
 
-    // Defense-in-depth: verify resolved path is within .claude/worktrees/
+    // Defense-in-depth: verify resolved path stays within the worktree root
     if (
       !worktreePath.startsWith(allowedPrefix + '/') &&
       worktreePath !== allowedPrefix.slice(0, -1)
@@ -67,7 +68,7 @@ export const enterWorktreeTool: ToolDefinition = {
       return {
         success: false,
         content: '',
-        error: 'Worktree path must be within .claude/worktrees/.',
+        error: 'Worktree path must be within .mipham/worktrees/.',
       }
     }
 

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

@@ -1,4 +1,5 @@
 import type { ToolDefinition } from '../../shared/index.ts'
+import { worktreeRoots } from '../../core/paths.ts'
 
 export const exitWorktreeTool: ToolDefinition = {
   name: 'ExitWorktree',
@@ -13,7 +14,8 @@ export const exitWorktreeTool: ToolDefinition = {
     properties: {
       path: {
         type: 'string',
-        description: 'Absolute path to the worktree to exit. Must be under .claude/worktrees/.',
+        description:
+          'Absolute path to the worktree to exit. Must be under .mipham/worktrees/ (or the legacy .claude/worktrees/).',
       },
       action: {
         type: 'string',
@@ -34,18 +36,21 @@ export const exitWorktreeTool: ToolDefinition = {
     const action = params.action as string
     const discardChanges = params.discard_changes === true
 
-    // Validate the path is under .claude/worktrees
+    // Validate the path is under a worktree root（新目录优先，兼容历史 .claude/）
     const cwd = ctx.cwd
     const { resolve } = await import('node:path')
     const resolvedPath = resolve(worktreePath)
-    const allowedPrefix = resolve(`${cwd}/.claude/worktrees/`)
+    const roots = worktreeRoots(cwd).map((root) => resolve(root))
+    const inWorktree = roots.some(
+      (root) => resolvedPath === root || resolvedPath.startsWith(root + '/'),
+    )
 
-    if (!resolvedPath.startsWith(allowedPrefix)) {
+    if (!inWorktree) {
       return {
         success: false,
         content: '',
         error:
-          `Path "${worktreePath}" is not under .claude/worktrees/. ` +
+          `Path "${worktreePath}" is not under .mipham/worktrees/ or .claude/worktrees/. ` +
           `Only worktrees created by EnterWorktree can be managed here.`,
       }
     }

package/src/tools/exec/git.ts

@@ -1,4 +1,7 @@
+import { resolve } from 'node:path'
 import type { ToolDefinition } from '../../shared/index.ts'
+import { findWorktreeMarker } from '../../core/paths.ts'
+import { isWithin } from '../../security/path.ts'
 
 // P0-4 (v2.1.222 alignment): Regex-based word-boundary patterns replace
 // fragile substring matching. Each pattern describes what it blocks.
@@ -52,21 +55,33 @@ export const DANGEROUS_GIT_PATTERNS: Array<{ pattern: RegExp; description: strin
  * when operating in a worktree context.
  */
 function isOutsideWorktree(command: string, cwd: string): string | null {
-  const WORKTREE_MARKER = '.claude/worktrees/'
-  if (!cwd.includes(WORKTREE_MARKER)) return null
-
-  // Extract the project root (everything before .claude/worktrees/)
-  const worktreeRoot = cwd.substring(0, cwd.indexOf(WORKTREE_MARKER))
-
-  // Detect git commands that reference the main checkout path
-  const mainCheckoutPaths = [/\b--work-tree=([^\s]+)/g, /\b--git-dir=([^\s]+)/g, /\b-C\s+([^\s]+)/g]
+  // 标记取自 core/paths.ts：新目录与历史 .claude/worktrees/ 都认，隔离度只增不减。
+  const marker = findWorktreeMarker(cwd)
+  if (!marker) return null
+
+  // Extract the project root (everything before the worktree marker)
+  const worktreeRoot = marker.root
+
+  // Detect git commands that reference the main checkout path.
+  // NOTE: no `\b` before the leading `-` — `\b` needs a word/non-word
+  // transition and `-` is itself a non-word char, so `\b--work-tree=` never
+  // matched anything and this whole check was silently dead. `-C` needs an
+  // explicit boundary because without one it would match inside a path.
+  const mainCheckoutPaths = [
+    /--work-tree=([^\s]+)/g,
+    /--git-dir=([^\s]+)/g,
+    /(?:^|\s)-C\s+([^\s]+)/g,
+  ]
 
   for (const pathPattern of mainCheckoutPaths) {
     let match: RegExpExecArray | null
     while ((match = pathPattern.exec(command)) !== null) {
       const refPath = match[1]!
-      // If the referenced path is outside the worktree, block it
-      if (!refPath.startsWith(cwd) && !refPath.startsWith(worktreeRoot + '/')) {
+      // 归一后按**路径分段**判归属，不用字符串前缀：此前 `refPath.startsWith(cwd)`
+      // 从不解析 `..`，`--work-tree=/proj/../etc` 因为「以 /proj/ 开头」被放行，
+      // 而 git 拿到的是 /etc。判据与 Bash 守卫（resolveWorktreeEscape）同一套。
+      const resolved = resolve(cwd, refPath)
+      if (!isWithin(resolved, cwd) && !isWithin(resolved, worktreeRoot)) {
         return `Git command references path outside worktree: ${refPath}`
       }
     }

package/src/tools/file/grep.ts

@@ -16,17 +16,23 @@ export async function runSearch(
   cmd: string[],
   cwd: string,
   timeoutMs: number,
-): Promise<{ stdout: string; timedOut: boolean; exitCode: number | null }> {
+): Promise<{ stdout: string; stderr: string; timedOut: boolean; exitCode: number | null }> {
   const proc = Bun.spawn(cmd, { cwd, stdout: 'pipe', stderr: 'pipe' })
   let timedOut = false
   const timer = setTimeout(() => {
     timedOut = true
     proc.kill()
   }, timeoutMs)
-  const stdout = await new Response(proc.stdout).text()
+  // 两条管道必须**并发**读。先读满 stdout 再读 stderr 会在子进程写满
+  // stderr（~64 KB 管道缓冲）时死锁：它阻塞在 write 上不退出，stdout 也就
+  // 永远读不到 EOF —— 只能等超时兜底，而超时会把「慢」和「错」说成同一件事。
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
   await proc.exited
   clearTimeout(timer)
-  return { stdout, timedOut, exitCode: proc.exitCode }
+  return { stdout, stderr, timedOut, exitCode: proc.exitCode }
 }
 
 /** grep 输出上限：超过则显式截断并附标记（不能静默丢内容——模型会误以为看全了）。 */
@@ -107,7 +113,9 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
         if (exitCode === 0) {
           return {
             success: true,
-            content: maskSearchOutput(stdout || '(no matches)', credentialConfig, 'heading'),
+            content: truncateGrepOutput(
+              maskSearchOutput(stdout || '(no matches)', credentialConfig, 'heading'),
+            ),
           }
         }
         // rg exit 2 (error, e.g. permission denied on protected dirs) — do NOT
@@ -117,12 +125,11 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
         if (stdout && stdout.trim()) {
           return {
             success: true,
-            content: maskSearchOutput(
-              stdout +
-                '\n\n(rg exited 2 — some paths unreadable; narrow scope for complete results)',
-              credentialConfig,
-              'heading',
-            ),
+            // 先截断正文、再拼注解：注解拼在截断之内的话，它自己会被切掉，
+            // 模型拿到的就是一句没头没尾的提示。
+            content:
+              truncateGrepOutput(maskSearchOutput(stdout, credentialConfig, 'heading')) +
+              '\n\n(rg exited 2 — some paths unreadable; narrow scope for complete results)',
           }
         }
         return {
@@ -153,7 +160,11 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
         '+',
       ]
       try {
-        const { stdout, timedOut, exitCode } = await runSearch(grepArgs, ctx.cwd, GREP_TIMEOUT_MS)
+        const { stdout, stderr, timedOut, exitCode } = await runSearch(
+          grepArgs,
+          ctx.cwd,
+          GREP_TIMEOUT_MS,
+        )
         if (timedOut) {
           return {
             success: false,
@@ -161,7 +172,17 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
             error: `Grep timed out after ${GREP_TIMEOUT_MS / 1000}s — narrow scope with "path" and "include".`,
           }
         }
-        if (exitCode === 1) return { success: true, content: '(no matches)' }
+        // 退出码 1 在 find 这里是**两件事**：真的没搜到，和「根本没搜成」
+        // —— 目录不可读、grep 正则非法、grep 不在 PATH，BSD find 全都退 1。
+        // 后者一律伴随 stderr，所以用 stderr 而非退出码分辨；不加这一刀，
+        // 模型会被告知「没有匹配」，而真相是这次搜索压根没跑起来。
+        if (exitCode === 1) {
+          const err = stderr.trim()
+          if (err) {
+            return { success: false, content: '', error: `Search failed: ${err.slice(0, 500)}` }
+          }
+          return { success: true, content: '(no matches)' }
+        }
         if (exitCode === 0) {
           return {
             success: true,
@@ -171,7 +192,10 @@ export function createGrepTool(credentialConfig?: CredentialMaskingConfig): Tool
         return {
           success: false,
           content: '',
-          error: 'grep failed. Install ripgrep: brew install ripgrep',
+          error:
+            `grep failed (exit ${exitCode})` +
+            (stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : '') +
+            '. Install ripgrep: brew install ripgrep',
         }
       } catch {
         return {