chore: initialize recovered claude workspace

src/tools/AgentTool/agentColorManager.ts

@@ -0,0 +1,66 @@
+import { getAgentColorMap } from '../../bootstrap/state.js'
+import type { Theme } from '../../utils/theme.js'
+
+export type AgentColorName =
+  | 'red'
+  | 'blue'
+  | 'green'
+  | 'yellow'
+  | 'purple'
+  | 'orange'
+  | 'pink'
+  | 'cyan'
+
+export const AGENT_COLORS: readonly AgentColorName[] = [
+  'red',
+  'blue',
+  'green',
+  'yellow',
+  'purple',
+  'orange',
+  'pink',
+  'cyan',
+] as const
+
+export const AGENT_COLOR_TO_THEME_COLOR = {
+  red: 'red_FOR_SUBAGENTS_ONLY',
+  blue: 'blue_FOR_SUBAGENTS_ONLY',
+  green: 'green_FOR_SUBAGENTS_ONLY',
+  yellow: 'yellow_FOR_SUBAGENTS_ONLY',
+  purple: 'purple_FOR_SUBAGENTS_ONLY',
+  orange: 'orange_FOR_SUBAGENTS_ONLY',
+  pink: 'pink_FOR_SUBAGENTS_ONLY',
+  cyan: 'cyan_FOR_SUBAGENTS_ONLY',
+} as const satisfies Record<AgentColorName, keyof Theme>
+
+export function getAgentColor(agentType: string): keyof Theme | undefined {
+  if (agentType === 'general-purpose') {
+    return undefined
+  }
+
+  const agentColorMap = getAgentColorMap()
+
+  // Check if color already assigned
+  const existingColor = agentColorMap.get(agentType)
+  if (existingColor && AGENT_COLORS.includes(existingColor)) {
+    return AGENT_COLOR_TO_THEME_COLOR[existingColor]
+  }
+
+  return undefined
+}
+
+export function setAgentColor(
+  agentType: string,
+  color: AgentColorName | undefined,
+): void {
+  const agentColorMap = getAgentColorMap()
+
+  if (!color) {
+    agentColorMap.delete(agentType)
+    return
+  }
+
+  if (AGENT_COLORS.includes(color)) {
+    agentColorMap.set(agentType, color)
+  }
+}

src/tools/AgentTool/agentDisplay.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared utilities for displaying agent information.
+ * Used by both the CLI `claude agents` handler and the interactive `/agents` command.
+ */
+
+import { getDefaultSubagentModel } from '../../utils/model/agent.js'
+import {
+  getSourceDisplayName,
+  type SettingSource,
+} from '../../utils/settings/constants.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+
+type AgentSource = SettingSource | 'built-in' | 'plugin'
+
+export type AgentSourceGroup = {
+  label: string
+  source: AgentSource
+}
+
+/**
+ * Ordered list of agent source groups for display.
+ * Both the CLI and interactive UI should use this to ensure consistent ordering.
+ */
+export const AGENT_SOURCE_GROUPS: AgentSourceGroup[] = [
+  { label: 'User agents', source: 'userSettings' },
+  { label: 'Project agents', source: 'projectSettings' },
+  { label: 'Local agents', source: 'localSettings' },
+  { label: 'Managed agents', source: 'policySettings' },
+  { label: 'Plugin agents', source: 'plugin' },
+  { label: 'CLI arg agents', source: 'flagSettings' },
+  { label: 'Built-in agents', source: 'built-in' },
+]
+
+export type ResolvedAgent = AgentDefinition & {
+  overriddenBy?: AgentSource
+}
+
+/**
+ * Annotate agents with override information by comparing against the active
+ * (winning) agent list. An agent is "overridden" when another agent with the
+ * same type from a higher-priority source takes precedence.
+ *
+ * Also deduplicates by (agentType, source) to handle git worktree duplicates
+ * where the same agent file is loaded from both the worktree and main repo.
+ */
+export function resolveAgentOverrides(
+  allAgents: AgentDefinition[],
+  activeAgents: AgentDefinition[],
+): ResolvedAgent[] {
+  const activeMap = new Map<string, AgentDefinition>()
+  for (const agent of activeAgents) {
+    activeMap.set(agent.agentType, agent)
+  }
+
+  const seen = new Set<string>()
+  const resolved: ResolvedAgent[] = []
+
+  // Iterate allAgents, annotating each with override info from activeAgents.
+  // Deduplicate by (agentType, source) to handle git worktree duplicates.
+  for (const agent of allAgents) {
+    const key = `${agent.agentType}:${agent.source}`
+    if (seen.has(key)) continue
+    seen.add(key)
+
+    const active = activeMap.get(agent.agentType)
+    const overriddenBy =
+      active && active.source !== agent.source ? active.source : undefined
+    resolved.push({ ...agent, overriddenBy })
+  }
+
+  return resolved
+}
+
+/**
+ * Resolve the display model string for an agent.
+ * Returns the model alias or 'inherit' for display purposes.
+ */
+export function resolveAgentModelDisplay(
+  agent: AgentDefinition,
+): string | undefined {
+  const model = agent.model || getDefaultSubagentModel()
+  if (!model) return undefined
+  return model === 'inherit' ? 'inherit' : model
+}
+
+/**
+ * Get a human-readable label for the source that overrides an agent.
+ * Returns lowercase, e.g. "user", "project", "managed".
+ */
+export function getOverrideSourceLabel(source: AgentSource): string {
+  return getSourceDisplayName(source).toLowerCase()
+}
+
+/**
+ * Compare agents alphabetically by name (case-insensitive).
+ */
+export function compareAgentsByName(
+  a: AgentDefinition,
+  b: AgentDefinition,
+): number {
+  return a.agentType.localeCompare(b.agentType, undefined, {
+    sensitivity: 'base',
+  })
+}

src/tools/AgentTool/agentMemory.ts

@@ -0,0 +1,177 @@
+import { join, normalize, sep } from 'path'
+import { getProjectRoot } from '../../bootstrap/state.js'
+import {
+  buildMemoryPrompt,
+  ensureMemoryDirExists,
+} from '../../memdir/memdir.js'
+import { getMemoryBaseDir } from '../../memdir/paths.js'
+import { getCwd } from '../../utils/cwd.js'
+import { findCanonicalGitRoot } from '../../utils/git.js'
+import { sanitizePath } from '../../utils/path.js'
+
+// Persistent agent memory scope: 'user' (~/.claude/agent-memory/), 'project' (.claude/agent-memory/), or 'local' (.claude/agent-memory-local/)
+export type AgentMemoryScope = 'user' | 'project' | 'local'
+
+/**
+ * Sanitize an agent type name for use as a directory name.
+ * Replaces colons (invalid on Windows, used in plugin-namespaced agent
+ * types like "my-plugin:my-agent") with dashes.
+ */
+function sanitizeAgentTypeForPath(agentType: string): string {
+  return agentType.replace(/:/g, '-')
+}
+
+/**
+ * Returns the local agent memory directory, which is project-specific and not checked into VCS.
+ * When CLAUDE_CODE_REMOTE_MEMORY_DIR is set, persists to the mount with project namespacing.
+ * Otherwise, uses <cwd>/.claude/agent-memory-local/<agentType>/.
+ */
+function getLocalAgentMemoryDir(dirName: string): string {
+  if (process.env.CLAUDE_CODE_REMOTE_MEMORY_DIR) {
+    return (
+      join(
+        process.env.CLAUDE_CODE_REMOTE_MEMORY_DIR,
+        'projects',
+        sanitizePath(
+          findCanonicalGitRoot(getProjectRoot()) ?? getProjectRoot(),
+        ),
+        'agent-memory-local',
+        dirName,
+      ) + sep
+    )
+  }
+  return join(getCwd(), '.claude', 'agent-memory-local', dirName) + sep
+}
+
+/**
+ * Returns the agent memory directory for a given agent type and scope.
+ * - 'user' scope: <memoryBase>/agent-memory/<agentType>/
+ * - 'project' scope: <cwd>/.claude/agent-memory/<agentType>/
+ * - 'local' scope: see getLocalAgentMemoryDir()
+ */
+export function getAgentMemoryDir(
+  agentType: string,
+  scope: AgentMemoryScope,
+): string {
+  const dirName = sanitizeAgentTypeForPath(agentType)
+  switch (scope) {
+    case 'project':
+      return join(getCwd(), '.claude', 'agent-memory', dirName) + sep
+    case 'local':
+      return getLocalAgentMemoryDir(dirName)
+    case 'user':
+      return join(getMemoryBaseDir(), 'agent-memory', dirName) + sep
+  }
+}
+
+// Check if file is within an agent memory directory (any scope).
+export function isAgentMemoryPath(absolutePath: string): boolean {
+  // SECURITY: Normalize to prevent path traversal bypasses via .. segments
+  const normalizedPath = normalize(absolutePath)
+  const memoryBase = getMemoryBaseDir()
+
+  // User scope: check memory base (may be custom dir or config home)
+  if (normalizedPath.startsWith(join(memoryBase, 'agent-memory') + sep)) {
+    return true
+  }
+
+  // Project scope: always cwd-based (not redirected)
+  if (
+    normalizedPath.startsWith(join(getCwd(), '.claude', 'agent-memory') + sep)
+  ) {
+    return true
+  }
+
+  // Local scope: persisted to mount when CLAUDE_CODE_REMOTE_MEMORY_DIR is set, otherwise cwd-based
+  if (process.env.CLAUDE_CODE_REMOTE_MEMORY_DIR) {
+    if (
+      normalizedPath.includes(sep + 'agent-memory-local' + sep) &&
+      normalizedPath.startsWith(
+        join(process.env.CLAUDE_CODE_REMOTE_MEMORY_DIR, 'projects') + sep,
+      )
+    ) {
+      return true
+    }
+  } else if (
+    normalizedPath.startsWith(
+      join(getCwd(), '.claude', 'agent-memory-local') + sep,
+    )
+  ) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Returns the agent memory file path for a given agent type and scope.
+ */
+export function getAgentMemoryEntrypoint(
+  agentType: string,
+  scope: AgentMemoryScope,
+): string {
+  return join(getAgentMemoryDir(agentType, scope), 'MEMORY.md')
+}
+
+export function getMemoryScopeDisplay(
+  memory: AgentMemoryScope | undefined,
+): string {
+  switch (memory) {
+    case 'user':
+      return `User (${join(getMemoryBaseDir(), 'agent-memory')}/)`
+    case 'project':
+      return 'Project (.claude/agent-memory/)'
+    case 'local':
+      return `Local (${getLocalAgentMemoryDir('...')})`
+    default:
+      return 'None'
+  }
+}
+
+/**
+ * Load persistent memory for an agent with memory enabled.
+ * Creates the memory directory if needed and returns a prompt with memory contents.
+ *
+ * @param agentType The agent's type name (used as directory name)
+ * @param scope 'user' for ~/.claude/agent-memory/ or 'project' for .claude/agent-memory/
+ */
+export function loadAgentMemoryPrompt(
+  agentType: string,
+  scope: AgentMemoryScope,
+): string {
+  let scopeNote: string
+  switch (scope) {
+    case 'user':
+      scopeNote =
+        '- Since this memory is user-scope, keep learnings general since they apply across all projects'
+      break
+    case 'project':
+      scopeNote =
+        '- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project'
+      break
+    case 'local':
+      scopeNote =
+        '- Since this memory is local-scope (not checked into version control), tailor your memories to this project and machine'
+      break
+  }
+
+  const memoryDir = getAgentMemoryDir(agentType, scope)
+
+  // Fire-and-forget: this runs at agent-spawn time inside a sync
+  // getSystemPrompt() callback (called from React render in AgentDetail.tsx,
+  // so it cannot be async). The spawned agent won't try to Write until after
+  // a full API round-trip, by which time mkdir will have completed. Even if
+  // it hasn't, FileWriteTool does its own mkdir of the parent directory.
+  void ensureMemoryDirExists(memoryDir)
+
+  const coworkExtraGuidelines =
+    process.env.CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES
+  return buildMemoryPrompt({
+    displayName: 'Persistent Agent Memory',
+    memoryDir,
+    extraGuidelines:
+      coworkExtraGuidelines && coworkExtraGuidelines.trim().length > 0
+        ? [scopeNote, coworkExtraGuidelines]
+        : [scopeNote],
+  })
+}

src/tools/AgentTool/agentMemorySnapshot.ts

@@ -0,0 +1,197 @@
+import { mkdir, readdir, readFile, unlink, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { z } from 'zod/v4'
+import { getCwd } from '../../utils/cwd.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { jsonParse, jsonStringify } from '../../utils/slowOperations.js'
+import { type AgentMemoryScope, getAgentMemoryDir } from './agentMemory.js'
+
+const SNAPSHOT_BASE = 'agent-memory-snapshots'
+const SNAPSHOT_JSON = 'snapshot.json'
+const SYNCED_JSON = '.snapshot-synced.json'
+
+const snapshotMetaSchema = lazySchema(() =>
+  z.object({
+    updatedAt: z.string().min(1),
+  }),
+)
+
+const syncedMetaSchema = lazySchema(() =>
+  z.object({
+    syncedFrom: z.string().min(1),
+  }),
+)
+type SyncedMeta = z.infer<ReturnType<typeof syncedMetaSchema>>
+
+/**
+ * Returns the path to the snapshot directory for an agent in the current project.
+ * e.g., <cwd>/.claude/agent-memory-snapshots/<agentType>/
+ */
+export function getSnapshotDirForAgent(agentType: string): string {
+  return join(getCwd(), '.claude', SNAPSHOT_BASE, agentType)
+}
+
+function getSnapshotJsonPath(agentType: string): string {
+  return join(getSnapshotDirForAgent(agentType), SNAPSHOT_JSON)
+}
+
+function getSyncedJsonPath(agentType: string, scope: AgentMemoryScope): string {
+  return join(getAgentMemoryDir(agentType, scope), SYNCED_JSON)
+}
+
+async function readJsonFile<T>(
+  path: string,
+  schema: z.ZodType<T>,
+): Promise<T | null> {
+  try {
+    const content = await readFile(path, { encoding: 'utf-8' })
+    const result = schema.safeParse(jsonParse(content))
+    return result.success ? result.data : null
+  } catch {
+    return null
+  }
+}
+
+async function copySnapshotToLocal(
+  agentType: string,
+  scope: AgentMemoryScope,
+): Promise<void> {
+  const snapshotMemDir = getSnapshotDirForAgent(agentType)
+  const localMemDir = getAgentMemoryDir(agentType, scope)
+
+  await mkdir(localMemDir, { recursive: true })
+
+  try {
+    const files = await readdir(snapshotMemDir, { withFileTypes: true })
+    for (const dirent of files) {
+      if (!dirent.isFile() || dirent.name === SNAPSHOT_JSON) continue
+      const content = await readFile(join(snapshotMemDir, dirent.name), {
+        encoding: 'utf-8',
+      })
+      await writeFile(join(localMemDir, dirent.name), content)
+    }
+  } catch (e) {
+    logForDebugging(`Failed to copy snapshot to local agent memory: ${e}`)
+  }
+}
+
+async function saveSyncedMeta(
+  agentType: string,
+  scope: AgentMemoryScope,
+  snapshotTimestamp: string,
+): Promise<void> {
+  const syncedPath = getSyncedJsonPath(agentType, scope)
+  const localMemDir = getAgentMemoryDir(agentType, scope)
+  await mkdir(localMemDir, { recursive: true })
+  const meta: SyncedMeta = { syncedFrom: snapshotTimestamp }
+  try {
+    await writeFile(syncedPath, jsonStringify(meta))
+  } catch (e) {
+    logForDebugging(`Failed to save snapshot sync metadata: ${e}`)
+  }
+}
+
+/**
+ * Check if a snapshot exists and whether it's newer than what we last synced.
+ */
+export async function checkAgentMemorySnapshot(
+  agentType: string,
+  scope: AgentMemoryScope,
+): Promise<{
+  action: 'none' | 'initialize' | 'prompt-update'
+  snapshotTimestamp?: string
+}> {
+  const snapshotMeta = await readJsonFile(
+    getSnapshotJsonPath(agentType),
+    snapshotMetaSchema(),
+  )
+
+  if (!snapshotMeta) {
+    return { action: 'none' }
+  }
+
+  const localMemDir = getAgentMemoryDir(agentType, scope)
+
+  let hasLocalMemory = false
+  try {
+    const dirents = await readdir(localMemDir, { withFileTypes: true })
+    hasLocalMemory = dirents.some(d => d.isFile() && d.name.endsWith('.md'))
+  } catch {
+    // Directory doesn't exist
+  }
+
+  if (!hasLocalMemory) {
+    return { action: 'initialize', snapshotTimestamp: snapshotMeta.updatedAt }
+  }
+
+  const syncedMeta = await readJsonFile(
+    getSyncedJsonPath(agentType, scope),
+    syncedMetaSchema(),
+  )
+
+  if (
+    !syncedMeta ||
+    new Date(snapshotMeta.updatedAt) > new Date(syncedMeta.syncedFrom)
+  ) {
+    return {
+      action: 'prompt-update',
+      snapshotTimestamp: snapshotMeta.updatedAt,
+    }
+  }
+
+  return { action: 'none' }
+}
+
+/**
+ * Initialize local agent memory from a snapshot (first-time setup).
+ */
+export async function initializeFromSnapshot(
+  agentType: string,
+  scope: AgentMemoryScope,
+  snapshotTimestamp: string,
+): Promise<void> {
+  logForDebugging(
+    `Initializing agent memory for ${agentType} from project snapshot`,
+  )
+  await copySnapshotToLocal(agentType, scope)
+  await saveSyncedMeta(agentType, scope, snapshotTimestamp)
+}
+
+/**
+ * Replace local agent memory with the snapshot.
+ */
+export async function replaceFromSnapshot(
+  agentType: string,
+  scope: AgentMemoryScope,
+  snapshotTimestamp: string,
+): Promise<void> {
+  logForDebugging(
+    `Replacing agent memory for ${agentType} with project snapshot`,
+  )
+  // Remove existing .md files before copying to avoid orphans
+  const localMemDir = getAgentMemoryDir(agentType, scope)
+  try {
+    const existing = await readdir(localMemDir, { withFileTypes: true })
+    for (const dirent of existing) {
+      if (dirent.isFile() && dirent.name.endsWith('.md')) {
+        await unlink(join(localMemDir, dirent.name))
+      }
+    }
+  } catch {
+    // Directory may not exist yet
+  }
+  await copySnapshotToLocal(agentType, scope)
+  await saveSyncedMeta(agentType, scope, snapshotTimestamp)
+}
+
+/**
+ * Mark the current snapshot as synced without changing local memory.
+ */
+export async function markSnapshotSynced(
+  agentType: string,
+  scope: AgentMemoryScope,
+  snapshotTimestamp: string,
+): Promise<void> {
+  await saveSyncedMeta(agentType, scope, snapshotTimestamp)
+}

src/tools/AgentTool/agentToolUtils.ts

@@ -0,0 +1,686 @@
+import { feature } from 'bun:bundle'
+import { z } from 'zod/v4'
+import { clearInvokedSkillsForAgent } from '../../bootstrap/state.js'
+import {
+  ALL_AGENT_DISALLOWED_TOOLS,
+  ASYNC_AGENT_ALLOWED_TOOLS,
+  CUSTOM_AGENT_DISALLOWED_TOOLS,
+  IN_PROCESS_TEAMMATE_ALLOWED_TOOLS,
+} from '../../constants/tools.js'
+import { startAgentSummarization } from '../../services/AgentSummary/agentSummary.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../../services/analytics/index.js'
+import { clearDumpState } from '../../services/api/dumpPrompts.js'
+import type { AppState } from '../../state/AppState.js'
+import type {
+  Tool,
+  ToolPermissionContext,
+  Tools,
+  ToolUseContext,
+} from '../../Tool.js'
+import { toolMatchesName } from '../../Tool.js'
+import {
+  completeAgentTask as completeAsyncAgent,
+  createActivityDescriptionResolver,
+  createProgressTracker,
+  enqueueAgentNotification,
+  failAgentTask as failAsyncAgent,
+  getProgressUpdate,
+  getTokenCountFromTracker,
+  isLocalAgentTask,
+  killAsyncAgent,
+  type ProgressTracker,
+  updateAgentProgress as updateAsyncAgentProgress,
+  updateProgressFromMessage,
+} from '../../tasks/LocalAgentTask/LocalAgentTask.js'
+import { asAgentId } from '../../types/ids.js'
+import type { Message as MessageType } from '../../types/message.js'
+import { isAgentSwarmsEnabled } from '../../utils/agentSwarmsEnabled.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { isInProtectedNamespace } from '../../utils/envUtils.js'
+import { AbortError, errorMessage } from '../../utils/errors.js'
+import type { CacheSafeParams } from '../../utils/forkedAgent.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import {
+  extractTextContent,
+  getLastAssistantMessage,
+} from '../../utils/messages.js'
+import type { PermissionMode } from '../../utils/permissions/PermissionMode.js'
+import { permissionRuleValueFromString } from '../../utils/permissions/permissionRuleParser.js'
+import {
+  buildTranscriptForClassifier,
+  classifyYoloAction,
+} from '../../utils/permissions/yoloClassifier.js'
+import { emitTaskProgress as emitTaskProgressEvent } from '../../utils/task/sdkProgress.js'
+import { isInProcessTeammate } from '../../utils/teammateContext.js'
+import { getTokenCountFromUsage } from '../../utils/tokens.js'
+import { EXIT_PLAN_MODE_V2_TOOL_NAME } from '../ExitPlanModeTool/constants.js'
+import { AGENT_TOOL_NAME, LEGACY_AGENT_TOOL_NAME } from './constants.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+export type ResolvedAgentTools = {
+  hasWildcard: boolean
+  validTools: string[]
+  invalidTools: string[]
+  resolvedTools: Tools
+  allowedAgentTypes?: string[]
+}
+
+export function filterToolsForAgent({
+  tools,
+  isBuiltIn,
+  isAsync = false,
+  permissionMode,
+}: {
+  tools: Tools
+  isBuiltIn: boolean
+  isAsync?: boolean
+  permissionMode?: PermissionMode
+}): Tools {
+  return tools.filter(tool => {
+    // Allow MCP tools for all agents
+    if (tool.name.startsWith('mcp__')) {
+      return true
+    }
+    // Allow ExitPlanMode for agents in plan mode (e.g., in-process teammates)
+    // This bypasses both the ALL_AGENT_DISALLOWED_TOOLS and async tool filters
+    if (
+      toolMatchesName(tool, EXIT_PLAN_MODE_V2_TOOL_NAME) &&
+      permissionMode === 'plan'
+    ) {
+      return true
+    }
+    if (ALL_AGENT_DISALLOWED_TOOLS.has(tool.name)) {
+      return false
+    }
+    if (!isBuiltIn && CUSTOM_AGENT_DISALLOWED_TOOLS.has(tool.name)) {
+      return false
+    }
+    if (isAsync && !ASYNC_AGENT_ALLOWED_TOOLS.has(tool.name)) {
+      if (isAgentSwarmsEnabled() && isInProcessTeammate()) {
+        // Allow AgentTool for in-process teammates to spawn sync subagents.
+        // Validation in AgentTool.call() prevents background agents and teammate spawning.
+        if (toolMatchesName(tool, AGENT_TOOL_NAME)) {
+          return true
+        }
+        // Allow task tools for in-process teammates to coordinate via shared task list
+        if (IN_PROCESS_TEAMMATE_ALLOWED_TOOLS.has(tool.name)) {
+          return true
+        }
+      }
+      return false
+    }
+    return true
+  })
+}
+
+/**
+ * Resolves and validates agent tools against available tools
+ * Handles wildcard expansion and validation in one place
+ */
+export function resolveAgentTools(
+  agentDefinition: Pick<
+    AgentDefinition,
+    'tools' | 'disallowedTools' | 'source' | 'permissionMode'
+  >,
+  availableTools: Tools,
+  isAsync = false,
+  isMainThread = false,
+): ResolvedAgentTools {
+  const {
+    tools: agentTools,
+    disallowedTools,
+    source,
+    permissionMode,
+  } = agentDefinition
+  // When isMainThread is true, skip filterToolsForAgent entirely — the main
+  // thread's tool pool is already properly assembled by useMergedTools(), so
+  // the sub-agent disallow lists shouldn't apply.
+  const filteredAvailableTools = isMainThread
+    ? availableTools
+    : filterToolsForAgent({
+        tools: availableTools,
+        isBuiltIn: source === 'built-in',
+        isAsync,
+        permissionMode,
+      })
+
+  // Create a set of disallowed tool names for quick lookup
+  const disallowedToolSet = new Set(
+    disallowedTools?.map(toolSpec => {
+      const { toolName } = permissionRuleValueFromString(toolSpec)
+      return toolName
+    }) ?? [],
+  )
+
+  // Filter available tools based on disallowed list
+  const allowedAvailableTools = filteredAvailableTools.filter(
+    tool => !disallowedToolSet.has(tool.name),
+  )
+
+  // If tools is undefined or ['*'], allow all tools (after filtering disallowed)
+  const hasWildcard =
+    agentTools === undefined ||
+    (agentTools.length === 1 && agentTools[0] === '*')
+  if (hasWildcard) {
+    return {
+      hasWildcard: true,
+      validTools: [],
+      invalidTools: [],
+      resolvedTools: allowedAvailableTools,
+    }
+  }
+
+  const availableToolMap = new Map<string, Tool>()
+  for (const tool of allowedAvailableTools) {
+    availableToolMap.set(tool.name, tool)
+  }
+
+  const validTools: string[] = []
+  const invalidTools: string[] = []
+  const resolved: Tool[] = []
+  const resolvedToolsSet = new Set<Tool>()
+  let allowedAgentTypes: string[] | undefined
+
+  for (const toolSpec of agentTools) {
+    // Parse the tool spec to extract the base tool name and any permission pattern
+    const { toolName, ruleContent } = permissionRuleValueFromString(toolSpec)
+
+    // Special case: Agent tool carries allowedAgentTypes metadata in its spec
+    if (toolName === AGENT_TOOL_NAME) {
+      if (ruleContent) {
+        // Parse comma-separated agent types: "worker, researcher" → ["worker", "researcher"]
+        allowedAgentTypes = ruleContent.split(',').map(s => s.trim())
+      }
+      // For sub-agents, Agent is excluded by filterToolsForAgent — mark the spec
+      // valid for allowedAgentTypes tracking but skip tool resolution.
+      if (!isMainThread) {
+        validTools.push(toolSpec)
+        continue
+      }
+      // For main thread, filtering was skipped so Agent is in availableToolMap —
+      // fall through to normal resolution below.
+    }
+
+    const tool = availableToolMap.get(toolName)
+    if (tool) {
+      validTools.push(toolSpec)
+      if (!resolvedToolsSet.has(tool)) {
+        resolved.push(tool)
+        resolvedToolsSet.add(tool)
+      }
+    } else {
+      invalidTools.push(toolSpec)
+    }
+  }
+
+  return {
+    hasWildcard: false,
+    validTools,
+    invalidTools,
+    resolvedTools: resolved,
+    allowedAgentTypes,
+  }
+}
+
+export const agentToolResultSchema = lazySchema(() =>
+  z.object({
+    agentId: z.string(),
+    // Optional: older persisted sessions won't have this (resume replays
+    // results verbatim without re-validation). Used to gate the sync
+    // result trailer — one-shot built-ins skip the SendMessage hint.
+    agentType: z.string().optional(),
+    content: z.array(z.object({ type: z.literal('text'), text: z.string() })),
+    totalToolUseCount: z.number(),
+    totalDurationMs: z.number(),
+    totalTokens: z.number(),
+    usage: z.object({
+      input_tokens: z.number(),
+      output_tokens: z.number(),
+      cache_creation_input_tokens: z.number().nullable(),
+      cache_read_input_tokens: z.number().nullable(),
+      server_tool_use: z
+        .object({
+          web_search_requests: z.number(),
+          web_fetch_requests: z.number(),
+        })
+        .nullable(),
+      service_tier: z.enum(['standard', 'priority', 'batch']).nullable(),
+      cache_creation: z
+        .object({
+          ephemeral_1h_input_tokens: z.number(),
+          ephemeral_5m_input_tokens: z.number(),
+        })
+        .nullable(),
+    }),
+  }),
+)
+
+export type AgentToolResult = z.input<ReturnType<typeof agentToolResultSchema>>
+
+export function countToolUses(messages: MessageType[]): number {
+  let count = 0
+  for (const m of messages) {
+    if (m.type === 'assistant') {
+      for (const block of m.message.content) {
+        if (block.type === 'tool_use') {
+          count++
+        }
+      }
+    }
+  }
+  return count
+}
+
+export function finalizeAgentTool(
+  agentMessages: MessageType[],
+  agentId: string,
+  metadata: {
+    prompt: string
+    resolvedAgentModel: string
+    isBuiltInAgent: boolean
+    startTime: number
+    agentType: string
+    isAsync: boolean
+  },
+): AgentToolResult {
+  const {
+    prompt,
+    resolvedAgentModel,
+    isBuiltInAgent,
+    startTime,
+    agentType,
+    isAsync,
+  } = metadata
+
+  const lastAssistantMessage = getLastAssistantMessage(agentMessages)
+  if (lastAssistantMessage === undefined) {
+    throw new Error('No assistant messages found')
+  }
+  // Extract text content from the agent's response. If the final assistant
+  // message is a pure tool_use block (loop exited mid-turn), fall back to
+  // the most recent assistant message that has text content.
+  let content = lastAssistantMessage.message.content.filter(
+    _ => _.type === 'text',
+  )
+  if (content.length === 0) {
+    for (let i = agentMessages.length - 1; i >= 0; i--) {
+      const m = agentMessages[i]!
+      if (m.type !== 'assistant') continue
+      const textBlocks = m.message.content.filter(_ => _.type === 'text')
+      if (textBlocks.length > 0) {
+        content = textBlocks
+        break
+      }
+    }
+  }
+
+  const totalTokens = getTokenCountFromUsage(lastAssistantMessage.message.usage)
+  const totalToolUseCount = countToolUses(agentMessages)
+
+  logEvent('tengu_agent_tool_completed', {
+    agent_type:
+      agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    model:
+      resolvedAgentModel as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    prompt_char_count: prompt.length,
+    response_char_count: content.length,
+    assistant_message_count: agentMessages.length,
+    total_tool_uses: totalToolUseCount,
+    duration_ms: Date.now() - startTime,
+    total_tokens: totalTokens,
+    is_built_in_agent: isBuiltInAgent,
+    is_async: isAsync,
+  })
+
+  // Signal to inference that this subagent's cache chain can be evicted.
+  const lastRequestId = lastAssistantMessage.requestId
+  if (lastRequestId) {
+    logEvent('tengu_cache_eviction_hint', {
+      scope:
+        'subagent_end' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      last_request_id:
+        lastRequestId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    })
+  }
+
+  return {
+    agentId,
+    agentType,
+    content,
+    totalDurationMs: Date.now() - startTime,
+    totalTokens,
+    totalToolUseCount,
+    usage: lastAssistantMessage.message.usage,
+  }
+}
+
+/**
+ * Returns the name of the last tool_use block in an assistant message,
+ * or undefined if the message is not an assistant message with tool_use.
+ */
+export function getLastToolUseName(message: MessageType): string | undefined {
+  if (message.type !== 'assistant') return undefined
+  const block = message.message.content.findLast(b => b.type === 'tool_use')
+  return block?.type === 'tool_use' ? block.name : undefined
+}
+
+export function emitTaskProgress(
+  tracker: ProgressTracker,
+  taskId: string,
+  toolUseId: string | undefined,
+  description: string,
+  startTime: number,
+  lastToolName: string,
+): void {
+  const progress = getProgressUpdate(tracker)
+  emitTaskProgressEvent({
+    taskId,
+    toolUseId,
+    description: progress.lastActivity?.activityDescription ?? description,
+    startTime,
+    totalTokens: progress.tokenCount,
+    toolUses: progress.toolUseCount,
+    lastToolName,
+  })
+}
+
+export async function classifyHandoffIfNeeded({
+  agentMessages,
+  tools,
+  toolPermissionContext,
+  abortSignal,
+  subagentType,
+  totalToolUseCount,
+}: {
+  agentMessages: MessageType[]
+  tools: Tools
+  toolPermissionContext: AppState['toolPermissionContext']
+  abortSignal: AbortSignal
+  subagentType: string
+  totalToolUseCount: number
+}): Promise<string | null> {
+  if (feature('TRANSCRIPT_CLASSIFIER')) {
+    if (toolPermissionContext.mode !== 'auto') return null
+
+    const agentTranscript = buildTranscriptForClassifier(agentMessages, tools)
+    if (!agentTranscript) return null
+
+    const classifierResult = await classifyYoloAction(
+      agentMessages,
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: "Sub-agent has finished and is handing back control to the main agent. Review the sub-agent's work based on the block rules and let the main agent know if any file is dangerous (the main agent will see the reason).",
+          },
+        ],
+      },
+      tools,
+      toolPermissionContext as ToolPermissionContext,
+      abortSignal,
+    )
+
+    const handoffDecision = classifierResult.unavailable
+      ? 'unavailable'
+      : classifierResult.shouldBlock
+        ? 'blocked'
+        : 'allowed'
+    logEvent('tengu_auto_mode_decision', {
+      decision:
+        handoffDecision as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      toolName:
+        // Use legacy name for analytics continuity across the Task→Agent rename
+        LEGACY_AGENT_TOOL_NAME as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      inProtectedNamespace: isInProtectedNamespace(),
+      classifierModel:
+        classifierResult.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      agentType:
+        subagentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      toolUseCount: totalToolUseCount,
+      isHandoff: true,
+      // For handoff, the relevant agent completion is the subagent's final
+      // assistant message — the last thing the classifier transcript shows
+      // before the handoff review prompt.
+      agentMsgId: getLastAssistantMessage(agentMessages)?.message
+        .id as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      classifierStage:
+        classifierResult.stage as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      classifierStage1RequestId:
+        classifierResult.stage1RequestId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      classifierStage1MsgId:
+        classifierResult.stage1MsgId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      classifierStage2RequestId:
+        classifierResult.stage2RequestId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      classifierStage2MsgId:
+        classifierResult.stage2MsgId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    })
+
+    if (classifierResult.shouldBlock) {
+      // When classifier is unavailable, still propagate the sub-agent's
+      // results but with a warning so the parent agent can verify the work.
+      if (classifierResult.unavailable) {
+        logForDebugging(
+          'Handoff classifier unavailable, allowing sub-agent output with warning',
+          { level: 'warn' },
+        )
+        return `Note: The safety classifier was unavailable when reviewing this sub-agent's work. Please carefully verify the sub-agent's actions and output before acting on them.`
+      }
+
+      logForDebugging(
+        `Handoff classifier flagged sub-agent output: ${classifierResult.reason}`,
+        { level: 'warn' },
+      )
+      return `SECURITY WARNING: This sub-agent performed actions that may violate security policy. Reason: ${classifierResult.reason}. Review the sub-agent's actions carefully before acting on its output.`
+    }
+  }
+
+  return null
+}
+
+/**
+ * Extract a partial result string from an agent's accumulated messages.
+ * Used when an async agent is killed to preserve what it accomplished.
+ * Returns undefined if no text content is found.
+ */
+export function extractPartialResult(
+  messages: MessageType[],
+): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!
+    if (m.type !== 'assistant') continue
+    const text = extractTextContent(m.message.content, '\n')
+    if (text) {
+      return text
+    }
+  }
+  return undefined
+}
+
+type SetAppState = (f: (prev: AppState) => AppState) => void
+
+/**
+ * Drives a background agent from spawn to terminal notification.
+ * Shared between AgentTool's async-from-start path and resumeAgentBackground.
+ */
+export async function runAsyncAgentLifecycle({
+  taskId,
+  abortController,
+  makeStream,
+  metadata,
+  description,
+  toolUseContext,
+  rootSetAppState,
+  agentIdForCleanup,
+  enableSummarization,
+  getWorktreeResult,
+}: {
+  taskId: string
+  abortController: AbortController
+  makeStream: (
+    onCacheSafeParams: ((p: CacheSafeParams) => void) | undefined,
+  ) => AsyncGenerator<MessageType, void>
+  metadata: Parameters<typeof finalizeAgentTool>[2]
+  description: string
+  toolUseContext: ToolUseContext
+  rootSetAppState: SetAppState
+  agentIdForCleanup: string
+  enableSummarization: boolean
+  getWorktreeResult: () => Promise<{
+    worktreePath?: string
+    worktreeBranch?: string
+  }>
+}): Promise<void> {
+  let stopSummarization: (() => void) | undefined
+  const agentMessages: MessageType[] = []
+  try {
+    const tracker = createProgressTracker()
+    const resolveActivity = createActivityDescriptionResolver(
+      toolUseContext.options.tools,
+    )
+    const onCacheSafeParams = enableSummarization
+      ? (params: CacheSafeParams) => {
+          const { stop } = startAgentSummarization(
+            taskId,
+            asAgentId(taskId),
+            params,
+            rootSetAppState,
+          )
+          stopSummarization = stop
+        }
+      : undefined
+    for await (const message of makeStream(onCacheSafeParams)) {
+      agentMessages.push(message)
+      // Append immediately when UI holds the task (retain). Bootstrap reads
+      // disk in parallel and UUID-merges the prefix — disk-write-before-yield
+      // means live is always a suffix of disk, so merge is order-correct.
+      rootSetAppState(prev => {
+        const t = prev.tasks[taskId]
+        if (!isLocalAgentTask(t) || !t.retain) return prev
+        const base = t.messages ?? []
+        return {
+          ...prev,
+          tasks: {
+            ...prev.tasks,
+            [taskId]: { ...t, messages: [...base, message] },
+          },
+        }
+      })
+      updateProgressFromMessage(
+        tracker,
+        message,
+        resolveActivity,
+        toolUseContext.options.tools,
+      )
+      updateAsyncAgentProgress(
+        taskId,
+        getProgressUpdate(tracker),
+        rootSetAppState,
+      )
+      const lastToolName = getLastToolUseName(message)
+      if (lastToolName) {
+        emitTaskProgress(
+          tracker,
+          taskId,
+          toolUseContext.toolUseId,
+          description,
+          metadata.startTime,
+          lastToolName,
+        )
+      }
+    }
+
+    stopSummarization?.()
+
+    const agentResult = finalizeAgentTool(agentMessages, taskId, metadata)
+
+    // Mark task completed FIRST so TaskOutput(block=true) unblocks
+    // immediately. classifyHandoffIfNeeded (API call) and getWorktreeResult
+    // (git exec) are notification embellishments that can hang — they must
+    // not gate the status transition (gh-20236).
+    completeAsyncAgent(agentResult, rootSetAppState)
+
+    let finalMessage = extractTextContent(agentResult.content, '\n')
+
+    if (feature('TRANSCRIPT_CLASSIFIER')) {
+      const handoffWarning = await classifyHandoffIfNeeded({
+        agentMessages,
+        tools: toolUseContext.options.tools,
+        toolPermissionContext:
+          toolUseContext.getAppState().toolPermissionContext,
+        abortSignal: abortController.signal,
+        subagentType: metadata.agentType,
+        totalToolUseCount: agentResult.totalToolUseCount,
+      })
+      if (handoffWarning) {
+        finalMessage = `${handoffWarning}\n\n${finalMessage}`
+      }
+    }
+
+    const worktreeResult = await getWorktreeResult()
+
+    enqueueAgentNotification({
+      taskId,
+      description,
+      status: 'completed',
+      setAppState: rootSetAppState,
+      finalMessage,
+      usage: {
+        totalTokens: getTokenCountFromTracker(tracker),
+        toolUses: agentResult.totalToolUseCount,
+        durationMs: agentResult.totalDurationMs,
+      },
+      toolUseId: toolUseContext.toolUseId,
+      ...worktreeResult,
+    })
+  } catch (error) {
+    stopSummarization?.()
+    if (error instanceof AbortError) {
+      // killAsyncAgent is a no-op if TaskStop already set status='killed' —
+      // but only this catch handler has agentMessages, so the notification
+      // must fire unconditionally. Transition status BEFORE worktree cleanup
+      // so TaskOutput unblocks even if git hangs (gh-20236).
+      killAsyncAgent(taskId, rootSetAppState)
+      logEvent('tengu_agent_tool_terminated', {
+        agent_type:
+          metadata.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        model:
+          metadata.resolvedAgentModel as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        duration_ms: Date.now() - metadata.startTime,
+        is_async: true,
+        is_built_in_agent: metadata.isBuiltInAgent,
+        reason:
+          'user_kill_async' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+      const worktreeResult = await getWorktreeResult()
+      const partialResult = extractPartialResult(agentMessages)
+      enqueueAgentNotification({
+        taskId,
+        description,
+        status: 'killed',
+        setAppState: rootSetAppState,
+        toolUseId: toolUseContext.toolUseId,
+        finalMessage: partialResult,
+        ...worktreeResult,
+      })
+      return
+    }
+    const msg = errorMessage(error)
+    failAsyncAgent(taskId, msg, rootSetAppState)
+    const worktreeResult = await getWorktreeResult()
+    enqueueAgentNotification({
+      taskId,
+      description,
+      status: 'failed',
+      error: msg,
+      setAppState: rootSetAppState,
+      toolUseId: toolUseContext.toolUseId,
+      ...worktreeResult,
+    })
+  } finally {
+    clearInvokedSkillsForAgent(agentIdForCleanup)
+    clearDumpState(agentIdForCleanup)
+  }
+}

src/tools/AgentTool/built-in/claudeCodeGuideAgent.ts

@@ -0,0 +1,205 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js'
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js'
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js'
+import { SEND_MESSAGE_TOOL_NAME } from 'src/tools/SendMessageTool/constants.js'
+import { WEB_FETCH_TOOL_NAME } from 'src/tools/WebFetchTool/prompt.js'
+import { WEB_SEARCH_TOOL_NAME } from 'src/tools/WebSearchTool/prompt.js'
+import { isUsing3PServices } from 'src/utils/auth.js'
+import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js'
+import { getSettings_DEPRECATED } from 'src/utils/settings/settings.js'
+import { jsonStringify } from '../../../utils/slowOperations.js'
+import type {
+  AgentDefinition,
+  BuiltInAgentDefinition,
+} from '../loadAgentsDir.js'
+
+const CLAUDE_CODE_DOCS_MAP_URL =
+  'https://code.claude.com/docs/en/claude_code_docs_map.md'
+const CDP_DOCS_MAP_URL = 'https://platform.claude.com/llms.txt'
+
+export const CLAUDE_CODE_GUIDE_AGENT_TYPE = 'claude-code-guide'
+
+function getClaudeCodeGuideBasePrompt(): string {
+  // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+  // dedicated Glob/Grep tools, so point at find/grep instead.
+  const localSearchHint = hasEmbeddedSearchTools()
+    ? `${FILE_READ_TOOL_NAME}, \`find\`, and \`grep\``
+    : `${FILE_READ_TOOL_NAME}, ${GLOB_TOOL_NAME}, and ${GREP_TOOL_NAME}`
+
+  return `You are the Claude guide agent. Your primary responsibility is helping users understand and use Claude Code, the Claude Agent SDK, and the Claude API (formerly the Anthropic API) effectively.
+
+**Your expertise spans three domains:**
+
+1. **Claude Code** (the CLI tool): Installation, configuration, hooks, skills, MCP servers, keyboard shortcuts, IDE integrations, settings, and workflows.
+
+2. **Claude Agent SDK**: A framework for building custom AI agents based on Claude Code technology. Available for Node.js/TypeScript and Python.
+
+3. **Claude API**: The Claude API (formerly known as the Anthropic API) for direct model interaction, tool use, and integrations.
+
+**Documentation sources:**
+
+- **Claude Code docs** (${CLAUDE_CODE_DOCS_MAP_URL}): Fetch this for questions about the Claude Code CLI tool, including:
+  - Installation, setup, and getting started
+  - Hooks (pre/post command execution)
+  - Custom skills
+  - MCP server configuration
+  - IDE integrations (VS Code, JetBrains)
+  - Settings files and configuration
+  - Keyboard shortcuts and hotkeys
+  - Subagents and plugins
+  - Sandboxing and security
+
+- **Claude Agent SDK docs** (${CDP_DOCS_MAP_URL}): Fetch this for questions about building agents with the SDK, including:
+  - SDK overview and getting started (Python and TypeScript)
+  - Agent configuration + custom tools
+  - Session management and permissions
+  - MCP integration in agents
+  - Hosting and deployment
+  - Cost tracking and context management
+  Note: Agent SDK docs are part of the Claude API documentation at the same URL.
+
+- **Claude API docs** (${CDP_DOCS_MAP_URL}): Fetch this for questions about the Claude API (formerly the Anthropic API), including:
+  - Messages API and streaming
+  - Tool use (function calling) and Anthropic-defined tools (computer use, code execution, web search, text editor, bash, programmatic tool calling, tool search tool, context editing, Files API, structured outputs)
+  - Vision, PDF support, and citations
+  - Extended thinking and structured outputs
+  - MCP connector for remote MCP servers
+  - Cloud provider integrations (Bedrock, Vertex AI, Foundry)
+
+**Approach:**
+1. Determine which domain the user's question falls into
+2. Use ${WEB_FETCH_TOOL_NAME} to fetch the appropriate docs map
+3. Identify the most relevant documentation URLs from the map
+4. Fetch the specific documentation pages
+5. Provide clear, actionable guidance based on official documentation
+6. Use ${WEB_SEARCH_TOOL_NAME} if docs don't cover the topic
+7. Reference local project files (CLAUDE.md, .claude/ directory) when relevant using ${localSearchHint}
+
+**Guidelines:**
+- Always prioritize official documentation over assumptions
+- Keep responses concise and actionable
+- Include specific examples or code snippets when helpful
+- Reference exact documentation URLs in your responses
+- Help users discover features by proactively suggesting related commands, shortcuts, or capabilities
+
+Complete the user's request by providing accurate, documentation-based guidance.`
+}
+
+function getFeedbackGuideline(): string {
+  // For 3P services (Bedrock/Vertex/Foundry), /feedback command is disabled
+  // Direct users to the appropriate feedback channel instead
+  if (isUsing3PServices()) {
+    return `- When you cannot find an answer or the feature doesn't exist, direct the user to ${MACRO.ISSUES_EXPLAINER}`
+  }
+  return "- When you cannot find an answer or the feature doesn't exist, direct the user to use /feedback to report a feature request or bug"
+}
+
+export const CLAUDE_CODE_GUIDE_AGENT: BuiltInAgentDefinition = {
+  agentType: CLAUDE_CODE_GUIDE_AGENT_TYPE,
+  whenToUse: `Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can continue via ${SEND_MESSAGE_TOOL_NAME}.`,
+  // Ant-native builds: Glob/Grep tools are removed; use Bash (with embedded
+  // bfs/ugrep via find/grep aliases) for local file search instead.
+  tools: hasEmbeddedSearchTools()
+    ? [
+        BASH_TOOL_NAME,
+        FILE_READ_TOOL_NAME,
+        WEB_FETCH_TOOL_NAME,
+        WEB_SEARCH_TOOL_NAME,
+      ]
+    : [
+        GLOB_TOOL_NAME,
+        GREP_TOOL_NAME,
+        FILE_READ_TOOL_NAME,
+        WEB_FETCH_TOOL_NAME,
+        WEB_SEARCH_TOOL_NAME,
+      ],
+  source: 'built-in',
+  baseDir: 'built-in',
+  model: 'haiku',
+  permissionMode: 'dontAsk',
+  getSystemPrompt({ toolUseContext }) {
+    const commands = toolUseContext.options.commands
+
+    // Build context sections
+    const contextSections: string[] = []
+
+    // 1. Custom skills
+    const customCommands = commands.filter(cmd => cmd.type === 'prompt')
+    if (customCommands.length > 0) {
+      const commandList = customCommands
+        .map(cmd => `- /${cmd.name}: ${cmd.description}`)
+        .join('\n')
+      contextSections.push(
+        `**Available custom skills in this project:**\n${commandList}`,
+      )
+    }
+
+    // 2. Custom agents from .claude/agents/
+    const customAgents =
+      toolUseContext.options.agentDefinitions.activeAgents.filter(
+        (a: AgentDefinition) => a.source !== 'built-in',
+      )
+    if (customAgents.length > 0) {
+      const agentList = customAgents
+        .map((a: AgentDefinition) => `- ${a.agentType}: ${a.whenToUse}`)
+        .join('\n')
+      contextSections.push(
+        `**Available custom agents configured:**\n${agentList}`,
+      )
+    }
+
+    // 3. MCP servers
+    const mcpClients = toolUseContext.options.mcpClients
+    if (mcpClients && mcpClients.length > 0) {
+      const mcpList = mcpClients
+        .map((client: { name: string }) => `- ${client.name}`)
+        .join('\n')
+      contextSections.push(`**Configured MCP servers:**\n${mcpList}`)
+    }
+
+    // 4. Plugin commands
+    const pluginCommands = commands.filter(
+      cmd => cmd.type === 'prompt' && cmd.source === 'plugin',
+    )
+    if (pluginCommands.length > 0) {
+      const pluginList = pluginCommands
+        .map(cmd => `- /${cmd.name}: ${cmd.description}`)
+        .join('\n')
+      contextSections.push(`**Available plugin skills:**\n${pluginList}`)
+    }
+
+    // 5. User settings
+    const settings = getSettings_DEPRECATED()
+    if (Object.keys(settings).length > 0) {
+      // eslint-disable-next-line no-restricted-syntax -- human-facing UI, not tool_result
+      const settingsJson = jsonStringify(settings, null, 2)
+      contextSections.push(
+        `**User's settings.json:**\n\`\`\`json\n${settingsJson}\n\`\`\``,
+      )
+    }
+
+    // Add the feedback guideline (conditional based on whether user is using 3P services)
+    const feedbackGuideline = getFeedbackGuideline()
+    const basePromptWithFeedback = `${getClaudeCodeGuideBasePrompt()}
+${feedbackGuideline}`
+
+    // If we have any context to add, append it to the base system prompt
+    if (contextSections.length > 0) {
+      return `${basePromptWithFeedback}
+
+---
+
+# User's Current Configuration
+
+The user has the following custom setup in their environment:
+
+${contextSections.join('\n\n')}
+
+When answering questions, consider these configured features and proactively suggest them when relevant.`
+    }
+
+    // Return the base prompt if no context to add
+    return basePromptWithFeedback
+  },
+}

src/tools/AgentTool/built-in/exploreAgent.ts

@@ -0,0 +1,83 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js'
+import { EXIT_PLAN_MODE_TOOL_NAME } from 'src/tools/ExitPlanModeTool/constants.js'
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js'
+import { NOTEBOOK_EDIT_TOOL_NAME } from 'src/tools/NotebookEditTool/constants.js'
+import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js'
+import { AGENT_TOOL_NAME } from '../constants.js'
+import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'
+
+function getExploreSystemPrompt(): string {
+  // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+  // dedicated Glob/Grep tools, so point at find/grep via Bash instead.
+  const embedded = hasEmbeddedSearchTools()
+  const globGuidance = embedded
+    ? `- Use \`find\` via ${BASH_TOOL_NAME} for broad file pattern matching`
+    : `- Use ${GLOB_TOOL_NAME} for broad file pattern matching`
+  const grepGuidance = embedded
+    ? `- Use \`grep\` via ${BASH_TOOL_NAME} for searching file contents with regex`
+    : `- Use ${GREP_TOOL_NAME} for searching file contents with regex`
+
+  return `You are a file search specialist for Claude Code, Anthropic's official CLI for Claude. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+${globGuidance}
+${grepGuidance}
+- Use ${FILE_READ_TOOL_NAME} when you know the specific file path you need to read
+- Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find${embedded ? ', grep' : ''}, cat, head, tail)
+- NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.`
+}
+
+export const EXPLORE_AGENT_MIN_QUERIES = 3
+
+const EXPLORE_WHEN_TO_USE =
+  'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+
+export const EXPLORE_AGENT: BuiltInAgentDefinition = {
+  agentType: 'Explore',
+  whenToUse: EXPLORE_WHEN_TO_USE,
+  disallowedTools: [
+    AGENT_TOOL_NAME,
+    EXIT_PLAN_MODE_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    NOTEBOOK_EDIT_TOOL_NAME,
+  ],
+  source: 'built-in',
+  baseDir: 'built-in',
+  // Ants get inherit to use the main agent's model; external users get haiku for speed
+  // Note: For ants, getAgentModel() checks tengu_explore_agent GrowthBook flag at runtime
+  model: process.env.USER_TYPE === 'ant' ? 'inherit' : 'haiku',
+  // Explore is a fast read-only search agent — it doesn't need commit/PR/lint
+  // rules from CLAUDE.md. The main agent has full context and interprets results.
+  omitClaudeMd: true,
+  getSystemPrompt: () => getExploreSystemPrompt(),
+}

src/tools/AgentTool/built-in/generalPurposeAgent.ts

@@ -0,0 +1,34 @@
+import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'
+
+const SHARED_PREFIX = `You are an agent for Claude Code, Anthropic's official CLI for Claude. Given the user's message, you should use the tools available to complete the task. Complete the task fully—don't gold-plate, but don't leave it half-done.`
+
+const SHARED_GUIDELINES = `Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: search broadly when you don't know where something lives. Use Read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.`
+
+// Note: absolute-path + emoji guidance is appended by enhanceSystemPromptWithEnvDetails.
+function getGeneralPurposeSystemPrompt(): string {
+  return `${SHARED_PREFIX} When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.
+
+${SHARED_GUIDELINES}`
+}
+
+export const GENERAL_PURPOSE_AGENT: BuiltInAgentDefinition = {
+  agentType: 'general-purpose',
+  whenToUse:
+    'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.',
+  tools: ['*'],
+  source: 'built-in',
+  baseDir: 'built-in',
+  // model is intentionally omitted - uses getDefaultSubagentModel().
+  getSystemPrompt: getGeneralPurposeSystemPrompt,
+}

src/tools/AgentTool/built-in/planAgent.ts

@@ -0,0 +1,92 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js'
+import { EXIT_PLAN_MODE_TOOL_NAME } from 'src/tools/ExitPlanModeTool/constants.js'
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js'
+import { NOTEBOOK_EDIT_TOOL_NAME } from 'src/tools/NotebookEditTool/constants.js'
+import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js'
+import { AGENT_TOOL_NAME } from '../constants.js'
+import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'
+import { EXPLORE_AGENT } from './exploreAgent.js'
+
+function getPlanV2SystemPrompt(): string {
+  // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+  // dedicated Glob/Grep tools, so point at find/grep instead.
+  const searchToolsHint = hasEmbeddedSearchTools()
+    ? `\`find\`, \`grep\`, and ${FILE_READ_TOOL_NAME}`
+    : `${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, and ${FILE_READ_TOOL_NAME}`
+
+  return `You are a software architect and planning specialist for Claude Code. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using ${searchToolsHint}
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find${hasEmbeddedSearchTools() ? ', grep' : ''}, cat, head, tail)
+   - NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts
+- path/to/file2.ts
+- path/to/file3.ts
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.`
+}
+
+export const PLAN_AGENT: BuiltInAgentDefinition = {
+  agentType: 'Plan',
+  whenToUse:
+    'Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.',
+  disallowedTools: [
+    AGENT_TOOL_NAME,
+    EXIT_PLAN_MODE_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    NOTEBOOK_EDIT_TOOL_NAME,
+  ],
+  source: 'built-in',
+  tools: EXPLORE_AGENT.tools,
+  baseDir: 'built-in',
+  model: 'inherit',
+  // Plan is read-only and can Read CLAUDE.md directly if it needs conventions.
+  // Dropping it from context saves tokens without blocking access.
+  omitClaudeMd: true,
+  getSystemPrompt: () => getPlanV2SystemPrompt(),
+}

src/tools/AgentTool/built-in/statuslineSetup.ts

@@ -0,0 +1,144 @@
+import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'
+
+const STATUSLINE_SYSTEM_PROMPT = `You are a status line setup agent for Claude Code. Your job is to create or update the statusLine command in the user's Claude Code settings.
+
+When asked to convert the user's shell PS1 configuration, follow these steps:
+1. Read the user's shell configuration files in this order of preference:
+   - ~/.zshrc
+   - ~/.bashrc  
+   - ~/.bash_profile
+   - ~/.profile
+
+2. Extract the PS1 value using this regex pattern: /(?:^|\\n)\\s*(?:export\\s+)?PS1\\s*=\\s*["']([^"']+)["']/m
+
+3. Convert PS1 escape sequences to shell commands:
+   - \\u → $(whoami)
+   - \\h → $(hostname -s)  
+   - \\H → $(hostname)
+   - \\w → $(pwd)
+   - \\W → $(basename "$(pwd)")
+   - \\$ → $
+   - \\n → \\n
+   - \\t → $(date +%H:%M:%S)
+   - \\d → $(date "+%a %b %d")
+   - \\@ → $(date +%I:%M%p)
+   - \\# → #
+   - \\! → !
+
+4. When using ANSI color codes, be sure to use \`printf\`. Do not remove colors. Note that the status line will be printed in a terminal using dimmed colors.
+
+5. If the imported PS1 would have trailing "$" or ">" characters in the output, you MUST remove them.
+
+6. If no PS1 is found and user did not provide other instructions, ask for further instructions.
+
+How to use the statusLine command:
+1. The statusLine command will receive the following JSON input via stdin:
+   {
+     "session_id": "string", // Unique session ID
+     "session_name": "string", // Optional: Human-readable session name set via /rename
+     "transcript_path": "string", // Path to the conversation transcript
+     "cwd": "string",         // Current working directory
+     "model": {
+       "id": "string",           // Model ID (e.g., "claude-3-5-sonnet-20241022")
+       "display_name": "string"  // Display name (e.g., "Claude 3.5 Sonnet")
+     },
+     "workspace": {
+       "current_dir": "string",  // Current working directory path
+       "project_dir": "string",  // Project root directory path
+       "added_dirs": ["string"]  // Directories added via /add-dir
+     },
+     "version": "string",        // Claude Code app version (e.g., "1.0.71")
+     "output_style": {
+       "name": "string",         // Output style name (e.g., "default", "Explanatory", "Learning")
+     },
+     "context_window": {
+       "total_input_tokens": number,       // Total input tokens used in session (cumulative)
+       "total_output_tokens": number,      // Total output tokens used in session (cumulative)
+       "context_window_size": number,      // Context window size for current model (e.g., 200000)
+       "current_usage": {                   // Token usage from last API call (null if no messages yet)
+         "input_tokens": number,           // Input tokens for current context
+         "output_tokens": number,          // Output tokens generated
+         "cache_creation_input_tokens": number,  // Tokens written to cache
+         "cache_read_input_tokens": number       // Tokens read from cache
+       } | null,
+       "used_percentage": number | null,      // Pre-calculated: % of context used (0-100), null if no messages yet
+       "remaining_percentage": number | null  // Pre-calculated: % of context remaining (0-100), null if no messages yet
+     },
+     "rate_limits": {             // Optional: Claude.ai subscription usage limits. Only present for subscribers after first API response.
+       "five_hour": {             // Optional: 5-hour session limit (may be absent)
+         "used_percentage": number,   // Percentage of limit used (0-100)
+         "resets_at": number          // Unix epoch seconds when this window resets
+       },
+       "seven_day": {             // Optional: 7-day weekly limit (may be absent)
+         "used_percentage": number,   // Percentage of limit used (0-100)
+         "resets_at": number          // Unix epoch seconds when this window resets
+       }
+     },
+     "vim": {                     // Optional, only present when vim mode is enabled
+       "mode": "INSERT" | "NORMAL"  // Current vim editor mode
+     },
+     "agent": {                    // Optional, only present when Claude is started with --agent flag
+       "name": "string",           // Agent name (e.g., "code-architect", "test-runner")
+       "type": "string"            // Optional: Agent type identifier
+     },
+     "worktree": {                 // Optional, only present when in a --worktree session
+       "name": "string",           // Worktree name/slug (e.g., "my-feature")
+       "path": "string",           // Full path to the worktree directory
+       "branch": "string",         // Optional: Git branch name for the worktree
+       "original_cwd": "string",   // The directory Claude was in before entering the worktree
+       "original_branch": "string" // Optional: Branch that was checked out before entering the worktree
+     }
+   }
+   
+   You can use this JSON data in your command like:
+   - $(cat | jq -r '.model.display_name')
+   - $(cat | jq -r '.workspace.current_dir')
+   - $(cat | jq -r '.output_style.name')
+
+   Or store it in a variable first:
+   - input=$(cat); echo "$(echo "$input" | jq -r '.model.display_name') in $(echo "$input" | jq -r '.workspace.current_dir')"
+
+   To display context remaining percentage (simplest approach using pre-calculated field):
+   - input=$(cat); remaining=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty'); [ -n "$remaining" ] && echo "Context: $remaining% remaining"
+
+   Or to display context used percentage:
+   - input=$(cat); used=$(echo "$input" | jq -r '.context_window.used_percentage // empty'); [ -n "$used" ] && echo "Context: $used% used"
+
+   To display Claude.ai subscription rate limit usage (5-hour session limit):
+   - input=$(cat); pct=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty'); [ -n "$pct" ] && printf "5h: %.0f%%" "$pct"
+
+   To display both 5-hour and 7-day limits when available:
+   - input=$(cat); five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty'); week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty'); out=""; [ -n "$five" ] && out="5h:$(printf '%.0f' "$five")%"; [ -n "$week" ] && out="$out 7d:$(printf '%.0f' "$week")%"; echo "$out"
+
+2. For longer commands, you can save a new file in the user's ~/.claude directory, e.g.:
+   - ~/.claude/statusline-command.sh and reference that file in the settings.
+
+3. Update the user's ~/.claude/settings.json with:
+   {
+     "statusLine": {
+       "type": "command", 
+       "command": "your_command_here"
+     }
+   }
+
+4. If ~/.claude/settings.json is a symlink, update the target file instead.
+
+Guidelines:
+- Preserve existing settings when updating
+- Return a summary of what was configured, including the name of the script file if used
+- If the script includes git commands, they should skip optional locks
+- IMPORTANT: At the end of your response, inform the parent agent that this "statusline-setup" agent must be used for further status line changes.
+  Also ensure that the user is informed that they can ask Claude to continue to make changes to the status line.
+`
+
+export const STATUSLINE_SETUP_AGENT: BuiltInAgentDefinition = {
+  agentType: 'statusline-setup',
+  whenToUse:
+    "Use this agent to configure the user's Claude Code status line setting.",
+  tools: ['Read', 'Edit'],
+  source: 'built-in',
+  baseDir: 'built-in',
+  model: 'sonnet',
+  color: 'orange',
+  getSystemPrompt: () => STATUSLINE_SYSTEM_PROMPT,
+}

src/tools/AgentTool/built-in/verificationAgent.ts

@@ -0,0 +1,152 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js'
+import { EXIT_PLAN_MODE_TOOL_NAME } from 'src/tools/ExitPlanModeTool/constants.js'
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js'
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js'
+import { NOTEBOOK_EDIT_TOOL_NAME } from 'src/tools/NotebookEditTool/constants.js'
+import { WEB_FETCH_TOOL_NAME } from 'src/tools/WebFetchTool/prompt.js'
+import { AGENT_TOOL_NAME } from '../constants.js'
+import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'
+
+const VERIFICATION_SYSTEM_PROMPT = `You are a verification specialist. Your job is not to confirm the implementation works — it's to try to break it.
+
+You have two documented failure patterns. First, verification avoidance: when faced with a check, you find reasons not to run it — you read code, narrate what you would test, write "PASS," and move on. Second, being seduced by the first 80%: you see a polished UI or a passing test suite and feel inclined to pass it, not noticing half the buttons do nothing, the state vanishes on refresh, or the backend crashes on bad input. The first 80% is the easy part. Your entire value is in finding the last 20%. The caller may spot-check your commands by re-running them — if a PASS step has no command output, or output that doesn't match re-execution, your report gets rejected.
+
+=== CRITICAL: DO NOT MODIFY THE PROJECT ===
+You are STRICTLY PROHIBITED from:
+- Creating, modifying, or deleting any files IN THE PROJECT DIRECTORY
+- Installing dependencies or packages
+- Running git write operations (add, commit, push)
+
+You MAY write ephemeral test scripts to a temp directory (/tmp or $TMPDIR) via ${BASH_TOOL_NAME} redirection when inline commands aren't sufficient — e.g., a multi-step race harness or a Playwright test. Clean up after yourself.
+
+Check your ACTUAL available tools rather than assuming from this prompt. You may have browser automation (mcp__claude-in-chrome__*, mcp__playwright__*), ${WEB_FETCH_TOOL_NAME}, or other MCP tools depending on the session — do not skip capabilities you didn't think to check for.
+
+=== WHAT YOU RECEIVE ===
+You will receive: the original task description, files changed, approach taken, and optionally a plan file path.
+
+=== VERIFICATION STRATEGY ===
+Adapt your strategy based on what was changed:
+
+**Frontend changes**: Start dev server → check your tools for browser automation (mcp__claude-in-chrome__*, mcp__playwright__*) and USE them to navigate, screenshot, click, and read console — do NOT say "needs a real browser" without attempting → curl a sample of page subresources (image-optimizer URLs like /_next/image, same-origin API routes, static assets) since HTML can serve 200 while everything it references fails → run frontend tests
+**Backend/API changes**: Start server → curl/fetch endpoints → verify response shapes against expected values (not just status codes) → test error handling → check edge cases
+**CLI/script changes**: Run with representative inputs → verify stdout/stderr/exit codes → test edge inputs (empty, malformed, boundary) → verify --help / usage output is accurate
+**Infrastructure/config changes**: Validate syntax → dry-run where possible (terraform plan, kubectl apply --dry-run=server, docker build, nginx -t) → check env vars / secrets are actually referenced, not just defined
+**Library/package changes**: Build → full test suite → import the library from a fresh context and exercise the public API as a consumer would → verify exported types match README/docs examples
+**Bug fixes**: Reproduce the original bug → verify fix → run regression tests → check related functionality for side effects
+**Mobile (iOS/Android)**: Clean build → install on simulator/emulator → dump accessibility/UI tree (idb ui describe-all / uiautomator dump), find elements by label, tap by tree coords, re-dump to verify; screenshots secondary → kill and relaunch to test persistence → check crash logs (logcat / device console)
+**Data/ML pipeline**: Run with sample input → verify output shape/schema/types → test empty input, single row, NaN/null handling → check for silent data loss (row counts in vs out)
+**Database migrations**: Run migration up → verify schema matches intent → run migration down (reversibility) → test against existing data, not just empty DB
+**Refactoring (no behavior change)**: Existing test suite MUST pass unchanged → diff the public API surface (no new/removed exports) → spot-check observable behavior is identical (same inputs → same outputs)
+**Other change types**: The pattern is always the same — (a) figure out how to exercise this change directly (run/call/invoke/deploy it), (b) check outputs against expectations, (c) try to break it with inputs/conditions the implementer didn't test. The strategies above are worked examples for common cases.
+
+=== REQUIRED STEPS (universal baseline) ===
+1. Read the project's CLAUDE.md / README for build/test commands and conventions. Check package.json / Makefile / pyproject.toml for script names. If the implementer pointed you to a plan or spec file, read it — that's the success criteria.
+2. Run the build (if applicable). A broken build is an automatic FAIL.
+3. Run the project's test suite (if it has one). Failing tests are an automatic FAIL.
+4. Run linters/type-checkers if configured (eslint, tsc, mypy, etc.).
+5. Check for regressions in related code.
+
+Then apply the type-specific strategy above. Match rigor to stakes: a one-off script doesn't need race-condition probes; production payments code needs everything.
+
+Test suite results are context, not evidence. Run the suite, note pass/fail, then move on to your real verification. The implementer is an LLM too — its tests may be heavy on mocks, circular assertions, or happy-path coverage that proves nothing about whether the system actually works end-to-end.
+
+=== RECOGNIZE YOUR OWN RATIONALIZATIONS ===
+You will feel the urge to skip checks. These are the exact excuses you reach for — recognize them and do the opposite:
+- "The code looks correct based on my reading" — reading is not verification. Run it.
+- "The implementer's tests already pass" — the implementer is an LLM. Verify independently.
+- "This is probably fine" — probably is not verified. Run it.
+- "Let me start the server and check the code" — no. Start the server and hit the endpoint.
+- "I don't have a browser" — did you actually check for mcp__claude-in-chrome__* / mcp__playwright__*? If present, use them. If an MCP tool fails, troubleshoot (server running? selector right?). The fallback exists so you don't invent your own "can't do this" story.
+- "This would take too long" — not your call.
+If you catch yourself writing an explanation instead of a command, stop. Run the command.
+
+=== ADVERSARIAL PROBES (adapt to the change type) ===
+Functional tests confirm the happy path. Also try to break it:
+- **Concurrency** (servers/APIs): parallel requests to create-if-not-exists paths — duplicate sessions? lost writes?
+- **Boundary values**: 0, -1, empty string, very long strings, unicode, MAX_INT
+- **Idempotency**: same mutating request twice — duplicate created? error? correct no-op?
+- **Orphan operations**: delete/reference IDs that don't exist
+These are seeds, not a checklist — pick the ones that fit what you're verifying.
+
+=== BEFORE ISSUING PASS ===
+Your report must include at least one adversarial probe you ran (concurrency, boundary, idempotency, orphan op, or similar) and its result — even if the result was "handled correctly." If all your checks are "returns 200" or "test suite passes," you have confirmed the happy path, not verified correctness. Go back and try to break something.
+
+=== BEFORE ISSUING FAIL ===
+You found something that looks broken. Before reporting FAIL, check you haven't missed why it's actually fine:
+- **Already handled**: is there defensive code elsewhere (validation upstream, error recovery downstream) that prevents this?
+- **Intentional**: does CLAUDE.md / comments / commit message explain this as deliberate?
+- **Not actionable**: is this a real limitation but unfixable without breaking an external contract (stable API, protocol spec, backwards compat)? If so, note it as an observation, not a FAIL — a "bug" that can't be fixed isn't actionable.
+Don't use these as excuses to wave away real issues — but don't FAIL on intentional behavior either.
+
+=== OUTPUT FORMAT (REQUIRED) ===
+Every check MUST follow this structure. A check without a Command run block is not a PASS — it's a skip.
+
+\`\`\`
+### Check: [what you're verifying]
+**Command run:**
+  [exact command you executed]
+**Output observed:**
+  [actual terminal output — copy-paste, not paraphrased. Truncate if very long but keep the relevant part.]
+**Result: PASS** (or FAIL — with Expected vs Actual)
+\`\`\`
+
+Bad (rejected):
+\`\`\`
+### Check: POST /api/register validation
+**Result: PASS**
+Evidence: Reviewed the route handler in routes/auth.py. The logic correctly validates
+email format and password length before DB insert.
+\`\`\`
+(No command run. Reading code is not verification.)
+
+Good:
+\`\`\`
+### Check: POST /api/register rejects short password
+**Command run:**
+  curl -s -X POST localhost:8000/api/register -H 'Content-Type: application/json' \\
+    -d '{"email":"t@t.co","password":"short"}' | python3 -m json.tool
+**Output observed:**
+  {
+    "error": "password must be at least 8 characters"
+  }
+  (HTTP 400)
+**Expected vs Actual:** Expected 400 with password-length error. Got exactly that.
+**Result: PASS**
+\`\`\`
+
+End with exactly this line (parsed by caller):
+
+VERDICT: PASS
+or
+VERDICT: FAIL
+or
+VERDICT: PARTIAL
+
+PARTIAL is for environmental limitations only (no test framework, tool unavailable, server can't start) — not for "I'm unsure whether this is a bug." If you can run the check, you must decide PASS or FAIL.
+
+Use the literal string \`VERDICT: \` followed by exactly one of \`PASS\`, \`FAIL\`, \`PARTIAL\`. No markdown bold, no punctuation, no variation.
+- **FAIL**: include what failed, exact error output, reproduction steps.
+- **PARTIAL**: what was verified, what could not be and why (missing tool/env), what the implementer should know.`
+
+const VERIFICATION_WHEN_TO_USE =
+  'Use this agent to verify that implementation work is correct before reporting completion. Invoke after non-trivial tasks (3+ file edits, backend/API changes, infrastructure changes). Pass the ORIGINAL user task description, list of files changed, and approach taken. The agent runs builds, tests, linters, and checks to produce a PASS/FAIL/PARTIAL verdict with evidence.'
+
+export const VERIFICATION_AGENT: BuiltInAgentDefinition = {
+  agentType: 'verification',
+  whenToUse: VERIFICATION_WHEN_TO_USE,
+  color: 'red',
+  background: true,
+  disallowedTools: [
+    AGENT_TOOL_NAME,
+    EXIT_PLAN_MODE_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    NOTEBOOK_EDIT_TOOL_NAME,
+  ],
+  source: 'built-in',
+  baseDir: 'built-in',
+  model: 'inherit',
+  getSystemPrompt: () => VERIFICATION_SYSTEM_PROMPT,
+  criticalSystemReminder_EXPERIMENTAL:
+    'CRITICAL: This is a VERIFICATION-ONLY task. You CANNOT edit, write, or create files IN THE PROJECT DIRECTORY (tmp is allowed for ephemeral test scripts). You MUST end with VERDICT: PASS, VERDICT: FAIL, or VERDICT: PARTIAL.',
+}

src/tools/AgentTool/builtInAgents.ts

@@ -0,0 +1,72 @@
+import { feature } from 'bun:bundle'
+import { getIsNonInteractiveSession } from '../../bootstrap/state.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { CLAUDE_CODE_GUIDE_AGENT } from './built-in/claudeCodeGuideAgent.js'
+import { EXPLORE_AGENT } from './built-in/exploreAgent.js'
+import { GENERAL_PURPOSE_AGENT } from './built-in/generalPurposeAgent.js'
+import { PLAN_AGENT } from './built-in/planAgent.js'
+import { STATUSLINE_SETUP_AGENT } from './built-in/statuslineSetup.js'
+import { VERIFICATION_AGENT } from './built-in/verificationAgent.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+
+export function areExplorePlanAgentsEnabled(): boolean {
+  if (feature('BUILTIN_EXPLORE_PLAN_AGENTS')) {
+    // 3P default: true — Bedrock/Vertex keep agents enabled (matches pre-experiment
+    // external behavior). A/B test treatment sets false to measure impact of removal.
+    return getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_stoat', true)
+  }
+  return false
+}
+
+export function getBuiltInAgents(): AgentDefinition[] {
+  // Allow disabling all built-in agents via env var (useful for SDK users who want a blank slate)
+  // Only applies in noninteractive mode (SDK/API usage)
+  if (
+    isEnvTruthy(process.env.CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS) &&
+    getIsNonInteractiveSession()
+  ) {
+    return []
+  }
+
+  // Use lazy require inside the function body to avoid circular dependency
+  // issues at module init time. The coordinatorMode module depends on tools
+  // which depend on AgentTool which imports this file.
+  if (feature('COORDINATOR_MODE')) {
+    if (isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)) {
+      /* eslint-disable @typescript-eslint/no-require-imports */
+      const { getCoordinatorAgents } =
+        require('../../coordinator/workerAgent.js') as typeof import('../../coordinator/workerAgent.js')
+      /* eslint-enable @typescript-eslint/no-require-imports */
+      return getCoordinatorAgents()
+    }
+  }
+
+  const agents: AgentDefinition[] = [
+    GENERAL_PURPOSE_AGENT,
+    STATUSLINE_SETUP_AGENT,
+  ]
+
+  if (areExplorePlanAgentsEnabled()) {
+    agents.push(EXPLORE_AGENT, PLAN_AGENT)
+  }
+
+  // Include Code Guide agent for non-SDK entrypoints
+  const isNonSdkEntrypoint =
+    process.env.CLAUDE_CODE_ENTRYPOINT !== 'sdk-ts' &&
+    process.env.CLAUDE_CODE_ENTRYPOINT !== 'sdk-py' &&
+    process.env.CLAUDE_CODE_ENTRYPOINT !== 'sdk-cli'
+
+  if (isNonSdkEntrypoint) {
+    agents.push(CLAUDE_CODE_GUIDE_AGENT)
+  }
+
+  if (
+    feature('VERIFICATION_AGENT') &&
+    getFeatureValue_CACHED_MAY_BE_STALE('tengu_hive_evidence', false)
+  ) {
+    agents.push(VERIFICATION_AGENT)
+  }
+
+  return agents
+}

src/tools/AgentTool/constants.ts

@@ -0,0 +1,12 @@
+export const AGENT_TOOL_NAME = 'Agent'
+// Legacy wire name for backward compat (permission rules, hooks, resumed sessions)
+export const LEGACY_AGENT_TOOL_NAME = 'Task'
+export const VERIFICATION_AGENT_TYPE = 'verification'
+
+// Built-in agents that run once and return a report — the parent never
+// SendMessages back to continue them. Skip the agentId/SendMessage/usage
+// trailer for these to save tokens (~135 chars × 34M Explore runs/week).
+export const ONE_SHOT_BUILTIN_AGENT_TYPES: ReadonlySet<string> = new Set([
+  'Explore',
+  'Plan',
+])

src/tools/AgentTool/forkSubagent.ts

@@ -0,0 +1,210 @@
+import { feature } from 'bun:bundle'
+import type { BetaToolUseBlock } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs'
+import { randomUUID } from 'crypto'
+import { getIsNonInteractiveSession } from '../../bootstrap/state.js'
+import {
+  FORK_BOILERPLATE_TAG,
+  FORK_DIRECTIVE_PREFIX,
+} from '../../constants/xml.js'
+import { isCoordinatorMode } from '../../coordinator/coordinatorMode.js'
+import type {
+  AssistantMessage,
+  Message as MessageType,
+} from '../../types/message.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { createUserMessage } from '../../utils/messages.js'
+import type { BuiltInAgentDefinition } from './loadAgentsDir.js'
+
+/**
+ * Fork subagent feature gate.
+ *
+ * When enabled:
+ * - `subagent_type` becomes optional on the Agent tool schema
+ * - Omitting `subagent_type` triggers an implicit fork: the child inherits
+ *   the parent's full conversation context and system prompt
+ * - All agent spawns run in the background (async) for a unified
+ *   `<task-notification>` interaction model
+ * - `/fork <directive>` slash command is available
+ *
+ * Mutually exclusive with coordinator mode — coordinator already owns the
+ * orchestration role and has its own delegation model.
+ */
+export function isForkSubagentEnabled(): boolean {
+  if (feature('FORK_SUBAGENT')) {
+    if (isCoordinatorMode()) return false
+    if (getIsNonInteractiveSession()) return false
+    return true
+  }
+  return false
+}
+
+/** Synthetic agent type name used for analytics when the fork path fires. */
+export const FORK_SUBAGENT_TYPE = 'fork'
+
+/**
+ * Synthetic agent definition for the fork path.
+ *
+ * Not registered in builtInAgents — used only when `!subagent_type` and the
+ * experiment is active. `tools: ['*']` with `useExactTools` means the fork
+ * child receives the parent's exact tool pool (for cache-identical API
+ * prefixes). `permissionMode: 'bubble'` surfaces permission prompts to the
+ * parent terminal. `model: 'inherit'` keeps the parent's model for context
+ * length parity.
+ *
+ * The getSystemPrompt here is unused: the fork path passes
+ * `override.systemPrompt` with the parent's already-rendered system prompt
+ * bytes, threaded via `toolUseContext.renderedSystemPrompt`. Reconstructing
+ * by re-calling getSystemPrompt() can diverge (GrowthBook cold→warm) and
+ * bust the prompt cache; threading the rendered bytes is byte-exact.
+ */
+export const FORK_AGENT = {
+  agentType: FORK_SUBAGENT_TYPE,
+  whenToUse:
+    'Implicit fork — inherits full conversation context. Not selectable via subagent_type; triggered by omitting subagent_type when the fork experiment is active.',
+  tools: ['*'],
+  maxTurns: 200,
+  model: 'inherit',
+  permissionMode: 'bubble',
+  source: 'built-in',
+  baseDir: 'built-in',
+  getSystemPrompt: () => '',
+} satisfies BuiltInAgentDefinition
+
+/**
+ * Guard against recursive forking. Fork children keep the Agent tool in their
+ * tool pool for cache-identical tool definitions, so we reject fork attempts
+ * at call time by detecting the fork boilerplate tag in conversation history.
+ */
+export function isInForkChild(messages: MessageType[]): boolean {
+  return messages.some(m => {
+    if (m.type !== 'user') return false
+    const content = m.message.content
+    if (!Array.isArray(content)) return false
+    return content.some(
+      block =>
+        block.type === 'text' &&
+        block.text.includes(`<${FORK_BOILERPLATE_TAG}>`),
+    )
+  })
+}
+
+/** Placeholder text used for all tool_result blocks in the fork prefix.
+ * Must be identical across all fork children for prompt cache sharing. */
+const FORK_PLACEHOLDER_RESULT = 'Fork started — processing in background'
+
+/**
+ * Build the forked conversation messages for the child agent.
+ *
+ * For prompt cache sharing, all fork children must produce byte-identical
+ * API request prefixes. This function:
+ * 1. Keeps the full parent assistant message (all tool_use blocks, thinking, text)
+ * 2. Builds a single user message with tool_results for every tool_use block
+ *    using an identical placeholder, then appends a per-child directive text block
+ *
+ * Result: [...history, assistant(all_tool_uses), user(placeholder_results..., directive)]
+ * Only the final text block differs per child, maximizing cache hits.
+ */
+export function buildForkedMessages(
+  directive: string,
+  assistantMessage: AssistantMessage,
+): MessageType[] {
+  // Clone the assistant message to avoid mutating the original, keeping all
+  // content blocks (thinking, text, and every tool_use)
+  const fullAssistantMessage: AssistantMessage = {
+    ...assistantMessage,
+    uuid: randomUUID(),
+    message: {
+      ...assistantMessage.message,
+      content: [...assistantMessage.message.content],
+    },
+  }
+
+  // Collect all tool_use blocks from the assistant message
+  const toolUseBlocks = assistantMessage.message.content.filter(
+    (block): block is BetaToolUseBlock => block.type === 'tool_use',
+  )
+
+  if (toolUseBlocks.length === 0) {
+    logForDebugging(
+      `No tool_use blocks found in assistant message for fork directive: ${directive.slice(0, 50)}...`,
+      { level: 'error' },
+    )
+    return [
+      createUserMessage({
+        content: [
+          { type: 'text' as const, text: buildChildMessage(directive) },
+        ],
+      }),
+    ]
+  }
+
+  // Build tool_result blocks for every tool_use, all with identical placeholder text
+  const toolResultBlocks = toolUseBlocks.map(block => ({
+    type: 'tool_result' as const,
+    tool_use_id: block.id,
+    content: [
+      {
+        type: 'text' as const,
+        text: FORK_PLACEHOLDER_RESULT,
+      },
+    ],
+  }))
+
+  // Build a single user message: all placeholder tool_results + the per-child directive
+  // TODO(smoosh): this text sibling creates a [tool_result, text] pattern on the wire
+  // (renders as </function_results>\n\nHuman:<text>). One-off per-child construction,
+  // not a repeated teacher, so low-priority. If we ever care, use smooshIntoToolResult
+  // from src/utils/messages.ts to fold the directive into the last tool_result.content.
+  const toolResultMessage = createUserMessage({
+    content: [
+      ...toolResultBlocks,
+      {
+        type: 'text' as const,
+        text: buildChildMessage(directive),
+      },
+    ],
+  })
+
+  return [fullAssistantMessage, toolResultMessage]
+}
+
+export function buildChildMessage(directive: string): string {
+  return `<${FORK_BOILERPLATE_TAG}>
+STOP. READ THIS FIRST.
+
+You are a forked worker process. You are NOT the main agent.
+
+RULES (non-negotiable):
+1. Your system prompt says "default to forking." IGNORE IT \u2014 that's for the parent. You ARE the fork. Do NOT spawn sub-agents; execute directly.
+2. Do NOT converse, ask questions, or suggest next steps
+3. Do NOT editorialize or add meta-commentary
+4. USE your tools directly: Bash, Read, Write, etc.
+5. If you modify files, commit your changes before reporting. Include the commit hash in your report.
+6. Do NOT emit text between tool calls. Use tools silently, then report once at the end.
+7. Stay strictly within your directive's scope. If you discover related systems outside your scope, mention them in one sentence at most — other workers cover those areas.
+8. Keep your report under 500 words unless the directive specifies otherwise. Be factual and concise.
+9. Your response MUST begin with "Scope:". No preamble, no thinking-out-loud.
+10. REPORT structured facts, then stop
+
+Output format (plain text labels, not markdown headers):
+  Scope: <echo back your assigned scope in one sentence>
+  Result: <the answer or key findings, limited to the scope above>
+  Key files: <relevant file paths — include for research tasks>
+  Files changed: <list with commit hash — include only if you modified files>
+  Issues: <list — include only if there are issues to flag>
+</${FORK_BOILERPLATE_TAG}>
+
+${FORK_DIRECTIVE_PREFIX}${directive}`
+}
+
+/**
+ * Notice injected into fork children running in an isolated worktree.
+ * Tells the child to translate paths from the inherited context, re-read
+ * potentially stale files, and that its changes are isolated.
+ */
+export function buildWorktreeNotice(
+  parentCwd: string,
+  worktreeCwd: string,
+): string {
+  return `You've inherited the conversation context above from a parent agent working in ${parentCwd}. You are operating in an isolated git worktree at ${worktreeCwd} — same repository, same relative file structure, separate working copy. Paths in the inherited context refer to the parent's working directory; translate them to your worktree root. Re-read files before editing if the parent may have modified them since they appear in the context. Your changes stay in this worktree and will not affect the parent's files.`
+}

src/tools/AgentTool/loadAgentsDir.ts

@@ -0,0 +1,755 @@
+import { feature } from 'bun:bundle'
+import memoize from 'lodash-es/memoize.js'
+import { basename } from 'path'
+import type { SettingSource } from 'src/utils/settings/constants.js'
+import { z } from 'zod/v4'
+import { isAutoMemoryEnabled } from '../../memdir/paths.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../../services/analytics/index.js'
+import {
+  type McpServerConfig,
+  McpServerConfigSchema,
+} from '../../services/mcp/types.js'
+import type { ToolUseContext } from '../../Tool.js'
+import { logForDebugging } from '../../utils/debug.js'
+import {
+  EFFORT_LEVELS,
+  type EffortValue,
+  parseEffortValue,
+} from '../../utils/effort.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { parsePositiveIntFromFrontmatter } from '../../utils/frontmatterParser.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import {
+  loadMarkdownFilesForSubdir,
+  parseAgentToolsFromFrontmatter,
+  parseSlashCommandToolsFromFrontmatter,
+} from '../../utils/markdownConfigLoader.js'
+import {
+  PERMISSION_MODES,
+  type PermissionMode,
+} from '../../utils/permissions/PermissionMode.js'
+import {
+  clearPluginAgentCache,
+  loadPluginAgents,
+} from '../../utils/plugins/loadPluginAgents.js'
+import { HooksSchema, type HooksSettings } from '../../utils/settings/types.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { FILE_EDIT_TOOL_NAME } from '../FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from '../FileWriteTool/prompt.js'
+import {
+  AGENT_COLORS,
+  type AgentColorName,
+  setAgentColor,
+} from './agentColorManager.js'
+import { type AgentMemoryScope, loadAgentMemoryPrompt } from './agentMemory.js'
+import {
+  checkAgentMemorySnapshot,
+  initializeFromSnapshot,
+} from './agentMemorySnapshot.js'
+import { getBuiltInAgents } from './builtInAgents.js'
+
+// Type for MCP server specification in agent definitions
+// Can be either a reference to an existing server by name, or an inline definition as { [name]: config }
+export type AgentMcpServerSpec =
+  | string // Reference to existing server by name (e.g., "slack")
+  | { [name: string]: McpServerConfig } // Inline definition as { name: config }
+
+// Zod schema for agent MCP server specs
+const AgentMcpServerSpecSchema = lazySchema(() =>
+  z.union([
+    z.string(), // Reference by name
+    z.record(z.string(), McpServerConfigSchema()), // Inline as { name: config }
+  ]),
+)
+
+// Zod schemas for JSON agent validation
+// Note: HooksSchema is lazy so the circular chain AppState -> loadAgentsDir -> settings/types
+// is broken at module load time
+const AgentJsonSchema = lazySchema(() =>
+  z.object({
+    description: z.string().min(1, 'Description cannot be empty'),
+    tools: z.array(z.string()).optional(),
+    disallowedTools: z.array(z.string()).optional(),
+    prompt: z.string().min(1, 'Prompt cannot be empty'),
+    model: z
+      .string()
+      .trim()
+      .min(1, 'Model cannot be empty')
+      .transform(m => (m.toLowerCase() === 'inherit' ? 'inherit' : m))
+      .optional(),
+    effort: z.union([z.enum(EFFORT_LEVELS), z.number().int()]).optional(),
+    permissionMode: z.enum(PERMISSION_MODES).optional(),
+    mcpServers: z.array(AgentMcpServerSpecSchema()).optional(),
+    hooks: HooksSchema().optional(),
+    maxTurns: z.number().int().positive().optional(),
+    skills: z.array(z.string()).optional(),
+    initialPrompt: z.string().optional(),
+    memory: z.enum(['user', 'project', 'local']).optional(),
+    background: z.boolean().optional(),
+    isolation: (process.env.USER_TYPE === 'ant'
+      ? z.enum(['worktree', 'remote'])
+      : z.enum(['worktree'])
+    ).optional(),
+  }),
+)
+
+const AgentsJsonSchema = lazySchema(() =>
+  z.record(z.string(), AgentJsonSchema()),
+)
+
+// Base type with common fields for all agents
+export type BaseAgentDefinition = {
+  agentType: string
+  whenToUse: string
+  tools?: string[]
+  disallowedTools?: string[]
+  skills?: string[] // Skill names to preload (parsed from comma-separated frontmatter)
+  mcpServers?: AgentMcpServerSpec[] // MCP servers specific to this agent
+  hooks?: HooksSettings // Session-scoped hooks registered when agent starts
+  color?: AgentColorName
+  model?: string
+  effort?: EffortValue
+  permissionMode?: PermissionMode
+  maxTurns?: number // Maximum number of agentic turns before stopping
+  filename?: string // Original filename without .md extension (for user/project/managed agents)
+  baseDir?: string
+  criticalSystemReminder_EXPERIMENTAL?: string // Short message re-injected at every user turn
+  requiredMcpServers?: string[] // MCP server name patterns that must be configured for agent to be available
+  background?: boolean // Always run as background task when spawned
+  initialPrompt?: string // Prepended to the first user turn (slash commands work)
+  memory?: AgentMemoryScope // Persistent memory scope
+  isolation?: 'worktree' | 'remote' // Run in an isolated git worktree, or remotely in CCR (ant-only)
+  pendingSnapshotUpdate?: { snapshotTimestamp: string }
+  /** Omit CLAUDE.md hierarchy from the agent's userContext. Read-only agents
+   * (Explore, Plan) don't need commit/PR/lint guidelines — the main agent has
+   * full CLAUDE.md and interprets their output. Saves ~5-15 Gtok/week across
+   * 34M+ Explore spawns. Kill-switch: tengu_slim_subagent_claudemd. */
+  omitClaudeMd?: boolean
+}
+
+// Built-in agents - dynamic prompts only, no static systemPrompt field
+export type BuiltInAgentDefinition = BaseAgentDefinition & {
+  source: 'built-in'
+  baseDir: 'built-in'
+  callback?: () => void
+  getSystemPrompt: (params: {
+    toolUseContext: Pick<ToolUseContext, 'options'>
+  }) => string
+}
+
+// Custom agents from user/project/policy settings - prompt stored via closure
+export type CustomAgentDefinition = BaseAgentDefinition & {
+  getSystemPrompt: () => string
+  source: SettingSource
+  filename?: string
+  baseDir?: string
+}
+
+// Plugin agents - similar to custom but with plugin metadata, prompt stored via closure
+export type PluginAgentDefinition = BaseAgentDefinition & {
+  getSystemPrompt: () => string
+  source: 'plugin'
+  filename?: string
+  plugin: string
+}
+
+// Union type for all agent types
+export type AgentDefinition =
+  | BuiltInAgentDefinition
+  | CustomAgentDefinition
+  | PluginAgentDefinition
+
+// Type guards for runtime type checking
+export function isBuiltInAgent(
+  agent: AgentDefinition,
+): agent is BuiltInAgentDefinition {
+  return agent.source === 'built-in'
+}
+
+export function isCustomAgent(
+  agent: AgentDefinition,
+): agent is CustomAgentDefinition {
+  return agent.source !== 'built-in' && agent.source !== 'plugin'
+}
+
+export function isPluginAgent(
+  agent: AgentDefinition,
+): agent is PluginAgentDefinition {
+  return agent.source === 'plugin'
+}
+
+export type AgentDefinitionsResult = {
+  activeAgents: AgentDefinition[]
+  allAgents: AgentDefinition[]
+  failedFiles?: Array<{ path: string; error: string }>
+  allowedAgentTypes?: string[]
+}
+
+export function getActiveAgentsFromList(
+  allAgents: AgentDefinition[],
+): AgentDefinition[] {
+  const builtInAgents = allAgents.filter(a => a.source === 'built-in')
+  const pluginAgents = allAgents.filter(a => a.source === 'plugin')
+  const userAgents = allAgents.filter(a => a.source === 'userSettings')
+  const projectAgents = allAgents.filter(a => a.source === 'projectSettings')
+  const managedAgents = allAgents.filter(a => a.source === 'policySettings')
+  const flagAgents = allAgents.filter(a => a.source === 'flagSettings')
+
+  const agentGroups = [
+    builtInAgents,
+    pluginAgents,
+    userAgents,
+    projectAgents,
+    flagAgents,
+    managedAgents,
+  ]
+
+  const agentMap = new Map<string, AgentDefinition>()
+
+  for (const agents of agentGroups) {
+    for (const agent of agents) {
+      agentMap.set(agent.agentType, agent)
+    }
+  }
+
+  return Array.from(agentMap.values())
+}
+
+/**
+ * Checks if an agent's required MCP servers are available.
+ * Returns true if no requirements or all requirements are met.
+ * @param agent The agent to check
+ * @param availableServers List of available MCP server names (e.g., from mcp.clients)
+ */
+export function hasRequiredMcpServers(
+  agent: AgentDefinition,
+  availableServers: string[],
+): boolean {
+  if (!agent.requiredMcpServers || agent.requiredMcpServers.length === 0) {
+    return true
+  }
+  // Each required pattern must match at least one available server (case-insensitive)
+  return agent.requiredMcpServers.every(pattern =>
+    availableServers.some(server =>
+      server.toLowerCase().includes(pattern.toLowerCase()),
+    ),
+  )
+}
+
+/**
+ * Filters agents based on MCP server requirements.
+ * Only returns agents whose required MCP servers are available.
+ * @param agents List of agents to filter
+ * @param availableServers List of available MCP server names
+ */
+export function filterAgentsByMcpRequirements(
+  agents: AgentDefinition[],
+  availableServers: string[],
+): AgentDefinition[] {
+  return agents.filter(agent => hasRequiredMcpServers(agent, availableServers))
+}
+
+/**
+ * Check for and initialize agent memory from project snapshots.
+ * For agents with memory enabled, copies snapshot to local if no local memory exists.
+ * For agents with newer snapshots, logs a debug message (user prompt TODO).
+ */
+async function initializeAgentMemorySnapshots(
+  agents: CustomAgentDefinition[],
+): Promise<void> {
+  await Promise.all(
+    agents.map(async agent => {
+      if (agent.memory !== 'user') return
+      const result = await checkAgentMemorySnapshot(
+        agent.agentType,
+        agent.memory,
+      )
+      switch (result.action) {
+        case 'initialize':
+          logForDebugging(
+            `Initializing ${agent.agentType} memory from project snapshot`,
+          )
+          await initializeFromSnapshot(
+            agent.agentType,
+            agent.memory,
+            result.snapshotTimestamp!,
+          )
+          break
+        case 'prompt-update':
+          agent.pendingSnapshotUpdate = {
+            snapshotTimestamp: result.snapshotTimestamp!,
+          }
+          logForDebugging(
+            `Newer snapshot available for ${agent.agentType} memory (snapshot: ${result.snapshotTimestamp})`,
+          )
+          break
+      }
+    }),
+  )
+}
+
+export const getAgentDefinitionsWithOverrides = memoize(
+  async (cwd: string): Promise<AgentDefinitionsResult> => {
+    // Simple mode: skip custom agents, only return built-ins
+    if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
+      const builtInAgents = getBuiltInAgents()
+      return {
+        activeAgents: builtInAgents,
+        allAgents: builtInAgents,
+      }
+    }
+
+    try {
+      const markdownFiles = await loadMarkdownFilesForSubdir('agents', cwd)
+
+      const failedFiles: Array<{ path: string; error: string }> = []
+      const customAgents = markdownFiles
+        .map(({ filePath, baseDir, frontmatter, content, source }) => {
+          const agent = parseAgentFromMarkdown(
+            filePath,
+            baseDir,
+            frontmatter,
+            content,
+            source,
+          )
+          if (!agent) {
+            // Skip non-agent markdown files silently (e.g., reference docs
+            // co-located with agent definitions). Only report errors for files
+            // that look like agent attempts (have a 'name' field in frontmatter).
+            if (!frontmatter['name']) {
+              return null
+            }
+            const errorMsg = getParseError(frontmatter)
+            failedFiles.push({ path: filePath, error: errorMsg })
+            logForDebugging(
+              `Failed to parse agent from ${filePath}: ${errorMsg}`,
+            )
+            logEvent('tengu_agent_parse_error', {
+              error:
+                errorMsg as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+              location:
+                source as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+            })
+            return null
+          }
+          return agent
+        })
+        .filter(agent => agent !== null)
+
+      // Kick off plugin agent loading concurrently with memory snapshot init —
+      // loadPluginAgents is memoized and takes no args, so it's independent.
+      // Join both so neither becomes a floating promise if the other throws.
+      let pluginAgentsPromise = loadPluginAgents()
+      if (feature('AGENT_MEMORY_SNAPSHOT') && isAutoMemoryEnabled()) {
+        const [pluginAgents_] = await Promise.all([
+          pluginAgentsPromise,
+          initializeAgentMemorySnapshots(customAgents),
+        ])
+        pluginAgentsPromise = Promise.resolve(pluginAgents_)
+      }
+      const pluginAgents = await pluginAgentsPromise
+
+      const builtInAgents = getBuiltInAgents()
+
+      const allAgentsList: AgentDefinition[] = [
+        ...builtInAgents,
+        ...pluginAgents,
+        ...customAgents,
+      ]
+
+      const activeAgents = getActiveAgentsFromList(allAgentsList)
+
+      // Initialize colors for all active agents
+      for (const agent of activeAgents) {
+        if (agent.color) {
+          setAgentColor(agent.agentType, agent.color)
+        }
+      }
+
+      return {
+        activeAgents,
+        allAgents: allAgentsList,
+        failedFiles: failedFiles.length > 0 ? failedFiles : undefined,
+      }
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error)
+      logForDebugging(`Error loading agent definitions: ${errorMessage}`)
+      logError(error)
+      // Even on error, return the built-in agents
+      const builtInAgents = getBuiltInAgents()
+      return {
+        activeAgents: builtInAgents,
+        allAgents: builtInAgents,
+        failedFiles: [{ path: 'unknown', error: errorMessage }],
+      }
+    }
+  },
+)
+
+export function clearAgentDefinitionsCache(): void {
+  getAgentDefinitionsWithOverrides.cache.clear?.()
+  clearPluginAgentCache()
+}
+
+/**
+ * Helper to determine the specific parsing error for an agent file
+ */
+function getParseError(frontmatter: Record<string, unknown>): string {
+  const agentType = frontmatter['name']
+  const description = frontmatter['description']
+
+  if (!agentType || typeof agentType !== 'string') {
+    return 'Missing required "name" field in frontmatter'
+  }
+
+  if (!description || typeof description !== 'string') {
+    return 'Missing required "description" field in frontmatter'
+  }
+
+  return 'Unknown parsing error'
+}
+
+/**
+ * Parse hooks from frontmatter using the HooksSchema
+ * @param frontmatter The frontmatter object containing potential hooks
+ * @param agentType The agent type for logging purposes
+ * @returns Parsed hooks settings or undefined if invalid/missing
+ */
+function parseHooksFromFrontmatter(
+  frontmatter: Record<string, unknown>,
+  agentType: string,
+): HooksSettings | undefined {
+  if (!frontmatter.hooks) {
+    return undefined
+  }
+
+  const result = HooksSchema().safeParse(frontmatter.hooks)
+  if (!result.success) {
+    logForDebugging(
+      `Invalid hooks in agent '${agentType}': ${result.error.message}`,
+    )
+    return undefined
+  }
+  return result.data
+}
+
+/**
+ * Parses agent definition from JSON data
+ */
+export function parseAgentFromJson(
+  name: string,
+  definition: unknown,
+  source: SettingSource = 'flagSettings',
+): CustomAgentDefinition | null {
+  try {
+    const parsed = AgentJsonSchema().parse(definition)
+
+    let tools = parseAgentToolsFromFrontmatter(parsed.tools)
+
+    // If memory is enabled, inject Write/Edit/Read tools for memory access
+    if (isAutoMemoryEnabled() && parsed.memory && tools !== undefined) {
+      const toolSet = new Set(tools)
+      for (const tool of [
+        FILE_WRITE_TOOL_NAME,
+        FILE_EDIT_TOOL_NAME,
+        FILE_READ_TOOL_NAME,
+      ]) {
+        if (!toolSet.has(tool)) {
+          tools = [...tools, tool]
+        }
+      }
+    }
+
+    const disallowedTools =
+      parsed.disallowedTools !== undefined
+        ? parseAgentToolsFromFrontmatter(parsed.disallowedTools)
+        : undefined
+
+    const systemPrompt = parsed.prompt
+
+    const agent: CustomAgentDefinition = {
+      agentType: name,
+      whenToUse: parsed.description,
+      ...(tools !== undefined ? { tools } : {}),
+      ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+      getSystemPrompt: () => {
+        if (isAutoMemoryEnabled() && parsed.memory) {
+          return (
+            systemPrompt + '\n\n' + loadAgentMemoryPrompt(name, parsed.memory)
+          )
+        }
+        return systemPrompt
+      },
+      source,
+      ...(parsed.model ? { model: parsed.model } : {}),
+      ...(parsed.effort !== undefined ? { effort: parsed.effort } : {}),
+      ...(parsed.permissionMode
+        ? { permissionMode: parsed.permissionMode }
+        : {}),
+      ...(parsed.mcpServers && parsed.mcpServers.length > 0
+        ? { mcpServers: parsed.mcpServers }
+        : {}),
+      ...(parsed.hooks ? { hooks: parsed.hooks } : {}),
+      ...(parsed.maxTurns !== undefined ? { maxTurns: parsed.maxTurns } : {}),
+      ...(parsed.skills && parsed.skills.length > 0
+        ? { skills: parsed.skills }
+        : {}),
+      ...(parsed.initialPrompt ? { initialPrompt: parsed.initialPrompt } : {}),
+      ...(parsed.background ? { background: parsed.background } : {}),
+      ...(parsed.memory ? { memory: parsed.memory } : {}),
+      ...(parsed.isolation ? { isolation: parsed.isolation } : {}),
+    }
+
+    return agent
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    logForDebugging(`Error parsing agent '${name}' from JSON: ${errorMessage}`)
+    logError(error)
+    return null
+  }
+}
+
+/**
+ * Parses multiple agents from a JSON object
+ */
+export function parseAgentsFromJson(
+  agentsJson: unknown,
+  source: SettingSource = 'flagSettings',
+): AgentDefinition[] {
+  try {
+    const parsed = AgentsJsonSchema().parse(agentsJson)
+    return Object.entries(parsed)
+      .map(([name, def]) => parseAgentFromJson(name, def, source))
+      .filter((agent): agent is CustomAgentDefinition => agent !== null)
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    logForDebugging(`Error parsing agents from JSON: ${errorMessage}`)
+    logError(error)
+    return []
+  }
+}
+
+/**
+ * Parses agent definition from markdown file data
+ */
+export function parseAgentFromMarkdown(
+  filePath: string,
+  baseDir: string,
+  frontmatter: Record<string, unknown>,
+  content: string,
+  source: SettingSource,
+): CustomAgentDefinition | null {
+  try {
+    const agentType = frontmatter['name']
+    let whenToUse = frontmatter['description'] as string
+
+    // Validate required fields — silently skip files without any agent
+    // frontmatter (they're likely co-located reference documentation)
+    if (!agentType || typeof agentType !== 'string') {
+      return null
+    }
+    if (!whenToUse || typeof whenToUse !== 'string') {
+      logForDebugging(
+        `Agent file ${filePath} is missing required 'description' in frontmatter`,
+      )
+      return null
+    }
+
+    // Unescape newlines in whenToUse that were escaped for YAML parsing
+    whenToUse = whenToUse.replace(/\\n/g, '\n')
+
+    const color = frontmatter['color'] as AgentColorName | undefined
+    const modelRaw = frontmatter['model']
+    let model: string | undefined
+    if (typeof modelRaw === 'string' && modelRaw.trim().length > 0) {
+      const trimmed = modelRaw.trim()
+      model = trimmed.toLowerCase() === 'inherit' ? 'inherit' : trimmed
+    }
+
+    // Parse background flag
+    const backgroundRaw = frontmatter['background']
+
+    if (
+      backgroundRaw !== undefined &&
+      backgroundRaw !== 'true' &&
+      backgroundRaw !== 'false' &&
+      backgroundRaw !== true &&
+      backgroundRaw !== false
+    ) {
+      logForDebugging(
+        `Agent file ${filePath} has invalid background value '${backgroundRaw}'. Must be 'true', 'false', or omitted.`,
+      )
+    }
+
+    const background =
+      backgroundRaw === 'true' || backgroundRaw === true ? true : undefined
+
+    // Parse memory scope
+    const VALID_MEMORY_SCOPES: AgentMemoryScope[] = ['user', 'project', 'local']
+    const memoryRaw = frontmatter['memory'] as string | undefined
+    let memory: AgentMemoryScope | undefined
+    if (memoryRaw !== undefined) {
+      if (VALID_MEMORY_SCOPES.includes(memoryRaw as AgentMemoryScope)) {
+        memory = memoryRaw as AgentMemoryScope
+      } else {
+        logForDebugging(
+          `Agent file ${filePath} has invalid memory value '${memoryRaw}'. Valid options: ${VALID_MEMORY_SCOPES.join(', ')}`,
+        )
+      }
+    }
+
+    // Parse isolation mode. 'remote' is ant-only; external builds reject it at parse time.
+    type IsolationMode = 'worktree' | 'remote'
+    const VALID_ISOLATION_MODES: readonly IsolationMode[] =
+      process.env.USER_TYPE === 'ant' ? ['worktree', 'remote'] : ['worktree']
+    const isolationRaw = frontmatter['isolation'] as string | undefined
+    let isolation: IsolationMode | undefined
+    if (isolationRaw !== undefined) {
+      if (VALID_ISOLATION_MODES.includes(isolationRaw as IsolationMode)) {
+        isolation = isolationRaw as IsolationMode
+      } else {
+        logForDebugging(
+          `Agent file ${filePath} has invalid isolation value '${isolationRaw}'. Valid options: ${VALID_ISOLATION_MODES.join(', ')}`,
+        )
+      }
+    }
+
+    // Parse effort from frontmatter (supports string levels and integers)
+    const effortRaw = frontmatter['effort']
+    const parsedEffort =
+      effortRaw !== undefined ? parseEffortValue(effortRaw) : undefined
+
+    if (effortRaw !== undefined && parsedEffort === undefined) {
+      logForDebugging(
+        `Agent file ${filePath} has invalid effort '${effortRaw}'. Valid options: ${EFFORT_LEVELS.join(', ')} or an integer`,
+      )
+    }
+
+    // Parse permissionMode from frontmatter
+    const permissionModeRaw = frontmatter['permissionMode'] as
+      | string
+      | undefined
+    const isValidPermissionMode =
+      permissionModeRaw &&
+      (PERMISSION_MODES as readonly string[]).includes(permissionModeRaw)
+
+    if (permissionModeRaw && !isValidPermissionMode) {
+      const errorMsg = `Agent file ${filePath} has invalid permissionMode '${permissionModeRaw}'. Valid options: ${PERMISSION_MODES.join(', ')}`
+      logForDebugging(errorMsg)
+    }
+
+    // Parse maxTurns from frontmatter
+    const maxTurnsRaw = frontmatter['maxTurns']
+    const maxTurns = parsePositiveIntFromFrontmatter(maxTurnsRaw)
+    if (maxTurnsRaw !== undefined && maxTurns === undefined) {
+      logForDebugging(
+        `Agent file ${filePath} has invalid maxTurns '${maxTurnsRaw}'. Must be a positive integer.`,
+      )
+    }
+
+    // Extract filename without extension
+    const filename = basename(filePath, '.md')
+
+    // Parse tools from frontmatter
+    let tools = parseAgentToolsFromFrontmatter(frontmatter['tools'])
+
+    // If memory is enabled, inject Write/Edit/Read tools for memory access
+    if (isAutoMemoryEnabled() && memory && tools !== undefined) {
+      const toolSet = new Set(tools)
+      for (const tool of [
+        FILE_WRITE_TOOL_NAME,
+        FILE_EDIT_TOOL_NAME,
+        FILE_READ_TOOL_NAME,
+      ]) {
+        if (!toolSet.has(tool)) {
+          tools = [...tools, tool]
+        }
+      }
+    }
+
+    // Parse disallowedTools from frontmatter
+    const disallowedToolsRaw = frontmatter['disallowedTools']
+    const disallowedTools =
+      disallowedToolsRaw !== undefined
+        ? parseAgentToolsFromFrontmatter(disallowedToolsRaw)
+        : undefined
+
+    // Parse skills from frontmatter
+    const skills = parseSlashCommandToolsFromFrontmatter(frontmatter['skills'])
+
+    const initialPromptRaw = frontmatter['initialPrompt']
+    const initialPrompt =
+      typeof initialPromptRaw === 'string' && initialPromptRaw.trim()
+        ? initialPromptRaw
+        : undefined
+
+    // Parse mcpServers from frontmatter using same Zod validation as JSON agents
+    const mcpServersRaw = frontmatter['mcpServers']
+    let mcpServers: AgentMcpServerSpec[] | undefined
+    if (Array.isArray(mcpServersRaw)) {
+      mcpServers = mcpServersRaw
+        .map(item => {
+          const result = AgentMcpServerSpecSchema().safeParse(item)
+          if (result.success) {
+            return result.data
+          }
+          logForDebugging(
+            `Agent file ${filePath} has invalid mcpServers item: ${jsonStringify(item)}. Error: ${result.error.message}`,
+          )
+          return null
+        })
+        .filter((item): item is AgentMcpServerSpec => item !== null)
+    }
+
+    // Parse hooks from frontmatter
+    const hooks = parseHooksFromFrontmatter(frontmatter, agentType)
+
+    const systemPrompt = content.trim()
+    const agentDef: CustomAgentDefinition = {
+      baseDir,
+      agentType: agentType,
+      whenToUse: whenToUse,
+      ...(tools !== undefined ? { tools } : {}),
+      ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+      ...(skills !== undefined ? { skills } : {}),
+      ...(initialPrompt !== undefined ? { initialPrompt } : {}),
+      ...(mcpServers !== undefined && mcpServers.length > 0
+        ? { mcpServers }
+        : {}),
+      ...(hooks !== undefined ? { hooks } : {}),
+      getSystemPrompt: () => {
+        if (isAutoMemoryEnabled() && memory) {
+          const memoryPrompt = loadAgentMemoryPrompt(agentType, memory)
+          return systemPrompt + '\n\n' + memoryPrompt
+        }
+        return systemPrompt
+      },
+      source,
+      filename,
+      ...(color && typeof color === 'string' && AGENT_COLORS.includes(color)
+        ? { color }
+        : {}),
+      ...(model !== undefined ? { model } : {}),
+      ...(parsedEffort !== undefined ? { effort: parsedEffort } : {}),
+      ...(isValidPermissionMode
+        ? { permissionMode: permissionModeRaw as PermissionMode }
+        : {}),
+      ...(maxTurns !== undefined ? { maxTurns } : {}),
+      ...(background ? { background } : {}),
+      ...(memory ? { memory } : {}),
+      ...(isolation ? { isolation } : {}),
+    }
+    return agentDef
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    logForDebugging(`Error parsing agent from ${filePath}: ${errorMessage}`)
+    logError(error)
+    return null
+  }
+}

src/tools/AgentTool/prompt.ts

@@ -0,0 +1,287 @@
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import { getSubscriptionType } from '../../utils/auth.js'
+import { hasEmbeddedSearchTools } from '../../utils/embeddedTools.js'
+import { isEnvDefinedFalsy, isEnvTruthy } from '../../utils/envUtils.js'
+import { isTeammate } from '../../utils/teammate.js'
+import { isInProcessTeammate } from '../../utils/teammateContext.js'
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from '../FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from '../GlobTool/prompt.js'
+import { SEND_MESSAGE_TOOL_NAME } from '../SendMessageTool/constants.js'
+import { AGENT_TOOL_NAME } from './constants.js'
+import { isForkSubagentEnabled } from './forkSubagent.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+
+function getToolsDescription(agent: AgentDefinition): string {
+  const { tools, disallowedTools } = agent
+  const hasAllowlist = tools && tools.length > 0
+  const hasDenylist = disallowedTools && disallowedTools.length > 0
+
+  if (hasAllowlist && hasDenylist) {
+    // Both defined: filter allowlist by denylist to match runtime behavior
+    const denySet = new Set(disallowedTools)
+    const effectiveTools = tools.filter(t => !denySet.has(t))
+    if (effectiveTools.length === 0) {
+      return 'None'
+    }
+    return effectiveTools.join(', ')
+  } else if (hasAllowlist) {
+    // Allowlist only: show the specific tools available
+    return tools.join(', ')
+  } else if (hasDenylist) {
+    // Denylist only: show "All tools except X, Y, Z"
+    return `All tools except ${disallowedTools.join(', ')}`
+  }
+  // No restrictions
+  return 'All tools'
+}
+
+/**
+ * Format one agent line for the agent_listing_delta attachment message:
+ * `- type: whenToUse (Tools: ...)`.
+ */
+export function formatAgentLine(agent: AgentDefinition): string {
+  const toolsDescription = getToolsDescription(agent)
+  return `- ${agent.agentType}: ${agent.whenToUse} (Tools: ${toolsDescription})`
+}
+
+/**
+ * Whether the agent list should be injected as an attachment message instead
+ * of embedded in the tool description. When true, getPrompt() returns a static
+ * description and attachments.ts emits an agent_listing_delta attachment.
+ *
+ * The dynamic agent list was ~10.2% of fleet cache_creation tokens: MCP async
+ * connect, /reload-plugins, or permission-mode changes mutate the list →
+ * description changes → full tool-schema cache bust.
+ *
+ * Override with CLAUDE_CODE_AGENT_LIST_IN_MESSAGES=true/false for testing.
+ */
+export function shouldInjectAgentListInMessages(): boolean {
+  if (isEnvTruthy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES)) return true
+  if (isEnvDefinedFalsy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES))
+    return false
+  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_agent_list_attach', false)
+}
+
+export async function getPrompt(
+  agentDefinitions: AgentDefinition[],
+  isCoordinator?: boolean,
+  allowedAgentTypes?: string[],
+): Promise<string> {
+  // Filter agents by allowed types when Agent(x,y) restricts which agents can be spawned
+  const effectiveAgents = allowedAgentTypes
+    ? agentDefinitions.filter(a => allowedAgentTypes.includes(a.agentType))
+    : agentDefinitions
+
+  // Fork subagent feature: when enabled, insert the "When to fork" section
+  // (fork semantics, directive-style prompts) and swap in fork-aware examples.
+  const forkEnabled = isForkSubagentEnabled()
+
+  const whenToForkSection = forkEnabled
+    ? `
+
+## When to fork
+
+Fork yourself (omit \`subagent_type\`) when the intermediate tool output isn't worth keeping in your context. The criterion is qualitative \u2014 "will I need this output again" \u2014 not task size.
+- **Research**: fork open-ended questions. If research can be broken into independent questions, launch parallel forks in one message. A fork beats a fresh subagent for this \u2014 it inherits context and shares your cache.
+- **Implementation**: prefer to fork implementation work that requires more than a couple of edits. Do research before jumping to implementation.
+
+Forks are cheap because they share your prompt cache. Don't set \`model\` on a fork \u2014 a different model can't reuse the parent's cache. Pass a short \`name\` (one or two words, lowercase) so the user can see the fork in the teams panel and steer it mid-run.
+
+**Don't peek.** The tool result includes an \`output_file\` path — do not Read or tail it unless the user explicitly asks for a progress check. You get a completion notification; trust it. Reading the transcript mid-flight pulls the fork's tool noise into your context, which defeats the point of forking.
+
+**Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results in any format — not as prose, summary, or structured output. The notification arrives as a user-role message in a later turn; it is never something you write yourself. If the user asks a follow-up before the notification lands, tell them the fork is still running — give status, not a guess.
+
+**Writing a fork prompt.** Since the fork inherits your context, the prompt is a *directive* — what to do, not what the situation is. Be specific about scope: what's in, what's out, what another agent is handling. Don't re-explain background.
+`
+    : ''
+
+  const writingThePromptSection = `
+
+## Writing the prompt
+
+${forkEnabled ? 'When spawning a fresh agent (with a `subagent_type`), it starts with zero context. ' : ''}Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+${forkEnabled ? 'For fresh agents, terse' : 'Terse'} command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
+`
+
+  const forkExamples = `Example usage:
+
+<example>
+user: "What's left on this branch before we can ship?"
+assistant: <thinking>Forking this \u2014 it's a survey question. I want the punch list, not the git output in my context.</thinking>
+${AGENT_TOOL_NAME}({
+  name: "ship-audit",
+  description: "Branch ship-readiness audit",
+  prompt: "Audit what's left before this branch can ship. Check: uncommitted changes, commits ahead of main, whether tests exist, whether the GrowthBook gate is wired up, whether CI-relevant files changed. Report a punch list \u2014 done vs. missing. Under 200 words."
+})
+assistant: Ship-readiness audit running.
+<commentary>
+Turn ends here. The coordinator knows nothing about the findings yet. What follows is a SEPARATE turn \u2014 the notification arrives from outside, as a user-role message. It is not something the coordinator writes.
+</commentary>
+[later turn \u2014 notification arrives as user message]
+assistant: Audit's back. Three blockers: no tests for the new prompt path, GrowthBook gate wired but not in build_flags.yaml, and one uncommitted file.
+</example>
+
+<example>
+user: "so is the gate wired up or not"
+<commentary>
+User asks mid-wait. The audit fork was launched to answer exactly this, and it hasn't returned. The coordinator does not have this answer. Give status, not a fabricated result.
+</commentary>
+assistant: Still waiting on the audit \u2014 that's one of the things it's checking. Should land shortly.
+</example>
+
+<example>
+user: "Can you get a second opinion on whether this migration is safe?"
+assistant: <thinking>I'll ask the code-reviewer agent — it won't see my analysis, so it can give an independent read.</thinking>
+<commentary>
+A subagent_type is specified, so the agent starts fresh. It needs full context in the prompt. The briefing explains what to assess and why.
+</commentary>
+${AGENT_TOOL_NAME}({
+  name: "migration-review",
+  description: "Independent migration review",
+  subagent_type: "code-reviewer",
+  prompt: "Review migration 0042_user_schema.sql for safety. Context: we're adding a NOT NULL column to a 50M-row table. Existing rows get a backfill default. I want a second opinion on whether the backfill approach is safe under concurrent writes — I've checked locking behavior but want independent verification. Report: is this safe, and if not, what specifically breaks?"
+})
+</example>
+`
+
+  const currentExamples = `Example usage:
+
+<example_agent_descriptions>
+"test-runner": use this agent after you are done writing code to run tests
+"greeting-responder": use this agent to respond to user greetings with a friendly joke
+</example_agent_descriptions>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: I'm going to use the ${FILE_WRITE_TOOL_NAME} tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
+</commentary>
+assistant: Uses the ${AGENT_TOOL_NAME} tool to launch the test-runner agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the ${AGENT_TOOL_NAME} tool to launch the greeting-responder agent"
+</example>
+`
+
+  // When the gate is on, the agent list lives in an agent_listing_delta
+  // attachment (see attachments.ts) instead of inline here. This keeps the
+  // tool description static across MCP/plugin/permission changes so the
+  // tools-block prompt cache doesn't bust every time an agent loads.
+  const listViaAttachment = shouldInjectAgentListInMessages()
+
+  const agentListSection = listViaAttachment
+    ? `Available agent types are listed in <system-reminder> messages in the conversation.`
+    : `Available agent types and the tools they have access to:
+${effectiveAgents.map(agent => formatAgentLine(agent)).join('\n')}`
+
+  // Shared core prompt used by both coordinator and non-coordinator modes
+  const shared = `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The ${AGENT_TOOL_NAME} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+${agentListSection}
+
+${
+  forkEnabled
+    ? `When using the ${AGENT_TOOL_NAME} tool, specify a subagent_type to use a specialized agent, or omit it to fork yourself — a fork inherits your full conversation context.`
+    : `When using the ${AGENT_TOOL_NAME} tool, specify a subagent_type parameter to select which agent type to use. If omitted, the general-purpose agent is used.`
+}`
+
+  // Coordinator mode gets the slim prompt -- the coordinator system prompt
+  // already covers usage notes, examples, and when-not-to-use guidance.
+  if (isCoordinator) {
+    return shared
+  }
+
+  // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+  // dedicated Glob/Grep tools, so point at find via Bash instead.
+  const embedded = hasEmbeddedSearchTools()
+  const fileSearchHint = embedded
+    ? '`find` via the Bash tool'
+    : `the ${GLOB_TOOL_NAME} tool`
+  // The "class Foo" example is about content search. Non-embedded stays Glob
+  // (original intent: find-the-file-containing). Embedded gets grep because
+  // find -name doesn't look at file contents.
+  const contentSearchHint = embedded
+    ? '`grep` via the Bash tool'
+    : `the ${GLOB_TOOL_NAME} tool`
+  const whenNotToUseSection = forkEnabled
+    ? ''
+    : `
+When NOT to use the ${AGENT_TOOL_NAME} tool:
+- If you want to read a specific file path, use the ${FILE_READ_TOOL_NAME} tool or ${fileSearchHint} instead of the ${AGENT_TOOL_NAME} tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use ${contentSearchHint} instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the ${FILE_READ_TOOL_NAME} tool instead of the ${AGENT_TOOL_NAME} tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+`
+
+  // When listing via attachment, the "launch multiple agents" note is in the
+  // attachment message (conditioned on subscription there). When inline, keep
+  // the existing per-call getSubscriptionType() check.
+  const concurrencyNote =
+    !listViaAttachment && getSubscriptionType() !== 'pro'
+      ? `
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses`
+      : ''
+
+  // Non-coordinator gets the full prompt with all sections
+  return `${shared}
+${whenNotToUseSection}
+
+Usage notes:
+- Always include a short description (3-5 words) summarizing what the agent will do${concurrencyNote}
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.${
+    // eslint-disable-next-line custom-rules/no-process-env-top-level
+    !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS) &&
+    !isInProcessTeammate() &&
+    !forkEnabled
+      ? `
+- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
+- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.`
+      : ''
+  }
+- To continue a previously spawned agent, use ${SEND_MESSAGE_TOOL_NAME} with the agent's ID or name as the \`to\` field. The agent resumes with its full context preserved. ${forkEnabled ? 'Each fresh Agent invocation with a subagent_type starts without context — provide a complete task description.' : 'Each Agent invocation starts fresh — provide a complete task description.'}
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.)${forkEnabled ? '' : ", since it is not aware of the user's intent"}
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple ${AGENT_TOOL_NAME} tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
+- You can optionally set \`isolation: "worktree"\` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.${
+    process.env.USER_TYPE === 'ant'
+      ? `\n- You can set \`isolation: "remote"\` to run the agent in a remote CCR environment. This is always a background task; you'll be notified when it completes. Use for long-running tasks that need a fresh sandbox.`
+      : ''
+  }${
+    isInProcessTeammate()
+      ? `
+- The run_in_background, name, team_name, and mode parameters are not available in this context. Only synchronous subagents are supported.`
+      : isTeammate()
+        ? `
+- The name, team_name, and mode parameters are not available in this context — teammates cannot spawn other teammates. Omit them to spawn a subagent.`
+        : ''
+  }${whenToForkSection}${writingThePromptSection}
+
+${forkEnabled ? forkExamples : currentExamples}`
+}

src/tools/AgentTool/resumeAgent.ts

@@ -0,0 +1,265 @@
+import { promises as fsp } from 'fs'
+import { getSdkAgentProgressSummariesEnabled } from '../../bootstrap/state.js'
+import { getSystemPrompt } from '../../constants/prompts.js'
+import { isCoordinatorMode } from '../../coordinator/coordinatorMode.js'
+import type { CanUseToolFn } from '../../hooks/useCanUseTool.js'
+import type { ToolUseContext } from '../../Tool.js'
+import { registerAsyncAgent } from '../../tasks/LocalAgentTask/LocalAgentTask.js'
+import { assembleToolPool } from '../../tools.js'
+import { asAgentId } from '../../types/ids.js'
+import { runWithAgentContext } from '../../utils/agentContext.js'
+import { runWithCwdOverride } from '../../utils/cwd.js'
+import { logForDebugging } from '../../utils/debug.js'
+import {
+  createUserMessage,
+  filterOrphanedThinkingOnlyMessages,
+  filterUnresolvedToolUses,
+  filterWhitespaceOnlyAssistantMessages,
+} from '../../utils/messages.js'
+import { getAgentModel } from '../../utils/model/agent.js'
+import { getQuerySourceForAgent } from '../../utils/promptCategory.js'
+import {
+  getAgentTranscript,
+  readAgentMetadata,
+} from '../../utils/sessionStorage.js'
+import { buildEffectiveSystemPrompt } from '../../utils/systemPrompt.js'
+import type { SystemPrompt } from '../../utils/systemPromptType.js'
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js'
+import { getParentSessionId } from '../../utils/teammate.js'
+import { reconstructForSubagentResume } from '../../utils/toolResultStorage.js'
+import { runAsyncAgentLifecycle } from './agentToolUtils.js'
+import { GENERAL_PURPOSE_AGENT } from './built-in/generalPurposeAgent.js'
+import { FORK_AGENT, isForkSubagentEnabled } from './forkSubagent.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+import { isBuiltInAgent } from './loadAgentsDir.js'
+import { runAgent } from './runAgent.js'
+
+export type ResumeAgentResult = {
+  agentId: string
+  description: string
+  outputFile: string
+}
+export async function resumeAgentBackground({
+  agentId,
+  prompt,
+  toolUseContext,
+  canUseTool,
+  invokingRequestId,
+}: {
+  agentId: string
+  prompt: string
+  toolUseContext: ToolUseContext
+  canUseTool: CanUseToolFn
+  invokingRequestId?: string
+}): Promise<ResumeAgentResult> {
+  const startTime = Date.now()
+  const appState = toolUseContext.getAppState()
+  // In-process teammates get a no-op setAppState; setAppStateForTasks
+  // reaches the root store so task registration/progress/kill stay visible.
+  const rootSetAppState =
+    toolUseContext.setAppStateForTasks ?? toolUseContext.setAppState
+  const permissionMode = appState.toolPermissionContext.mode
+
+  const [transcript, meta] = await Promise.all([
+    getAgentTranscript(asAgentId(agentId)),
+    readAgentMetadata(asAgentId(agentId)),
+  ])
+  if (!transcript) {
+    throw new Error(`No transcript found for agent ID: ${agentId}`)
+  }
+  const resumedMessages = filterWhitespaceOnlyAssistantMessages(
+    filterOrphanedThinkingOnlyMessages(
+      filterUnresolvedToolUses(transcript.messages),
+    ),
+  )
+  const resumedReplacementState = reconstructForSubagentResume(
+    toolUseContext.contentReplacementState,
+    resumedMessages,
+    transcript.contentReplacements,
+  )
+  // Best-effort: if the original worktree was removed externally, fall back
+  // to parent cwd rather than crashing on chdir later.
+  const resumedWorktreePath = meta?.worktreePath
+    ? await fsp.stat(meta.worktreePath).then(
+        s => (s.isDirectory() ? meta.worktreePath : undefined),
+        () => {
+          logForDebugging(
+            `Resumed worktree ${meta.worktreePath} no longer exists; falling back to parent cwd`,
+          )
+          return undefined
+        },
+      )
+    : undefined
+  if (resumedWorktreePath) {
+    // Bump mtime so stale-worktree cleanup doesn't delete a just-resumed worktree (#22355)
+    const now = new Date()
+    await fsp.utimes(resumedWorktreePath, now, now)
+  }
+
+  // Skip filterDeniedAgents re-gating — original spawn already passed permission checks
+  let selectedAgent: AgentDefinition
+  let isResumedFork = false
+  if (meta?.agentType === FORK_AGENT.agentType) {
+    selectedAgent = FORK_AGENT
+    isResumedFork = true
+  } else if (meta?.agentType) {
+    const found = toolUseContext.options.agentDefinitions.activeAgents.find(
+      a => a.agentType === meta.agentType,
+    )
+    selectedAgent = found ?? GENERAL_PURPOSE_AGENT
+  } else {
+    selectedAgent = GENERAL_PURPOSE_AGENT
+  }
+
+  const uiDescription = meta?.description ?? '(resumed)'
+
+  let forkParentSystemPrompt: SystemPrompt | undefined
+  if (isResumedFork) {
+    if (toolUseContext.renderedSystemPrompt) {
+      forkParentSystemPrompt = toolUseContext.renderedSystemPrompt
+    } else {
+      const mainThreadAgentDefinition = appState.agent
+        ? appState.agentDefinitions.activeAgents.find(
+            a => a.agentType === appState.agent,
+          )
+        : undefined
+      const additionalWorkingDirectories = Array.from(
+        appState.toolPermissionContext.additionalWorkingDirectories.keys(),
+      )
+      const defaultSystemPrompt = await getSystemPrompt(
+        toolUseContext.options.tools,
+        toolUseContext.options.mainLoopModel,
+        additionalWorkingDirectories,
+        toolUseContext.options.mcpClients,
+      )
+      forkParentSystemPrompt = buildEffectiveSystemPrompt({
+        mainThreadAgentDefinition,
+        toolUseContext,
+        customSystemPrompt: toolUseContext.options.customSystemPrompt,
+        defaultSystemPrompt,
+        appendSystemPrompt: toolUseContext.options.appendSystemPrompt,
+      })
+    }
+    if (!forkParentSystemPrompt) {
+      throw new Error(
+        'Cannot resume fork agent: unable to reconstruct parent system prompt',
+      )
+    }
+  }
+
+  // Resolve model for analytics metadata (runAgent resolves its own internally)
+  const resolvedAgentModel = getAgentModel(
+    selectedAgent.model,
+    toolUseContext.options.mainLoopModel,
+    undefined,
+    permissionMode,
+  )
+
+  const workerPermissionContext = {
+    ...appState.toolPermissionContext,
+    mode: selectedAgent.permissionMode ?? 'acceptEdits',
+  }
+  const workerTools = isResumedFork
+    ? toolUseContext.options.tools
+    : assembleToolPool(workerPermissionContext, appState.mcp.tools)
+
+  const runAgentParams: Parameters<typeof runAgent>[0] = {
+    agentDefinition: selectedAgent,
+    promptMessages: [
+      ...resumedMessages,
+      createUserMessage({ content: prompt }),
+    ],
+    toolUseContext,
+    canUseTool,
+    isAsync: true,
+    querySource: getQuerySourceForAgent(
+      selectedAgent.agentType,
+      isBuiltInAgent(selectedAgent),
+    ),
+    model: undefined,
+    // Fork resume: pass parent's system prompt (cache-identical prefix).
+    // Non-fork: undefined → runAgent recomputes under wrapWithCwd so
+    // getCwd() sees resumedWorktreePath.
+    override: isResumedFork
+      ? { systemPrompt: forkParentSystemPrompt }
+      : undefined,
+    availableTools: workerTools,
+    // Transcript already contains the parent context slice from the
+    // original fork. Re-supplying it would cause duplicate tool_use IDs.
+    forkContextMessages: undefined,
+    ...(isResumedFork && { useExactTools: true }),
+    // Re-persist so metadata survives runAgent's writeAgentMetadata overwrite
+    worktreePath: resumedWorktreePath,
+    description: meta?.description,
+    contentReplacementState: resumedReplacementState,
+  }
+
+  // Skip name-registry write — original entry persists from the initial spawn
+  const agentBackgroundTask = registerAsyncAgent({
+    agentId,
+    description: uiDescription,
+    prompt,
+    selectedAgent,
+    setAppState: rootSetAppState,
+    toolUseId: toolUseContext.toolUseId,
+  })
+
+  const metadata = {
+    prompt,
+    resolvedAgentModel,
+    isBuiltInAgent: isBuiltInAgent(selectedAgent),
+    startTime,
+    agentType: selectedAgent.agentType,
+    isAsync: true,
+  }
+
+  const asyncAgentContext = {
+    agentId,
+    parentSessionId: getParentSessionId(),
+    agentType: 'subagent' as const,
+    subagentName: selectedAgent.agentType,
+    isBuiltIn: isBuiltInAgent(selectedAgent),
+    invokingRequestId,
+    invocationKind: 'resume' as const,
+    invocationEmitted: false,
+  }
+
+  const wrapWithCwd = <T>(fn: () => T): T =>
+    resumedWorktreePath ? runWithCwdOverride(resumedWorktreePath, fn) : fn()
+
+  void runWithAgentContext(asyncAgentContext, () =>
+    wrapWithCwd(() =>
+      runAsyncAgentLifecycle({
+        taskId: agentBackgroundTask.agentId,
+        abortController: agentBackgroundTask.abortController!,
+        makeStream: onCacheSafeParams =>
+          runAgent({
+            ...runAgentParams,
+            override: {
+              ...runAgentParams.override,
+              agentId: asAgentId(agentBackgroundTask.agentId),
+              abortController: agentBackgroundTask.abortController!,
+            },
+            onCacheSafeParams,
+          }),
+        metadata,
+        description: uiDescription,
+        toolUseContext,
+        rootSetAppState,
+        agentIdForCleanup: agentId,
+        enableSummarization:
+          isCoordinatorMode() ||
+          isForkSubagentEnabled() ||
+          getSdkAgentProgressSummariesEnabled(),
+        getWorktreeResult: async () =>
+          resumedWorktreePath ? { worktreePath: resumedWorktreePath } : {},
+      }),
+    ),
+  )
+
+  return {
+    agentId,
+    description: uiDescription,
+    outputFile: getTaskOutputPath(agentId),
+  }
+}

src/tools/AgentTool/runAgent.ts

@@ -0,0 +1,973 @@
+import { feature } from 'bun:bundle'
+import type { UUID } from 'crypto'
+import { randomUUID } from 'crypto'
+import uniqBy from 'lodash-es/uniqBy.js'
+import { logForDebugging } from 'src/utils/debug.js'
+import { getProjectRoot, getSessionId } from '../../bootstrap/state.js'
+import { getCommand, getSkillToolCommands, hasCommand } from '../../commands.js'
+import {
+  DEFAULT_AGENT_PROMPT,
+  enhanceSystemPromptWithEnvDetails,
+} from '../../constants/prompts.js'
+import type { QuerySource } from '../../constants/querySource.js'
+import { getSystemContext, getUserContext } from '../../context.js'
+import type { CanUseToolFn } from '../../hooks/useCanUseTool.js'
+import { query } from '../../query.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import { getDumpPromptsPath } from '../../services/api/dumpPrompts.js'
+import { cleanupAgentTracking } from '../../services/api/promptCacheBreakDetection.js'
+import {
+  connectToServer,
+  fetchToolsForClient,
+} from '../../services/mcp/client.js'
+import { getMcpConfigByName } from '../../services/mcp/config.js'
+import type {
+  MCPServerConnection,
+  ScopedMcpServerConfig,
+} from '../../services/mcp/types.js'
+import type { Tool, Tools, ToolUseContext } from '../../Tool.js'
+import { killShellTasksForAgent } from '../../tasks/LocalShellTask/killShellTasks.js'
+import type { Command } from '../../types/command.js'
+import type { AgentId } from '../../types/ids.js'
+import type {
+  AssistantMessage,
+  Message,
+  ProgressMessage,
+  RequestStartEvent,
+  StreamEvent,
+  SystemCompactBoundaryMessage,
+  TombstoneMessage,
+  ToolUseSummaryMessage,
+  UserMessage,
+} from '../../types/message.js'
+import { createAttachmentMessage } from '../../utils/attachments.js'
+import { AbortError } from '../../utils/errors.js'
+import { getDisplayPath } from '../../utils/file.js'
+import {
+  cloneFileStateCache,
+  createFileStateCacheWithSizeLimit,
+  READ_FILE_STATE_CACHE_SIZE,
+} from '../../utils/fileStateCache.js'
+import {
+  type CacheSafeParams,
+  createSubagentContext,
+} from '../../utils/forkedAgent.js'
+import { registerFrontmatterHooks } from '../../utils/hooks/registerFrontmatterHooks.js'
+import { clearSessionHooks } from '../../utils/hooks/sessionHooks.js'
+import { executeSubagentStartHooks } from '../../utils/hooks.js'
+import { createUserMessage } from '../../utils/messages.js'
+import { getAgentModel } from '../../utils/model/agent.js'
+import type { ModelAlias } from '../../utils/model/aliases.js'
+import {
+  clearAgentTranscriptSubdir,
+  recordSidechainTranscript,
+  setAgentTranscriptSubdir,
+  writeAgentMetadata,
+} from '../../utils/sessionStorage.js'
+import {
+  isRestrictedToPluginOnly,
+  isSourceAdminTrusted,
+} from '../../utils/settings/pluginOnlyPolicy.js'
+import {
+  asSystemPrompt,
+  type SystemPrompt,
+} from '../../utils/systemPromptType.js'
+import {
+  isPerfettoTracingEnabled,
+  registerAgent as registerPerfettoAgent,
+  unregisterAgent as unregisterPerfettoAgent,
+} from '../../utils/telemetry/perfettoTracing.js'
+import type { ContentReplacementState } from '../../utils/toolResultStorage.js'
+import { createAgentId } from '../../utils/uuid.js'
+import { resolveAgentTools } from './agentToolUtils.js'
+import { type AgentDefinition, isBuiltInAgent } from './loadAgentsDir.js'
+
+/**
+ * Initialize agent-specific MCP servers
+ * Agents can define their own MCP servers in their frontmatter that are additive
+ * to the parent's MCP clients. These servers are connected when the agent starts
+ * and cleaned up when the agent finishes.
+ *
+ * @param agentDefinition The agent definition with optional mcpServers
+ * @param parentClients MCP clients inherited from parent context
+ * @returns Merged clients (parent + agent-specific), agent MCP tools, and cleanup function
+ */
+async function initializeAgentMcpServers(
+  agentDefinition: AgentDefinition,
+  parentClients: MCPServerConnection[],
+): Promise<{
+  clients: MCPServerConnection[]
+  tools: Tools
+  cleanup: () => Promise<void>
+}> {
+  // If no agent-specific servers defined, return parent clients as-is
+  if (!agentDefinition.mcpServers?.length) {
+    return {
+      clients: parentClients,
+      tools: [],
+      cleanup: async () => {},
+    }
+  }
+
+  // When MCP is locked to plugin-only, skip frontmatter MCP servers for
+  // USER-CONTROLLED agents only. Plugin, built-in, and policySettings agents
+  // are admin-trusted — their frontmatter MCP is part of the admin-approved
+  // surface. Blocking them (as the first cut did) breaks plugin agents that
+  // legitimately need MCP, contradicting "plugin-provided always loads."
+  const agentIsAdminTrusted = isSourceAdminTrusted(agentDefinition.source)
+  if (isRestrictedToPluginOnly('mcp') && !agentIsAdminTrusted) {
+    logForDebugging(
+      `[Agent: ${agentDefinition.agentType}] Skipping MCP servers: strictPluginOnlyCustomization locks MCP to plugin-only (agent source: ${agentDefinition.source})`,
+    )
+    return {
+      clients: parentClients,
+      tools: [],
+      cleanup: async () => {},
+    }
+  }
+
+  const agentClients: MCPServerConnection[] = []
+  // Track which clients were newly created (inline definitions) vs. shared from parent
+  // Only newly created clients should be cleaned up when the agent finishes
+  const newlyCreatedClients: MCPServerConnection[] = []
+  const agentTools: Tool[] = []
+
+  for (const spec of agentDefinition.mcpServers) {
+    let config: ScopedMcpServerConfig | null = null
+    let name: string
+    let isNewlyCreated = false
+
+    if (typeof spec === 'string') {
+      // Reference by name - look up in existing MCP configs
+      // This uses the memoized connectToServer, so we may get a shared client
+      name = spec
+      config = getMcpConfigByName(spec)
+      if (!config) {
+        logForDebugging(
+          `[Agent: ${agentDefinition.agentType}] MCP server not found: ${spec}`,
+          { level: 'warn' },
+        )
+        continue
+      }
+    } else {
+      // Inline definition as { [name]: config }
+      // These are agent-specific servers that should be cleaned up
+      const entries = Object.entries(spec)
+      if (entries.length !== 1) {
+        logForDebugging(
+          `[Agent: ${agentDefinition.agentType}] Invalid MCP server spec: expected exactly one key`,
+          { level: 'warn' },
+        )
+        continue
+      }
+      const [serverName, serverConfig] = entries[0]!
+      name = serverName
+      config = {
+        ...serverConfig,
+        scope: 'dynamic' as const,
+      } as ScopedMcpServerConfig
+      isNewlyCreated = true
+    }
+
+    // Connect to the server
+    const client = await connectToServer(name, config)
+    agentClients.push(client)
+    if (isNewlyCreated) {
+      newlyCreatedClients.push(client)
+    }
+
+    // Fetch tools if connected
+    if (client.type === 'connected') {
+      const tools = await fetchToolsForClient(client)
+      agentTools.push(...tools)
+      logForDebugging(
+        `[Agent: ${agentDefinition.agentType}] Connected to MCP server '${name}' with ${tools.length} tools`,
+      )
+    } else {
+      logForDebugging(
+        `[Agent: ${agentDefinition.agentType}] Failed to connect to MCP server '${name}': ${client.type}`,
+        { level: 'warn' },
+      )
+    }
+  }
+
+  // Create cleanup function for agent-specific servers
+  // Only clean up newly created clients (inline definitions), not shared/referenced ones
+  // Shared clients (referenced by string name) are memoized and used by the parent context
+  const cleanup = async () => {
+    for (const client of newlyCreatedClients) {
+      if (client.type === 'connected') {
+        try {
+          await client.cleanup()
+        } catch (error) {
+          logForDebugging(
+            `[Agent: ${agentDefinition.agentType}] Error cleaning up MCP server '${client.name}': ${error}`,
+            { level: 'warn' },
+          )
+        }
+      }
+    }
+  }
+
+  // Return merged clients (parent + agent-specific) and agent tools
+  return {
+    clients: [...parentClients, ...agentClients],
+    tools: agentTools,
+    cleanup,
+  }
+}
+
+type QueryMessage =
+  | StreamEvent
+  | RequestStartEvent
+  | Message
+  | ToolUseSummaryMessage
+  | TombstoneMessage
+
+/**
+ * Type guard to check if a message from query() is a recordable Message type.
+ * Matches the types we want to record: assistant, user, progress, or system compact_boundary.
+ */
+function isRecordableMessage(
+  msg: QueryMessage,
+): msg is
+  | AssistantMessage
+  | UserMessage
+  | ProgressMessage
+  | SystemCompactBoundaryMessage {
+  return (
+    msg.type === 'assistant' ||
+    msg.type === 'user' ||
+    msg.type === 'progress' ||
+    (msg.type === 'system' &&
+      'subtype' in msg &&
+      msg.subtype === 'compact_boundary')
+  )
+}
+
+export async function* runAgent({
+  agentDefinition,
+  promptMessages,
+  toolUseContext,
+  canUseTool,
+  isAsync,
+  canShowPermissionPrompts,
+  forkContextMessages,
+  querySource,
+  override,
+  model,
+  maxTurns,
+  preserveToolUseResults,
+  availableTools,
+  allowedTools,
+  onCacheSafeParams,
+  contentReplacementState,
+  useExactTools,
+  worktreePath,
+  description,
+  transcriptSubdir,
+  onQueryProgress,
+}: {
+  agentDefinition: AgentDefinition
+  promptMessages: Message[]
+  toolUseContext: ToolUseContext
+  canUseTool: CanUseToolFn
+  isAsync: boolean
+  /** Whether this agent can show permission prompts. Defaults to !isAsync.
+   * Set to true for in-process teammates that run async but share the terminal. */
+  canShowPermissionPrompts?: boolean
+  forkContextMessages?: Message[]
+  querySource: QuerySource
+  override?: {
+    userContext?: { [k: string]: string }
+    systemContext?: { [k: string]: string }
+    systemPrompt?: SystemPrompt
+    abortController?: AbortController
+    agentId?: AgentId
+  }
+  model?: ModelAlias
+  maxTurns?: number
+  /** Preserve toolUseResult on messages for subagents with viewable transcripts */
+  preserveToolUseResults?: boolean
+  /** Precomputed tool pool for the worker agent. Computed by the caller
+   * (AgentTool.tsx) to avoid a circular dependency between runAgent and tools.ts.
+   * Always contains the full tool pool assembled with the worker's own permission
+   * mode, independent of the parent's tool restrictions. */
+  availableTools: Tools
+  /** Tool permission rules to add to the agent's session allow rules.
+   * When provided, replaces ALL allow rules so the agent only has what's
+   * explicitly listed (parent approvals don't leak through). */
+  allowedTools?: string[]
+  /** Optional callback invoked with CacheSafeParams after constructing the agent's
+   * system prompt, context, and tools. Used by background summarization to fork
+   * the agent's conversation for periodic progress summaries. */
+  onCacheSafeParams?: (params: CacheSafeParams) => void
+  /** Replacement state reconstructed from a resumed sidechain transcript so
+   * the same tool results are re-replaced (prompt cache stability). When
+   * omitted, createSubagentContext clones the parent's state. */
+  contentReplacementState?: ContentReplacementState
+  /** When true, use availableTools directly without filtering through
+   * resolveAgentTools(). Also inherits the parent's thinkingConfig and
+   * isNonInteractiveSession instead of overriding them. Used by the fork
+   * subagent path to produce byte-identical API request prefixes for
+   * prompt cache hits. */
+  useExactTools?: boolean
+  /** Worktree path if the agent was spawned with isolation: "worktree".
+   * Persisted to metadata so resume can restore the correct cwd. */
+  worktreePath?: string
+  /** Original task description from AgentTool input. Persisted to metadata
+   * so a resumed agent's notification can show the original description. */
+  description?: string
+  /** Optional subdirectory under subagents/ to group this agent's transcript
+   * with related ones (e.g. workflows/<runId> for workflow subagents). */
+  transcriptSubdir?: string
+  /** Optional callback fired on every message yielded by query() — including
+   * stream_event deltas that runAgent otherwise drops. Use to detect liveness
+   * during long single-block streams (e.g. thinking) where no assistant
+   * message is yielded for >60s. */
+  onQueryProgress?: () => void
+}): AsyncGenerator<Message, void> {
+  // Track subagent usage for feature discovery
+
+  const appState = toolUseContext.getAppState()
+  const permissionMode = appState.toolPermissionContext.mode
+  // Always-shared channel to the root AppState store. toolUseContext.setAppState
+  // is a no-op when the *parent* is itself an async agent (nested async→async),
+  // so session-scoped writes (hooks, bash tasks) must go through this instead.
+  const rootSetAppState =
+    toolUseContext.setAppStateForTasks ?? toolUseContext.setAppState
+
+  const resolvedAgentModel = getAgentModel(
+    agentDefinition.model,
+    toolUseContext.options.mainLoopModel,
+    model,
+    permissionMode,
+  )
+
+  const agentId = override?.agentId ? override.agentId : createAgentId()
+
+  // Route this agent's transcript into a grouping subdirectory if requested
+  // (e.g. workflow subagents write to subagents/workflows/<runId>/).
+  if (transcriptSubdir) {
+    setAgentTranscriptSubdir(agentId, transcriptSubdir)
+  }
+
+  // Register agent in Perfetto trace for hierarchy visualization
+  if (isPerfettoTracingEnabled()) {
+    const parentId = toolUseContext.agentId ?? getSessionId()
+    registerPerfettoAgent(agentId, agentDefinition.agentType, parentId)
+  }
+
+  // Log API calls path for subagents (ant-only)
+  if (process.env.USER_TYPE === 'ant') {
+    logForDebugging(
+      `[Subagent ${agentDefinition.agentType}] API calls: ${getDisplayPath(getDumpPromptsPath(agentId))}`,
+    )
+  }
+
+  // Handle message forking for context sharing
+  // Filter out incomplete tool calls from parent messages to avoid API errors
+  const contextMessages: Message[] = forkContextMessages
+    ? filterIncompleteToolCalls(forkContextMessages)
+    : []
+  const initialMessages: Message[] = [...contextMessages, ...promptMessages]
+
+  const agentReadFileState =
+    forkContextMessages !== undefined
+      ? cloneFileStateCache(toolUseContext.readFileState)
+      : createFileStateCacheWithSizeLimit(READ_FILE_STATE_CACHE_SIZE)
+
+  const [baseUserContext, baseSystemContext] = await Promise.all([
+    override?.userContext ?? getUserContext(),
+    override?.systemContext ?? getSystemContext(),
+  ])
+
+  // Read-only agents (Explore, Plan) don't act on commit/PR/lint rules from
+  // CLAUDE.md — the main agent has full context and interprets their output.
+  // Dropping claudeMd here saves ~5-15 Gtok/week across 34M+ Explore spawns.
+  // Explicit override.userContext from callers is preserved untouched.
+  // Kill-switch defaults true; flip tengu_slim_subagent_claudemd=false to revert.
+  const shouldOmitClaudeMd =
+    agentDefinition.omitClaudeMd &&
+    !override?.userContext &&
+    getFeatureValue_CACHED_MAY_BE_STALE('tengu_slim_subagent_claudemd', true)
+  const { claudeMd: _omittedClaudeMd, ...userContextNoClaudeMd } =
+    baseUserContext
+  const resolvedUserContext = shouldOmitClaudeMd
+    ? userContextNoClaudeMd
+    : baseUserContext
+
+  // Explore/Plan are read-only search agents — the parent-session-start
+  // gitStatus (up to 40KB, explicitly labeled stale) is dead weight. If they
+  // need git info they run `git status` themselves and get fresh data.
+  // Saves ~1-3 Gtok/week fleet-wide.
+  const { gitStatus: _omittedGitStatus, ...systemContextNoGit } =
+    baseSystemContext
+  const resolvedSystemContext =
+    agentDefinition.agentType === 'Explore' ||
+    agentDefinition.agentType === 'Plan'
+      ? systemContextNoGit
+      : baseSystemContext
+
+  // Override permission mode if agent defines one
+  // However, don't override if parent is in bypassPermissions or acceptEdits mode - those should always take precedence
+  // For async agents, also set shouldAvoidPermissionPrompts since they can't show UI
+  const agentPermissionMode = agentDefinition.permissionMode
+  const agentGetAppState = () => {
+    const state = toolUseContext.getAppState()
+    let toolPermissionContext = state.toolPermissionContext
+
+    // Override permission mode if agent defines one (unless parent is bypassPermissions, acceptEdits, or auto)
+    if (
+      agentPermissionMode &&
+      state.toolPermissionContext.mode !== 'bypassPermissions' &&
+      state.toolPermissionContext.mode !== 'acceptEdits' &&
+      !(
+        feature('TRANSCRIPT_CLASSIFIER') &&
+        state.toolPermissionContext.mode === 'auto'
+      )
+    ) {
+      toolPermissionContext = {
+        ...toolPermissionContext,
+        mode: agentPermissionMode,
+      }
+    }
+
+    // Set flag to auto-deny prompts for agents that can't show UI
+    // Use explicit canShowPermissionPrompts if provided, otherwise:
+    //   - bubble mode: always show prompts (bubbles to parent terminal)
+    //   - default: !isAsync (sync agents show prompts, async agents don't)
+    const shouldAvoidPrompts =
+      canShowPermissionPrompts !== undefined
+        ? !canShowPermissionPrompts
+        : agentPermissionMode === 'bubble'
+          ? false
+          : isAsync
+    if (shouldAvoidPrompts) {
+      toolPermissionContext = {
+        ...toolPermissionContext,
+        shouldAvoidPermissionPrompts: true,
+      }
+    }
+
+    // For background agents that can show prompts, await automated checks
+    // (classifier, permission hooks) before showing the permission dialog.
+    // Since these are background agents, waiting is fine — the user should
+    // only be interrupted when automated checks can't resolve the permission.
+    // This applies to bubble mode (always) and explicit canShowPermissionPrompts.
+    if (isAsync && !shouldAvoidPrompts) {
+      toolPermissionContext = {
+        ...toolPermissionContext,
+        awaitAutomatedChecksBeforeDialog: true,
+      }
+    }
+
+    // Scope tool permissions: when allowedTools is provided, use them as session rules.
+    // IMPORTANT: Preserve cliArg rules (from SDK's --allowedTools) since those are
+    // explicit permissions from the SDK consumer that should apply to all agents.
+    // Only clear session-level rules from the parent to prevent unintended leakage.
+    if (allowedTools !== undefined) {
+      toolPermissionContext = {
+        ...toolPermissionContext,
+        alwaysAllowRules: {
+          // Preserve SDK-level permissions from --allowedTools
+          cliArg: state.toolPermissionContext.alwaysAllowRules.cliArg,
+          // Use the provided allowedTools as session-level permissions
+          session: [...allowedTools],
+        },
+      }
+    }
+
+    // Override effort level if agent defines one
+    const effortValue =
+      agentDefinition.effort !== undefined
+        ? agentDefinition.effort
+        : state.effortValue
+
+    if (
+      toolPermissionContext === state.toolPermissionContext &&
+      effortValue === state.effortValue
+    ) {
+      return state
+    }
+    return {
+      ...state,
+      toolPermissionContext,
+      effortValue,
+    }
+  }
+
+  const resolvedTools = useExactTools
+    ? availableTools
+    : resolveAgentTools(agentDefinition, availableTools, isAsync).resolvedTools
+
+  const additionalWorkingDirectories = Array.from(
+    appState.toolPermissionContext.additionalWorkingDirectories.keys(),
+  )
+
+  const agentSystemPrompt = override?.systemPrompt
+    ? override.systemPrompt
+    : asSystemPrompt(
+        await getAgentSystemPrompt(
+          agentDefinition,
+          toolUseContext,
+          resolvedAgentModel,
+          additionalWorkingDirectories,
+          resolvedTools,
+        ),
+      )
+
+  // Determine abortController:
+  // - Override takes precedence
+  // - Async agents get a new unlinked controller (runs independently)
+  // - Sync agents share parent's controller
+  const agentAbortController = override?.abortController
+    ? override.abortController
+    : isAsync
+      ? new AbortController()
+      : toolUseContext.abortController
+
+  // Execute SubagentStart hooks and collect additional context
+  const additionalContexts: string[] = []
+  for await (const hookResult of executeSubagentStartHooks(
+    agentId,
+    agentDefinition.agentType,
+    agentAbortController.signal,
+  )) {
+    if (
+      hookResult.additionalContexts &&
+      hookResult.additionalContexts.length > 0
+    ) {
+      additionalContexts.push(...hookResult.additionalContexts)
+    }
+  }
+
+  // Add SubagentStart hook context as a user message (consistent with SessionStart/UserPromptSubmit)
+  if (additionalContexts.length > 0) {
+    const contextMessage = createAttachmentMessage({
+      type: 'hook_additional_context',
+      content: additionalContexts,
+      hookName: 'SubagentStart',
+      toolUseID: randomUUID(),
+      hookEvent: 'SubagentStart',
+    })
+    initialMessages.push(contextMessage)
+  }
+
+  // Register agent's frontmatter hooks (scoped to agent lifecycle)
+  // Pass isAgent=true to convert Stop hooks to SubagentStop (since subagents trigger SubagentStop)
+  // Same admin-trusted gate for frontmatter hooks: under ["hooks"] alone
+  // (skills/agents not locked), user agents still load — block their
+  // frontmatter-hook REGISTRATION here where source is known, rather than
+  // blanket-blocking all session hooks at execution time (which would
+  // also kill plugin agents' hooks).
+  const hooksAllowedForThisAgent =
+    !isRestrictedToPluginOnly('hooks') ||
+    isSourceAdminTrusted(agentDefinition.source)
+  if (agentDefinition.hooks && hooksAllowedForThisAgent) {
+    registerFrontmatterHooks(
+      rootSetAppState,
+      agentId,
+      agentDefinition.hooks,
+      `agent '${agentDefinition.agentType}'`,
+      true, // isAgent - converts Stop to SubagentStop
+    )
+  }
+
+  // Preload skills from agent frontmatter
+  const skillsToPreload = agentDefinition.skills ?? []
+  if (skillsToPreload.length > 0) {
+    const allSkills = await getSkillToolCommands(getProjectRoot())
+
+    // Filter valid skills and warn about missing ones
+    const validSkills: Array<{
+      skillName: string
+      skill: (typeof allSkills)[0] & { type: 'prompt' }
+    }> = []
+
+    for (const skillName of skillsToPreload) {
+      // Resolve the skill name, trying multiple strategies:
+      // 1. Exact match (hasCommand checks name, userFacingName, aliases)
+      // 2. Fully-qualified with agent's plugin prefix (e.g., "my-skill" → "plugin:my-skill")
+      // 3. Suffix match on ":skillName" for plugin-namespaced skills
+      const resolvedName = resolveSkillName(
+        skillName,
+        allSkills,
+        agentDefinition,
+      )
+      if (!resolvedName) {
+        logForDebugging(
+          `[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' specified in frontmatter was not found`,
+          { level: 'warn' },
+        )
+        continue
+      }
+
+      const skill = getCommand(resolvedName, allSkills)
+      if (skill.type !== 'prompt') {
+        logForDebugging(
+          `[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' is not a prompt-based skill`,
+          { level: 'warn' },
+        )
+        continue
+      }
+      validSkills.push({ skillName, skill })
+    }
+
+    // Load all skill contents concurrently and add to initial messages
+    const { formatSkillLoadingMetadata } = await import(
+      '../../utils/processUserInput/processSlashCommand.js'
+    )
+    const loaded = await Promise.all(
+      validSkills.map(async ({ skillName, skill }) => ({
+        skillName,
+        skill,
+        content: await skill.getPromptForCommand('', toolUseContext),
+      })),
+    )
+    for (const { skillName, skill, content } of loaded) {
+      logForDebugging(
+        `[Agent: ${agentDefinition.agentType}] Preloaded skill '${skillName}'`,
+      )
+
+      // Add command-message metadata so the UI shows which skill is loading
+      const metadata = formatSkillLoadingMetadata(
+        skillName,
+        skill.progressMessage,
+      )
+
+      initialMessages.push(
+        createUserMessage({
+          content: [{ type: 'text', text: metadata }, ...content],
+          isMeta: true,
+        }),
+      )
+    }
+  }
+
+  // Initialize agent-specific MCP servers (additive to parent's servers)
+  const {
+    clients: mergedMcpClients,
+    tools: agentMcpTools,
+    cleanup: mcpCleanup,
+  } = await initializeAgentMcpServers(
+    agentDefinition,
+    toolUseContext.options.mcpClients,
+  )
+
+  // Merge agent MCP tools with resolved agent tools, deduplicating by name.
+  // resolvedTools is already deduplicated (see resolveAgentTools), so skip
+  // the spread + uniqBy overhead when there are no agent-specific MCP tools.
+  const allTools =
+    agentMcpTools.length > 0
+      ? uniqBy([...resolvedTools, ...agentMcpTools], 'name')
+      : resolvedTools
+
+  // Build agent-specific options
+  const agentOptions: ToolUseContext['options'] = {
+    isNonInteractiveSession: useExactTools
+      ? toolUseContext.options.isNonInteractiveSession
+      : isAsync
+        ? true
+        : (toolUseContext.options.isNonInteractiveSession ?? false),
+    appendSystemPrompt: toolUseContext.options.appendSystemPrompt,
+    tools: allTools,
+    commands: [],
+    debug: toolUseContext.options.debug,
+    verbose: toolUseContext.options.verbose,
+    mainLoopModel: resolvedAgentModel,
+    // For fork children (useExactTools), inherit thinking config to match the
+    // parent's API request prefix for prompt cache hits. For regular
+    // sub-agents, disable thinking to control output token costs.
+    thinkingConfig: useExactTools
+      ? toolUseContext.options.thinkingConfig
+      : { type: 'disabled' as const },
+    mcpClients: mergedMcpClients,
+    mcpResources: toolUseContext.options.mcpResources,
+    agentDefinitions: toolUseContext.options.agentDefinitions,
+    // Fork children (useExactTools path) need querySource on context.options
+    // for the recursive-fork guard at AgentTool.tsx call() — it checks
+    // options.querySource === 'agent:builtin:fork'. This survives autocompact
+    // (which rewrites messages, not context.options). Without this, the guard
+    // reads undefined and only the message-scan fallback fires — which
+    // autocompact defeats by replacing the fork-boilerplate message.
+    ...(useExactTools && { querySource }),
+  }
+
+  // Create subagent context using shared helper
+  // - Sync agents share setAppState, setResponseLength, abortController with parent
+  // - Async agents are fully isolated (but with explicit unlinked abortController)
+  const agentToolUseContext = createSubagentContext(toolUseContext, {
+    options: agentOptions,
+    agentId,
+    agentType: agentDefinition.agentType,
+    messages: initialMessages,
+    readFileState: agentReadFileState,
+    abortController: agentAbortController,
+    getAppState: agentGetAppState,
+    // Sync agents share these callbacks with parent
+    shareSetAppState: !isAsync,
+    shareSetResponseLength: true, // Both sync and async contribute to response metrics
+    criticalSystemReminder_EXPERIMENTAL:
+      agentDefinition.criticalSystemReminder_EXPERIMENTAL,
+    contentReplacementState,
+  })
+
+  // Preserve tool use results for subagents with viewable transcripts (in-process teammates)
+  if (preserveToolUseResults) {
+    agentToolUseContext.preserveToolUseResults = true
+  }
+
+  // Expose cache-safe params for background summarization (prompt cache sharing)
+  if (onCacheSafeParams) {
+    onCacheSafeParams({
+      systemPrompt: agentSystemPrompt,
+      userContext: resolvedUserContext,
+      systemContext: resolvedSystemContext,
+      toolUseContext: agentToolUseContext,
+      forkContextMessages: initialMessages,
+    })
+  }
+
+  // Record initial messages before the query loop starts, plus the agentType
+  // so resume can route correctly when subagent_type is omitted. Both writes
+  // are fire-and-forget — persistence failure shouldn't block the agent.
+  void recordSidechainTranscript(initialMessages, agentId).catch(_err =>
+    logForDebugging(`Failed to record sidechain transcript: ${_err}`),
+  )
+  void writeAgentMetadata(agentId, {
+    agentType: agentDefinition.agentType,
+    ...(worktreePath && { worktreePath }),
+    ...(description && { description }),
+  }).catch(_err => logForDebugging(`Failed to write agent metadata: ${_err}`))
+
+  // Track the last recorded message UUID for parent chain continuity
+  let lastRecordedUuid: UUID | null = initialMessages.at(-1)?.uuid ?? null
+
+  try {
+    for await (const message of query({
+      messages: initialMessages,
+      systemPrompt: agentSystemPrompt,
+      userContext: resolvedUserContext,
+      systemContext: resolvedSystemContext,
+      canUseTool,
+      toolUseContext: agentToolUseContext,
+      querySource,
+      maxTurns: maxTurns ?? agentDefinition.maxTurns,
+    })) {
+      onQueryProgress?.()
+      // Forward subagent API request starts to parent's metrics display
+      // so TTFT/OTPS update during subagent execution.
+      if (
+        message.type === 'stream_event' &&
+        message.event.type === 'message_start' &&
+        message.ttftMs != null
+      ) {
+        toolUseContext.pushApiMetricsEntry?.(message.ttftMs)
+        continue
+      }
+
+      // Yield attachment messages (e.g., structured_output) without recording them
+      if (message.type === 'attachment') {
+        // Handle max turns reached signal from query.ts
+        if (message.attachment.type === 'max_turns_reached') {
+          logForDebugging(
+            `[Agent
+: $
+{
+  agentDefinition.agentType
+}
+] Reached max turns limit ($
+{
+  message.attachment.maxTurns
+}
+)`,
+          )
+          break
+        }
+        yield message
+        continue
+      }
+
+      if (isRecordableMessage(message)) {
+        // Record only the new message with correct parent (O(1) per message)
+        await recordSidechainTranscript(
+          [message],
+          agentId,
+          lastRecordedUuid,
+        ).catch(err =>
+          logForDebugging(`Failed to record sidechain transcript: ${err}`),
+        )
+        if (message.type !== 'progress') {
+          lastRecordedUuid = message.uuid
+        }
+        yield message
+      }
+    }
+
+    if (agentAbortController.signal.aborted) {
+      throw new AbortError()
+    }
+
+    // Run callback if provided (only built-in agents have callbacks)
+    if (isBuiltInAgent(agentDefinition) && agentDefinition.callback) {
+      agentDefinition.callback()
+    }
+  } finally {
+    // Clean up agent-specific MCP servers (runs on normal completion, abort, or error)
+    await mcpCleanup()
+    // Clean up agent's session hooks
+    if (agentDefinition.hooks) {
+      clearSessionHooks(rootSetAppState, agentId)
+    }
+    // Clean up prompt cache tracking state for this agent
+    if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
+      cleanupAgentTracking(agentId)
+    }
+    // Release cloned file state cache memory
+    agentToolUseContext.readFileState.clear()
+    // Release the cloned fork context messages
+    initialMessages.length = 0
+    // Release perfetto agent registry entry
+    unregisterPerfettoAgent(agentId)
+    // Release transcript subdir mapping
+    clearAgentTranscriptSubdir(agentId)
+    // Release this agent's todos entry. Without this, every subagent that
+    // called TodoWrite leaves a key in AppState.todos forever (even after all
+    // items complete, the value is [] but the key stays). Whale sessions
+    // spawn hundreds of agents; each orphaned key is a small leak that adds up.
+    rootSetAppState(prev => {
+      if (!(agentId in prev.todos)) return prev
+      const { [agentId]: _removed, ...todos } = prev.todos
+      return { ...prev, todos }
+    })
+    // Kill any background bash tasks this agent spawned. Without this, a
+    // `run_in_background` shell loop (e.g. test fixture fake-logs.sh) outlives
+    // the agent as a PPID=1 zombie once the main session eventually exits.
+    killShellTasksForAgent(agentId, toolUseContext.getAppState, rootSetAppState)
+    /* eslint-disable @typescript-eslint/no-require-imports */
+    if (feature('MONITOR_TOOL')) {
+      const mcpMod =
+        require('../../tasks/MonitorMcpTask/MonitorMcpTask.js') as typeof import('../../tasks/MonitorMcpTask/MonitorMcpTask.js')
+      mcpMod.killMonitorMcpTasksForAgent(
+        agentId,
+        toolUseContext.getAppState,
+        rootSetAppState,
+      )
+    }
+    /* eslint-enable @typescript-eslint/no-require-imports */
+  }
+}
+
+/**
+ * Filters out assistant messages with incomplete tool calls (tool uses without results).
+ * This prevents API errors when sending messages with orphaned tool calls.
+ */
+export function filterIncompleteToolCalls(messages: Message[]): Message[] {
+  // Build a set of tool use IDs that have results
+  const toolUseIdsWithResults = new Set<string>()
+
+  for (const message of messages) {
+    if (message?.type === 'user') {
+      const userMessage = message as UserMessage
+      const content = userMessage.message.content
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'tool_result' && block.tool_use_id) {
+            toolUseIdsWithResults.add(block.tool_use_id)
+          }
+        }
+      }
+    }
+  }
+
+  // Filter out assistant messages that contain tool calls without results
+  return messages.filter(message => {
+    if (message?.type === 'assistant') {
+      const assistantMessage = message as AssistantMessage
+      const content = assistantMessage.message.content
+      if (Array.isArray(content)) {
+        // Check if this assistant message has any tool uses without results
+        const hasIncompleteToolCall = content.some(
+          block =>
+            block.type === 'tool_use' &&
+            block.id &&
+            !toolUseIdsWithResults.has(block.id),
+        )
+        // Exclude messages with incomplete tool calls
+        return !hasIncompleteToolCall
+      }
+    }
+    // Keep all non-assistant messages and assistant messages without tool calls
+    return true
+  })
+}
+
+async function getAgentSystemPrompt(
+  agentDefinition: AgentDefinition,
+  toolUseContext: Pick<ToolUseContext, 'options'>,
+  resolvedAgentModel: string,
+  additionalWorkingDirectories: string[],
+  resolvedTools: readonly Tool[],
+): Promise<string[]> {
+  const enabledToolNames = new Set(resolvedTools.map(t => t.name))
+  try {
+    const agentPrompt = agentDefinition.getSystemPrompt({ toolUseContext })
+    const prompts = [agentPrompt]
+
+    return await enhanceSystemPromptWithEnvDetails(
+      prompts,
+      resolvedAgentModel,
+      additionalWorkingDirectories,
+      enabledToolNames,
+    )
+  } catch (_error) {
+    return enhanceSystemPromptWithEnvDetails(
+      [DEFAULT_AGENT_PROMPT],
+      resolvedAgentModel,
+      additionalWorkingDirectories,
+      enabledToolNames,
+    )
+  }
+}
+
+/**
+ * Resolve a skill name from agent frontmatter to a registered command name.
+ *
+ * Plugin skills are registered with namespaced names (e.g., "my-plugin:my-skill")
+ * but agents reference them with bare names (e.g., "my-skill"). This function
+ * tries multiple resolution strategies:
+ *
+ * 1. Exact match via hasCommand (name, userFacingName, aliases)
+ * 2. Prefix with agent's plugin name (e.g., "my-skill" → "my-plugin:my-skill")
+ * 3. Suffix match — find any command whose name ends with ":skillName"
+ */
+function resolveSkillName(
+  skillName: string,
+  allSkills: Command[],
+  agentDefinition: AgentDefinition,
+): string | null {
+  // 1. Direct match
+  if (hasCommand(skillName, allSkills)) {
+    return skillName
+  }
+
+  // 2. Try prefixing with the agent's plugin name
+  // Plugin agents have agentType like "pluginName:agentName"
+  const pluginPrefix = agentDefinition.agentType.split(':')[0]
+  if (pluginPrefix) {
+    const qualifiedName = `${pluginPrefix}:${skillName}`
+    if (hasCommand(qualifiedName, allSkills)) {
+      return qualifiedName
+    }
+  }
+
+  // 3. Suffix match — find a skill whose name ends with ":skillName"
+  const suffix = `:${skillName}`
+  const match = allSkills.find(cmd => cmd.name.endsWith(suffix))
+  if (match) {
+    return match.name
+  }
+
+  return null
+}

src/tools/AskUserQuestionTool/prompt.ts

@@ -0,0 +1,44 @@
+import { EXIT_PLAN_MODE_TOOL_NAME } from '../ExitPlanModeTool/constants.js'
+
+export const ASK_USER_QUESTION_TOOL_NAME = 'AskUserQuestion'
+
+export const ASK_USER_QUESTION_TOOL_CHIP_WIDTH = 12
+
+export const DESCRIPTION =
+  'Asks the user multiple choice questions to gather information, clarify ambiguity, understand preferences, make decisions or offer them choices.'
+
+export const PREVIEW_FEATURE_PROMPT = {
+  markdown: `
+Preview feature:
+Use the optional \`preview\` field on options when presenting concrete artifacts that users need to visually compare:
+- ASCII mockups of UI layouts or components
+- Code snippets showing different implementations
+- Diagram variations
+- Configuration examples
+
+Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
+`,
+  html: `
+Preview feature:
+Use the optional \`preview\` field on options when presenting concrete artifacts that users need to visually compare:
+- HTML mockups of UI layouts or components
+- Formatted code snippets showing different implementations
+- Visual comparisons or diagrams
+
+Preview content must be a self-contained HTML fragment (no <html>/<body> wrapper, no <script> or <style> tags — use inline style attributes instead). Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
+`,
+} as const
+
+export const ASK_USER_QUESTION_TOOL_PROMPT = `Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+
+Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ${EXIT_PLAN_MODE_TOOL_NAME} for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g., "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ${EXIT_PLAN_MODE_TOOL_NAME}. If you need plan approval, use ${EXIT_PLAN_MODE_TOOL_NAME} instead.
+`

src/tools/BashTool/bashCommandHelpers.ts

@@ -0,0 +1,265 @@
+import type { z } from 'zod/v4'
+import {
+  isUnsafeCompoundCommand_DEPRECATED,
+  splitCommand_DEPRECATED,
+} from '../../utils/bash/commands.js'
+import {
+  buildParsedCommandFromRoot,
+  type IParsedCommand,
+  ParsedCommand,
+} from '../../utils/bash/ParsedCommand.js'
+import { type Node, PARSE_ABORTED } from '../../utils/bash/parser.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+import type { PermissionUpdate } from '../../utils/permissions/PermissionUpdateSchema.js'
+import { createPermissionRequestMessage } from '../../utils/permissions/permissions.js'
+import { BashTool } from './BashTool.js'
+import { bashCommandIsSafeAsync_DEPRECATED } from './bashSecurity.js'
+
+export type CommandIdentityCheckers = {
+  isNormalizedCdCommand: (command: string) => boolean
+  isNormalizedGitCommand: (command: string) => boolean
+}
+
+async function segmentedCommandPermissionResult(
+  input: z.infer<typeof BashTool.inputSchema>,
+  segments: string[],
+  bashToolHasPermissionFn: (
+    input: z.infer<typeof BashTool.inputSchema>,
+  ) => Promise<PermissionResult>,
+  checkers: CommandIdentityCheckers,
+): Promise<PermissionResult> {
+  // Check for multiple cd commands across all segments
+  const cdCommands = segments.filter(segment => {
+    const trimmed = segment.trim()
+    return checkers.isNormalizedCdCommand(trimmed)
+  })
+  if (cdCommands.length > 1) {
+    const decisionReason = {
+      type: 'other' as const,
+      reason:
+        'Multiple directory changes in one command require approval for clarity',
+    }
+    return {
+      behavior: 'ask',
+      decisionReason,
+      message: createPermissionRequestMessage(BashTool.name, decisionReason),
+    }
+  }
+
+  // SECURITY: Check for cd+git across pipe segments to prevent bare repo fsmonitor bypass.
+  // When cd and git are in different pipe segments (e.g., "cd sub && echo | git status"),
+  // each segment is checked independently and neither triggers the cd+git check in
+  // bashPermissions.ts. We must detect this cross-segment pattern here.
+  // Each pipe segment can itself be a compound command (e.g., "cd sub && echo"),
+  // so we split each segment into subcommands before checking.
+  {
+    let hasCd = false
+    let hasGit = false
+    for (const segment of segments) {
+      const subcommands = splitCommand_DEPRECATED(segment)
+      for (const sub of subcommands) {
+        const trimmed = sub.trim()
+        if (checkers.isNormalizedCdCommand(trimmed)) {
+          hasCd = true
+        }
+        if (checkers.isNormalizedGitCommand(trimmed)) {
+          hasGit = true
+        }
+      }
+    }
+    if (hasCd && hasGit) {
+      const decisionReason = {
+        type: 'other' as const,
+        reason:
+          'Compound commands with cd and git require approval to prevent bare repository attacks',
+      }
+      return {
+        behavior: 'ask',
+        decisionReason,
+        message: createPermissionRequestMessage(BashTool.name, decisionReason),
+      }
+    }
+  }
+
+  const segmentResults = new Map<string, PermissionResult>()
+
+  // Check each segment through the full permission system
+  for (const segment of segments) {
+    const trimmedSegment = segment.trim()
+    if (!trimmedSegment) continue // Skip empty segments
+
+    const segmentResult = await bashToolHasPermissionFn({
+      ...input,
+      command: trimmedSegment,
+    })
+    segmentResults.set(trimmedSegment, segmentResult)
+  }
+
+  // Check if any segment is denied (after evaluating all)
+  const deniedSegment = Array.from(segmentResults.entries()).find(
+    ([, result]) => result.behavior === 'deny',
+  )
+
+  if (deniedSegment) {
+    const [segmentCommand, segmentResult] = deniedSegment
+    return {
+      behavior: 'deny',
+      message:
+        segmentResult.behavior === 'deny'
+          ? segmentResult.message
+          : `Permission denied for: ${segmentCommand}`,
+      decisionReason: {
+        type: 'subcommandResults',
+        reasons: segmentResults,
+      },
+    }
+  }
+
+  const allAllowed = Array.from(segmentResults.values()).every(
+    result => result.behavior === 'allow',
+  )
+
+  if (allAllowed) {
+    return {
+      behavior: 'allow',
+      updatedInput: input,
+      decisionReason: {
+        type: 'subcommandResults',
+        reasons: segmentResults,
+      },
+    }
+  }
+
+  // Collect suggestions from segments that need approval
+  const suggestions: PermissionUpdate[] = []
+  for (const [, result] of segmentResults) {
+    if (
+      result.behavior !== 'allow' &&
+      'suggestions' in result &&
+      result.suggestions
+    ) {
+      suggestions.push(...result.suggestions)
+    }
+  }
+
+  const decisionReason = {
+    type: 'subcommandResults' as const,
+    reasons: segmentResults,
+  }
+
+  return {
+    behavior: 'ask',
+    message: createPermissionRequestMessage(BashTool.name, decisionReason),
+    decisionReason,
+    suggestions: suggestions.length > 0 ? suggestions : undefined,
+  }
+}
+
+/**
+ * Builds a command segment, stripping output redirections to avoid
+ * treating filenames as commands in permission checking.
+ * Uses ParsedCommand to preserve original quoting.
+ */
+async function buildSegmentWithoutRedirections(
+  segmentCommand: string,
+): Promise<string> {
+  // Fast path: skip parsing if no redirection operators present
+  if (!segmentCommand.includes('>')) {
+    return segmentCommand
+  }
+
+  // Use ParsedCommand to strip redirections while preserving quotes
+  const parsed = await ParsedCommand.parse(segmentCommand)
+  return parsed?.withoutOutputRedirections() ?? segmentCommand
+}
+
+/**
+ * Wrapper that resolves an IParsedCommand (from a pre-parsed AST root if
+ * available, else via ParsedCommand.parse) and delegates to
+ * bashToolCheckCommandOperatorPermissions.
+ */
+export async function checkCommandOperatorPermissions(
+  input: z.infer<typeof BashTool.inputSchema>,
+  bashToolHasPermissionFn: (
+    input: z.infer<typeof BashTool.inputSchema>,
+  ) => Promise<PermissionResult>,
+  checkers: CommandIdentityCheckers,
+  astRoot: Node | null | typeof PARSE_ABORTED,
+): Promise<PermissionResult> {
+  const parsed =
+    astRoot && astRoot !== PARSE_ABORTED
+      ? buildParsedCommandFromRoot(input.command, astRoot)
+      : await ParsedCommand.parse(input.command)
+  if (!parsed) {
+    return { behavior: 'passthrough', message: 'Failed to parse command' }
+  }
+  return bashToolCheckCommandOperatorPermissions(
+    input,
+    bashToolHasPermissionFn,
+    checkers,
+    parsed,
+  )
+}
+
+/**
+ * Checks if the command has special operators that require behavior beyond
+ * simple subcommand checking.
+ */
+async function bashToolCheckCommandOperatorPermissions(
+  input: z.infer<typeof BashTool.inputSchema>,
+  bashToolHasPermissionFn: (
+    input: z.infer<typeof BashTool.inputSchema>,
+  ) => Promise<PermissionResult>,
+  checkers: CommandIdentityCheckers,
+  parsed: IParsedCommand,
+): Promise<PermissionResult> {
+  // 1. Check for unsafe compound commands (subshells, command groups).
+  const tsAnalysis = parsed.getTreeSitterAnalysis()
+  const isUnsafeCompound = tsAnalysis
+    ? tsAnalysis.compoundStructure.hasSubshell ||
+      tsAnalysis.compoundStructure.hasCommandGroup
+    : isUnsafeCompoundCommand_DEPRECATED(input.command)
+  if (isUnsafeCompound) {
+    // This command contains an operator like `>` that we don't support as a subcommand separator
+    // Check if bashCommandIsSafe_DEPRECATED has a more specific message
+    const safetyResult = await bashCommandIsSafeAsync_DEPRECATED(input.command)
+
+    const decisionReason = {
+      type: 'other' as const,
+      reason:
+        safetyResult.behavior === 'ask' && safetyResult.message
+          ? safetyResult.message
+          : 'This command uses shell operators that require approval for safety',
+    }
+    return {
+      behavior: 'ask',
+      message: createPermissionRequestMessage(BashTool.name, decisionReason),
+      decisionReason,
+      // This is an unsafe compound command, so we don't want to suggest rules since we wont be able to allow it
+    }
+  }
+
+  // 2. Check for piped commands using ParsedCommand (preserves quotes)
+  const pipeSegments = parsed.getPipeSegments()
+
+  // If no pipes (single segment), let normal flow handle it
+  if (pipeSegments.length <= 1) {
+    return {
+      behavior: 'passthrough',
+      message: 'No pipes found in command',
+    }
+  }
+
+  // Strip output redirections from each segment while preserving quotes
+  const segments = await Promise.all(
+    pipeSegments.map(segment => buildSegmentWithoutRedirections(segment)),
+  )
+
+  // Handle as segmented command
+  return segmentedCommandPermissionResult(
+    input,
+    segments,
+    bashToolHasPermissionFn,
+    checkers,
+  )
+}

src/tools/BashTool/commandSemantics.ts

@@ -0,0 +1,140 @@
+/**
+ * Command semantics configuration for interpreting exit codes in different contexts.
+ *
+ * Many commands use exit codes to convey information other than just success/failure.
+ * For example, grep returns 1 when no matches are found, which is not an error condition.
+ */
+
+import { splitCommand_DEPRECATED } from '../../utils/bash/commands.js'
+
+export type CommandSemantic = (
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+) => {
+  isError: boolean
+  message?: string
+}
+
+/**
+ * Default semantic: treat only 0 as success, everything else as error
+ */
+const DEFAULT_SEMANTIC: CommandSemantic = (exitCode, _stdout, _stderr) => ({
+  isError: exitCode !== 0,
+  message:
+    exitCode !== 0 ? `Command failed with exit code ${exitCode}` : undefined,
+})
+
+/**
+ * Command-specific semantics
+ */
+const COMMAND_SEMANTICS: Map<string, CommandSemantic> = new Map([
+  // grep: 0=matches found, 1=no matches, 2+=error
+  [
+    'grep',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message: exitCode === 1 ? 'No matches found' : undefined,
+    }),
+  ],
+
+  // ripgrep has same semantics as grep
+  [
+    'rg',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message: exitCode === 1 ? 'No matches found' : undefined,
+    }),
+  ],
+
+  // find: 0=success, 1=partial success (some dirs inaccessible), 2+=error
+  [
+    'find',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message:
+        exitCode === 1 ? 'Some directories were inaccessible' : undefined,
+    }),
+  ],
+
+  // diff: 0=no differences, 1=differences found, 2+=error
+  [
+    'diff',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message: exitCode === 1 ? 'Files differ' : undefined,
+    }),
+  ],
+
+  // test/[: 0=condition true, 1=condition false, 2+=error
+  [
+    'test',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message: exitCode === 1 ? 'Condition is false' : undefined,
+    }),
+  ],
+
+  // [ is an alias for test
+  [
+    '[',
+    (exitCode, _stdout, _stderr) => ({
+      isError: exitCode >= 2,
+      message: exitCode === 1 ? 'Condition is false' : undefined,
+    }),
+  ],
+
+  // wc, head, tail, cat, etc.: these typically only fail on real errors
+  // so we use default semantics
+])
+
+/**
+ * Get the semantic interpretation for a command
+ */
+function getCommandSemantic(command: string): CommandSemantic {
+  // Extract the base command (first word, handling pipes)
+  const baseCommand = heuristicallyExtractBaseCommand(command)
+  const semantic = COMMAND_SEMANTICS.get(baseCommand)
+  return semantic !== undefined ? semantic : DEFAULT_SEMANTIC
+}
+
+/**
+ * Extract just the command name (first word) from a single command string.
+ */
+function extractBaseCommand(command: string): string {
+  return command.trim().split(/\s+/)[0] || ''
+}
+
+/**
+ * Extract the primary command from a complex command line;
+ * May get it super wrong - don't depend on this for security
+ */
+function heuristicallyExtractBaseCommand(command: string): string {
+  const segments = splitCommand_DEPRECATED(command)
+
+  // Take the last command as that's what determines the exit code
+  const lastCommand = segments[segments.length - 1] || command
+
+  return extractBaseCommand(lastCommand)
+}
+
+/**
+ * Interpret command result based on semantic rules
+ */
+export function interpretCommandResult(
+  command: string,
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+): {
+  isError: boolean
+  message?: string
+} {
+  const semantic = getCommandSemantic(command)
+  const result = semantic(exitCode, stdout, stderr)
+
+  return {
+    isError: result.isError,
+    message: result.message,
+  }
+}

src/tools/BashTool/commentLabel.ts

@@ -0,0 +1,13 @@
+/**
+ * If the first line of a bash command is a `# comment` (not a `#!` shebang),
+ * return the comment text stripped of the `#` prefix. Otherwise undefined.
+ *
+ * Under fullscreen mode this is the non-verbose tool-use label AND the
+ * collapse-group ⎿ hint — it's what Claude wrote for the human to read.
+ */
+export function extractBashCommentLabel(command: string): string | undefined {
+  const nl = command.indexOf('\n')
+  const firstLine = (nl === -1 ? command : command.slice(0, nl)).trim()
+  if (!firstLine.startsWith('#') || firstLine.startsWith('#!')) return undefined
+  return firstLine.replace(/^#+\s*/, '') || undefined
+}

src/tools/BashTool/destructiveCommandWarning.ts

@@ -0,0 +1,102 @@
+/**
+ * Detects potentially destructive bash commands and returns a warning string
+ * for display in the permission dialog. This is purely informational — it
+ * doesn't affect permission logic or auto-approval.
+ */
+
+type DestructivePattern = {
+  pattern: RegExp
+  warning: string
+}
+
+const DESTRUCTIVE_PATTERNS: DestructivePattern[] = [
+  // Git — data loss / hard to reverse
+  {
+    pattern: /\bgit\s+reset\s+--hard\b/,
+    warning: 'Note: may discard uncommitted changes',
+  },
+  {
+    pattern: /\bgit\s+push\b[^;&|\n]*[ \t](--force|--force-with-lease|-f)\b/,
+    warning: 'Note: may overwrite remote history',
+  },
+  {
+    pattern:
+      /\bgit\s+clean\b(?![^;&|\n]*(?:-[a-zA-Z]*n|--dry-run))[^;&|\n]*-[a-zA-Z]*f/,
+    warning: 'Note: may permanently delete untracked files',
+  },
+  {
+    pattern: /\bgit\s+checkout\s+(--\s+)?\.[ \t]*($|[;&|\n])/,
+    warning: 'Note: may discard all working tree changes',
+  },
+  {
+    pattern: /\bgit\s+restore\s+(--\s+)?\.[ \t]*($|[;&|\n])/,
+    warning: 'Note: may discard all working tree changes',
+  },
+  {
+    pattern: /\bgit\s+stash[ \t]+(drop|clear)\b/,
+    warning: 'Note: may permanently remove stashed changes',
+  },
+  {
+    pattern:
+      /\bgit\s+branch\s+(-D[ \t]|--delete\s+--force|--force\s+--delete)\b/,
+    warning: 'Note: may force-delete a branch',
+  },
+
+  // Git — safety bypass
+  {
+    pattern: /\bgit\s+(commit|push|merge)\b[^;&|\n]*--no-verify\b/,
+    warning: 'Note: may skip safety hooks',
+  },
+  {
+    pattern: /\bgit\s+commit\b[^;&|\n]*--amend\b/,
+    warning: 'Note: may rewrite the last commit',
+  },
+
+  // File deletion (dangerous paths already handled by checkDangerousRemovalPaths)
+  {
+    pattern:
+      /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*[rR][a-zA-Z]*f|(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*f[a-zA-Z]*[rR]/,
+    warning: 'Note: may recursively force-remove files',
+  },
+  {
+    pattern: /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*[rR]/,
+    warning: 'Note: may recursively remove files',
+  },
+  {
+    pattern: /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*f/,
+    warning: 'Note: may force-remove files',
+  },
+
+  // Database
+  {
+    pattern: /\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i,
+    warning: 'Note: may drop or truncate database objects',
+  },
+  {
+    pattern: /\bDELETE\s+FROM\s+\w+[ \t]*(;|"|'|\n|$)/i,
+    warning: 'Note: may delete all rows from a database table',
+  },
+
+  // Infrastructure
+  {
+    pattern: /\bkubectl\s+delete\b/,
+    warning: 'Note: may delete Kubernetes resources',
+  },
+  {
+    pattern: /\bterraform\s+destroy\b/,
+    warning: 'Note: may destroy Terraform infrastructure',
+  },
+]
+
+/**
+ * Checks if a bash command matches known destructive patterns.
+ * Returns a human-readable warning string, or null if no destructive pattern is detected.
+ */
+export function getDestructiveCommandWarning(command: string): string | null {
+  for (const { pattern, warning } of DESTRUCTIVE_PATTERNS) {
+    if (pattern.test(command)) {
+      return warning
+    }
+  }
+  return null
+}

src/tools/BashTool/modeValidation.ts

@@ -0,0 +1,115 @@
+import type { z } from 'zod/v4'
+import type { ToolPermissionContext } from '../../Tool.js'
+import { splitCommand_DEPRECATED } from '../../utils/bash/commands.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+import type { BashTool } from './BashTool.js'
+
+const ACCEPT_EDITS_ALLOWED_COMMANDS = [
+  'mkdir',
+  'touch',
+  'rm',
+  'rmdir',
+  'mv',
+  'cp',
+  'sed',
+] as const
+
+type FilesystemCommand = (typeof ACCEPT_EDITS_ALLOWED_COMMANDS)[number]
+
+function isFilesystemCommand(command: string): command is FilesystemCommand {
+  return ACCEPT_EDITS_ALLOWED_COMMANDS.includes(command as FilesystemCommand)
+}
+
+function validateCommandForMode(
+  cmd: string,
+  toolPermissionContext: ToolPermissionContext,
+): PermissionResult {
+  const trimmedCmd = cmd.trim()
+  const [baseCmd] = trimmedCmd.split(/\s+/)
+
+  if (!baseCmd) {
+    return {
+      behavior: 'passthrough',
+      message: 'Base command not found',
+    }
+  }
+
+  // In Accept Edits mode, auto-allow filesystem operations
+  if (
+    toolPermissionContext.mode === 'acceptEdits' &&
+    isFilesystemCommand(baseCmd)
+  ) {
+    return {
+      behavior: 'allow',
+      updatedInput: { command: cmd },
+      decisionReason: {
+        type: 'mode',
+        mode: 'acceptEdits',
+      },
+    }
+  }
+
+  return {
+    behavior: 'passthrough',
+    message: `No mode-specific handling for '${baseCmd}' in ${toolPermissionContext.mode} mode`,
+  }
+}
+
+/**
+ * Checks if commands should be handled differently based on the current permission mode
+ *
+ * This is the main entry point for mode-based permission logic.
+ * Currently handles Accept Edits mode for filesystem commands,
+ * but designed to be extended for other modes.
+ *
+ * @param input - The bash command input
+ * @param toolPermissionContext - Context containing mode and permissions
+ * @returns
+ * - 'allow' if the current mode permits auto-approval
+ * - 'ask' if the command needs approval in current mode
+ * - 'passthrough' if no mode-specific handling applies
+ */
+export function checkPermissionMode(
+  input: z.infer<typeof BashTool.inputSchema>,
+  toolPermissionContext: ToolPermissionContext,
+): PermissionResult {
+  // Skip if in bypass mode (handled elsewhere)
+  if (toolPermissionContext.mode === 'bypassPermissions') {
+    return {
+      behavior: 'passthrough',
+      message: 'Bypass mode is handled in main permission flow',
+    }
+  }
+
+  // Skip if in dontAsk mode (handled in main permission flow)
+  if (toolPermissionContext.mode === 'dontAsk') {
+    return {
+      behavior: 'passthrough',
+      message: 'DontAsk mode is handled in main permission flow',
+    }
+  }
+
+  const commands = splitCommand_DEPRECATED(input.command)
+
+  // Check each subcommand
+  for (const cmd of commands) {
+    const result = validateCommandForMode(cmd, toolPermissionContext)
+
+    // If any command triggers mode-specific behavior, return that result
+    if (result.behavior !== 'passthrough') {
+      return result
+    }
+  }
+
+  // No mode-specific handling needed
+  return {
+    behavior: 'passthrough',
+    message: 'No mode-specific validation required',
+  }
+}
+
+export function getAutoAllowedCommands(
+  mode: ToolPermissionContext['mode'],
+): readonly string[] {
+  return mode === 'acceptEdits' ? ACCEPT_EDITS_ALLOWED_COMMANDS : []
+}

src/tools/BashTool/prompt.ts

@@ -0,0 +1,369 @@
+import { feature } from 'bun:bundle'
+import { prependBullets } from '../../constants/prompts.js'
+import { getAttributionTexts } from '../../utils/attribution.js'
+import { hasEmbeddedSearchTools } from '../../utils/embeddedTools.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { shouldIncludeGitInstructions } from '../../utils/gitSettings.js'
+import { getClaudeTempDir } from '../../utils/permissions/filesystem.js'
+import { SandboxManager } from '../../utils/sandbox/sandbox-adapter.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import {
+  getDefaultBashTimeoutMs,
+  getMaxBashTimeoutMs,
+} from '../../utils/timeouts.js'
+import {
+  getUndercoverInstructions,
+  isUndercover,
+} from '../../utils/undercover.js'
+import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'
+import { FILE_EDIT_TOOL_NAME } from '../FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from '../FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from '../GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from '../GrepTool/prompt.js'
+import { TodoWriteTool } from '../TodoWriteTool/TodoWriteTool.js'
+import { BASH_TOOL_NAME } from './toolName.js'
+
+export function getDefaultTimeoutMs(): number {
+  return getDefaultBashTimeoutMs()
+}
+
+export function getMaxTimeoutMs(): number {
+  return getMaxBashTimeoutMs()
+}
+
+function getBackgroundUsageNote(): string | null {
+  if (isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS)) {
+    return null
+  }
+  return "You can use the `run_in_background` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter."
+}
+
+function getCommitAndPRInstructions(): string {
+  // Defense-in-depth: undercover instructions must survive even if the user
+  // has disabled git instructions entirely. Attribution stripping and model-ID
+  // hiding are mechanical and work regardless, but the explicit "don't blow
+  // your cover" instructions are the last line of defense against the model
+  // volunteering an internal codename in a commit message.
+  const undercoverSection =
+    process.env.USER_TYPE === 'ant' && isUndercover()
+      ? getUndercoverInstructions() + '\n'
+      : ''
+
+  if (!shouldIncludeGitInstructions()) return undercoverSection
+
+  // For ant users, use the short version pointing to skills
+  if (process.env.USER_TYPE === 'ant') {
+    const skillsSection = !isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
+      ? `For git commits and pull requests, use the \`/commit\` and \`/commit-push-pr\` skills:
+- \`/commit\` - Create a git commit with staged changes
+- \`/commit-push-pr\` - Commit, push, and create a pull request
+
+These skills handle git safety protocols, proper commit message formatting, and PR creation.
+
+Before creating a pull request, run \`/simplify\` to review your changes, then test end-to-end (e.g. via \`/tmux\` for interactive features).
+
+`
+      : ''
+    return `${undercoverSection}# Git operations
+
+${skillsSection}IMPORTANT: NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it.
+
+Use the gh command via the Bash tool for other GitHub-related tasks including working with issues, checks, and releases. If given a Github URL use the gh command to get the information needed.
+
+# Other common operations
+- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments`
+  }
+
+  // For external users, include full inline instructions
+  const { commit: commitAttribution, pr: prAttribution } = getAttributionTexts()
+
+  return `# Committing changes with git
+
+Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
+
+You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. The numbered steps below indicate which commands should be batched in parallel.
+
+Git Safety Protocol:
+- NEVER update the git config
+- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER run force push to main/master, warn the user if they request it
+- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
+- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
+- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
+
+1. Run the following bash commands in parallel, each using the ${BASH_TOOL_NAME} tool:
+  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
+  - Run a git diff command to see both staged and unstaged changes that will be committed.
+  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
+2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
+  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
+  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
+  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
+  - Ensure it accurately reflects the changes and their purpose
+3. Run the following commands in parallel:
+   - Add relevant untracked files to the staging area.
+   - Create the commit with a message${commitAttribution ? ` ending with:\n   ${commitAttribution}` : '.'}
+   - Run git status after the commit completes to verify success.
+   Note: git status depends on the commit completing, so run it sequentially after the commit.
+4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
+
+Important notes:
+- NEVER run additional commands to read or explore code, besides git bash commands
+- NEVER use the ${TodoWriteTool.name} or ${AGENT_TOOL_NAME} tools
+- DO NOT push to the remote repository unless the user explicitly asks you to do so
+- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
+- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
+- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
+- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
+<example>
+git commit -m "$(cat <<'EOF'
+   Commit message here.${commitAttribution ? `\n\n   ${commitAttribution}` : ''}
+   EOF
+   )"
+</example>
+
+# Creating pull requests
+Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+
+IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+
+1. Run the following bash commands in parallel using the ${BASH_TOOL_NAME} tool, in order to understand the current state of the branch since it diverged from the main branch:
+   - Run a git status command to see all untracked files (never use -uall flag)
+   - Run a git diff command to see both staged and unstaged changes that will be committed
+   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
+   - Run a git log command and \`git diff [base-branch]...HEAD\` to understand the full commit history for the current branch (from the time it diverged from the base branch)
+2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
+   - Keep the PR title short (under 70 characters)
+   - Use the description/body for details, not the title
+3. Run the following commands in parallel:
+   - Create new branch if needed
+   - Push to remote with -u flag if needed
+   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.
+<example>
+gh pr create --title "the pr title" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points>
+
+## Test plan
+[Bulleted markdown checklist of TODOs for testing the pull request...]${prAttribution ? `\n\n${prAttribution}` : ''}
+EOF
+)"
+</example>
+
+Important:
+- DO NOT use the ${TodoWriteTool.name} or ${AGENT_TOOL_NAME} tools
+- Return the PR URL when you're done, so the user can see it
+
+# Other common operations
+- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments`
+}
+
+// SandboxManager merges config from multiple sources (settings layers, defaults,
+// CLI flags) without deduping, so paths like ~/.cache appear 3× in allowOnly.
+// Dedup here before inlining into the prompt — affects only what the model sees,
+// not sandbox enforcement. Saves ~150-200 tokens/request when sandbox is enabled.
+function dedup<T>(arr: T[] | undefined): T[] | undefined {
+  if (!arr || arr.length === 0) return arr
+  return [...new Set(arr)]
+}
+
+function getSimpleSandboxSection(): string {
+  if (!SandboxManager.isSandboxingEnabled()) {
+    return ''
+  }
+
+  const fsReadConfig = SandboxManager.getFsReadConfig()
+  const fsWriteConfig = SandboxManager.getFsWriteConfig()
+  const networkRestrictionConfig = SandboxManager.getNetworkRestrictionConfig()
+  const allowUnixSockets = SandboxManager.getAllowUnixSockets()
+  const ignoreViolations = SandboxManager.getIgnoreViolations()
+  const allowUnsandboxedCommands =
+    SandboxManager.areUnsandboxedCommandsAllowed()
+
+  // Replace the per-UID temp dir literal (e.g. /private/tmp/claude-1001/) with
+  // "$TMPDIR" so the prompt is identical across users — avoids busting the
+  // cross-user global prompt cache. The sandbox already sets $TMPDIR at runtime.
+  const claudeTempDir = getClaudeTempDir()
+  const normalizeAllowOnly = (paths: string[]): string[] =>
+    [...new Set(paths)].map(p => (p === claudeTempDir ? '$TMPDIR' : p))
+
+  const filesystemConfig = {
+    read: {
+      denyOnly: dedup(fsReadConfig.denyOnly),
+      ...(fsReadConfig.allowWithinDeny && {
+        allowWithinDeny: dedup(fsReadConfig.allowWithinDeny),
+      }),
+    },
+    write: {
+      allowOnly: normalizeAllowOnly(fsWriteConfig.allowOnly),
+      denyWithinAllow: dedup(fsWriteConfig.denyWithinAllow),
+    },
+  }
+
+  const networkConfig = {
+    ...(networkRestrictionConfig?.allowedHosts && {
+      allowedHosts: dedup(networkRestrictionConfig.allowedHosts),
+    }),
+    ...(networkRestrictionConfig?.deniedHosts && {
+      deniedHosts: dedup(networkRestrictionConfig.deniedHosts),
+    }),
+    ...(allowUnixSockets && { allowUnixSockets: dedup(allowUnixSockets) }),
+  }
+
+  const restrictionsLines = []
+  if (Object.keys(filesystemConfig).length > 0) {
+    restrictionsLines.push(`Filesystem: ${jsonStringify(filesystemConfig)}`)
+  }
+  if (Object.keys(networkConfig).length > 0) {
+    restrictionsLines.push(`Network: ${jsonStringify(networkConfig)}`)
+  }
+  if (ignoreViolations) {
+    restrictionsLines.push(
+      `Ignored violations: ${jsonStringify(ignoreViolations)}`,
+    )
+  }
+
+  const sandboxOverrideItems: Array<string | string[]> =
+    allowUnsandboxedCommands
+      ? [
+          'You should always default to running commands within the sandbox. Do NOT attempt to set `dangerouslyDisableSandbox: true` unless:',
+          [
+            'The user *explicitly* asks you to bypass sandbox',
+            'A specific command just failed and you see evidence of sandbox restrictions causing the failure. Note that commands can fail for many reasons unrelated to the sandbox (missing files, wrong arguments, network issues, etc.).',
+          ],
+          'Evidence of sandbox-caused failures includes:',
+          [
+            '"Operation not permitted" errors for file/network operations',
+            'Access denied to specific paths outside allowed directories',
+            'Network connection failures to non-whitelisted hosts',
+            'Unix socket connection errors',
+          ],
+          'When you see evidence of sandbox-caused failure:',
+          [
+            "Immediately retry with `dangerouslyDisableSandbox: true` (don't ask, just do it)",
+            'Briefly explain what sandbox restriction likely caused the failure. Be sure to mention that the user can use the `/sandbox` command to manage restrictions.',
+            'This will prompt the user for permission',
+          ],
+          'Treat each command you execute with `dangerouslyDisableSandbox: true` individually. Even if you have recently run a command with this setting, you should default to running future commands within the sandbox.',
+          'Do not suggest adding sensitive paths like ~/.bashrc, ~/.zshrc, ~/.ssh/*, or credential files to the sandbox allowlist.',
+        ]
+      : [
+          'All commands MUST run in sandbox mode - the `dangerouslyDisableSandbox` parameter is disabled by policy.',
+          'Commands cannot run outside the sandbox under any circumstances.',
+          'If a command fails due to sandbox restrictions, work with the user to adjust sandbox settings instead.',
+        ]
+
+  const items: Array<string | string[]> = [
+    ...sandboxOverrideItems,
+    'For temporary files, always use the `$TMPDIR` environment variable. TMPDIR is automatically set to the correct sandbox-writable directory in sandbox mode. Do NOT use `/tmp` directly - use `$TMPDIR` instead.',
+  ]
+
+  return [
+    '',
+    '## Command sandbox',
+    'By default, your command will be run in a sandbox. This sandbox controls which directories and network hosts commands may access or modify without an explicit override.',
+    '',
+    'The sandbox has the following restrictions:',
+    restrictionsLines.join('\n'),
+    '',
+    ...prependBullets(items),
+  ].join('\n')
+}
+
+export function getSimplePrompt(): string {
+  // Ant-native builds alias find/grep to embedded bfs/ugrep in Claude's shell,
+  // so we don't steer away from them (and Glob/Grep tools are removed).
+  const embedded = hasEmbeddedSearchTools()
+
+  const toolPreferenceItems = [
+    ...(embedded
+      ? []
+      : [
+          `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
+          `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
+        ]),
+    `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
+    `Edit files: Use ${FILE_EDIT_TOOL_NAME} (NOT sed/awk)`,
+    `Write files: Use ${FILE_WRITE_TOOL_NAME} (NOT echo >/cat <<EOF)`,
+    'Communication: Output text directly (NOT echo/printf)',
+  ]
+
+  const avoidCommands = embedded
+    ? '`cat`, `head`, `tail`, `sed`, `awk`, or `echo`'
+    : '`find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo`'
+
+  const multipleCommandsSubitems = [
+    `If the commands are independent and can run in parallel, make multiple ${BASH_TOOL_NAME} tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two ${BASH_TOOL_NAME} tool calls in parallel.`,
+    `If the commands depend on each other and must run sequentially, use a single ${BASH_TOOL_NAME} call with '&&' to chain them together.`,
+    "Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.",
+    'DO NOT use newlines to separate commands (newlines are ok in quoted strings).',
+  ]
+
+  const gitSubitems = [
+    'Prefer to create a new commit rather than amending an existing commit.',
+    'Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.',
+    'Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.',
+  ]
+
+  const sleepSubitems = [
+    'Do not sleep between commands that can run immediately — just run them.',
+    ...(feature('MONITOR_TOOL')
+      ? [
+          'Use the Monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use Bash with run_in_background instead.',
+        ]
+      : []),
+    'If your command is long running and you would like to be notified when it finishes — use `run_in_background`. No sleep needed.',
+    'Do not retry failing commands in a sleep loop — diagnose the root cause.',
+    'If waiting for a background task you started with `run_in_background`, you will be notified when it completes — do not poll.',
+    ...(feature('MONITOR_TOOL')
+      ? [
+          '`sleep N` as the first command with N ≥ 2 is blocked. If you need a delay (rate limiting, deliberate pacing), keep it under 2 seconds.',
+        ]
+      : [
+          'If you must poll an external process, use a check command (e.g. `gh run view`) rather than sleeping first.',
+          'If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.',
+        ]),
+  ]
+  const backgroundNote = getBackgroundUsageNote()
+
+  const instructionItems: Array<string | string[]> = [
+    'If your command will create new directories or files, first use this tool to run `ls` to verify the parent directory exists and is the correct location.',
+    'Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")',
+    'Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.',
+    `You may specify an optional timeout in milliseconds (up to ${getMaxTimeoutMs()}ms / ${getMaxTimeoutMs() / 60000} minutes). By default, your command will timeout after ${getDefaultTimeoutMs()}ms (${getDefaultTimeoutMs() / 60000} minutes).`,
+    ...(backgroundNote !== null ? [backgroundNote] : []),
+    'When issuing multiple commands:',
+    multipleCommandsSubitems,
+    'For git commands:',
+    gitSubitems,
+    'Avoid unnecessary `sleep` commands:',
+    sleepSubitems,
+    ...(embedded
+      ? [
+          // bfs (which backs `find`) uses Oniguruma for -regex, which picks the
+          // FIRST matching alternative (leftmost-first), unlike GNU find's
+          // POSIX leftmost-longest. This silently drops matches when a shorter
+          // alternative is a prefix of a longer one.
+          "When using `find -regex` with alternation, put the longest alternative first. Example: use `'.*\\.\\(tsx\\|ts\\)'` not `'.*\\.\\(ts\\|tsx\\)'` — the second form silently skips `.tsx` files.",
+        ]
+      : []),
+  ]
+
+  return [
+    'Executes a given bash command and returns its output.',
+    '',
+    "The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).",
+    '',
+    `IMPORTANT: Avoid using this tool to run ${avoidCommands} commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:`,
+    '',
+    ...prependBullets(toolPreferenceItems),
+    `While the ${BASH_TOOL_NAME} tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.`,
+    '',
+    '# Instructions',
+    ...prependBullets(instructionItems),
+    getSimpleSandboxSection(),
+    ...(getCommitAndPRInstructions() ? ['', getCommitAndPRInstructions()] : []),
+  ].join('\n')
+}

src/tools/BashTool/sedEditParser.ts

@@ -0,0 +1,322 @@
+/**
+ * Parser for sed edit commands (-i flag substitutions)
+ * Extracts file paths and substitution patterns to enable file-edit-style rendering
+ */
+
+import { randomBytes } from 'crypto'
+import { tryParseShellCommand } from '../../utils/bash/shellQuote.js'
+
+// BRE→ERE conversion placeholders (null-byte sentinels, never appear in user input)
+const BACKSLASH_PLACEHOLDER = '\x00BACKSLASH\x00'
+const PLUS_PLACEHOLDER = '\x00PLUS\x00'
+const QUESTION_PLACEHOLDER = '\x00QUESTION\x00'
+const PIPE_PLACEHOLDER = '\x00PIPE\x00'
+const LPAREN_PLACEHOLDER = '\x00LPAREN\x00'
+const RPAREN_PLACEHOLDER = '\x00RPAREN\x00'
+const BACKSLASH_PLACEHOLDER_RE = new RegExp(BACKSLASH_PLACEHOLDER, 'g')
+const PLUS_PLACEHOLDER_RE = new RegExp(PLUS_PLACEHOLDER, 'g')
+const QUESTION_PLACEHOLDER_RE = new RegExp(QUESTION_PLACEHOLDER, 'g')
+const PIPE_PLACEHOLDER_RE = new RegExp(PIPE_PLACEHOLDER, 'g')
+const LPAREN_PLACEHOLDER_RE = new RegExp(LPAREN_PLACEHOLDER, 'g')
+const RPAREN_PLACEHOLDER_RE = new RegExp(RPAREN_PLACEHOLDER, 'g')
+
+export type SedEditInfo = {
+  /** The file path being edited */
+  filePath: string
+  /** The search pattern (regex) */
+  pattern: string
+  /** The replacement string */
+  replacement: string
+  /** Substitution flags (g, i, etc.) */
+  flags: string
+  /** Whether to use extended regex (-E or -r flag) */
+  extendedRegex: boolean
+}
+
+/**
+ * Check if a command is a sed in-place edit command
+ * Returns true only for simple sed -i 's/pattern/replacement/flags' file commands
+ */
+export function isSedInPlaceEdit(command: string): boolean {
+  const info = parseSedEditCommand(command)
+  return info !== null
+}
+
+/**
+ * Parse a sed edit command and extract the edit information
+ * Returns null if the command is not a valid sed in-place edit
+ */
+export function parseSedEditCommand(command: string): SedEditInfo | null {
+  const trimmed = command.trim()
+
+  // Must start with sed
+  const sedMatch = trimmed.match(/^\s*sed\s+/)
+  if (!sedMatch) return null
+
+  const withoutSed = trimmed.slice(sedMatch[0].length)
+  const parseResult = tryParseShellCommand(withoutSed)
+  if (!parseResult.success) return null
+  const tokens = parseResult.tokens
+
+  // Extract string tokens only
+  const args: string[] = []
+  for (const token of tokens) {
+    if (typeof token === 'string') {
+      args.push(token)
+    } else if (
+      typeof token === 'object' &&
+      token !== null &&
+      'op' in token &&
+      token.op === 'glob'
+    ) {
+      // Glob patterns are too complex for this simple parser
+      return null
+    }
+  }
+
+  // Parse flags and arguments
+  let hasInPlaceFlag = false
+  let extendedRegex = false
+  let expression: string | null = null
+  let filePath: string | null = null
+
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]!
+
+    // Handle -i flag (with or without backup suffix)
+    if (arg === '-i' || arg === '--in-place') {
+      hasInPlaceFlag = true
+      i++
+      // On macOS, -i requires a suffix argument (even if empty string)
+      // Check if next arg looks like a backup suffix (empty, or starts with dot)
+      // Don't consume flags (-E, -r) or sed expressions (starting with s, y, d)
+      if (i < args.length) {
+        const nextArg = args[i]
+        // If next arg is empty string or starts with dot, it's a backup suffix
+        if (
+          typeof nextArg === 'string' &&
+          !nextArg.startsWith('-') &&
+          (nextArg === '' || nextArg.startsWith('.'))
+        ) {
+          i++ // Skip the backup suffix
+        }
+      }
+      continue
+    }
+    if (arg.startsWith('-i')) {
+      // -i.bak or similar (inline suffix)
+      hasInPlaceFlag = true
+      i++
+      continue
+    }
+
+    // Handle extended regex flags
+    if (arg === '-E' || arg === '-r' || arg === '--regexp-extended') {
+      extendedRegex = true
+      i++
+      continue
+    }
+
+    // Handle -e flag with expression
+    if (arg === '-e' || arg === '--expression') {
+      if (i + 1 < args.length && typeof args[i + 1] === 'string') {
+        // Only support single expression
+        if (expression !== null) return null
+        expression = args[i + 1]!
+        i += 2
+        continue
+      }
+      return null
+    }
+    if (arg.startsWith('--expression=')) {
+      if (expression !== null) return null
+      expression = arg.slice('--expression='.length)
+      i++
+      continue
+    }
+
+    // Skip other flags we don't understand
+    if (arg.startsWith('-')) {
+      // Unknown flag - not safe to parse
+      return null
+    }
+
+    // Non-flag argument
+    if (expression === null) {
+      // First non-flag arg is the expression
+      expression = arg
+    } else if (filePath === null) {
+      // Second non-flag arg is the file path
+      filePath = arg
+    } else {
+      // More than one file - not supported for simple rendering
+      return null
+    }
+
+    i++
+  }
+
+  // Must have -i flag, expression, and file path
+  if (!hasInPlaceFlag || !expression || !filePath) {
+    return null
+  }
+
+  // Parse the substitution expression: s/pattern/replacement/flags
+  // Only support / as delimiter for simplicity
+  const substMatch = expression.match(/^s\//)
+  if (!substMatch) {
+    return null
+  }
+
+  const rest = expression.slice(2) // Skip 's/'
+
+  // Find pattern and replacement by tracking escaped characters
+  let pattern = ''
+  let replacement = ''
+  let flags = ''
+  let state: 'pattern' | 'replacement' | 'flags' = 'pattern'
+  let j = 0
+
+  while (j < rest.length) {
+    const char = rest[j]!
+
+    if (char === '\\' && j + 1 < rest.length) {
+      // Escaped character
+      if (state === 'pattern') {
+        pattern += char + rest[j + 1]
+      } else if (state === 'replacement') {
+        replacement += char + rest[j + 1]
+      } else {
+        flags += char + rest[j + 1]
+      }
+      j += 2
+      continue
+    }
+
+    if (char === '/') {
+      if (state === 'pattern') {
+        state = 'replacement'
+      } else if (state === 'replacement') {
+        state = 'flags'
+      } else {
+        // Extra delimiter in flags - unexpected
+        return null
+      }
+      j++
+      continue
+    }
+
+    if (state === 'pattern') {
+      pattern += char
+    } else if (state === 'replacement') {
+      replacement += char
+    } else {
+      flags += char
+    }
+    j++
+  }
+
+  // Must have found all three parts (pattern, replacement delimiter, and optional flags)
+  if (state !== 'flags') {
+    return null
+  }
+
+  // Validate flags - only allow safe substitution flags
+  const validFlags = /^[gpimIM1-9]*$/
+  if (!validFlags.test(flags)) {
+    return null
+  }
+
+  return {
+    filePath,
+    pattern,
+    replacement,
+    flags,
+    extendedRegex,
+  }
+}
+
+/**
+ * Apply a sed substitution to file content
+ * Returns the new content after applying the substitution
+ */
+export function applySedSubstitution(
+  content: string,
+  sedInfo: SedEditInfo,
+): string {
+  // Convert sed pattern to JavaScript regex
+  let regexFlags = ''
+
+  // Handle global flag
+  if (sedInfo.flags.includes('g')) {
+    regexFlags += 'g'
+  }
+
+  // Handle case-insensitive flag (i or I in sed)
+  if (sedInfo.flags.includes('i') || sedInfo.flags.includes('I')) {
+    regexFlags += 'i'
+  }
+
+  // Handle multiline flag (m or M in sed)
+  if (sedInfo.flags.includes('m') || sedInfo.flags.includes('M')) {
+    regexFlags += 'm'
+  }
+
+  // Convert sed pattern to JavaScript regex pattern
+  let jsPattern = sedInfo.pattern
+    // Unescape \/ to /
+    .replace(/\\\//g, '/')
+
+  // In BRE mode (no -E flag), metacharacters have opposite escaping:
+  // BRE: \+ means "one or more", + is literal
+  // ERE/JS: + means "one or more", \+ is literal
+  // We need to convert BRE escaping to ERE for JavaScript regex
+  if (!sedInfo.extendedRegex) {
+    jsPattern = jsPattern
+      // Step 1: Protect literal backslashes (\\) first - in both BRE and ERE, \\ is literal backslash
+      .replace(/\\\\/g, BACKSLASH_PLACEHOLDER)
+      // Step 2: Replace escaped metacharacters with placeholders (these should become unescaped in JS)
+      .replace(/\\\+/g, PLUS_PLACEHOLDER)
+      .replace(/\\\?/g, QUESTION_PLACEHOLDER)
+      .replace(/\\\|/g, PIPE_PLACEHOLDER)
+      .replace(/\\\(/g, LPAREN_PLACEHOLDER)
+      .replace(/\\\)/g, RPAREN_PLACEHOLDER)
+      // Step 3: Escape unescaped metacharacters (these are literal in BRE)
+      .replace(/\+/g, '\\+')
+      .replace(/\?/g, '\\?')
+      .replace(/\|/g, '\\|')
+      .replace(/\(/g, '\\(')
+      .replace(/\)/g, '\\)')
+      // Step 4: Replace placeholders with their JS equivalents
+      .replace(BACKSLASH_PLACEHOLDER_RE, '\\\\')
+      .replace(PLUS_PLACEHOLDER_RE, '+')
+      .replace(QUESTION_PLACEHOLDER_RE, '?')
+      .replace(PIPE_PLACEHOLDER_RE, '|')
+      .replace(LPAREN_PLACEHOLDER_RE, '(')
+      .replace(RPAREN_PLACEHOLDER_RE, ')')
+  }
+
+  // Unescape sed-specific escapes in replacement
+  // Convert \n to newline, & to $& (match), etc.
+  // Use a unique placeholder with random salt to prevent injection attacks
+  const salt = randomBytes(8).toString('hex')
+  const ESCAPED_AMP_PLACEHOLDER = `___ESCAPED_AMPERSAND_${salt}___`
+  const jsReplacement = sedInfo.replacement
+    // Unescape \/ to /
+    .replace(/\\\//g, '/')
+    // First escape \& to a placeholder
+    .replace(/\\&/g, ESCAPED_AMP_PLACEHOLDER)
+    // Convert & to $& (full match) - use $$& to get literal $& in output
+    .replace(/&/g, '$$&')
+    // Convert placeholder back to literal &
+    .replace(new RegExp(ESCAPED_AMP_PLACEHOLDER, 'g'), '&')
+
+  try {
+    const regex = new RegExp(jsPattern, regexFlags)
+    return content.replace(regex, jsReplacement)
+  } catch {
+    // If regex is invalid, return original content
+    return content
+  }
+}

src/tools/BashTool/sedValidation.ts

@@ -0,0 +1,684 @@
+import type { ToolPermissionContext } from '../../Tool.js'
+import { splitCommand_DEPRECATED } from '../../utils/bash/commands.js'
+import { tryParseShellCommand } from '../../utils/bash/shellQuote.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+
+/**
+ * Helper: Validate flags against an allowlist
+ * Handles both single flags and combined flags (e.g., -nE)
+ * @param flags Array of flags to validate
+ * @param allowedFlags Array of allowed single-character and long flags
+ * @returns true if all flags are valid, false otherwise
+ */
+function validateFlagsAgainstAllowlist(
+  flags: string[],
+  allowedFlags: string[],
+): boolean {
+  for (const flag of flags) {
+    // Handle combined flags like -nE or -Er
+    if (flag.startsWith('-') && !flag.startsWith('--') && flag.length > 2) {
+      // Check each character in combined flag
+      for (let i = 1; i < flag.length; i++) {
+        const singleFlag = '-' + flag[i]
+        if (!allowedFlags.includes(singleFlag)) {
+          return false
+        }
+      }
+    } else {
+      // Single flag or long flag
+      if (!allowedFlags.includes(flag)) {
+        return false
+      }
+    }
+  }
+  return true
+}
+
+/**
+ * Pattern 1: Check if this is a line printing command with -n flag
+ * Allows: sed -n 'N' | sed -n 'N,M' with optional -E, -r, -z flags
+ * Allows semicolon-separated print commands like: sed -n '1p;2p;3p'
+ * File arguments are ALLOWED for this pattern
+ * @internal Exported for testing
+ */
+export function isLinePrintingCommand(
+  command: string,
+  expressions: string[],
+): boolean {
+  const sedMatch = command.match(/^\s*sed\s+/)
+  if (!sedMatch) return false
+
+  const withoutSed = command.slice(sedMatch[0].length)
+  const parseResult = tryParseShellCommand(withoutSed)
+  if (!parseResult.success) return false
+  const parsed = parseResult.tokens
+
+  // Extract all flags
+  const flags: string[] = []
+  for (const arg of parsed) {
+    if (typeof arg === 'string' && arg.startsWith('-') && arg !== '--') {
+      flags.push(arg)
+    }
+  }
+
+  // Validate flags - only allow -n, -E, -r, -z and their long forms
+  const allowedFlags = [
+    '-n',
+    '--quiet',
+    '--silent',
+    '-E',
+    '--regexp-extended',
+    '-r',
+    '-z',
+    '--zero-terminated',
+    '--posix',
+  ]
+
+  if (!validateFlagsAgainstAllowlist(flags, allowedFlags)) {
+    return false
+  }
+
+  // Check if -n flag is present (required for Pattern 1)
+  let hasNFlag = false
+  for (const flag of flags) {
+    if (flag === '-n' || flag === '--quiet' || flag === '--silent') {
+      hasNFlag = true
+      break
+    }
+    // Check in combined flags
+    if (flag.startsWith('-') && !flag.startsWith('--') && flag.includes('n')) {
+      hasNFlag = true
+      break
+    }
+  }
+
+  // Must have -n flag for Pattern 1
+  if (!hasNFlag) {
+    return false
+  }
+
+  // Must have at least one expression
+  if (expressions.length === 0) {
+    return false
+  }
+
+  // All expressions must be print commands (strict allowlist)
+  // Allow semicolon-separated commands
+  for (const expr of expressions) {
+    const commands = expr.split(';')
+    for (const cmd of commands) {
+      if (!isPrintCommand(cmd.trim())) {
+        return false
+      }
+    }
+  }
+
+  return true
+}
+
+/**
+ * Helper: Check if a single command is a valid print command
+ * STRICT ALLOWLIST - only these exact forms are allowed:
+ * - p (print all)
+ * - Np (print line N, where N is digits)
+ * - N,Mp (print lines N through M)
+ * Anything else (including w, W, e, E commands) is rejected.
+ * @internal Exported for testing
+ */
+export function isPrintCommand(cmd: string): boolean {
+  if (!cmd) return false
+  // Single strict regex that only matches allowed print commands
+  // ^(?:\d+|\d+,\d+)?p$ matches: p, 1p, 123p, 1,5p, 10,200p
+  return /^(?:\d+|\d+,\d+)?p$/.test(cmd)
+}
+
+/**
+ * Pattern 2: Check if this is a substitution command
+ * Allows: sed 's/pattern/replacement/flags' where flags are only: g, p, i, I, m, M, 1-9
+ * When allowFileWrites is true, allows -i flag and file arguments for in-place editing
+ * When allowFileWrites is false (default), requires stdout-only (no file arguments, no -i flag)
+ * @internal Exported for testing
+ */
+function isSubstitutionCommand(
+  command: string,
+  expressions: string[],
+  hasFileArguments: boolean,
+  options?: { allowFileWrites?: boolean },
+): boolean {
+  const allowFileWrites = options?.allowFileWrites ?? false
+
+  // When not allowing file writes, must NOT have file arguments
+  if (!allowFileWrites && hasFileArguments) {
+    return false
+  }
+
+  const sedMatch = command.match(/^\s*sed\s+/)
+  if (!sedMatch) return false
+
+  const withoutSed = command.slice(sedMatch[0].length)
+  const parseResult = tryParseShellCommand(withoutSed)
+  if (!parseResult.success) return false
+  const parsed = parseResult.tokens
+
+  // Extract all flags
+  const flags: string[] = []
+  for (const arg of parsed) {
+    if (typeof arg === 'string' && arg.startsWith('-') && arg !== '--') {
+      flags.push(arg)
+    }
+  }
+
+  // Validate flags based on mode
+  // Base allowed flags for both modes
+  const allowedFlags = ['-E', '--regexp-extended', '-r', '--posix']
+
+  // When allowing file writes, also permit -i and --in-place
+  if (allowFileWrites) {
+    allowedFlags.push('-i', '--in-place')
+  }
+
+  if (!validateFlagsAgainstAllowlist(flags, allowedFlags)) {
+    return false
+  }
+
+  // Must have exactly one expression
+  if (expressions.length !== 1) {
+    return false
+  }
+
+  const expr = expressions[0]!.trim()
+
+  // STRICT ALLOWLIST: Must be exactly a substitution command starting with 's'
+  // This rejects standalone commands like 'e', 'w file', etc.
+  if (!expr.startsWith('s')) {
+    return false
+  }
+
+  // Parse substitution: s/pattern/replacement/flags
+  // Only allow / as delimiter (strict)
+  const substitutionMatch = expr.match(/^s\/(.*?)$/)
+  if (!substitutionMatch) {
+    return false
+  }
+
+  const rest = substitutionMatch[1]!
+
+  // Find the positions of / delimiters
+  let delimiterCount = 0
+  let lastDelimiterPos = -1
+  let i = 0
+  while (i < rest.length) {
+    if (rest[i] === '\\') {
+      // Skip escaped character
+      i += 2
+      continue
+    }
+    if (rest[i] === '/') {
+      delimiterCount++
+      lastDelimiterPos = i
+    }
+    i++
+  }
+
+  // Must have found exactly 2 delimiters (pattern and replacement)
+  if (delimiterCount !== 2) {
+    return false
+  }
+
+  // Extract flags (everything after the last delimiter)
+  const exprFlags = rest.slice(lastDelimiterPos + 1)
+
+  // Validate flags: only allow g, p, i, I, m, M, and optionally ONE digit 1-9
+  const allowedFlagChars = /^[gpimIM]*[1-9]?[gpimIM]*$/
+  if (!allowedFlagChars.test(exprFlags)) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Checks if a sed command is allowed by the allowlist.
+ * The allowlist patterns themselves are strict enough to reject dangerous operations.
+ * @param command The sed command to check
+ * @param options.allowFileWrites When true, allows -i flag and file arguments for substitution commands
+ * @returns true if the command is allowed (matches allowlist and passes denylist check), false otherwise
+ */
+export function sedCommandIsAllowedByAllowlist(
+  command: string,
+  options?: { allowFileWrites?: boolean },
+): boolean {
+  const allowFileWrites = options?.allowFileWrites ?? false
+
+  // Extract sed expressions (content inside quotes where actual sed commands live)
+  let expressions: string[]
+  try {
+    expressions = extractSedExpressions(command)
+  } catch (_error) {
+    // If parsing failed, treat as not allowed
+    return false
+  }
+
+  // Check if sed command has file arguments
+  const hasFileArguments = hasFileArgs(command)
+
+  // Check if command matches allowlist patterns
+  let isPattern1 = false
+  let isPattern2 = false
+
+  if (allowFileWrites) {
+    // When allowing file writes, only check substitution commands (Pattern 2 variant)
+    // Pattern 1 (line printing) doesn't need file writes
+    isPattern2 = isSubstitutionCommand(command, expressions, hasFileArguments, {
+      allowFileWrites: true,
+    })
+  } else {
+    // Standard read-only mode: check both patterns
+    isPattern1 = isLinePrintingCommand(command, expressions)
+    isPattern2 = isSubstitutionCommand(command, expressions, hasFileArguments)
+  }
+
+  if (!isPattern1 && !isPattern2) {
+    return false
+  }
+
+  // Pattern 2 does not allow semicolons (command separators)
+  // Pattern 1 allows semicolons for separating print commands
+  for (const expr of expressions) {
+    if (isPattern2 && expr.includes(';')) {
+      return false
+    }
+  }
+
+  // Defense-in-depth: Even if allowlist matches, check denylist
+  for (const expr of expressions) {
+    if (containsDangerousOperations(expr)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Check if a sed command has file arguments (not just stdin)
+ * @internal Exported for testing
+ */
+export function hasFileArgs(command: string): boolean {
+  const sedMatch = command.match(/^\s*sed\s+/)
+  if (!sedMatch) return false
+
+  const withoutSed = command.slice(sedMatch[0].length)
+  const parseResult = tryParseShellCommand(withoutSed)
+  if (!parseResult.success) return true
+  const parsed = parseResult.tokens
+
+  try {
+    let argCount = 0
+    let hasEFlag = false
+
+    for (let i = 0; i < parsed.length; i++) {
+      const arg = parsed[i]
+
+      // Handle both string arguments and glob patterns (like *.log)
+      if (typeof arg !== 'string' && typeof arg !== 'object') continue
+
+      // If it's a glob pattern, it counts as a file argument
+      if (
+        typeof arg === 'object' &&
+        arg !== null &&
+        'op' in arg &&
+        arg.op === 'glob'
+      ) {
+        return true
+      }
+
+      // Skip non-string arguments that aren't glob patterns
+      if (typeof arg !== 'string') continue
+
+      // Handle -e flag followed by expression
+      if ((arg === '-e' || arg === '--expression') && i + 1 < parsed.length) {
+        hasEFlag = true
+        i++ // Skip the next argument since it's the expression
+        continue
+      }
+
+      // Handle --expression=value format
+      if (arg.startsWith('--expression=')) {
+        hasEFlag = true
+        continue
+      }
+
+      // Handle -e=value format (non-standard but defense in depth)
+      if (arg.startsWith('-e=')) {
+        hasEFlag = true
+        continue
+      }
+
+      // Skip other flags
+      if (arg.startsWith('-')) continue
+
+      argCount++
+
+      // If we used -e flags, ALL non-flag arguments are file arguments
+      if (hasEFlag) {
+        return true
+      }
+
+      // If we didn't use -e flags, the first non-flag argument is the sed expression,
+      // so we need more than 1 non-flag argument to have file arguments
+      if (argCount > 1) {
+        return true
+      }
+    }
+
+    return false
+  } catch (_error) {
+    return true // Assume dangerous if parsing fails
+  }
+}
+
+/**
+ * Extract sed expressions from command, ignoring flags and filenames
+ * @param command Full sed command
+ * @returns Array of sed expressions to check for dangerous operations
+ * @throws Error if parsing fails
+ * @internal Exported for testing
+ */
+export function extractSedExpressions(command: string): string[] {
+  const expressions: string[] = []
+
+  // Calculate withoutSed by trimming off the first N characters (removing 'sed ')
+  const sedMatch = command.match(/^\s*sed\s+/)
+  if (!sedMatch) return expressions
+
+  const withoutSed = command.slice(sedMatch[0].length)
+
+  // Reject dangerous flag combinations like -ew, -eW, -ee, -we (combined -e/-w with dangerous commands)
+  if (/-e[wWe]/.test(withoutSed) || /-w[eE]/.test(withoutSed)) {
+    throw new Error('Dangerous flag combination detected')
+  }
+
+  // Use shell-quote to parse the arguments properly
+  const parseResult = tryParseShellCommand(withoutSed)
+  if (!parseResult.success) {
+    // Malformed shell syntax - throw error to be caught by caller
+    throw new Error(`Malformed shell syntax: ${parseResult.error}`)
+  }
+  const parsed = parseResult.tokens
+  try {
+    let foundEFlag = false
+    let foundExpression = false
+
+    for (let i = 0; i < parsed.length; i++) {
+      const arg = parsed[i]
+
+      // Skip non-string arguments (like control operators)
+      if (typeof arg !== 'string') continue
+
+      // Handle -e flag followed by expression
+      if ((arg === '-e' || arg === '--expression') && i + 1 < parsed.length) {
+        foundEFlag = true
+        const nextArg = parsed[i + 1]
+        if (typeof nextArg === 'string') {
+          expressions.push(nextArg)
+          i++ // Skip the next argument since we consumed it
+        }
+        continue
+      }
+
+      // Handle --expression=value format
+      if (arg.startsWith('--expression=')) {
+        foundEFlag = true
+        expressions.push(arg.slice('--expression='.length))
+        continue
+      }
+
+      // Handle -e=value format (non-standard but defense in depth)
+      if (arg.startsWith('-e=')) {
+        foundEFlag = true
+        expressions.push(arg.slice('-e='.length))
+        continue
+      }
+
+      // Skip other flags
+      if (arg.startsWith('-')) continue
+
+      // If we haven't found any -e flags, the first non-flag argument is the sed expression
+      if (!foundEFlag && !foundExpression) {
+        expressions.push(arg)
+        foundExpression = true
+        continue
+      }
+
+      // If we've already found -e flags or a standalone expression,
+      // remaining non-flag arguments are filenames
+      break
+    }
+  } catch (error) {
+    // If shell-quote parsing fails, treat the sed command as unsafe
+    throw new Error(
+      `Failed to parse sed command: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    )
+  }
+
+  return expressions
+}
+
+/**
+ * Check if a sed expression contains dangerous operations (denylist)
+ * @param expression Single sed expression (without quotes)
+ * @returns true if dangerous, false if safe
+ */
+function containsDangerousOperations(expression: string): boolean {
+  const cmd = expression.trim()
+  if (!cmd) return false
+
+  // CONSERVATIVE REJECTIONS: Broadly reject patterns that could be dangerous
+  // When in doubt, treat as unsafe
+
+  // Reject non-ASCII characters (Unicode homoglyphs, combining chars, etc.)
+  // Examples: ｗ (fullwidth), ᴡ (small capital), w̃ (combining tilde)
+  // Check for characters outside ASCII range (0x01-0x7F, excluding null byte)
+  // eslint-disable-next-line no-control-regex
+  if (/[^\x01-\x7F]/.test(cmd)) {
+    return true
+  }
+
+  // Reject curly braces (blocks) - too complex to parse
+  if (cmd.includes('{') || cmd.includes('}')) {
+    return true
+  }
+
+  // Reject newlines - multi-line commands are too complex
+  if (cmd.includes('\n')) {
+    return true
+  }
+
+  // Reject comments (# not immediately after s command)
+  // Comments look like: #comment or start with #
+  // Delimiter looks like: s#pattern#replacement#
+  const hashIndex = cmd.indexOf('#')
+  if (hashIndex !== -1 && !(hashIndex > 0 && cmd[hashIndex - 1] === 's')) {
+    return true
+  }
+
+  // Reject negation operator
+  // Negation can appear: at start (!/pattern/), after address (/pattern/!, 1,10!, $!)
+  // Delimiter looks like: s!pattern!replacement! (has 's' before it)
+  if (/^!/.test(cmd) || /[/\d$]!/.test(cmd)) {
+    return true
+  }
+
+  // Reject tilde in GNU step address format (digit~digit, ,~digit, or $~digit)
+  // Allow whitespace around tilde
+  if (/\d\s*~\s*\d|,\s*~\s*\d|\$\s*~\s*\d/.test(cmd)) {
+    return true
+  }
+
+  // Reject comma at start (bare comma is shorthand for 1,$ address range)
+  if (/^,/.test(cmd)) {
+    return true
+  }
+
+  // Reject comma followed by +/- (GNU offset addresses)
+  if (/,\s*[+-]/.test(cmd)) {
+    return true
+  }
+
+  // Reject backslash tricks:
+  // 1. s\ (substitution with backslash delimiter)
+  // 2. \X where X could be an alternate delimiter (|, #, %, etc.) - not regex escapes
+  if (/s\\/.test(cmd) || /\\[|#%@]/.test(cmd)) {
+    return true
+  }
+
+  // Reject escaped slashes followed by w/W (patterns like /\/path\/to\/file/w)
+  if (/\\\/.*[wW]/.test(cmd)) {
+    return true
+  }
+
+  // Reject malformed/suspicious patterns we don't understand
+  // If there's a slash followed by non-slash chars, then whitespace, then dangerous commands
+  // Examples: /pattern w file, /pattern e cmd, /foo X;w file
+  if (/\/[^/]*\s+[wWeE]/.test(cmd)) {
+    return true
+  }
+
+  // Reject malformed substitution commands that don't follow normal pattern
+  // Examples: s/foobareoutput.txt (missing delimiters), s/foo/bar//w (extra delimiter)
+  if (/^s\//.test(cmd) && !/^s\/[^/]*\/[^/]*\/[^/]*$/.test(cmd)) {
+    return true
+  }
+
+  // PARANOID: Reject any command starting with 's' that ends with dangerous chars (w, W, e, E)
+  // and doesn't match our known safe substitution pattern. This catches malformed s commands
+  // with non-slash delimiters that might be trying to use dangerous flags.
+  if (/^s./.test(cmd) && /[wWeE]$/.test(cmd)) {
+    // Check if it's a properly formed substitution (any delimiter, not just /)
+    const properSubst = /^s([^\\\n]).*?\1.*?\1[^wWeE]*$/.test(cmd)
+    if (!properSubst) {
+      return true
+    }
+  }
+
+  // Check for dangerous write commands
+  // Patterns: [address]w filename, [address]W filename, /pattern/w filename, /pattern/W filename
+  // Simplified to avoid exponential backtracking (CodeQL issue)
+  // Check for w/W in contexts where it would be a command (with optional whitespace)
+  if (
+    /^[wW]\s*\S+/.test(cmd) || // At start: w file
+    /^\d+\s*[wW]\s*\S+/.test(cmd) || // After line number: 1w file or 1 w file
+    /^\$\s*[wW]\s*\S+/.test(cmd) || // After $: $w file or $ w file
+    /^\/[^/]*\/[IMim]*\s*[wW]\s*\S+/.test(cmd) || // After pattern: /pattern/w file
+    /^\d+,\d+\s*[wW]\s*\S+/.test(cmd) || // After range: 1,10w file
+    /^\d+,\$\s*[wW]\s*\S+/.test(cmd) || // After range: 1,$w file
+    /^\/[^/]*\/[IMim]*,\/[^/]*\/[IMim]*\s*[wW]\s*\S+/.test(cmd) // After pattern range: /s/,/e/w file
+  ) {
+    return true
+  }
+
+  // Check for dangerous execute commands
+  // Patterns: [address]e [command], /pattern/e [command], or commands starting with e
+  // Simplified to avoid exponential backtracking (CodeQL issue)
+  // Check for e in contexts where it would be a command (with optional whitespace)
+  if (
+    /^e/.test(cmd) || // At start: e cmd
+    /^\d+\s*e/.test(cmd) || // After line number: 1e or 1 e
+    /^\$\s*e/.test(cmd) || // After $: $e or $ e
+    /^\/[^/]*\/[IMim]*\s*e/.test(cmd) || // After pattern: /pattern/e
+    /^\d+,\d+\s*e/.test(cmd) || // After range: 1,10e
+    /^\d+,\$\s*e/.test(cmd) || // After range: 1,$e
+    /^\/[^/]*\/[IMim]*,\/[^/]*\/[IMim]*\s*e/.test(cmd) // After pattern range: /s/,/e/e
+  ) {
+    return true
+  }
+
+  // Check for substitution commands with dangerous flags
+  // Pattern: s<delim>pattern<delim>replacement<delim>flags where flags contain w or e
+  // Per POSIX, sed allows any character except backslash and newline as delimiter
+  const substitutionMatch = cmd.match(/s([^\\\n]).*?\1.*?\1(.*?)$/)
+  if (substitutionMatch) {
+    const flags = substitutionMatch[2] || ''
+
+    // Check for write flag: s/old/new/w filename or s/old/new/gw filename
+    if (flags.includes('w') || flags.includes('W')) {
+      return true
+    }
+
+    // Check for execute flag: s/old/new/e or s/old/new/ge
+    if (flags.includes('e') || flags.includes('E')) {
+      return true
+    }
+  }
+
+  // Check for y (transliterate) command followed by dangerous operations
+  // Pattern: y<delim>source<delim>dest<delim> followed by anything
+  // The y command uses same delimiter syntax as s command
+  // PARANOID: Reject any y command that has w/W/e/E anywhere after the delimiters
+  const yCommandMatch = cmd.match(/y([^\\\n])/)
+  if (yCommandMatch) {
+    // If we see a y command, check if there's any w, W, e, or E in the entire command
+    // This is paranoid but safe - y commands are rare and w/e after y is suspicious
+    if (/[wWeE]/.test(cmd)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Cross-cutting validation step for sed commands.
+ *
+ * This is a constraint check that blocks dangerous sed operations regardless of mode.
+ * It returns 'passthrough' for non-sed commands or safe sed commands,
+ * and 'ask' for dangerous sed operations (w/W/e/E commands).
+ *
+ * @param input - Object containing the command string
+ * @param toolPermissionContext - Context containing mode and permissions
+ * @returns
+ * - 'ask' if any sed command contains dangerous operations
+ * - 'passthrough' if no sed commands or all are safe
+ */
+export function checkSedConstraints(
+  input: { command: string },
+  toolPermissionContext: ToolPermissionContext,
+): PermissionResult {
+  const commands = splitCommand_DEPRECATED(input.command)
+
+  for (const cmd of commands) {
+    // Skip non-sed commands
+    const trimmed = cmd.trim()
+    const baseCmd = trimmed.split(/\s+/)[0]
+    if (baseCmd !== 'sed') {
+      continue
+    }
+
+    // In acceptEdits mode, allow file writes (-i flag) but still block dangerous operations
+    const allowFileWrites = toolPermissionContext.mode === 'acceptEdits'
+
+    const isAllowed = sedCommandIsAllowedByAllowlist(trimmed, {
+      allowFileWrites,
+    })
+
+    if (!isAllowed) {
+      return {
+        behavior: 'ask',
+        message:
+          'sed command requires approval (contains potentially dangerous operations)',
+        decisionReason: {
+          type: 'other',
+          reason:
+            'sed command contains operations that require explicit approval (e.g., write commands, execute commands)',
+        },
+      }
+    }
+  }
+
+  // No dangerous sed commands found (or no sed commands at all)
+  return {
+    behavior: 'passthrough',
+    message: 'No dangerous sed operations detected',
+  }
+}

src/tools/BashTool/shouldUseSandbox.ts

@@ -0,0 +1,153 @@
+import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'
+import { splitCommand_DEPRECATED } from '../../utils/bash/commands.js'
+import { SandboxManager } from '../../utils/sandbox/sandbox-adapter.js'
+import { getSettings_DEPRECATED } from '../../utils/settings/settings.js'
+import {
+  BINARY_HIJACK_VARS,
+  bashPermissionRule,
+  matchWildcardPattern,
+  stripAllLeadingEnvVars,
+  stripSafeWrappers,
+} from './bashPermissions.js'
+
+type SandboxInput = {
+  command?: string
+  dangerouslyDisableSandbox?: boolean
+}
+
+// NOTE: excludedCommands is a user-facing convenience feature, not a security boundary.
+// It is not a security bug to be able to bypass excludedCommands — the sandbox permission
+// system (which prompts users) is the actual security control.
+function containsExcludedCommand(command: string): boolean {
+  // Check dynamic config for disabled commands and substrings (only for ants)
+  if (process.env.USER_TYPE === 'ant') {
+    const disabledCommands = getFeatureValue_CACHED_MAY_BE_STALE<{
+      commands: string[]
+      substrings: string[]
+    }>('tengu_sandbox_disabled_commands', { commands: [], substrings: [] })
+
+    // Check if command contains any disabled substrings
+    for (const substring of disabledCommands.substrings) {
+      if (command.includes(substring)) {
+        return true
+      }
+    }
+
+    // Check if command starts with any disabled commands
+    try {
+      const commandParts = splitCommand_DEPRECATED(command)
+      for (const part of commandParts) {
+        const baseCommand = part.trim().split(' ')[0]
+        if (baseCommand && disabledCommands.commands.includes(baseCommand)) {
+          return true
+        }
+      }
+    } catch {
+      // If we can't parse the command (e.g., malformed bash syntax),
+      // treat it as not excluded to allow other validation checks to handle it
+      // This prevents crashes when rendering tool use messages
+    }
+  }
+
+  // Check user-configured excluded commands from settings
+  const settings = getSettings_DEPRECATED()
+  const userExcludedCommands = settings.sandbox?.excludedCommands ?? []
+
+  if (userExcludedCommands.length === 0) {
+    return false
+  }
+
+  // Split compound commands (e.g. "docker ps && curl evil.com") into individual
+  // subcommands and check each one against excluded patterns. This prevents a
+  // compound command from escaping the sandbox just because its first subcommand
+  // matches an excluded pattern.
+  let subcommands: string[]
+  try {
+    subcommands = splitCommand_DEPRECATED(command)
+  } catch {
+    subcommands = [command]
+  }
+
+  for (const subcommand of subcommands) {
+    const trimmed = subcommand.trim()
+    // Also try matching with env var prefixes and wrapper commands stripped, so
+    // that `FOO=bar bazel ...` and `timeout 30 bazel ...` match `bazel:*`. Not a
+    // security boundary (see NOTE at top); the &&-split above already lets
+    // `export FOO=bar && bazel ...` match. BINARY_HIJACK_VARS kept as a heuristic.
+    //
+    // We iteratively apply both stripping operations until no new candidates are
+    // produced (fixed-point), matching the approach in filterRulesByContentsMatchingInput.
+    // This handles interleaved patterns like `timeout 300 FOO=bar bazel run`
+    // where single-pass composition would fail.
+    const candidates = [trimmed]
+    const seen = new Set(candidates)
+    let startIdx = 0
+    while (startIdx < candidates.length) {
+      const endIdx = candidates.length
+      for (let i = startIdx; i < endIdx; i++) {
+        const cmd = candidates[i]!
+        const envStripped = stripAllLeadingEnvVars(cmd, BINARY_HIJACK_VARS)
+        if (!seen.has(envStripped)) {
+          candidates.push(envStripped)
+          seen.add(envStripped)
+        }
+        const wrapperStripped = stripSafeWrappers(cmd)
+        if (!seen.has(wrapperStripped)) {
+          candidates.push(wrapperStripped)
+          seen.add(wrapperStripped)
+        }
+      }
+      startIdx = endIdx
+    }
+
+    for (const pattern of userExcludedCommands) {
+      const rule = bashPermissionRule(pattern)
+      for (const cand of candidates) {
+        switch (rule.type) {
+          case 'prefix':
+            if (cand === rule.prefix || cand.startsWith(rule.prefix + ' ')) {
+              return true
+            }
+            break
+          case 'exact':
+            if (cand === rule.command) {
+              return true
+            }
+            break
+          case 'wildcard':
+            if (matchWildcardPattern(rule.pattern, cand)) {
+              return true
+            }
+            break
+        }
+      }
+    }
+  }
+
+  return false
+}
+
+export function shouldUseSandbox(input: Partial<SandboxInput>): boolean {
+  if (!SandboxManager.isSandboxingEnabled()) {
+    return false
+  }
+
+  // Don't sandbox if explicitly overridden AND unsandboxed commands are allowed by policy
+  if (
+    input.dangerouslyDisableSandbox &&
+    SandboxManager.areUnsandboxedCommandsAllowed()
+  ) {
+    return false
+  }
+
+  if (!input.command) {
+    return false
+  }
+
+  // Don't sandbox if the command contains user-configured excluded commands
+  if (containsExcludedCommand(input.command)) {
+    return false
+  }
+
+  return true
+}

src/tools/BashTool/toolName.ts

@@ -0,0 +1,2 @@
+// Here to break circular dependency from prompt.ts
+export const BASH_TOOL_NAME = 'Bash'

src/tools/BashTool/utils.ts

@@ -0,0 +1,223 @@
+import type {
+  Base64ImageSource,
+  ContentBlockParam,
+  ToolResultBlockParam,
+} from '@anthropic-ai/sdk/resources/index.mjs'
+import { readFile, stat } from 'fs/promises'
+import { getOriginalCwd } from 'src/bootstrap/state.js'
+import { logEvent } from 'src/services/analytics/index.js'
+import type { ToolPermissionContext } from 'src/Tool.js'
+import { getCwd } from 'src/utils/cwd.js'
+import { pathInAllowedWorkingPath } from 'src/utils/permissions/filesystem.js'
+import { setCwd } from 'src/utils/Shell.js'
+import { shouldMaintainProjectWorkingDir } from '../../utils/envUtils.js'
+import { maybeResizeAndDownsampleImageBuffer } from '../../utils/imageResizer.js'
+import { getMaxOutputLength } from '../../utils/shell/outputLimits.js'
+import { countCharInString, plural } from '../../utils/stringUtils.js'
+/**
+ * Strips leading and trailing lines that contain only whitespace/newlines.
+ * Unlike trim(), this preserves whitespace within content lines and only removes
+ * completely empty lines from the beginning and end.
+ */
+export function stripEmptyLines(content: string): string {
+  const lines = content.split('\n')
+
+  // Find the first non-empty line
+  let startIndex = 0
+  while (startIndex < lines.length && lines[startIndex]?.trim() === '') {
+    startIndex++
+  }
+
+  // Find the last non-empty line
+  let endIndex = lines.length - 1
+  while (endIndex >= 0 && lines[endIndex]?.trim() === '') {
+    endIndex--
+  }
+
+  // If all lines are empty, return empty string
+  if (startIndex > endIndex) {
+    return ''
+  }
+
+  // Return the slice with non-empty lines
+  return lines.slice(startIndex, endIndex + 1).join('\n')
+}
+
+/**
+ * Check if content is a base64 encoded image data URL
+ */
+export function isImageOutput(content: string): boolean {
+  return /^data:image\/[a-z0-9.+_-]+;base64,/i.test(content)
+}
+
+const DATA_URI_RE = /^data:([^;]+);base64,(.+)$/
+
+/**
+ * Parse a data-URI string into its media type and base64 payload.
+ * Input is trimmed before matching.
+ */
+export function parseDataUri(
+  s: string,
+): { mediaType: string; data: string } | null {
+  const match = s.trim().match(DATA_URI_RE)
+  if (!match || !match[1] || !match[2]) return null
+  return { mediaType: match[1], data: match[2] }
+}
+
+/**
+ * Build an image tool_result block from shell stdout containing a data URI.
+ * Returns null if parse fails so callers can fall through to text handling.
+ */
+export function buildImageToolResult(
+  stdout: string,
+  toolUseID: string,
+): ToolResultBlockParam | null {
+  const parsed = parseDataUri(stdout)
+  if (!parsed) return null
+  return {
+    tool_use_id: toolUseID,
+    type: 'tool_result',
+    content: [
+      {
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: parsed.mediaType as Base64ImageSource['media_type'],
+          data: parsed.data,
+        },
+      },
+    ],
+  }
+}
+
+// Cap file reads to 20 MB — any image data URI larger than this is
+// well beyond what the API accepts (5 MB base64) and would OOM if read
+// into memory.
+const MAX_IMAGE_FILE_SIZE = 20 * 1024 * 1024
+
+/**
+ * Resize image output from a shell tool. stdout is capped at
+ * getMaxOutputLength() when read back from the shell output file — if the
+ * full output spilled to disk, re-read it from there, since truncated base64
+ * would decode to a corrupt image that either throws here or gets rejected by
+ * the API. Caps dimensions too: compressImageBuffer only checks byte size, so
+ * a small-but-high-DPI PNG (e.g. matplotlib at dpi=300) sails through at full
+ * resolution and poisons many-image requests (CC-304).
+ *
+ * Returns the re-encoded data URI on success, or null if the source didn't
+ * parse as a data URI (caller decides whether to flip isImage).
+ */
+export async function resizeShellImageOutput(
+  stdout: string,
+  outputFilePath: string | undefined,
+  outputFileSize: number | undefined,
+): Promise<string | null> {
+  let source = stdout
+  if (outputFilePath) {
+    const size = outputFileSize ?? (await stat(outputFilePath)).size
+    if (size > MAX_IMAGE_FILE_SIZE) return null
+    source = await readFile(outputFilePath, 'utf8')
+  }
+  const parsed = parseDataUri(source)
+  if (!parsed) return null
+  const buf = Buffer.from(parsed.data, 'base64')
+  const ext = parsed.mediaType.split('/')[1] || 'png'
+  const resized = await maybeResizeAndDownsampleImageBuffer(
+    buf,
+    buf.length,
+    ext,
+  )
+  return `data:image/${resized.mediaType};base64,${resized.buffer.toString('base64')}`
+}
+
+export function formatOutput(content: string): {
+  totalLines: number
+  truncatedContent: string
+  isImage?: boolean
+} {
+  const isImage = isImageOutput(content)
+  if (isImage) {
+    return {
+      totalLines: 1,
+      truncatedContent: content,
+      isImage,
+    }
+  }
+
+  const maxOutputLength = getMaxOutputLength()
+  if (content.length <= maxOutputLength) {
+    return {
+      totalLines: countCharInString(content, '\n') + 1,
+      truncatedContent: content,
+      isImage,
+    }
+  }
+
+  const truncatedPart = content.slice(0, maxOutputLength)
+  const remainingLines = countCharInString(content, '\n', maxOutputLength) + 1
+  const truncated = `${truncatedPart}\n\n... [${remainingLines} lines truncated] ...`
+
+  return {
+    totalLines: countCharInString(content, '\n') + 1,
+    truncatedContent: truncated,
+    isImage,
+  }
+}
+
+export const stdErrAppendShellResetMessage = (stderr: string): string =>
+  `${stderr.trim()}\nShell cwd was reset to ${getOriginalCwd()}`
+
+export function resetCwdIfOutsideProject(
+  toolPermissionContext: ToolPermissionContext,
+): boolean {
+  const cwd = getCwd()
+  const originalCwd = getOriginalCwd()
+  const shouldMaintain = shouldMaintainProjectWorkingDir()
+  if (
+    shouldMaintain ||
+    // Fast path: originalCwd is unconditionally in allWorkingDirectories
+    // (filesystem.ts), so when cwd hasn't moved, pathInAllowedWorkingPath is
+    // trivially true — skip its syscalls for the no-cd common case.
+    (cwd !== originalCwd &&
+      !pathInAllowedWorkingPath(cwd, toolPermissionContext))
+  ) {
+    // Reset to original directory if maintaining project dir OR outside allowed working directory
+    setCwd(originalCwd)
+    if (!shouldMaintain) {
+      logEvent('tengu_bash_tool_reset_to_original_dir', {})
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Creates a human-readable summary of structured content blocks.
+ * Used to display MCP results with images and text in the UI.
+ */
+export function createContentSummary(content: ContentBlockParam[]): string {
+  const parts: string[] = []
+  let textCount = 0
+  let imageCount = 0
+
+  for (const block of content) {
+    if (block.type === 'image') {
+      imageCount++
+    } else if (block.type === 'text' && 'text' in block) {
+      textCount++
+      // Include first 200 chars of text blocks for context
+      const preview = block.text.slice(0, 200)
+      parts.push(preview + (block.text.length > 200 ? '...' : ''))
+    }
+  }
+
+  const summary: string[] = []
+  if (imageCount > 0) {
+    summary.push(`[${imageCount} ${plural(imageCount, 'image')}]`)
+  }
+  if (textCount > 0) {
+    summary.push(`[${textCount} text ${plural(textCount, 'block')}]`)
+  }
+
+  return `MCP Result: ${summary.join(', ')}${parts.length > 0 ? '\n\n' + parts.join('\n\n') : ''}`
+}

src/tools/BriefTool/BriefTool.ts

@@ -0,0 +1,204 @@
+import { feature } from 'bun:bundle'
+import { z } from 'zod/v4'
+import { getKairosActive, getUserMsgOptIn } from '../../bootstrap/state.js'
+import { getFeatureValue_CACHED_WITH_REFRESH } from '../../services/analytics/growthbook.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { plural } from '../../utils/stringUtils.js'
+import { resolveAttachments, validateAttachmentPaths } from './attachments.js'
+import {
+  BRIEF_TOOL_NAME,
+  BRIEF_TOOL_PROMPT,
+  DESCRIPTION,
+  LEGACY_BRIEF_TOOL_NAME,
+} from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    message: z
+      .string()
+      .describe('The message for the user. Supports markdown formatting.'),
+    attachments: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Optional file paths (absolute or relative to cwd) to attach. Use for photos, screenshots, diffs, logs, or any file the user should see alongside your message.',
+      ),
+    status: z
+      .enum(['normal', 'proactive'])
+      .describe(
+        "Use 'proactive' when you're surfacing something the user hasn't asked for and needs to see now — task completion while they're away, a blocker you hit, an unsolicited status update. Use 'normal' when replying to something the user just said.",
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+// attachments MUST remain optional — resumed sessions replay pre-attachment
+// outputs verbatim and a required field would crash the UI renderer on resume.
+const outputSchema = lazySchema(() =>
+  z.object({
+    message: z.string().describe('The message'),
+    attachments: z
+      .array(
+        z.object({
+          path: z.string(),
+          size: z.number(),
+          isImage: z.boolean(),
+          file_uuid: z.string().optional(),
+        }),
+      )
+      .optional()
+      .describe('Resolved attachment metadata'),
+    sentAt: z
+      .string()
+      .optional()
+      .describe(
+        'ISO timestamp captured at tool execution on the emitting process. Optional — resumed sessions replay pre-sentAt outputs verbatim.',
+      ),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+const KAIROS_BRIEF_REFRESH_MS = 5 * 60 * 1000
+
+/**
+ * Entitlement check — is the user ALLOWED to use Brief? Combines build-time
+ * flags with runtime GB gate + assistant-mode passthrough. No opt-in check
+ * here — this decides whether opt-in should be HONORED, not whether the user
+ * has opted in.
+ *
+ * Build-time OR-gated on KAIROS || KAIROS_BRIEF (same pattern as
+ * PROACTIVE || KAIROS): assistant mode depends on Brief, so KAIROS alone
+ * must bundle it. KAIROS_BRIEF lets Brief ship independently.
+ *
+ * Use this to decide whether `--brief` / `defaultView: 'chat'` / `--tools`
+ * listing should be honored. Use `isBriefEnabled()` to decide whether the
+ * tool is actually active in the current session.
+ *
+ * CLAUDE_CODE_BRIEF env var force-grants entitlement for dev/testing —
+ * bypasses the GB gate so you can test without being enrolled. Still
+ * requires an opt-in action to activate (--brief, defaultView, etc.), but
+ * the env var alone also sets userMsgOptIn via maybeActivateBrief().
+ */
+export function isBriefEntitled(): boolean {
+  // Positive ternary — see docs/feature-gating.md. Negative early-return
+  // would not eliminate the GB gate string from external builds.
+  return feature('KAIROS') || feature('KAIROS_BRIEF')
+    ? getKairosActive() ||
+        isEnvTruthy(process.env.CLAUDE_CODE_BRIEF) ||
+        getFeatureValue_CACHED_WITH_REFRESH(
+          'tengu_kairos_brief',
+          false,
+          KAIROS_BRIEF_REFRESH_MS,
+        )
+    : false
+}
+
+/**
+ * Unified activation gate for the Brief tool. Governs model-facing behavior
+ * as a unit: tool availability, system prompt section (getBriefSection),
+ * tool-deferral bypass (isDeferredTool), and todo-nag suppression.
+ *
+ * Activation requires explicit opt-in (userMsgOptIn) set by one of:
+ *   - `--brief` CLI flag (maybeActivateBrief in main.tsx)
+ *   - `defaultView: 'chat'` in settings (main.tsx init)
+ *   - `/brief` slash command (brief.ts)
+ *   - `/config` defaultView picker (Config.tsx)
+ *   - SendUserMessage in `--tools` / SDK `tools` option (main.tsx)
+ *   - CLAUDE_CODE_BRIEF env var (maybeActivateBrief — dev/testing bypass)
+ * Assistant mode (kairosActive) bypasses opt-in since its system prompt
+ * hard-codes "you MUST use SendUserMessage" (systemPrompt.md:14).
+ *
+ * The GB gate is re-checked here as a kill-switch AND — flipping
+ * tengu_kairos_brief off mid-session disables the tool on the next 5-min
+ * refresh even for opted-in sessions. No opt-in → always false regardless
+ * of GB (this is the fix for "brief defaults on for enrolled ants").
+ *
+ * Called from Tool.isEnabled() (lazy, post-init), never at module scope.
+ * getKairosActive() and getUserMsgOptIn() are set in main.tsx before any
+ * caller reaches here.
+ */
+export function isBriefEnabled(): boolean {
+  // Top-level feature() guard is load-bearing for DCE: Bun can constant-fold
+  // the ternary to `false` in external builds and then dead-code the BriefTool
+  // object. Composing isBriefEntitled() alone (which has its own guard) is
+  // semantically equivalent but defeats constant-folding across the boundary.
+  return feature('KAIROS') || feature('KAIROS_BRIEF')
+    ? (getKairosActive() || getUserMsgOptIn()) && isBriefEntitled()
+    : false
+}
+
+export const BriefTool = buildTool({
+  name: BRIEF_TOOL_NAME,
+  aliases: [LEGACY_BRIEF_TOOL_NAME],
+  searchHint:
+    'send a message to the user — your primary visible output channel',
+  maxResultSizeChars: 100_000,
+  userFacingName() {
+    return ''
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isEnabled() {
+    return isBriefEnabled()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.message
+  },
+  async validateInput({ attachments }, _context): Promise<ValidationResult> {
+    if (!attachments || attachments.length === 0) {
+      return { result: true }
+    }
+    return validateAttachmentPaths(attachments)
+  },
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return BRIEF_TOOL_PROMPT
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    const n = output.attachments?.length ?? 0
+    const suffix = n === 0 ? '' : ` (${n} ${plural(n, 'attachment')} included)`
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: `Message delivered to user.${suffix}`,
+    }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call({ message, attachments, status }, context) {
+    const sentAt = new Date().toISOString()
+    logEvent('tengu_brief_send', {
+      proactive: status === 'proactive',
+      attachment_count: attachments?.length ?? 0,
+    })
+    if (!attachments || attachments.length === 0) {
+      return { data: { message, sentAt } }
+    }
+    const appState = context.getAppState()
+    const resolved = await resolveAttachments(attachments, {
+      replBridgeEnabled: appState.replBridgeEnabled,
+      signal: context.abortController.signal,
+    })
+    return {
+      data: { message, attachments: resolved, sentAt },
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/BriefTool/attachments.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared attachment validation + resolution for SendUserMessage and
+ * SendUserFile. Lives in BriefTool/ so the dynamic `./upload.js` import
+ * inside the feature('BRIDGE_MODE') guard stays relative and upload.ts
+ * (axios, crypto, auth utils) remains tree-shakeable from non-bridge builds.
+ */
+
+import { feature } from 'bun:bundle'
+import { stat } from 'fs/promises'
+
+import type { ValidationResult } from '../../Tool.js'
+
+import { getCwd } from '../../utils/cwd.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { getErrnoCode } from '../../utils/errors.js'
+import { IMAGE_EXTENSION_REGEX } from '../../utils/imagePaste.js'
+import { expandPath } from '../../utils/path.js'
+
+export type ResolvedAttachment = {
+  path: string
+  size: number
+  isImage: boolean
+  file_uuid?: string
+}
+
+export async function validateAttachmentPaths(
+  rawPaths: string[],
+): Promise<ValidationResult> {
+  const cwd = getCwd()
+  for (const rawPath of rawPaths) {
+    const fullPath = expandPath(rawPath)
+    try {
+      const stats = await stat(fullPath)
+      if (!stats.isFile()) {
+        return {
+          result: false,
+          message: `Attachment "${rawPath}" is not a regular file.`,
+          errorCode: 1,
+        }
+      }
+    } catch (e) {
+      const code = getErrnoCode(e)
+      if (code === 'ENOENT') {
+        return {
+          result: false,
+          message: `Attachment "${rawPath}" does not exist. Current working directory: ${cwd}.`,
+          errorCode: 1,
+        }
+      }
+      if (code === 'EACCES' || code === 'EPERM') {
+        return {
+          result: false,
+          message: `Attachment "${rawPath}" is not accessible (permission denied).`,
+          errorCode: 1,
+        }
+      }
+      throw e
+    }
+  }
+  return { result: true }
+}
+
+export async function resolveAttachments(
+  rawPaths: string[],
+  uploadCtx: { replBridgeEnabled: boolean; signal?: AbortSignal },
+): Promise<ResolvedAttachment[]> {
+  // Stat serially (local, fast) to keep ordering deterministic, then upload
+  // in parallel (network, slow). Upload failures resolve undefined — the
+  // attachment still carries {path, size, isImage} for local renderers.
+  const stated: ResolvedAttachment[] = []
+  for (const rawPath of rawPaths) {
+    const fullPath = expandPath(rawPath)
+    // Single stat — we need size, so this is the operation, not a guard.
+    // validateInput ran before us, but the file could have moved since
+    // (TOCTOU); if it did, let the error propagate so the model sees it.
+    const stats = await stat(fullPath)
+    stated.push({
+      path: fullPath,
+      size: stats.size,
+      isImage: IMAGE_EXTENSION_REGEX.test(fullPath),
+    })
+  }
+  // Dynamic import inside the feature() guard so upload.ts (axios, crypto,
+  // zod, auth utils, MIME map) is fully eliminated from non-BRIDGE_MODE
+  // builds. A static import would force module-scope evaluation regardless
+  // of the guard inside uploadBriefAttachment — CLAUDE.md: "helpers defined
+  // outside remain in the build even if never called".
+  if (feature('BRIDGE_MODE')) {
+    // Headless/SDK callers never set appState.replBridgeEnabled (only the TTY
+    // REPL does, at main.tsx init). CLAUDE_CODE_BRIEF_UPLOAD lets a host that
+    // runs the CLI as a subprocess opt in — e.g. the cowork desktop bridge,
+    // which already passes CLAUDE_CODE_OAUTH_TOKEN for auth.
+    const shouldUpload =
+      uploadCtx.replBridgeEnabled ||
+      isEnvTruthy(process.env.CLAUDE_CODE_BRIEF_UPLOAD)
+    const { uploadBriefAttachment } = await import('./upload.js')
+    const uuids = await Promise.all(
+      stated.map(a =>
+        uploadBriefAttachment(a.path, a.size, {
+          replBridgeEnabled: shouldUpload,
+          signal: uploadCtx.signal,
+        }),
+      ),
+    )
+    return stated.map((a, i) =>
+      uuids[i] === undefined ? a : { ...a, file_uuid: uuids[i] },
+    )
+  }
+  return stated
+}

src/tools/BriefTool/prompt.ts

@@ -0,0 +1,22 @@
+export const BRIEF_TOOL_NAME = 'SendUserMessage'
+export const LEGACY_BRIEF_TOOL_NAME = 'Brief'
+
+export const DESCRIPTION = 'Send a message to the user'
+
+export const BRIEF_TOOL_PROMPT = `Send a message the user will read. Text outside this tool is visible in the detail view, but most won't open it — the answer lives here.
+
+\`message\` supports markdown. \`attachments\` takes file paths (absolute or cwd-relative) for images, diffs, logs.
+
+\`status\` labels intent: 'normal' when replying to what they just asked; 'proactive' when you're initiating — a scheduled task finished, a blocker surfaced during background work, you need input on something they haven't asked about. Set it honestly; downstream routing uses it.`
+
+export const BRIEF_PROACTIVE_SECTION = `## Talking to the user
+
+${BRIEF_TOOL_NAME} is where your replies go. Text outside it is visible if the user expands the detail view, but most won't — assume unread. Anything you want them to actually see goes through ${BRIEF_TOOL_NAME}. The failure mode: the real answer lives in plain text while ${BRIEF_TOOL_NAME} just says "done!" — they see "done!" and miss everything.
+
+So: every time the user says something, the reply they actually read comes through ${BRIEF_TOOL_NAME}. Even for "hi". Even for "thanks".
+
+If you can answer right away, send the answer. If you need to go look — run a command, read files, check something — ack first in one line ("On it — checking the test output"), then work, then send the result. Without the ack they're staring at a spinner.
+
+For longer work: ack → work → result. Between those, send a checkpoint when something useful happened — a decision you made, a surprise you hit, a phase boundary. Skip the filler ("running tests...") — a checkpoint earns its place by carrying information.
+
+Keep messages tight — the decision, the file:line, the PR number. Second person always ("your config"), never third.`

src/tools/BriefTool/upload.ts

@@ -0,0 +1,174 @@
+/**
+ * Upload BriefTool attachments to private_api so web viewers can preview them.
+ *
+ * When the repl bridge is active, attachment paths are meaningless to a web
+ * viewer (they're on Claude's machine). We upload to /api/oauth/file_upload —
+ * the same store MessageComposer/SpaceMessage render from — and stash the
+ * returned file_uuid alongside the path. Web resolves file_uuid → preview;
+ * desktop/local try path first.
+ *
+ * Best-effort: any failure (no token, bridge off, network error, 4xx) logs
+ * debug and returns undefined. The attachment still carries {path, size,
+ * isImage}, so local-terminal and same-machine-desktop render unaffected.
+ */
+
+import { feature } from 'bun:bundle'
+import axios from 'axios'
+import { randomUUID } from 'crypto'
+import { readFile } from 'fs/promises'
+import { basename, extname } from 'path'
+import { z } from 'zod/v4'
+
+import {
+  getBridgeAccessToken,
+  getBridgeBaseUrlOverride,
+} from '../../bridge/bridgeConfig.js'
+import { getOauthConfig } from '../../constants/oauth.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+
+// Matches the private_api backend limit
+const MAX_UPLOAD_BYTES = 30 * 1024 * 1024
+
+const UPLOAD_TIMEOUT_MS = 30_000
+
+// Backend dispatches on mime: image/* → upload_image_wrapped (writes
+// PREVIEW/THUMBNAIL, no ORIGINAL), everything else → upload_generic_file
+// (ORIGINAL only, no preview). Only whitelist raster formats the
+// transcoder reliably handles — svg/bmp/ico risk a 400, and pdf routes
+// to upload_pdf_file_wrapped which also skips ORIGINAL. Dispatch
+// viewers use /preview for images and /contents for everything else,
+// so images go image/* and the rest go octet-stream.
+const MIME_BY_EXT: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+}
+
+function guessMimeType(filename: string): string {
+  const ext = extname(filename).toLowerCase()
+  return MIME_BY_EXT[ext] ?? 'application/octet-stream'
+}
+
+function debug(msg: string): void {
+  logForDebugging(`[brief:upload] ${msg}`)
+}
+
+/**
+ * Base URL for uploads. Must match the host the token is valid for.
+ *
+ * Subprocess hosts (cowork) pass ANTHROPIC_BASE_URL alongside
+ * CLAUDE_CODE_OAUTH_TOKEN — prefer that since getOauthConfig() only
+ * returns staging when USE_STAGING_OAUTH is set, which such hosts don't
+ * set. Without this a staging token hits api.anthropic.com → 401 → silent
+ * skip → web viewer sees inert cards with no file_uuid.
+ */
+function getBridgeBaseUrl(): string {
+  return (
+    getBridgeBaseUrlOverride() ??
+    process.env.ANTHROPIC_BASE_URL ??
+    getOauthConfig().BASE_API_URL
+  )
+}
+
+// /api/oauth/file_upload returns one of ChatMessage{Image,Blob,Document}FileSchema.
+// All share file_uuid; that's the only field we need.
+const uploadResponseSchema = lazySchema(() =>
+  z.object({ file_uuid: z.string() }),
+)
+
+export type BriefUploadContext = {
+  replBridgeEnabled: boolean
+  signal?: AbortSignal
+}
+
+/**
+ * Upload a single attachment. Returns file_uuid on success, undefined otherwise.
+ * Every early-return is intentional graceful degradation.
+ */
+export async function uploadBriefAttachment(
+  fullPath: string,
+  size: number,
+  ctx: BriefUploadContext,
+): Promise<string | undefined> {
+  // Positive pattern so bun:bundle eliminates the entire body from
+  // non-BRIDGE_MODE builds (negative `if (!feature(...)) return` does not).
+  if (feature('BRIDGE_MODE')) {
+    if (!ctx.replBridgeEnabled) return undefined
+
+    if (size > MAX_UPLOAD_BYTES) {
+      debug(`skip ${fullPath}: ${size} bytes exceeds ${MAX_UPLOAD_BYTES} limit`)
+      return undefined
+    }
+
+    const token = getBridgeAccessToken()
+    if (!token) {
+      debug('skip: no oauth token')
+      return undefined
+    }
+
+    let content: Buffer
+    try {
+      content = await readFile(fullPath)
+    } catch (e) {
+      debug(`read failed for ${fullPath}: ${e}`)
+      return undefined
+    }
+
+    const baseUrl = getBridgeBaseUrl()
+    const url = `${baseUrl}/api/oauth/file_upload`
+    const filename = basename(fullPath)
+    const mimeType = guessMimeType(filename)
+    const boundary = `----FormBoundary${randomUUID()}`
+
+    // Manual multipart — same pattern as filesApi.ts. The oauth endpoint takes
+    // a single "file" part (no "purpose" field like the public Files API).
+    const body = Buffer.concat([
+      Buffer.from(
+        `--${boundary}\r\n` +
+          `Content-Disposition: form-data; name="file"; filename="${filename}"\r\n` +
+          `Content-Type: ${mimeType}\r\n\r\n`,
+      ),
+      content,
+      Buffer.from(`\r\n--${boundary}--\r\n`),
+    ])
+
+    try {
+      const response = await axios.post(url, body, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': `multipart/form-data; boundary=${boundary}`,
+          'Content-Length': body.length.toString(),
+        },
+        timeout: UPLOAD_TIMEOUT_MS,
+        signal: ctx.signal,
+        validateStatus: () => true,
+      })
+
+      if (response.status !== 201) {
+        debug(
+          `upload failed for ${fullPath}: status=${response.status} body=${jsonStringify(response.data).slice(0, 200)}`,
+        )
+        return undefined
+      }
+
+      const parsed = uploadResponseSchema().safeParse(response.data)
+      if (!parsed.success) {
+        debug(
+          `unexpected response shape for ${fullPath}: ${parsed.error.message}`,
+        )
+        return undefined
+      }
+
+      debug(`uploaded ${fullPath} → ${parsed.data.file_uuid} (${size} bytes)`)
+      return parsed.data.file_uuid
+    } catch (e) {
+      debug(`upload threw for ${fullPath}: ${e}`)
+      return undefined
+    }
+  }
+  return undefined
+}

src/tools/ConfigTool/ConfigTool.ts

@@ -0,0 +1,467 @@
+import { feature } from 'bun:bundle'
+import { z } from 'zod/v4'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../../services/analytics/index.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import {
+  type GlobalConfig,
+  getGlobalConfig,
+  getRemoteControlAtStartup,
+  saveGlobalConfig,
+} from '../../utils/config.js'
+import { errorMessage } from '../../utils/errors.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import {
+  getInitialSettings,
+  updateSettingsForSource,
+} from '../../utils/settings/settings.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { CONFIG_TOOL_NAME } from './constants.js'
+import { DESCRIPTION, generatePrompt } from './prompt.js'
+import {
+  getConfig,
+  getOptionsForSetting,
+  getPath,
+  isSupported,
+} from './supportedSettings.js'
+import {
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    setting: z
+      .string()
+      .describe(
+        'The setting key (e.g., "theme", "model", "permissions.defaultMode")',
+      ),
+    value: z
+      .union([z.string(), z.boolean(), z.number()])
+      .optional()
+      .describe('The new value. Omit to get current value.'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    success: z.boolean(),
+    operation: z.enum(['get', 'set']).optional(),
+    setting: z.string().optional(),
+    value: z.unknown().optional(),
+    previousValue: z.unknown().optional(),
+    newValue: z.unknown().optional(),
+    error: z.string().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Input = z.infer<InputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const ConfigTool = buildTool({
+  name: CONFIG_TOOL_NAME,
+  searchHint: 'get or set Claude Code settings (theme, model)',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return generatePrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'Config'
+  },
+  shouldDefer: true,
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly(input: Input) {
+    return input.value === undefined
+  },
+  toAutoClassifierInput(input) {
+    return input.value === undefined
+      ? input.setting
+      : `${input.setting} = ${input.value}`
+  },
+  async checkPermissions(input: Input) {
+    // Auto-allow reading configs
+    if (input.value === undefined) {
+      return { behavior: 'allow' as const, updatedInput: input }
+    }
+    return {
+      behavior: 'ask' as const,
+      message: `Set ${input.setting} to ${jsonStringify(input.value)}`,
+    }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  renderToolUseRejectedMessage,
+  async call({ setting, value }: Input, context): Promise<{ data: Output }> {
+    // 1. Check if setting is supported
+    // Voice settings are registered at build-time (feature('VOICE_MODE')), but
+    // must also be gated at runtime. When the kill-switch is on, treat
+    // voiceEnabled as an unknown setting so no voice-specific strings leak.
+    if (feature('VOICE_MODE') && setting === 'voiceEnabled') {
+      const { isVoiceGrowthBookEnabled } = await import(
+        '../../voice/voiceModeEnabled.js'
+      )
+      if (!isVoiceGrowthBookEnabled()) {
+        return {
+          data: { success: false, error: `Unknown setting: "${setting}"` },
+        }
+      }
+    }
+    if (!isSupported(setting)) {
+      return {
+        data: { success: false, error: `Unknown setting: "${setting}"` },
+      }
+    }
+
+    const config = getConfig(setting)!
+    const path = getPath(setting)
+
+    // 2. GET operation
+    if (value === undefined) {
+      const currentValue = getValue(config.source, path)
+      const displayValue = config.formatOnRead
+        ? config.formatOnRead(currentValue)
+        : currentValue
+      return {
+        data: { success: true, operation: 'get', setting, value: displayValue },
+      }
+    }
+
+    // 3. SET operation
+
+    // Handle "default" — unset the config key so it falls back to the
+    // platform-aware default (determined by the bridge feature gate).
+    if (
+      setting === 'remoteControlAtStartup' &&
+      typeof value === 'string' &&
+      value.toLowerCase().trim() === 'default'
+    ) {
+      saveGlobalConfig(prev => {
+        if (prev.remoteControlAtStartup === undefined) return prev
+        const next = { ...prev }
+        delete next.remoteControlAtStartup
+        return next
+      })
+      const resolved = getRemoteControlAtStartup()
+      // Sync to AppState so useReplBridge reacts immediately
+      context.setAppState(prev => {
+        if (prev.replBridgeEnabled === resolved && !prev.replBridgeOutboundOnly)
+          return prev
+        return {
+          ...prev,
+          replBridgeEnabled: resolved,
+          replBridgeOutboundOnly: false,
+        }
+      })
+      return {
+        data: {
+          success: true,
+          operation: 'set',
+          setting,
+          value: resolved,
+        },
+      }
+    }
+
+    let finalValue: unknown = value
+
+    // Coerce and validate boolean values
+    if (config.type === 'boolean') {
+      if (typeof value === 'string') {
+        const lower = value.toLowerCase().trim()
+        if (lower === 'true') finalValue = true
+        else if (lower === 'false') finalValue = false
+      }
+      if (typeof finalValue !== 'boolean') {
+        return {
+          data: {
+            success: false,
+            operation: 'set',
+            setting,
+            error: `${setting} requires true or false.`,
+          },
+        }
+      }
+    }
+
+    // Check options
+    const options = getOptionsForSetting(setting)
+    if (options && !options.includes(String(finalValue))) {
+      return {
+        data: {
+          success: false,
+          operation: 'set',
+          setting,
+          error: `Invalid value "${value}". Options: ${options.join(', ')}`,
+        },
+      }
+    }
+
+    // Async validation (e.g., model API check)
+    if (config.validateOnWrite) {
+      const result = await config.validateOnWrite(finalValue)
+      if (!result.valid) {
+        return {
+          data: {
+            success: false,
+            operation: 'set',
+            setting,
+            error: result.error,
+          },
+        }
+      }
+    }
+
+    // Pre-flight checks for voice mode
+    if (
+      feature('VOICE_MODE') &&
+      setting === 'voiceEnabled' &&
+      finalValue === true
+    ) {
+      const { isVoiceModeEnabled } = await import(
+        '../../voice/voiceModeEnabled.js'
+      )
+      if (!isVoiceModeEnabled()) {
+        const { isAnthropicAuthEnabled } = await import('../../utils/auth.js')
+        return {
+          data: {
+            success: false,
+            error: !isAnthropicAuthEnabled()
+              ? 'Voice mode requires a Claude.ai account. Please run /login to sign in.'
+              : 'Voice mode is not available.',
+          },
+        }
+      }
+      const { isVoiceStreamAvailable } = await import(
+        '../../services/voiceStreamSTT.js'
+      )
+      const {
+        checkRecordingAvailability,
+        checkVoiceDependencies,
+        requestMicrophonePermission,
+      } = await import('../../services/voice.js')
+
+      const recording = await checkRecordingAvailability()
+      if (!recording.available) {
+        return {
+          data: {
+            success: false,
+            error:
+              recording.reason ??
+              'Voice mode is not available in this environment.',
+          },
+        }
+      }
+      if (!isVoiceStreamAvailable()) {
+        return {
+          data: {
+            success: false,
+            error:
+              'Voice mode requires a Claude.ai account. Please run /login to sign in.',
+          },
+        }
+      }
+      const deps = await checkVoiceDependencies()
+      if (!deps.available) {
+        return {
+          data: {
+            success: false,
+            error:
+              'No audio recording tool found.' +
+              (deps.installCommand ? ` Run: ${deps.installCommand}` : ''),
+          },
+        }
+      }
+      if (!(await requestMicrophonePermission())) {
+        let guidance: string
+        if (process.platform === 'win32') {
+          guidance = 'Settings \u2192 Privacy \u2192 Microphone'
+        } else if (process.platform === 'linux') {
+          guidance = "your system's audio settings"
+        } else {
+          guidance =
+            'System Settings \u2192 Privacy & Security \u2192 Microphone'
+        }
+        return {
+          data: {
+            success: false,
+            error: `Microphone access is denied. To enable it, go to ${guidance}, then try again.`,
+          },
+        }
+      }
+    }
+
+    const previousValue = getValue(config.source, path)
+
+    // 4. Write to storage
+    try {
+      if (config.source === 'global') {
+        const key = path[0]
+        if (!key) {
+          return {
+            data: {
+              success: false,
+              operation: 'set',
+              setting,
+              error: 'Invalid setting path',
+            },
+          }
+        }
+        saveGlobalConfig(prev => {
+          if (prev[key as keyof GlobalConfig] === finalValue) return prev
+          return { ...prev, [key]: finalValue }
+        })
+      } else {
+        const update = buildNestedObject(path, finalValue)
+        const result = updateSettingsForSource('userSettings', update)
+        if (result.error) {
+          return {
+            data: {
+              success: false,
+              operation: 'set',
+              setting,
+              error: result.error.message,
+            },
+          }
+        }
+      }
+
+      // 5a. Voice needs notifyChange so applySettingsChange resyncs
+      // AppState.settings (useVoiceEnabled reads settings.voiceEnabled)
+      // and the settings cache resets for the next /voice read.
+      if (feature('VOICE_MODE') && setting === 'voiceEnabled') {
+        const { settingsChangeDetector } = await import(
+          '../../utils/settings/changeDetector.js'
+        )
+        settingsChangeDetector.notifyChange('userSettings')
+      }
+
+      // 5b. Sync to AppState if needed for immediate UI effect
+      if (config.appStateKey) {
+        const appKey = config.appStateKey
+        context.setAppState(prev => {
+          if (prev[appKey] === finalValue) return prev
+          return { ...prev, [appKey]: finalValue }
+        })
+      }
+
+      // Sync remoteControlAtStartup to AppState so the bridge reacts
+      // immediately (the config key differs from the AppState field name,
+      // so the generic appStateKey mechanism can't handle this).
+      if (setting === 'remoteControlAtStartup') {
+        const resolved = getRemoteControlAtStartup()
+        context.setAppState(prev => {
+          if (
+            prev.replBridgeEnabled === resolved &&
+            !prev.replBridgeOutboundOnly
+          )
+            return prev
+          return {
+            ...prev,
+            replBridgeEnabled: resolved,
+            replBridgeOutboundOnly: false,
+          }
+        })
+      }
+
+      logEvent('tengu_config_tool_changed', {
+        setting:
+          setting as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        value: String(
+          finalValue,
+        ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+
+      return {
+        data: {
+          success: true,
+          operation: 'set',
+          setting,
+          previousValue,
+          newValue: finalValue,
+        },
+      }
+    } catch (error) {
+      logError(error)
+      return {
+        data: {
+          success: false,
+          operation: 'set',
+          setting,
+          error: errorMessage(error),
+        },
+      }
+    }
+  },
+  mapToolResultToToolResultBlockParam(content: Output, toolUseID: string) {
+    if (content.success) {
+      if (content.operation === 'get') {
+        return {
+          tool_use_id: toolUseID,
+          type: 'tool_result' as const,
+          content: `${content.setting} = ${jsonStringify(content.value)}`,
+        }
+      }
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result' as const,
+        content: `Set ${content.setting} to ${jsonStringify(content.newValue)}`,
+      }
+    }
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result' as const,
+      content: `Error: ${content.error}`,
+      is_error: true,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)
+
+function getValue(source: 'global' | 'settings', path: string[]): unknown {
+  if (source === 'global') {
+    const config = getGlobalConfig()
+    const key = path[0]
+    if (!key) return undefined
+    return config[key as keyof GlobalConfig]
+  }
+  const settings = getInitialSettings()
+  let current: unknown = settings
+  for (const key of path) {
+    if (current && typeof current === 'object' && key in current) {
+      current = (current as Record<string, unknown>)[key]
+    } else {
+      return undefined
+    }
+  }
+  return current
+}
+
+function buildNestedObject(
+  path: string[],
+  value: unknown,
+): Record<string, unknown> {
+  if (path.length === 0) {
+    return {}
+  }
+  const key = path[0]!
+  if (path.length === 1) {
+    return { [key]: value }
+  }
+  return { [key]: buildNestedObject(path.slice(1), value) }
+}

src/tools/ConfigTool/UI.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import { MessageResponse } from '../../components/MessageResponse.js';
+import { Text } from '../../ink.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+import type { Input, Output } from './ConfigTool.js';
+export function renderToolUseMessage(input: Partial<Input>): React.ReactNode {
+  if (!input.setting) return null;
+  if (input.value === undefined) {
+    return <Text dimColor>Getting {input.setting}</Text>;
+  }
+  return <Text dimColor>
+      Setting {input.setting} to {jsonStringify(input.value)}
+    </Text>;
+}
+export function renderToolResultMessage(content: Output): React.ReactNode {
+  if (!content.success) {
+    return <MessageResponse>
+        <Text color="error">Failed: {content.error}</Text>
+      </MessageResponse>;
+  }
+  if (content.operation === 'get') {
+    return <MessageResponse>
+        <Text>
+          <Text bold>{content.setting}</Text> = {jsonStringify(content.value)}
+        </Text>
+      </MessageResponse>;
+  }
+  return <MessageResponse>
+      <Text>
+        Set <Text bold>{content.setting}</Text> to{' '}
+        <Text bold>{jsonStringify(content.newValue)}</Text>
+      </Text>
+    </MessageResponse>;
+}
+export function renderToolUseRejectedMessage(): React.ReactNode {
+  return <Text color="warning">Config change rejected</Text>;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIk1lc3NhZ2VSZXNwb25zZSIsIlRleHQiLCJqc29uU3RyaW5naWZ5IiwiSW5wdXQiLCJPdXRwdXQiLCJyZW5kZXJUb29sVXNlTWVzc2FnZSIsImlucHV0IiwiUGFydGlhbCIsIlJlYWN0Tm9kZSIsInNldHRpbmciLCJ2YWx1ZSIsInVuZGVmaW5lZCIsInJlbmRlclRvb2xSZXN1bHRNZXNzYWdlIiwiY29udGVudCIsInN1Y2Nlc3MiLCJlcnJvciIsIm9wZXJhdGlvbiIsIm5ld1ZhbHVlIiwicmVuZGVyVG9vbFVzZVJlamVjdGVkTWVzc2FnZSJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgUmVhY3QgZnJvbSAncmVhY3QnXG5pbXBvcnQgeyBNZXNzYWdlUmVzcG9uc2UgfSBmcm9tICcuLi8uLi9jb21wb25lbnRzL01lc3NhZ2VSZXNwb25zZS5qcydcbmltcG9ydCB7IFRleHQgfSBmcm9tICcuLi8uLi9pbmsuanMnXG5pbXBvcnQgeyBqc29uU3RyaW5naWZ5IH0gZnJvbSAnLi4vLi4vdXRpbHMvc2xvd09wZXJhdGlvbnMuanMnXG5pbXBvcnQgdHlwZSB7IElucHV0LCBPdXRwdXQgfSBmcm9tICcuL0NvbmZpZ1Rvb2wuanMnXG5cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJUb29sVXNlTWVzc2FnZShpbnB1dDogUGFydGlhbDxJbnB1dD4pOiBSZWFjdC5SZWFjdE5vZGUge1xuICBpZiAoIWlucHV0LnNldHRpbmcpIHJldHVybiBudWxsXG4gIGlmIChpbnB1dC52YWx1ZSA9PT0gdW5kZWZpbmVkKSB7XG4gICAgcmV0dXJuIDxUZXh0IGRpbUNvbG9yPkdldHRpbmcge2lucHV0LnNldHRpbmd9PC9UZXh0PlxuICB9XG4gIHJldHVybiAoXG4gICAgPFRleHQgZGltQ29sb3I+XG4gICAgICBTZXR0aW5nIHtpbnB1dC5zZXR0aW5nfSB0byB7anNvblN0cmluZ2lmeShpbnB1dC52YWx1ZSl9XG4gICAgPC9UZXh0PlxuICApXG59XG5cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJUb29sUmVzdWx0TWVzc2FnZShjb250ZW50OiBPdXRwdXQpOiBSZWFjdC5SZWFjdE5vZGUge1xuICBpZiAoIWNvbnRlbnQuc3VjY2Vzcykge1xuICAgIHJldHVybiAoXG4gICAgICA8TWVzc2FnZVJlc3BvbnNlPlxuICAgICAgICA8VGV4dCBjb2xvcj1cImVycm9yXCI+RmFpbGVkOiB7Y29udGVudC5lcnJvcn08L1RleHQ+XG4gICAgICA8L01lc3NhZ2VSZXNwb25zZT5cbiAgICApXG4gIH1cbiAgaWYgKGNvbnRlbnQub3BlcmF0aW9uID09PSAnZ2V0Jykge1xuICAgIHJldHVybiAoXG4gICAgICA8TWVzc2FnZVJlc3BvbnNlPlxuICAgICAgICA8VGV4dD5cbiAgICAgICAgICA8VGV4dCBib2xkPntjb250ZW50LnNldHRpbmd9PC9UZXh0PiA9IHtqc29uU3RyaW5naWZ5KGNvbnRlbnQudmFsdWUpfVxuICAgICAgICA8L1RleHQ+XG4gICAgICA8L01lc3NhZ2VSZXNwb25zZT5cbiAgICApXG4gIH1cbiAgcmV0dXJuIChcbiAgICA8TWVzc2FnZVJlc3BvbnNlPlxuICAgICAgPFRleHQ+XG4gICAgICAgIFNldCA8VGV4dCBib2xkPntjb250ZW50LnNldHRpbmd9PC9UZXh0PiB0b3snICd9XG4gICAgICAgIDxUZXh0IGJvbGQ+e2pzb25TdHJpbmdpZnkoY29udGVudC5uZXdWYWx1ZSl9PC9UZXh0PlxuICAgICAgPC9UZXh0PlxuICAgIDwvTWVzc2FnZVJlc3BvbnNlPlxuICApXG59XG5cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJUb29sVXNlUmVqZWN0ZWRNZXNzYWdlKCk6IFJlYWN0LlJlYWN0Tm9kZSB7XG4gIHJldHVybiA8VGV4dCBjb2xvcj1cIndhcm5pbmdcIj5Db25maWcgY2hhbmdlIHJlamVjdGVkPC9UZXh0PlxufVxuIl0sIm1hcHBpbmdzIjoiQUFBQSxPQUFPQSxLQUFLLE1BQU0sT0FBTztBQUN6QixTQUFTQyxlQUFlLFFBQVEscUNBQXFDO0FBQ3JFLFNBQVNDLElBQUksUUFBUSxjQUFjO0FBQ25DLFNBQVNDLGFBQWEsUUFBUSwrQkFBK0I7QUFDN0QsY0FBY0MsS0FBSyxFQUFFQyxNQUFNLFFBQVEsaUJBQWlCO0FBRXBELE9BQU8sU0FBU0Msb0JBQW9CQSxDQUFDQyxLQUFLLEVBQUVDLE9BQU8sQ0FBQ0osS0FBSyxDQUFDLENBQUMsRUFBRUosS0FBSyxDQUFDUyxTQUFTLENBQUM7RUFDM0UsSUFBSSxDQUFDRixLQUFLLENBQUNHLE9BQU8sRUFBRSxPQUFPLElBQUk7RUFDL0IsSUFBSUgsS0FBSyxDQUFDSSxLQUFLLEtBQUtDLFNBQVMsRUFBRTtJQUM3QixPQUFPLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUNMLEtBQUssQ0FBQ0csT0FBTyxDQUFDLEVBQUUsSUFBSSxDQUFDO0VBQ3REO0VBQ0EsT0FDRSxDQUFDLElBQUksQ0FBQyxRQUFRO0FBQ2xCLGNBQWMsQ0FBQ0gsS0FBSyxDQUFDRyxPQUFPLENBQUMsSUFBSSxDQUFDUCxhQUFhLENBQUNJLEtBQUssQ0FBQ0ksS0FBSyxDQUFDO0FBQzVELElBQUksRUFBRSxJQUFJLENBQUM7QUFFWDtBQUVBLE9BQU8sU0FBU0UsdUJBQXVCQSxDQUFDQyxPQUFPLEVBQUVULE1BQU0sQ0FBQyxFQUFFTCxLQUFLLENBQUNTLFNBQVMsQ0FBQztFQUN4RSxJQUFJLENBQUNLLE9BQU8sQ0FBQ0MsT0FBTyxFQUFFO0lBQ3BCLE9BQ0UsQ0FBQyxlQUFlO0FBQ3RCLFFBQVEsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUNELE9BQU8sQ0FBQ0UsS0FBSyxDQUFDLEVBQUUsSUFBSTtBQUN6RCxNQUFNLEVBQUUsZUFBZSxDQUFDO0VBRXRCO0VBQ0EsSUFBSUYsT0FBTyxDQUFDRyxTQUFTLEtBQUssS0FBSyxFQUFFO0lBQy9CLE9BQ0UsQ0FBQyxlQUFlO0FBQ3RCLFFBQVEsQ0FBQyxJQUFJO0FBQ2IsVUFBVSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQ0gsT0FBTyxDQUFDSixPQUFPLENBQUMsRUFBRSxJQUFJLENBQUMsR0FBRyxDQUFDUCxhQUFhLENBQUNXLE9BQU8sQ0FBQ0gsS0FBSyxDQUFDO0FBQzdFLFFBQVEsRUFBRSxJQUFJO0FBQ2QsTUFBTSxFQUFFLGVBQWUsQ0FBQztFQUV0QjtFQUNBLE9BQ0UsQ0FBQyxlQUFlO0FBQ3BCLE1BQU0sQ0FBQyxJQUFJO0FBQ1gsWUFBWSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQ0csT0FBTyxDQUFDSixPQUFPLENBQUMsRUFBRSxJQUFJLENBQUMsR0FBRyxDQUFDLEdBQUc7QUFDdEQsUUFBUSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQ1AsYUFBYSxDQUFDVyxPQUFPLENBQUNJLFFBQVEsQ0FBQyxDQUFDLEVBQUUsSUFBSTtBQUMxRCxNQUFNLEVBQUUsSUFBSTtBQUNaLElBQUksRUFBRSxlQUFlLENBQUM7QUFFdEI7QUFFQSxPQUFPLFNBQVNDLDRCQUE0QkEsQ0FBQSxDQUFFLEVBQUVuQixLQUFLLENBQUNTLFNBQVMsQ0FBQztFQUM5RCxPQUFPLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxTQUFTLENBQUMsc0JBQXNCLEVBQUUsSUFBSSxDQUFDO0FBQzVEIiwiaWdub3JlTGlzdCI6W119

src/tools/ConfigTool/constants.ts

@@ -0,0 +1 @@
+export const CONFIG_TOOL_NAME = 'Config'

src/tools/ConfigTool/prompt.ts

@@ -0,0 +1,93 @@
+import { feature } from 'bun:bundle'
+import { getModelOptions } from '../../utils/model/modelOptions.js'
+import { isVoiceGrowthBookEnabled } from '../../voice/voiceModeEnabled.js'
+import {
+  getOptionsForSetting,
+  SUPPORTED_SETTINGS,
+} from './supportedSettings.js'
+
+export const DESCRIPTION = 'Get or set Claude Code configuration settings.'
+
+/**
+ * Generate the prompt documentation from the registry
+ */
+export function generatePrompt(): string {
+  const globalSettings: string[] = []
+  const projectSettings: string[] = []
+
+  for (const [key, config] of Object.entries(SUPPORTED_SETTINGS)) {
+    // Skip model - it gets its own section with dynamic options
+    if (key === 'model') continue
+    // Voice settings are registered at build-time but gated by GrowthBook
+    // at runtime. Hide from model prompt when the kill-switch is on.
+    if (
+      feature('VOICE_MODE') &&
+      key === 'voiceEnabled' &&
+      !isVoiceGrowthBookEnabled()
+    )
+      continue
+
+    const options = getOptionsForSetting(key)
+    let line = `- ${key}`
+
+    if (options) {
+      line += `: ${options.map(o => `"${o}"`).join(', ')}`
+    } else if (config.type === 'boolean') {
+      line += `: true/false`
+    }
+
+    line += ` - ${config.description}`
+
+    if (config.source === 'global') {
+      globalSettings.push(line)
+    } else {
+      projectSettings.push(line)
+    }
+  }
+
+  const modelSection = generateModelSection()
+
+  return `Get or set Claude Code configuration settings.
+
+  View or change Claude Code settings. Use when the user requests configuration changes, asks about current settings, or when adjusting a setting would benefit them.
+
+
+## Usage
+- **Get current value:** Omit the "value" parameter
+- **Set new value:** Include the "value" parameter
+
+## Configurable settings list
+The following settings are available for you to change:
+
+### Global Settings (stored in ~/.claude.json)
+${globalSettings.join('\n')}
+
+### Project Settings (stored in settings.json)
+${projectSettings.join('\n')}
+
+${modelSection}
+## Examples
+- Get theme: { "setting": "theme" }
+- Set dark theme: { "setting": "theme", "value": "dark" }
+- Enable vim mode: { "setting": "editorMode", "value": "vim" }
+- Enable verbose: { "setting": "verbose", "value": true }
+- Change model: { "setting": "model", "value": "opus" }
+- Change permission mode: { "setting": "permissions.defaultMode", "value": "plan" }
+`
+}
+
+function generateModelSection(): string {
+  try {
+    const options = getModelOptions()
+    const lines = options.map(o => {
+      const value = o.value === null ? 'null/"default"' : `"${o.value}"`
+      return `  - ${value}: ${o.descriptionForModel ?? o.description}`
+    })
+    return `## Model
+- model - Override the default model. Available options:
+${lines.join('\n')}`
+  } catch {
+    return `## Model
+- model - Override the default model (sonnet, opus, haiku, best, or full model ID)`
+  }
+}

src/tools/ConfigTool/supportedSettings.ts

@@ -0,0 +1,211 @@
+import { feature } from 'bun:bundle'
+import { getRemoteControlAtStartup } from '../../utils/config.js'
+import {
+  EDITOR_MODES,
+  NOTIFICATION_CHANNELS,
+  TEAMMATE_MODES,
+} from '../../utils/configConstants.js'
+import { getModelOptions } from '../../utils/model/modelOptions.js'
+import { validateModel } from '../../utils/model/validateModel.js'
+import { THEME_NAMES, THEME_SETTINGS } from '../../utils/theme.js'
+
+/** AppState keys that can be synced for immediate UI effect */
+type SyncableAppStateKey = 'verbose' | 'mainLoopModel' | 'thinkingEnabled'
+
+type SettingConfig = {
+  source: 'global' | 'settings'
+  type: 'boolean' | 'string'
+  description: string
+  path?: string[]
+  options?: readonly string[]
+  getOptions?: () => string[]
+  appStateKey?: SyncableAppStateKey
+  /** Async validation called when writing/setting a value */
+  validateOnWrite?: (v: unknown) => Promise<{ valid: boolean; error?: string }>
+  /** Format value when reading/getting for display */
+  formatOnRead?: (v: unknown) => unknown
+}
+
+export const SUPPORTED_SETTINGS: Record<string, SettingConfig> = {
+  theme: {
+    source: 'global',
+    type: 'string',
+    description: 'Color theme for the UI',
+    options: feature('AUTO_THEME') ? THEME_SETTINGS : THEME_NAMES,
+  },
+  editorMode: {
+    source: 'global',
+    type: 'string',
+    description: 'Key binding mode',
+    options: EDITOR_MODES,
+  },
+  verbose: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Show detailed debug output',
+    appStateKey: 'verbose',
+  },
+  preferredNotifChannel: {
+    source: 'global',
+    type: 'string',
+    description: 'Preferred notification channel',
+    options: NOTIFICATION_CHANNELS,
+  },
+  autoCompactEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Auto-compact when context is full',
+  },
+  autoMemoryEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable auto-memory',
+  },
+  autoDreamEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable background memory consolidation',
+  },
+  fileCheckpointingEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Enable file checkpointing for code rewind',
+  },
+  showTurnDuration: {
+    source: 'global',
+    type: 'boolean',
+    description:
+      'Show turn duration message after responses (e.g., "Cooked for 1m 6s")',
+  },
+  terminalProgressBarEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Show OSC 9;4 progress indicator in supported terminals',
+  },
+  todoFeatureEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Enable todo/task tracking',
+  },
+  model: {
+    source: 'settings',
+    type: 'string',
+    description: 'Override the default model',
+    appStateKey: 'mainLoopModel',
+    getOptions: () => {
+      try {
+        return getModelOptions()
+          .filter(o => o.value !== null)
+          .map(o => o.value as string)
+      } catch {
+        return ['sonnet', 'opus', 'haiku']
+      }
+    },
+    validateOnWrite: v => validateModel(String(v)),
+    formatOnRead: v => (v === null ? 'default' : v),
+  },
+  alwaysThinkingEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable extended thinking (false to disable)',
+    appStateKey: 'thinkingEnabled',
+  },
+  'permissions.defaultMode': {
+    source: 'settings',
+    type: 'string',
+    description: 'Default permission mode for tool usage',
+    options: feature('TRANSCRIPT_CLASSIFIER')
+      ? ['default', 'plan', 'acceptEdits', 'dontAsk', 'auto']
+      : ['default', 'plan', 'acceptEdits', 'dontAsk'],
+  },
+  language: {
+    source: 'settings',
+    type: 'string',
+    description:
+      'Preferred language for Claude responses and voice dictation (e.g., "japanese", "spanish")',
+  },
+  teammateMode: {
+    source: 'global',
+    type: 'string',
+    description:
+      'How to spawn teammates: "tmux" for traditional tmux, "in-process" for same process, "auto" to choose automatically',
+    options: TEAMMATE_MODES,
+  },
+  ...(process.env.USER_TYPE === 'ant'
+    ? {
+        classifierPermissionsEnabled: {
+          source: 'settings' as const,
+          type: 'boolean' as const,
+          description:
+            'Enable AI-based classification for Bash(prompt:...) permission rules',
+        },
+      }
+    : {}),
+  ...(feature('VOICE_MODE')
+    ? {
+        voiceEnabled: {
+          source: 'settings' as const,
+          type: 'boolean' as const,
+          description: 'Enable voice dictation (hold-to-talk)',
+        },
+      }
+    : {}),
+  ...(feature('BRIDGE_MODE')
+    ? {
+        remoteControlAtStartup: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Enable Remote Control for all sessions (true | false | default)',
+          formatOnRead: () => getRemoteControlAtStartup(),
+        },
+      }
+    : {}),
+  ...(feature('KAIROS') || feature('KAIROS_PUSH_NOTIFICATION')
+    ? {
+        taskCompleteNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Push to your mobile device when idle after Claude finishes (requires Remote Control)',
+        },
+        inputNeededNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Push to your mobile device when a permission prompt or question is waiting (requires Remote Control)',
+        },
+        agentPushNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Allow Claude to push to your mobile device when it deems it appropriate (requires Remote Control)',
+        },
+      }
+    : {}),
+}
+
+export function isSupported(key: string): boolean {
+  return key in SUPPORTED_SETTINGS
+}
+
+export function getConfig(key: string): SettingConfig | undefined {
+  return SUPPORTED_SETTINGS[key]
+}
+
+export function getAllKeys(): string[] {
+  return Object.keys(SUPPORTED_SETTINGS)
+}
+
+export function getOptionsForSetting(key: string): string[] | undefined {
+  const config = SUPPORTED_SETTINGS[key]
+  if (!config) return undefined
+  if (config.options) return [...config.options]
+  if (config.getOptions) return config.getOptions()
+  return undefined
+}
+
+export function getPath(key: string): string[] {
+  const config = SUPPORTED_SETTINGS[key]
+  return config?.path ?? key.split('.')
+}

src/tools/EnterPlanModeTool/EnterPlanModeTool.ts

@@ -0,0 +1,126 @@
+import { feature } from 'bun:bundle'
+import { z } from 'zod/v4'
+import {
+  getAllowedChannels,
+  handlePlanModeTransition,
+} from '../../bootstrap/state.js'
+import type { Tool } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { applyPermissionUpdate } from '../../utils/permissions/PermissionUpdate.js'
+import { prepareContextForPlanMode } from '../../utils/permissions/permissionSetup.js'
+import { isPlanModeInterviewPhaseEnabled } from '../../utils/planModeV2.js'
+import { ENTER_PLAN_MODE_TOOL_NAME } from './constants.js'
+import { getEnterPlanModeToolPrompt } from './prompt.js'
+import {
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    // No parameters needed
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    message: z.string().describe('Confirmation that plan mode was entered'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const EnterPlanModeTool: Tool<InputSchema, Output> = buildTool({
+  name: ENTER_PLAN_MODE_TOOL_NAME,
+  searchHint: 'switch to plan mode to design an approach before coding',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Requests permission to enter plan mode for complex tasks requiring exploration and design'
+  },
+  async prompt() {
+    return getEnterPlanModeToolPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return ''
+  },
+  shouldDefer: true,
+  isEnabled() {
+    // When --channels is active, ExitPlanMode is disabled (its approval
+    // dialog needs the terminal). Disable entry too so plan mode isn't a
+    // trap the model can enter but never leave.
+    if (
+      (feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
+      getAllowedChannels().length > 0
+    ) {
+      return false
+    }
+    return true
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  renderToolUseRejectedMessage,
+  async call(_input, context) {
+    if (context.agentId) {
+      throw new Error('EnterPlanMode tool cannot be used in agent contexts')
+    }
+
+    const appState = context.getAppState()
+    handlePlanModeTransition(appState.toolPermissionContext.mode, 'plan')
+
+    // Update the permission mode to 'plan'. prepareContextForPlanMode runs
+    // the classifier activation side effects when the user's defaultMode is
+    // 'auto' — see permissionSetup.ts for the full lifecycle.
+    context.setAppState(prev => ({
+      ...prev,
+      toolPermissionContext: applyPermissionUpdate(
+        prepareContextForPlanMode(prev.toolPermissionContext),
+        { type: 'setMode', mode: 'plan', destination: 'session' },
+      ),
+    }))
+
+    return {
+      data: {
+        message:
+          'Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.',
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam({ message }, toolUseID) {
+    const instructions = isPlanModeInterviewPhaseEnabled()
+      ? `${message}
+
+DO NOT write or edit any files except the plan file. Detailed workflow instructions will follow.`
+      : `${message}
+
+In plan mode, you should:
+1. Thoroughly explore the codebase to understand existing patterns
+2. Identify similar features and architectural approaches
+3. Consider multiple approaches and their trade-offs
+4. Use AskUserQuestion if you need to clarify the approach
+5. Design a concrete implementation strategy
+6. When ready, use ExitPlanMode to present your plan for approval
+
+Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase.`
+
+    return {
+      type: 'tool_result',
+      content: instructions,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/EnterPlanModeTool/UI.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { BLACK_CIRCLE } from 'src/constants/figures.js';
+import { getModeColor } from 'src/utils/permissions/PermissionMode.js';
+import { Box, Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import type { ThemeName } from '../../utils/theme.js';
+import type { Output } from './EnterPlanModeTool.js';
+export function renderToolUseMessage(): React.ReactNode {
+  return null;
+}
+export function renderToolResultMessage(_output: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], _options: {
+  theme: ThemeName;
+}): React.ReactNode {
+  return <Box flexDirection="column" marginTop={1}>
+      <Box flexDirection="row">
+        <Text color={getModeColor('plan')}>{BLACK_CIRCLE}</Text>
+        <Text> Entered plan mode</Text>
+      </Box>
+      <Box paddingLeft={2}>
+        <Text dimColor>
+          Claude is now exploring and designing an implementation approach.
+        </Text>
+      </Box>
+    </Box>;
+}
+export function renderToolUseRejectedMessage(): React.ReactNode {
+  return <Box flexDirection="row" marginTop={1}>
+      <Text color={getModeColor('default')}>{BLACK_CIRCLE}</Text>
+      <Text> User declined to enter plan mode</Text>
+    </Box>;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIkJMQUNLX0NJUkNMRSIsImdldE1vZGVDb2xvciIsIkJveCIsIlRleHQiLCJUb29sUHJvZ3Jlc3NEYXRhIiwiUHJvZ3Jlc3NNZXNzYWdlIiwiVGhlbWVOYW1lIiwiT3V0cHV0IiwicmVuZGVyVG9vbFVzZU1lc3NhZ2UiLCJSZWFjdE5vZGUiLCJyZW5kZXJUb29sUmVzdWx0TWVzc2FnZSIsIl9vdXRwdXQiLCJfcHJvZ3Jlc3NNZXNzYWdlc0Zvck1lc3NhZ2UiLCJfb3B0aW9ucyIsInRoZW1lIiwicmVuZGVyVG9vbFVzZVJlamVjdGVkTWVzc2FnZSJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgKiBhcyBSZWFjdCBmcm9tICdyZWFjdCdcbmltcG9ydCB7IEJMQUNLX0NJUkNMRSB9IGZyb20gJ3NyYy9jb25zdGFudHMvZmlndXJlcy5qcydcbmltcG9ydCB7IGdldE1vZGVDb2xvciB9IGZyb20gJ3NyYy91dGlscy9wZXJtaXNzaW9ucy9QZXJtaXNzaW9uTW9kZS5qcydcbmltcG9ydCB7IEJveCwgVGV4dCB9IGZyb20gJy4uLy4uL2luay5qcydcbmltcG9ydCB0eXBlIHsgVG9vbFByb2dyZXNzRGF0YSB9IGZyb20gJy4uLy4uL1Rvb2wuanMnXG5pbXBvcnQgdHlwZSB7IFByb2dyZXNzTWVzc2FnZSB9IGZyb20gJy4uLy4uL3R5cGVzL21lc3NhZ2UuanMnXG5pbXBvcnQgdHlwZSB7IFRoZW1lTmFtZSB9IGZyb20gJy4uLy4uL3V0aWxzL3RoZW1lLmpzJ1xuaW1wb3J0IHR5cGUgeyBPdXRwdXQgfSBmcm9tICcuL0VudGVyUGxhbk1vZGVUb29sLmpzJ1xuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZU1lc3NhZ2UoKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuIG51bGxcbn1cblxuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlclRvb2xSZXN1bHRNZXNzYWdlKFxuICBfb3V0cHV0OiBPdXRwdXQsXG4gIF9wcm9ncmVzc01lc3NhZ2VzRm9yTWVzc2FnZTogUHJvZ3Jlc3NNZXNzYWdlPFRvb2xQcm9ncmVzc0RhdGE+W10sXG4gIF9vcHRpb25zOiB7IHRoZW1lOiBUaGVtZU5hbWUgfSxcbik6IFJlYWN0LlJlYWN0Tm9kZSB7XG4gIHJldHVybiAoXG4gICAgPEJveCBmbGV4RGlyZWN0aW9uPVwiY29sdW1uXCIgbWFyZ2luVG9wPXsxfT5cbiAgICAgIDxCb3ggZmxleERpcmVjdGlvbj1cInJvd1wiPlxuICAgICAgICA8VGV4dCBjb2xvcj17Z2V0TW9kZUNvbG9yKCdwbGFuJyl9PntCTEFDS19DSVJDTEV9PC9UZXh0PlxuICAgICAgICA8VGV4dD4gRW50ZXJlZCBwbGFuIG1vZGU8L1RleHQ+XG4gICAgICA8L0JveD5cbiAgICAgIDxCb3ggcGFkZGluZ0xlZnQ9ezJ9PlxuICAgICAgICA8VGV4dCBkaW1Db2xvcj5cbiAgICAgICAgICBDbGF1ZGUgaXMgbm93IGV4cGxvcmluZyBhbmQgZGVzaWduaW5nIGFuIGltcGxlbWVudGF0aW9uIGFwcHJvYWNoLlxuICAgICAgICA8L1RleHQ+XG4gICAgICA8L0JveD5cbiAgICA8L0JveD5cbiAgKVxufVxuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZVJlamVjdGVkTWVzc2FnZSgpOiBSZWFjdC5SZWFjdE5vZGUge1xuICByZXR1cm4gKFxuICAgIDxCb3ggZmxleERpcmVjdGlvbj1cInJvd1wiIG1hcmdpblRvcD17MX0+XG4gICAgICA8VGV4dCBjb2xvcj17Z2V0TW9kZUNvbG9yKCdkZWZhdWx0Jyl9PntCTEFDS19DSVJDTEV9PC9UZXh0PlxuICAgICAgPFRleHQ+IFVzZXIgZGVjbGluZWQgdG8gZW50ZXIgcGxhbiBtb2RlPC9UZXh0PlxuICAgIDwvQm94PlxuICApXG59XG4iXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBS0EsS0FBSyxNQUFNLE9BQU87QUFDOUIsU0FBU0MsWUFBWSxRQUFRLDBCQUEwQjtBQUN2RCxTQUFTQyxZQUFZLFFBQVEseUNBQXlDO0FBQ3RFLFNBQVNDLEdBQUcsRUFBRUMsSUFBSSxRQUFRLGNBQWM7QUFDeEMsY0FBY0MsZ0JBQWdCLFFBQVEsZUFBZTtBQUNyRCxjQUFjQyxlQUFlLFFBQVEsd0JBQXdCO0FBQzdELGNBQWNDLFNBQVMsUUFBUSxzQkFBc0I7QUFDckQsY0FBY0MsTUFBTSxRQUFRLHdCQUF3QjtBQUVwRCxPQUFPLFNBQVNDLG9CQUFvQkEsQ0FBQSxDQUFFLEVBQUVULEtBQUssQ0FBQ1UsU0FBUyxDQUFDO0VBQ3RELE9BQU8sSUFBSTtBQUNiO0FBRUEsT0FBTyxTQUFTQyx1QkFBdUJBLENBQ3JDQyxPQUFPLEVBQUVKLE1BQU0sRUFDZkssMkJBQTJCLEVBQUVQLGVBQWUsQ0FBQ0QsZ0JBQWdCLENBQUMsRUFBRSxFQUNoRVMsUUFBUSxFQUFFO0VBQUVDLEtBQUssRUFBRVIsU0FBUztBQUFDLENBQUMsQ0FDL0IsRUFBRVAsS0FBSyxDQUFDVSxTQUFTLENBQUM7RUFDakIsT0FDRSxDQUFDLEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQztBQUM3QyxNQUFNLENBQUMsR0FBRyxDQUFDLGFBQWEsQ0FBQyxLQUFLO0FBQzlCLFFBQVEsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUNSLFlBQVksQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUNELFlBQVksQ0FBQyxFQUFFLElBQUk7QUFDL0QsUUFBUSxDQUFDLElBQUksQ0FBQyxrQkFBa0IsRUFBRSxJQUFJO0FBQ3RDLE1BQU0sRUFBRSxHQUFHO0FBQ1gsTUFBTSxDQUFDLEdBQUcsQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDMUIsUUFBUSxDQUFDLElBQUksQ0FBQyxRQUFRO0FBQ3RCO0FBQ0EsUUFBUSxFQUFFLElBQUk7QUFDZCxNQUFNLEVBQUUsR0FBRztBQUNYLElBQUksRUFBRSxHQUFHLENBQUM7QUFFVjtBQUVBLE9BQU8sU0FBU2UsNEJBQTRCQSxDQUFBLENBQUUsRUFBRWhCLEtBQUssQ0FBQ1UsU0FBUyxDQUFDO0VBQzlELE9BQ0UsQ0FBQyxHQUFHLENBQUMsYUFBYSxDQUFDLEtBQUssQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDMUMsTUFBTSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQ1IsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQ0QsWUFBWSxDQUFDLEVBQUUsSUFBSTtBQUNoRSxNQUFNLENBQUMsSUFBSSxDQUFDLGlDQUFpQyxFQUFFLElBQUk7QUFDbkQsSUFBSSxFQUFFLEdBQUcsQ0FBQztBQUVWIiwiaWdub3JlTGlzdCI6W119

src/tools/EnterPlanModeTool/constants.ts

@@ -0,0 +1 @@
+export const ENTER_PLAN_MODE_TOOL_NAME = 'EnterPlanMode'

src/tools/EnterPlanModeTool/prompt.ts

@@ -0,0 +1,170 @@
+import { isPlanModeInterviewPhaseEnabled } from '../../utils/planModeV2.js'
+import { ASK_USER_QUESTION_TOOL_NAME } from '../AskUserQuestionTool/prompt.js'
+
+const WHAT_HAPPENS_SECTION = `## What Happens in Plan Mode
+
+In plan mode, you'll:
+1. Thoroughly explore the codebase using Glob, Grep, and Read tools
+2. Understand existing patterns and architecture
+3. Design an implementation approach
+4. Present your plan to the user for approval
+5. Use ${ASK_USER_QUESTION_TOOL_NAME} if you need to clarify approaches
+6. Exit plan mode with ExitPlanMode when ready to implement
+
+`
+
+function getEnterPlanModeToolPromptExternal(): string {
+  // When interview phase is enabled, omit the "What Happens" section —
+  // detailed workflow instructions arrive via the plan_mode attachment (messages.ts).
+  const whatHappens = isPlanModeInterviewPhaseEnabled()
+    ? ''
+    : WHAT_HAPPENS_SECTION
+
+  return `Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
+
+## When to Use This Tool
+
+**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
+
+1. **New Feature Implementation**: Adding meaningful new functionality
+   - Example: "Add a logout button" - where should it go? What should happen on click?
+   - Example: "Add form validation" - what rules? What error messages?
+
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" - many optimization strategies possible
+
+3. **Code Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the login flow" - what exactly should change?
+   - Example: "Refactor this component" - what's the target architecture?
+
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+   - Example: "Implement state management" - Redux vs Context vs custom solution
+
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
+   - Example: "Refactor the authentication system"
+   - Example: "Add a new API endpoint with tests"
+
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make the app faster" - need to profile and identify bottlenecks
+   - Example: "Fix the bug in checkout" - need to investigate root cause
+
+7. **User Preferences Matter**: The implementation could reasonably go multiple ways
+   - If you would use ${ASK_USER_QUESTION_TOOL_NAME} to clarify the approach, use EnterPlanMode instead
+   - Plan mode lets you explore first, then present options with context
+
+## When NOT to Use This Tool
+
+Only skip EnterPlanMode for simple tasks:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- Adding a single function with clear requirements
+- Tasks where the user has given very specific, detailed instructions
+- Pure research/exploration tasks (use the Agent tool with explore agent instead)
+
+${whatHappens}## Examples
+
+### GOOD - Use EnterPlanMode:
+User: "Add user authentication to the app"
+- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
+
+User: "Optimize the database queries"
+- Multiple approaches possible, need to profile first, significant impact
+
+User: "Implement dark mode"
+- Architectural decision on theme system, affects many components
+
+User: "Add a delete button to the user profile"
+- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
+
+User: "Update the error handling in the API"
+- Affects multiple files, user should approve the approach
+
+### BAD - Don't use EnterPlanMode:
+User: "Fix the typo in the README"
+- Straightforward, no planning needed
+
+User: "Add a console.log to debug this function"
+- Simple, obvious implementation
+
+User: "What files handle routing?"
+- Research task, not implementation planning
+
+## Important Notes
+
+- This tool REQUIRES user approval - they must consent to entering plan mode
+- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
+- Users appreciate being consulted before significant changes are made to their codebase
+`
+}
+
+function getEnterPlanModeToolPromptAnt(): string {
+  // When interview phase is enabled, omit the "What Happens" section —
+  // detailed workflow instructions arrive via the plan_mode attachment (messages.ts).
+  const whatHappens = isPlanModeInterviewPhaseEnabled()
+    ? ''
+    : WHAT_HAPPENS_SECTION
+
+  return `Use this tool when a task has genuine ambiguity about the right approach and getting user input before coding would prevent significant rework. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
+
+## When to Use This Tool
+
+Plan mode is valuable when the implementation approach is genuinely unclear. Use it when:
+
+1. **Significant Architectural Ambiguity**: Multiple reasonable approaches exist and the choice meaningfully affects the codebase
+   - Example: "Add caching to the API" - Redis vs in-memory vs file-based
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+
+2. **Unclear Requirements**: You need to explore and clarify before you can make progress
+   - Example: "Make the app faster" - need to profile and identify bottlenecks
+   - Example: "Refactor this module" - need to understand what the target architecture should be
+
+3. **High-Impact Restructuring**: The task will significantly restructure existing code and getting buy-in first reduces risk
+   - Example: "Redesign the authentication system"
+   - Example: "Migrate from one state management approach to another"
+
+## When NOT to Use This Tool
+
+Skip plan mode when you can reasonably infer the right approach:
+- The task is straightforward even if it touches multiple files
+- The user's request is specific enough that the implementation path is clear
+- You're adding a feature with an obvious implementation pattern (e.g., adding a button, a new endpoint following existing conventions)
+- Bug fixes where the fix is clear once you understand the bug
+- Research/exploration tasks (use the Agent tool instead)
+- The user says something like "can we work on X" or "let's do X" — just get started
+
+When in doubt, prefer starting work and using ${ASK_USER_QUESTION_TOOL_NAME} for specific questions over entering a full planning phase.
+
+${whatHappens}## Examples
+
+### GOOD - Use EnterPlanMode:
+User: "Add user authentication to the app"
+- Genuinely ambiguous: session vs JWT, where to store tokens, middleware structure
+
+User: "Redesign the data pipeline"
+- Major restructuring where the wrong approach wastes significant effort
+
+### BAD - Don't use EnterPlanMode:
+User: "Add a delete button to the user profile"
+- Implementation path is clear; just do it
+
+User: "Can we work on the search feature?"
+- User wants to get started, not plan
+
+User: "Update the error handling in the API"
+- Start working; ask specific questions if needed
+
+User: "Fix the typo in the README"
+- Straightforward, no planning needed
+
+## Important Notes
+
+- This tool REQUIRES user approval - they must consent to entering plan mode
+`
+}
+
+export function getEnterPlanModeToolPrompt(): string {
+  return process.env.USER_TYPE === 'ant'
+    ? getEnterPlanModeToolPromptAnt()
+    : getEnterPlanModeToolPromptExternal()
+}

src/tools/EnterWorktreeTool/EnterWorktreeTool.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod/v4'
+import { getSessionId, setOriginalCwd } from '../../bootstrap/state.js'
+import { clearSystemPromptSections } from '../../constants/systemPromptSections.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { Tool } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { clearMemoryFileCaches } from '../../utils/claudemd.js'
+import { getCwd } from '../../utils/cwd.js'
+import { findCanonicalGitRoot } from '../../utils/git.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getPlanSlug, getPlansDirectory } from '../../utils/plans.js'
+import { setCwd } from '../../utils/Shell.js'
+import { saveWorktreeState } from '../../utils/sessionStorage.js'
+import {
+  createWorktreeForSession,
+  getCurrentWorktreeSession,
+  validateWorktreeSlug,
+} from '../../utils/worktree.js'
+import { ENTER_WORKTREE_TOOL_NAME } from './constants.js'
+import { getEnterWorktreeToolPrompt } from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    name: z
+      .string()
+      .superRefine((s, ctx) => {
+        try {
+          validateWorktreeSlug(s)
+        } catch (e) {
+          ctx.addIssue({ code: 'custom', message: (e as Error).message })
+        }
+      })
+      .optional()
+      .describe(
+        'Optional name for the worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided.',
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    worktreePath: z.string(),
+    worktreeBranch: z.string().optional(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const EnterWorktreeTool: Tool<InputSchema, Output> = buildTool({
+  name: ENTER_WORKTREE_TOOL_NAME,
+  searchHint: 'create an isolated git worktree and switch into it',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Creates an isolated worktree (via git or configured hooks) and switches the session into it'
+  },
+  async prompt() {
+    return getEnterWorktreeToolPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'Creating worktree'
+  },
+  shouldDefer: true,
+  toAutoClassifierInput(input) {
+    return input.name ?? ''
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call(input) {
+    // Validate not already in a worktree created by this session
+    if (getCurrentWorktreeSession()) {
+      throw new Error('Already in a worktree session')
+    }
+
+    // Resolve to main repo root so worktree creation works from within a worktree
+    const mainRepoRoot = findCanonicalGitRoot(getCwd())
+    if (mainRepoRoot && mainRepoRoot !== getCwd()) {
+      process.chdir(mainRepoRoot)
+      setCwd(mainRepoRoot)
+    }
+
+    const slug = input.name ?? getPlanSlug()
+
+    const worktreeSession = await createWorktreeForSession(getSessionId(), slug)
+
+    process.chdir(worktreeSession.worktreePath)
+    setCwd(worktreeSession.worktreePath)
+    setOriginalCwd(getCwd())
+    saveWorktreeState(worktreeSession)
+    // Clear cached system prompt sections so env_info_simple recomputes with worktree context
+    clearSystemPromptSections()
+    // Clear memoized caches that depend on CWD
+    clearMemoryFileCaches()
+    getPlansDirectory.cache.clear?.()
+
+    logEvent('tengu_worktree_created', {
+      mid_session: true,
+    })
+
+    const branchInfo = worktreeSession.worktreeBranch
+      ? ` on branch ${worktreeSession.worktreeBranch}`
+      : ''
+
+    return {
+      data: {
+        worktreePath: worktreeSession.worktreePath,
+        worktreeBranch: worktreeSession.worktreeBranch,
+        message: `Created worktree at ${worktreeSession.worktreePath}${branchInfo}. The session is now working in the worktree. Use ExitWorktree to leave mid-session, or exit the session to be prompted.`,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam({ message }, toolUseID) {
+    return {
+      type: 'tool_result',
+      content: message,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/EnterWorktreeTool/UI.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { Box, Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import type { ThemeName } from '../../utils/theme.js';
+import type { Output } from './EnterWorktreeTool.js';
+export function renderToolUseMessage(): React.ReactNode {
+  return 'Creating worktree…';
+}
+export function renderToolResultMessage(output: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], _options: {
+  theme: ThemeName;
+}): React.ReactNode {
+  return <Box flexDirection="column">
+      <Text>
+        Switched to worktree on branch <Text bold>{output.worktreeBranch}</Text>
+      </Text>
+      <Text dimColor>{output.worktreePath}</Text>
+    </Box>;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIkJveCIsIlRleHQiLCJUb29sUHJvZ3Jlc3NEYXRhIiwiUHJvZ3Jlc3NNZXNzYWdlIiwiVGhlbWVOYW1lIiwiT3V0cHV0IiwicmVuZGVyVG9vbFVzZU1lc3NhZ2UiLCJSZWFjdE5vZGUiLCJyZW5kZXJUb29sUmVzdWx0TWVzc2FnZSIsIm91dHB1dCIsIl9wcm9ncmVzc01lc3NhZ2VzRm9yTWVzc2FnZSIsIl9vcHRpb25zIiwidGhlbWUiLCJ3b3JrdHJlZUJyYW5jaCIsIndvcmt0cmVlUGF0aCJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgKiBhcyBSZWFjdCBmcm9tICdyZWFjdCdcbmltcG9ydCB7IEJveCwgVGV4dCB9IGZyb20gJy4uLy4uL2luay5qcydcbmltcG9ydCB0eXBlIHsgVG9vbFByb2dyZXNzRGF0YSB9IGZyb20gJy4uLy4uL1Rvb2wuanMnXG5pbXBvcnQgdHlwZSB7IFByb2dyZXNzTWVzc2FnZSB9IGZyb20gJy4uLy4uL3R5cGVzL21lc3NhZ2UuanMnXG5pbXBvcnQgdHlwZSB7IFRoZW1lTmFtZSB9IGZyb20gJy4uLy4uL3V0aWxzL3RoZW1lLmpzJ1xuaW1wb3J0IHR5cGUgeyBPdXRwdXQgfSBmcm9tICcuL0VudGVyV29ya3RyZWVUb29sLmpzJ1xuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZU1lc3NhZ2UoKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuICdDcmVhdGluZyB3b3JrdHJlZeKApidcbn1cblxuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlclRvb2xSZXN1bHRNZXNzYWdlKFxuICBvdXRwdXQ6IE91dHB1dCxcbiAgX3Byb2dyZXNzTWVzc2FnZXNGb3JNZXNzYWdlOiBQcm9ncmVzc01lc3NhZ2U8VG9vbFByb2dyZXNzRGF0YT5bXSxcbiAgX29wdGlvbnM6IHsgdGhlbWU6IFRoZW1lTmFtZSB9LFxuKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuIChcbiAgICA8Qm94IGZsZXhEaXJlY3Rpb249XCJjb2x1bW5cIj5cbiAgICAgIDxUZXh0PlxuICAgICAgICBTd2l0Y2hlZCB0byB3b3JrdHJlZSBvbiBicmFuY2ggPFRleHQgYm9sZD57b3V0cHV0Lndvcmt0cmVlQnJhbmNofTwvVGV4dD5cbiAgICAgIDwvVGV4dD5cbiAgICAgIDxUZXh0IGRpbUNvbG9yPntvdXRwdXQud29ya3RyZWVQYXRofTwvVGV4dD5cbiAgICA8L0JveD5cbiAgKVxufVxuIl0sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUtBLEtBQUssTUFBTSxPQUFPO0FBQzlCLFNBQVNDLEdBQUcsRUFBRUMsSUFBSSxRQUFRLGNBQWM7QUFDeEMsY0FBY0MsZ0JBQWdCLFFBQVEsZUFBZTtBQUNyRCxjQUFjQyxlQUFlLFFBQVEsd0JBQXdCO0FBQzdELGNBQWNDLFNBQVMsUUFBUSxzQkFBc0I7QUFDckQsY0FBY0MsTUFBTSxRQUFRLHdCQUF3QjtBQUVwRCxPQUFPLFNBQVNDLG9CQUFvQkEsQ0FBQSxDQUFFLEVBQUVQLEtBQUssQ0FBQ1EsU0FBUyxDQUFDO0VBQ3RELE9BQU8sb0JBQW9CO0FBQzdCO0FBRUEsT0FBTyxTQUFTQyx1QkFBdUJBLENBQ3JDQyxNQUFNLEVBQUVKLE1BQU0sRUFDZEssMkJBQTJCLEVBQUVQLGVBQWUsQ0FBQ0QsZ0JBQWdCLENBQUMsRUFBRSxFQUNoRVMsUUFBUSxFQUFFO0VBQUVDLEtBQUssRUFBRVIsU0FBUztBQUFDLENBQUMsQ0FDL0IsRUFBRUwsS0FBSyxDQUFDUSxTQUFTLENBQUM7RUFDakIsT0FDRSxDQUFDLEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUTtBQUMvQixNQUFNLENBQUMsSUFBSTtBQUNYLHVDQUF1QyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQ0UsTUFBTSxDQUFDSSxjQUFjLENBQUMsRUFBRSxJQUFJO0FBQy9FLE1BQU0sRUFBRSxJQUFJO0FBQ1osTUFBTSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQ0osTUFBTSxDQUFDSyxZQUFZLENBQUMsRUFBRSxJQUFJO0FBQ2hELElBQUksRUFBRSxHQUFHLENBQUM7QUFFViIsImlnbm9yZUxpc3QiOltdfQ==

src/tools/EnterWorktreeTool/constants.ts

@@ -0,0 +1 @@
+export const ENTER_WORKTREE_TOOL_NAME = 'EnterWorktree'

src/tools/EnterWorktreeTool/prompt.ts

@@ -0,0 +1,30 @@
+export function getEnterWorktreeToolPrompt(): string {
+  return `Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+
+## When to Use
+
+- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+
+## When NOT to Use
+
+- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
+- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
+- Never use this tool unless the user explicitly mentions "worktree"
+
+## Requirements
+
+- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
+- Must not already be in a worktree
+
+## Behavior
+
+- In a git repository: creates a new git worktree inside \`.claude/worktrees/\` with a new branch based on HEAD
+- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
+- Switches the session's working directory to the new worktree
+- Use ExitWorktree to leave the worktree mid-session (keep or remove). On session exit, if still in the worktree, the user will be prompted to keep or remove it
+
+## Parameters
+
+- \`name\` (optional): A name for the worktree. If not provided, a random name is generated.
+`
+}

src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts

@@ -0,0 +1,493 @@
+import { feature } from 'bun:bundle'
+import { writeFile } from 'fs/promises'
+import { z } from 'zod/v4'
+import {
+  getAllowedChannels,
+  hasExitedPlanModeInSession,
+  setHasExitedPlanMode,
+  setNeedsAutoModeExitAttachment,
+  setNeedsPlanModeExitAttachment,
+} from '../../bootstrap/state.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from '../../services/analytics/metadata.js'
+import {
+  buildTool,
+  type Tool,
+  type ToolDef,
+  toolMatchesName,
+} from '../../Tool.js'
+import { formatAgentId, generateRequestId } from '../../utils/agentId.js'
+import { isAgentSwarmsEnabled } from '../../utils/agentSwarmsEnabled.js'
+import { logForDebugging } from '../../utils/debug.js'
+import {
+  findInProcessTeammateTaskId,
+  setAwaitingPlanApproval,
+} from '../../utils/inProcessTeammateHelpers.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import {
+  getPlan,
+  getPlanFilePath,
+  persistFileSnapshotIfRemote,
+} from '../../utils/plans.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import {
+  getAgentName,
+  getTeamName,
+  isPlanModeRequired,
+  isTeammate,
+} from '../../utils/teammate.js'
+import { writeToMailbox } from '../../utils/teammateMailbox.js'
+import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'
+import { TEAM_CREATE_TOOL_NAME } from '../TeamCreateTool/constants.js'
+import { EXIT_PLAN_MODE_V2_TOOL_NAME } from './constants.js'
+import { EXIT_PLAN_MODE_V2_TOOL_PROMPT } from './prompt.js'
+import {
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+} from './UI.js'
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const autoModeStateModule = feature('TRANSCRIPT_CLASSIFIER')
+  ? (require('../../utils/permissions/autoModeState.js') as typeof import('../../utils/permissions/autoModeState.js'))
+  : null
+const permissionSetupModule = feature('TRANSCRIPT_CLASSIFIER')
+  ? (require('../../utils/permissions/permissionSetup.js') as typeof import('../../utils/permissions/permissionSetup.js'))
+  : null
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+/**
+ * Schema for prompt-based permission requests.
+ * Used by Claude to request semantic permissions when exiting plan mode.
+ */
+const allowedPromptSchema = lazySchema(() =>
+  z.object({
+    tool: z.enum(['Bash']).describe('The tool this prompt applies to'),
+    prompt: z
+      .string()
+      .describe(
+        'Semantic description of the action, e.g. "run tests", "install dependencies"',
+      ),
+  }),
+)
+
+export type AllowedPrompt = z.infer<ReturnType<typeof allowedPromptSchema>>
+
+const inputSchema = lazySchema(() =>
+  z
+    .strictObject({
+      // Prompt-based permissions requested by the plan
+      allowedPrompts: z
+        .array(allowedPromptSchema())
+        .optional()
+        .describe(
+          'Prompt-based permissions needed to implement the plan. These describe categories of actions rather than specific commands.',
+        ),
+    })
+    .passthrough(),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+/**
+ * SDK-facing input schema - includes fields injected by normalizeToolInput.
+ * The internal inputSchema doesn't have these fields because plan is read from disk,
+ * but the SDK/hooks see the normalized version with plan and file path included.
+ */
+export const _sdkInputSchema = lazySchema(() =>
+  inputSchema().extend({
+    plan: z
+      .string()
+      .optional()
+      .describe('The plan content (injected by normalizeToolInput from disk)'),
+    planFilePath: z
+      .string()
+      .optional()
+      .describe('The plan file path (injected by normalizeToolInput)'),
+  }),
+)
+
+export const outputSchema = lazySchema(() =>
+  z.object({
+    plan: z
+      .string()
+      .nullable()
+      .describe('The plan that was presented to the user'),
+    isAgent: z.boolean(),
+    filePath: z
+      .string()
+      .optional()
+      .describe('The file path where the plan was saved'),
+    hasTaskTool: z
+      .boolean()
+      .optional()
+      .describe('Whether the Agent tool is available in the current context'),
+    planWasEdited: z
+      .boolean()
+      .optional()
+      .describe(
+        'True when the user edited the plan (CCR web UI or Ctrl+G); determines whether the plan is echoed back in tool_result',
+      ),
+    awaitingLeaderApproval: z
+      .boolean()
+      .optional()
+      .describe(
+        'When true, the teammate has sent a plan approval request to the team leader',
+      ),
+    requestId: z
+      .string()
+      .optional()
+      .describe('Unique identifier for the plan approval request'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const ExitPlanModeV2Tool: Tool<InputSchema, Output> = buildTool({
+  name: EXIT_PLAN_MODE_V2_TOOL_NAME,
+  searchHint: 'present plan for approval and start coding (plan mode only)',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Prompts the user to exit plan mode and start coding'
+  },
+  async prompt() {
+    return EXIT_PLAN_MODE_V2_TOOL_PROMPT
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return ''
+  },
+  shouldDefer: true,
+  isEnabled() {
+    // When --channels is active the user is likely on Telegram/Discord, not
+    // watching the TUI. The plan-approval dialog would hang. Paired with the
+    // same gate on EnterPlanMode so plan mode isn't a trap.
+    if (
+      (feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
+      getAllowedChannels().length > 0
+    ) {
+      return false
+    }
+    return true
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return false // Now writes to disk
+  },
+  requiresUserInteraction() {
+    // For ALL teammates, no local user interaction needed:
+    // - If isPlanModeRequired(): team lead approves via mailbox
+    // - Otherwise: exits locally without approval (voluntary plan mode)
+    if (isTeammate()) {
+      return false
+    }
+    // For non-teammates, require user confirmation to exit plan mode
+    return true
+  },
+  async validateInput(_input, { getAppState, options }) {
+    // Teammate AppState may show leader's mode (runAgent.ts skips override in
+    // acceptEdits/bypassPermissions/auto); isPlanModeRequired() is the real source
+    if (isTeammate()) {
+      return { result: true }
+    }
+    // The deferred-tool list announces this tool regardless of mode, so the
+    // model can call it after plan approval (fresh delta on compact/clear).
+    // Reject before checkPermissions to avoid showing the approval dialog.
+    const mode = getAppState().toolPermissionContext.mode
+    if (mode !== 'plan') {
+      logEvent('tengu_exit_plan_mode_called_outside_plan', {
+        model:
+          options.mainLoopModel as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        mode: mode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        hasExitedPlanModeInSession: hasExitedPlanModeInSession(),
+      })
+      return {
+        result: false,
+        message:
+          'You are not in plan mode. This tool is only for exiting plan mode after writing a plan. If your plan was already approved, continue with implementation.',
+        errorCode: 1,
+      }
+    }
+    return { result: true }
+  },
+  async checkPermissions(input, context) {
+    // For ALL teammates, bypass the permission UI to avoid sending permission_request
+    // The call() method handles the appropriate behavior:
+    // - If isPlanModeRequired(): sends plan_approval_request to leader
+    // - Otherwise: exits plan mode locally (voluntary plan mode)
+    if (isTeammate()) {
+      return {
+        behavior: 'allow' as const,
+        updatedInput: input,
+      }
+    }
+
+    // For non-teammates, require user confirmation to exit plan mode
+    return {
+      behavior: 'ask' as const,
+      message: 'Exit plan mode?',
+      updatedInput: input,
+    }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  renderToolUseRejectedMessage,
+  async call(input, context) {
+    const isAgent = !!context.agentId
+
+    const filePath = getPlanFilePath(context.agentId)
+    // CCR web UI may send an edited plan via permissionResult.updatedInput.
+    // queryHelpers.ts full-replaces finalInput, so when CCR sends {} (no edit)
+    // input.plan is undefined -> disk fallback. The internal inputSchema omits
+    // `plan` (normally injected by normalizeToolInput), hence the narrowing.
+    const inputPlan =
+      'plan' in input && typeof input.plan === 'string' ? input.plan : undefined
+    const plan = inputPlan ?? getPlan(context.agentId)
+
+    // Sync disk so VerifyPlanExecution / Read see the edit. Re-snapshot
+    // after: the only other persistFileSnapshotIfRemote call (api.ts) runs
+    // in normalizeToolInput, pre-permission — it captured the old plan.
+    if (inputPlan !== undefined && filePath) {
+      await writeFile(filePath, inputPlan, 'utf-8').catch(e => logError(e))
+      void persistFileSnapshotIfRemote()
+    }
+
+    // Check if this is a teammate that requires leader approval
+    if (isTeammate() && isPlanModeRequired()) {
+      // Plan is required for plan_mode_required teammates
+      if (!plan) {
+        throw new Error(
+          `No plan file found at ${filePath}. Please write your plan to this file before calling ExitPlanMode.`,
+        )
+      }
+      const agentName = getAgentName() || 'unknown'
+      const teamName = getTeamName()
+      const requestId = generateRequestId(
+        'plan_approval',
+        formatAgentId(agentName, teamName || 'default'),
+      )
+
+      const approvalRequest = {
+        type: 'plan_approval_request',
+        from: agentName,
+        timestamp: new Date().toISOString(),
+        planFilePath: filePath,
+        planContent: plan,
+        requestId,
+      }
+
+      await writeToMailbox(
+        'team-lead',
+        {
+          from: agentName,
+          text: jsonStringify(approvalRequest),
+          timestamp: new Date().toISOString(),
+        },
+        teamName,
+      )
+
+      // Update task state to show awaiting approval (for in-process teammates)
+      const appState = context.getAppState()
+      const agentTaskId = findInProcessTeammateTaskId(agentName, appState)
+      if (agentTaskId) {
+        setAwaitingPlanApproval(agentTaskId, context.setAppState, true)
+      }
+
+      return {
+        data: {
+          plan,
+          isAgent: true,
+          filePath,
+          awaitingLeaderApproval: true,
+          requestId,
+        },
+      }
+    }
+
+    // Note: Background verification hook is registered in REPL.tsx AFTER context clear
+    // via registerPlanVerificationHook(). Registering here would be cleared during context clear.
+
+    // Ensure mode is changed when exiting plan mode.
+    // This handles cases where permission flow didn't set the mode
+    // (e.g., when PermissionRequest hook auto-approves without providing updatedPermissions).
+    const appState = context.getAppState()
+    // Compute gate-off fallback before setAppState so we can notify the user.
+    // Circuit breaker defense: if prePlanMode was an auto-like mode but the
+    // gate is now off (circuit breaker or settings disable), restore to
+    // 'default' instead. Without this, ExitPlanMode would bypass the circuit
+    // breaker by calling setAutoModeActive(true) directly.
+    let gateFallbackNotification: string | null = null
+    if (feature('TRANSCRIPT_CLASSIFIER')) {
+      const prePlanRaw = appState.toolPermissionContext.prePlanMode ?? 'default'
+      if (
+        prePlanRaw === 'auto' &&
+        !(permissionSetupModule?.isAutoModeGateEnabled() ?? false)
+      ) {
+        const reason =
+          permissionSetupModule?.getAutoModeUnavailableReason() ??
+          'circuit-breaker'
+        gateFallbackNotification =
+          permissionSetupModule?.getAutoModeUnavailableNotification(reason) ??
+          'auto mode unavailable'
+        logForDebugging(
+          `[auto-mode gate @ ExitPlanModeV2Tool] prePlanMode=${prePlanRaw} ` +
+            `but gate is off (reason=${reason}) — falling back to default on plan exit`,
+          { level: 'warn' },
+        )
+      }
+    }
+    if (gateFallbackNotification) {
+      context.addNotification?.({
+        key: 'auto-mode-gate-plan-exit-fallback',
+        text: `plan exit → default · ${gateFallbackNotification}`,
+        priority: 'immediate',
+        color: 'warning',
+        timeoutMs: 10000,
+      })
+    }
+
+    context.setAppState(prev => {
+      if (prev.toolPermissionContext.mode !== 'plan') return prev
+      setHasExitedPlanMode(true)
+      setNeedsPlanModeExitAttachment(true)
+      let restoreMode = prev.toolPermissionContext.prePlanMode ?? 'default'
+      if (feature('TRANSCRIPT_CLASSIFIER')) {
+        if (
+          restoreMode === 'auto' &&
+          !(permissionSetupModule?.isAutoModeGateEnabled() ?? false)
+        ) {
+          restoreMode = 'default'
+        }
+        const finalRestoringAuto = restoreMode === 'auto'
+        // Capture pre-restore state — isAutoModeActive() is the authoritative
+        // signal (prePlanMode/strippedDangerousRules are stale after
+        // transitionPlanAutoMode deactivates mid-plan).
+        const autoWasUsedDuringPlan =
+          autoModeStateModule?.isAutoModeActive() ?? false
+        autoModeStateModule?.setAutoModeActive(finalRestoringAuto)
+        if (autoWasUsedDuringPlan && !finalRestoringAuto) {
+          setNeedsAutoModeExitAttachment(true)
+        }
+      }
+      // If restoring to a non-auto mode and permissions were stripped (either
+      // from entering plan from auto, or from shouldPlanUseAutoMode),
+      // restore them. If restoring to auto, keep them stripped.
+      const restoringToAuto = restoreMode === 'auto'
+      let baseContext = prev.toolPermissionContext
+      if (restoringToAuto) {
+        baseContext =
+          permissionSetupModule?.stripDangerousPermissionsForAutoMode(
+            baseContext,
+          ) ?? baseContext
+      } else if (prev.toolPermissionContext.strippedDangerousRules) {
+        baseContext =
+          permissionSetupModule?.restoreDangerousPermissions(baseContext) ??
+          baseContext
+      }
+      return {
+        ...prev,
+        toolPermissionContext: {
+          ...baseContext,
+          mode: restoreMode,
+          prePlanMode: undefined,
+        },
+      }
+    })
+
+    const hasTaskTool =
+      isAgentSwarmsEnabled() &&
+      context.options.tools.some(t => toolMatchesName(t, AGENT_TOOL_NAME))
+
+    return {
+      data: {
+        plan,
+        isAgent,
+        filePath,
+        hasTaskTool: hasTaskTool || undefined,
+        planWasEdited: inputPlan !== undefined || undefined,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam(
+    {
+      isAgent,
+      plan,
+      filePath,
+      hasTaskTool,
+      planWasEdited,
+      awaitingLeaderApproval,
+      requestId,
+    },
+    toolUseID,
+  ) {
+    // Handle teammate awaiting leader approval
+    if (awaitingLeaderApproval) {
+      return {
+        type: 'tool_result',
+        content: `Your plan has been submitted to the team lead for approval.
+
+Plan file: ${filePath}
+
+**What happens next:**
+1. Wait for the team lead to review your plan
+2. You will receive a message in your inbox with approval/rejection
+3. If approved, you can proceed with implementation
+4. If rejected, refine your plan based on the feedback
+
+**Important:** Do NOT proceed until you receive approval. Check your inbox for response.
+
+Request ID: ${requestId}`,
+        tool_use_id: toolUseID,
+      }
+    }
+
+    if (isAgent) {
+      return {
+        type: 'tool_result',
+        content:
+          'User has approved the plan. There is nothing else needed from you now. Please respond with "ok"',
+        tool_use_id: toolUseID,
+      }
+    }
+
+    // Handle empty plan
+    if (!plan || plan.trim() === '') {
+      return {
+        type: 'tool_result',
+        content: 'User has approved exiting plan mode. You can now proceed.',
+        tool_use_id: toolUseID,
+      }
+    }
+
+    const teamHint = hasTaskTool
+      ? `\n\nIf this plan can be broken down into multiple independent tasks, consider using the ${TEAM_CREATE_TOOL_NAME} tool to create a team and parallelize the work.`
+      : ''
+
+    // Always include the plan — extractApprovedPlan() in the Ultraplan CCR
+    // flow parses the tool_result to retrieve the plan text for the local CLI.
+    // Label edited plans so the model knows the user changed something.
+    const planLabel = planWasEdited
+      ? 'Approved Plan (edited by user)'
+      : 'Approved Plan'
+
+    return {
+      type: 'tool_result',
+      content: `User has approved your plan. You can now start coding. Start with updating your todo list if applicable
+
+Your plan has been saved to: ${filePath}
+You can refer back to it if needed during implementation.${teamHint}
+
+## ${planLabel}:
+${plan}`,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/ExitPlanModeTool/constants.ts

@@ -0,0 +1,2 @@
+export const EXIT_PLAN_MODE_TOOL_NAME = 'ExitPlanMode'
+export const EXIT_PLAN_MODE_V2_TOOL_NAME = 'ExitPlanMode'

src/tools/ExitPlanModeTool/prompt.ts

@@ -0,0 +1,29 @@
+// External stub for ExitPlanModeTool prompt - excludes Ant-only allowedPrompts section
+
+// Hardcoded to avoid relative import issues in stub
+const ASK_USER_QUESTION_TOOL_NAME = 'AskUserQuestion'
+
+export const EXIT_PLAN_MODE_V2_TOOL_PROMPT = `Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+
+## How This Tool Works
+- You should have already written your plan to the plan file specified in the plan mode system message
+- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
+- This tool simply signals that you're done planning and ready for the user to review and approve
+- The user will see the contents of your plan file when they review it
+
+## When to Use This Tool
+IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+
+## Before Using This Tool
+Ensure your plan is complete and unambiguous:
+- If you have unresolved questions about requirements or approach, use ${ASK_USER_QUESTION_TOOL_NAME} first (in earlier phases)
+- Once your plan is finalized, use THIS tool to request approval
+
+**Important:** Do NOT use ${ASK_USER_QUESTION_TOOL_NAME} to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
+
+## Examples
+
+1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
+2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
+3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use ${ASK_USER_QUESTION_TOOL_NAME} first, then use exit plan mode tool after clarifying the approach.
+`

src/tools/ExitWorktreeTool/ExitWorktreeTool.ts

@@ -0,0 +1,329 @@
+import { z } from 'zod/v4'
+import {
+  getOriginalCwd,
+  getProjectRoot,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../../bootstrap/state.js'
+import { clearSystemPromptSections } from '../../constants/systemPromptSections.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { Tool } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { count } from '../../utils/array.js'
+import { clearMemoryFileCaches } from '../../utils/claudemd.js'
+import { execFileNoThrow } from '../../utils/execFileNoThrow.js'
+import { updateHooksConfigSnapshot } from '../../utils/hooks/hooksConfigSnapshot.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getPlansDirectory } from '../../utils/plans.js'
+import { setCwd } from '../../utils/Shell.js'
+import { saveWorktreeState } from '../../utils/sessionStorage.js'
+import {
+  cleanupWorktree,
+  getCurrentWorktreeSession,
+  keepWorktree,
+  killTmuxSession,
+} from '../../utils/worktree.js'
+import { EXIT_WORKTREE_TOOL_NAME } from './constants.js'
+import { getExitWorktreeToolPrompt } from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    action: z
+      .enum(['keep', 'remove'])
+      .describe(
+        '"keep" leaves the worktree and branch on disk; "remove" deletes both.',
+      ),
+    discard_changes: z
+      .boolean()
+      .optional()
+      .describe(
+        'Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise.',
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    action: z.enum(['keep', 'remove']),
+    originalCwd: z.string(),
+    worktreePath: z.string(),
+    worktreeBranch: z.string().optional(),
+    tmuxSessionName: z.string().optional(),
+    discardedFiles: z.number().optional(),
+    discardedCommits: z.number().optional(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+type ChangeSummary = {
+  changedFiles: number
+  commits: number
+}
+
+/**
+ * Returns null when state cannot be reliably determined — callers that use
+ * this as a safety gate must treat null as "unknown, assume unsafe"
+ * (fail-closed). A silent 0/0 would let cleanupWorktree destroy real work.
+ *
+ * Null is returned when:
+ * - git status or rev-list exit non-zero (lock file, corrupt index, bad ref)
+ * - originalHeadCommit is undefined but git status succeeded — this is the
+ *   hook-based-worktree-wrapping-git case (worktree.ts:525-532 doesn't set
+ *   originalHeadCommit). We can see the working tree is git, but cannot count
+ *   commits without a baseline, so we cannot prove the branch is clean.
+ */
+async function countWorktreeChanges(
+  worktreePath: string,
+  originalHeadCommit: string | undefined,
+): Promise<ChangeSummary | null> {
+  const status = await execFileNoThrow('git', [
+    '-C',
+    worktreePath,
+    'status',
+    '--porcelain',
+  ])
+  if (status.code !== 0) {
+    return null
+  }
+  const changedFiles = count(status.stdout.split('\n'), l => l.trim() !== '')
+
+  if (!originalHeadCommit) {
+    // git status succeeded → this is a git repo, but without a baseline
+    // commit we cannot count commits. Fail-closed rather than claim 0.
+    return null
+  }
+
+  const revList = await execFileNoThrow('git', [
+    '-C',
+    worktreePath,
+    'rev-list',
+    '--count',
+    `${originalHeadCommit}..HEAD`,
+  ])
+  if (revList.code !== 0) {
+    return null
+  }
+  const commits = parseInt(revList.stdout.trim(), 10) || 0
+
+  return { changedFiles, commits }
+}
+
+/**
+ * Restore session state to reflect the original directory.
+ * This is the inverse of the session-level mutations in EnterWorktreeTool.call().
+ *
+ * keepWorktree()/cleanupWorktree() handle process.chdir and currentWorktreeSession;
+ * this handles everything above the worktree utility layer.
+ */
+function restoreSessionToOriginalCwd(
+  originalCwd: string,
+  projectRootIsWorktree: boolean,
+): void {
+  setCwd(originalCwd)
+  // EnterWorktree sets originalCwd to the *worktree* path (intentional — see
+  // state.ts getProjectRoot comment). Reset to the real original.
+  setOriginalCwd(originalCwd)
+  // --worktree startup sets projectRoot to the worktree; mid-session
+  // EnterWorktreeTool does not. Only restore when it was actually changed —
+  // otherwise we'd move projectRoot to wherever the user had cd'd before
+  // entering the worktree (session.originalCwd), breaking the "stable project
+  // identity" contract.
+  if (projectRootIsWorktree) {
+    setProjectRoot(originalCwd)
+    // setup.ts's --worktree block called updateHooksConfigSnapshot() to re-read
+    // hooks from the worktree. Restore symmetrically. (Mid-session
+    // EnterWorktreeTool never touched the snapshot, so no-op there.)
+    updateHooksConfigSnapshot()
+  }
+  saveWorktreeState(null)
+  clearSystemPromptSections()
+  clearMemoryFileCaches()
+  getPlansDirectory.cache.clear?.()
+}
+
+export const ExitWorktreeTool: Tool<InputSchema, Output> = buildTool({
+  name: EXIT_WORKTREE_TOOL_NAME,
+  searchHint: 'exit a worktree session and return to the original directory',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Exits a worktree session created by EnterWorktree and restores the original working directory'
+  },
+  async prompt() {
+    return getExitWorktreeToolPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'Exiting worktree'
+  },
+  shouldDefer: true,
+  isDestructive(input) {
+    return input.action === 'remove'
+  },
+  toAutoClassifierInput(input) {
+    return input.action
+  },
+  async validateInput(input) {
+    // Scope guard: getCurrentWorktreeSession() is null unless EnterWorktree
+    // (specifically createWorktreeForSession) ran in THIS session. Worktrees
+    // created by `git worktree add`, or by EnterWorktree in a previous
+    // session, do not populate it. This is the sole entry gate — everything
+    // past this point operates on a path EnterWorktree created.
+    const session = getCurrentWorktreeSession()
+    if (!session) {
+      return {
+        result: false,
+        message:
+          'No-op: there is no active EnterWorktree session to exit. This tool only operates on worktrees created by EnterWorktree in the current session — it will not touch worktrees created manually or in a previous session. No filesystem changes were made.',
+        errorCode: 1,
+      }
+    }
+
+    if (input.action === 'remove' && !input.discard_changes) {
+      const summary = await countWorktreeChanges(
+        session.worktreePath,
+        session.originalHeadCommit,
+      )
+      if (summary === null) {
+        return {
+          result: false,
+          message: `Could not verify worktree state at ${session.worktreePath}. Refusing to remove without explicit confirmation. Re-invoke with discard_changes: true to proceed — or use action: "keep" to preserve the worktree.`,
+          errorCode: 3,
+        }
+      }
+      const { changedFiles, commits } = summary
+      if (changedFiles > 0 || commits > 0) {
+        const parts: string[] = []
+        if (changedFiles > 0) {
+          parts.push(
+            `${changedFiles} uncommitted ${changedFiles === 1 ? 'file' : 'files'}`,
+          )
+        }
+        if (commits > 0) {
+          parts.push(
+            `${commits} ${commits === 1 ? 'commit' : 'commits'} on ${session.worktreeBranch ?? 'the worktree branch'}`,
+          )
+        }
+        return {
+          result: false,
+          message: `Worktree has ${parts.join(' and ')}. Removing will discard this work permanently. Confirm with the user, then re-invoke with discard_changes: true — or use action: "keep" to preserve the worktree.`,
+          errorCode: 2,
+        }
+      }
+    }
+
+    return { result: true }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call(input) {
+    const session = getCurrentWorktreeSession()
+    if (!session) {
+      // validateInput guards this, but the session is module-level mutable
+      // state — defend against a race between validation and execution.
+      throw new Error('Not in a worktree session')
+    }
+
+    // Capture before keepWorktree/cleanupWorktree null out currentWorktreeSession.
+    const {
+      originalCwd,
+      worktreePath,
+      worktreeBranch,
+      tmuxSessionName,
+      originalHeadCommit,
+    } = session
+
+    // --worktree startup calls setOriginalCwd(getCwd()) and
+    // setProjectRoot(getCwd()) back-to-back right after setCwd(worktreePath)
+    // (setup.ts:235/239), so both hold the same realpath'd value and BashTool
+    // cd never touches either. Mid-session EnterWorktreeTool sets originalCwd
+    // but NOT projectRoot. (Can't use getCwd() — BashTool mutates it on every
+    // cd. Can't use session.worktreePath — it's join()'d, not realpath'd.)
+    const projectRootIsWorktree = getProjectRoot() === getOriginalCwd()
+
+    // Re-count at execution time for accurate analytics and output — the
+    // worktree state at validateInput time may not match now. Null (git
+    // failure) falls back to 0/0; safety gating already happened in
+    // validateInput, so this only affects analytics + messaging.
+    const { changedFiles, commits } = (await countWorktreeChanges(
+      worktreePath,
+      originalHeadCommit,
+    )) ?? { changedFiles: 0, commits: 0 }
+
+    if (input.action === 'keep') {
+      await keepWorktree()
+      restoreSessionToOriginalCwd(originalCwd, projectRootIsWorktree)
+
+      logEvent('tengu_worktree_kept', {
+        mid_session: true,
+        commits,
+        changed_files: changedFiles,
+      })
+
+      const tmuxNote = tmuxSessionName
+        ? ` Tmux session ${tmuxSessionName} is still running; reattach with: tmux attach -t ${tmuxSessionName}`
+        : ''
+      return {
+        data: {
+          action: 'keep' as const,
+          originalCwd,
+          worktreePath,
+          worktreeBranch,
+          tmuxSessionName,
+          message: `Exited worktree. Your work is preserved at ${worktreePath}${worktreeBranch ? ` on branch ${worktreeBranch}` : ''}. Session is now back in ${originalCwd}.${tmuxNote}`,
+        },
+      }
+    }
+
+    // action === 'remove'
+    if (tmuxSessionName) {
+      await killTmuxSession(tmuxSessionName)
+    }
+    await cleanupWorktree()
+    restoreSessionToOriginalCwd(originalCwd, projectRootIsWorktree)
+
+    logEvent('tengu_worktree_removed', {
+      mid_session: true,
+      commits,
+      changed_files: changedFiles,
+    })
+
+    const discardParts: string[] = []
+    if (commits > 0) {
+      discardParts.push(`${commits} ${commits === 1 ? 'commit' : 'commits'}`)
+    }
+    if (changedFiles > 0) {
+      discardParts.push(
+        `${changedFiles} uncommitted ${changedFiles === 1 ? 'file' : 'files'}`,
+      )
+    }
+    const discardNote =
+      discardParts.length > 0 ? ` Discarded ${discardParts.join(' and ')}.` : ''
+    return {
+      data: {
+        action: 'remove' as const,
+        originalCwd,
+        worktreePath,
+        worktreeBranch,
+        discardedFiles: changedFiles,
+        discardedCommits: commits,
+        message: `Exited and removed worktree at ${worktreePath}.${discardNote} Session is now back in ${originalCwd}.`,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam({ message }, toolUseID) {
+    return {
+      type: 'tool_result',
+      content: message,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/ExitWorktreeTool/UI.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Box, Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import type { ThemeName } from '../../utils/theme.js';
+import type { Output } from './ExitWorktreeTool.js';
+export function renderToolUseMessage(): React.ReactNode {
+  return 'Exiting worktree…';
+}
+export function renderToolResultMessage(output: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], _options: {
+  theme: ThemeName;
+}): React.ReactNode {
+  const actionLabel = output.action === 'keep' ? 'Kept worktree' : 'Removed worktree';
+  return <Box flexDirection="column">
+      <Text>
+        {actionLabel}
+        {output.worktreeBranch ? <>
+            {' '}
+            (branch <Text bold>{output.worktreeBranch}</Text>)
+          </> : null}
+      </Text>
+      <Text dimColor>Returned to {output.originalCwd}</Text>
+    </Box>;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIkJveCIsIlRleHQiLCJUb29sUHJvZ3Jlc3NEYXRhIiwiUHJvZ3Jlc3NNZXNzYWdlIiwiVGhlbWVOYW1lIiwiT3V0cHV0IiwicmVuZGVyVG9vbFVzZU1lc3NhZ2UiLCJSZWFjdE5vZGUiLCJyZW5kZXJUb29sUmVzdWx0TWVzc2FnZSIsIm91dHB1dCIsIl9wcm9ncmVzc01lc3NhZ2VzRm9yTWVzc2FnZSIsIl9vcHRpb25zIiwidGhlbWUiLCJhY3Rpb25MYWJlbCIsImFjdGlvbiIsIndvcmt0cmVlQnJhbmNoIiwib3JpZ2luYWxDd2QiXSwic291cmNlcyI6WyJVSS50c3giXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0ICogYXMgUmVhY3QgZnJvbSAncmVhY3QnXG5pbXBvcnQgeyBCb3gsIFRleHQgfSBmcm9tICcuLi8uLi9pbmsuanMnXG5pbXBvcnQgdHlwZSB7IFRvb2xQcm9ncmVzc0RhdGEgfSBmcm9tICcuLi8uLi9Ub29sLmpzJ1xuaW1wb3J0IHR5cGUgeyBQcm9ncmVzc01lc3NhZ2UgfSBmcm9tICcuLi8uLi90eXBlcy9tZXNzYWdlLmpzJ1xuaW1wb3J0IHR5cGUgeyBUaGVtZU5hbWUgfSBmcm9tICcuLi8uLi91dGlscy90aGVtZS5qcydcbmltcG9ydCB0eXBlIHsgT3V0cHV0IH0gZnJvbSAnLi9FeGl0V29ya3RyZWVUb29sLmpzJ1xuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZU1lc3NhZ2UoKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuICdFeGl0aW5nIHdvcmt0cmVl4oCmJ1xufVxuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFJlc3VsdE1lc3NhZ2UoXG4gIG91dHB1dDogT3V0cHV0LFxuICBfcHJvZ3Jlc3NNZXNzYWdlc0Zvck1lc3NhZ2U6IFByb2dyZXNzTWVzc2FnZTxUb29sUHJvZ3Jlc3NEYXRhPltdLFxuICBfb3B0aW9uczogeyB0aGVtZTogVGhlbWVOYW1lIH0sXG4pOiBSZWFjdC5SZWFjdE5vZGUge1xuICBjb25zdCBhY3Rpb25MYWJlbCA9XG4gICAgb3V0cHV0LmFjdGlvbiA9PT0gJ2tlZXAnID8gJ0tlcHQgd29ya3RyZWUnIDogJ1JlbW92ZWQgd29ya3RyZWUnXG4gIHJldHVybiAoXG4gICAgPEJveCBmbGV4RGlyZWN0aW9uPVwiY29sdW1uXCI+XG4gICAgICA8VGV4dD5cbiAgICAgICAge2FjdGlvbkxhYmVsfVxuICAgICAgICB7b3V0cHV0Lndvcmt0cmVlQnJhbmNoID8gKFxuICAgICAgICAgIDw+XG4gICAgICAgICAgICB7JyAnfVxuICAgICAgICAgICAgKGJyYW5jaCA8VGV4dCBib2xkPntvdXRwdXQud29ya3RyZWVCcmFuY2h9PC9UZXh0PilcbiAgICAgICAgICA8Lz5cbiAgICAgICAgKSA6IG51bGx9XG4gICAgICA8L1RleHQ+XG4gICAgICA8VGV4dCBkaW1Db2xvcj5SZXR1cm5lZCB0byB7b3V0cHV0Lm9yaWdpbmFsQ3dkfTwvVGV4dD5cbiAgICA8L0JveD5cbiAgKVxufVxuIl0sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUtBLEtBQUssTUFBTSxPQUFPO0FBQzlCLFNBQVNDLEdBQUcsRUFBRUMsSUFBSSxRQUFRLGNBQWM7QUFDeEMsY0FBY0MsZ0JBQWdCLFFBQVEsZUFBZTtBQUNyRCxjQUFjQyxlQUFlLFFBQVEsd0JBQXdCO0FBQzdELGNBQWNDLFNBQVMsUUFBUSxzQkFBc0I7QUFDckQsY0FBY0MsTUFBTSxRQUFRLHVCQUF1QjtBQUVuRCxPQUFPLFNBQVNDLG9CQUFvQkEsQ0FBQSxDQUFFLEVBQUVQLEtBQUssQ0FBQ1EsU0FBUyxDQUFDO0VBQ3RELE9BQU8sbUJBQW1CO0FBQzVCO0FBRUEsT0FBTyxTQUFTQyx1QkFBdUJBLENBQ3JDQyxNQUFNLEVBQUVKLE1BQU0sRUFDZEssMkJBQTJCLEVBQUVQLGVBQWUsQ0FBQ0QsZ0JBQWdCLENBQUMsRUFBRSxFQUNoRVMsUUFBUSxFQUFFO0VBQUVDLEtBQUssRUFBRVIsU0FBUztBQUFDLENBQUMsQ0FDL0IsRUFBRUwsS0FBSyxDQUFDUSxTQUFTLENBQUM7RUFDakIsTUFBTU0sV0FBVyxHQUNmSixNQUFNLENBQUNLLE1BQU0sS0FBSyxNQUFNLEdBQUcsZUFBZSxHQUFHLGtCQUFrQjtFQUNqRSxPQUNFLENBQUMsR0FBRyxDQUFDLGFBQWEsQ0FBQyxRQUFRO0FBQy9CLE1BQU0sQ0FBQyxJQUFJO0FBQ1gsUUFBUSxDQUFDRCxXQUFXO0FBQ3BCLFFBQVEsQ0FBQ0osTUFBTSxDQUFDTSxjQUFjLEdBQ3BCO0FBQ1YsWUFBWSxDQUFDLEdBQUc7QUFDaEIsb0JBQW9CLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDTixNQUFNLENBQUNNLGNBQWMsQ0FBQyxFQUFFLElBQUksQ0FBQztBQUM3RCxVQUFVLEdBQUcsR0FDRCxJQUFJO0FBQ2hCLE1BQU0sRUFBRSxJQUFJO0FBQ1osTUFBTSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsWUFBWSxDQUFDTixNQUFNLENBQUNPLFdBQVcsQ0FBQyxFQUFFLElBQUk7QUFDM0QsSUFBSSxFQUFFLEdBQUcsQ0FBQztBQUVWIiwiaWdub3JlTGlzdCI6W119

src/tools/ExitWorktreeTool/constants.ts

@@ -0,0 +1 @@
+export const EXIT_WORKTREE_TOOL_NAME = 'ExitWorktree'

src/tools/ExitWorktreeTool/prompt.ts

@@ -0,0 +1,32 @@
+export function getExitWorktreeToolPrompt(): string {
+  return `Exit a worktree session created by EnterWorktree and return the session to the original working directory.
+
+## Scope
+
+This tool ONLY operates on worktrees created by EnterWorktree in this session. It will NOT touch:
+- Worktrees you created manually with \`git worktree add\`
+- Worktrees from a previous session (even if created by EnterWorktree then)
+- The directory you're in if EnterWorktree was never called
+
+If called outside an EnterWorktree session, the tool is a **no-op**: it reports that no worktree session is active and takes no action. Filesystem state is unchanged.
+
+## When to Use
+
+- The user explicitly asks to "exit the worktree", "leave the worktree", "go back", or otherwise end the worktree session
+- Do NOT call this proactively — only when the user asks
+
+## Parameters
+
+- \`action\` (required): \`"keep"\` or \`"remove"\`
+  - \`"keep"\` — leave the worktree directory and branch intact on disk. Use this if the user wants to come back to the work later, or if there are changes to preserve.
+  - \`"remove"\` — delete the worktree directory and its branch. Use this for a clean exit when the work is done or abandoned.
+- \`discard_changes\` (optional, default false): only meaningful with \`action: "remove"\`. If the worktree has uncommitted files or commits not on the original branch, the tool will REFUSE to remove it unless this is set to \`true\`. If the tool returns an error listing changes, confirm with the user before re-invoking with \`discard_changes: true\`.
+
+## Behavior
+
+- Restores the session's working directory to where it was before EnterWorktree
+- Clears CWD-dependent caches (system prompt sections, memory files, plans directory) so the session state reflects the original directory
+- If a tmux session was attached to the worktree: killed on \`remove\`, left running on \`keep\` (its name is returned so the user can reattach)
+- Once exited, EnterWorktree can be called again to create a fresh worktree
+`
+}

src/tools/FileEditTool/FileEditTool.ts

@@ -0,0 +1,625 @@
+import { dirname, isAbsolute, sep } from 'path'
+import { logEvent } from 'src/services/analytics/index.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import { diagnosticTracker } from '../../services/diagnosticTracking.js'
+import { clearDeliveredDiagnosticsForFile } from '../../services/lsp/LSPDiagnosticRegistry.js'
+import { getLspServerManager } from '../../services/lsp/manager.js'
+import { notifyVscodeFileUpdated } from '../../services/mcp/vscodeSdkMcp.js'
+import { checkTeamMemSecrets } from '../../services/teamMemorySync/teamMemSecretGuard.js'
+import {
+  activateConditionalSkillsForPaths,
+  addSkillDirectories,
+  discoverSkillDirsForPaths,
+} from '../../skills/loadSkillsDir.js'
+import type { ToolUseContext } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { countLinesChanged } from '../../utils/diff.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { isENOENT } from '../../utils/errors.js'
+import {
+  FILE_NOT_FOUND_CWD_NOTE,
+  findSimilarFile,
+  getFileModificationTime,
+  suggestPathUnderCwd,
+  writeTextContent,
+} from '../../utils/file.js'
+import {
+  fileHistoryEnabled,
+  fileHistoryTrackEdit,
+} from '../../utils/fileHistory.js'
+import { logFileOperation } from '../../utils/fileOperationAnalytics.js'
+import {
+  type LineEndingType,
+  readFileSyncWithMetadata,
+} from '../../utils/fileRead.js'
+import { formatFileSize } from '../../utils/format.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import {
+  fetchSingleFileGitDiff,
+  type ToolUseDiff,
+} from '../../utils/gitDiff.js'
+import { logError } from '../../utils/log.js'
+import { expandPath } from '../../utils/path.js'
+import {
+  checkWritePermissionForTool,
+  matchingRuleForInput,
+} from '../../utils/permissions/filesystem.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { matchWildcardPattern } from '../../utils/permissions/shellRuleMatching.js'
+import { validateInputForSettingsFileEdit } from '../../utils/settings/validateEditTool.js'
+import { NOTEBOOK_EDIT_TOOL_NAME } from '../NotebookEditTool/constants.js'
+import {
+  FILE_EDIT_TOOL_NAME,
+  FILE_UNEXPECTEDLY_MODIFIED_ERROR,
+} from './constants.js'
+import { getEditToolDescription } from './prompt.js'
+import {
+  type FileEditInput,
+  type FileEditOutput,
+  inputSchema,
+  outputSchema,
+} from './types.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+  userFacingName,
+} from './UI.js'
+import {
+  areFileEditsInputsEquivalent,
+  findActualString,
+  getPatchForEdit,
+  preserveQuoteStyle,
+} from './utils.js'
+
+// V8/Bun string length limit is ~2^30 characters (~1 billion). For typical
+// ASCII/Latin-1 files, 1 byte on disk = 1 character, so 1 GiB in stat bytes
+// ≈ 1 billion characters ≈ the runtime string limit. Multi-byte UTF-8 files
+// can be larger on disk per character, but 1 GiB is a safe byte-level guard
+// that prevents OOM without being unnecessarily restrictive.
+const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB (stat bytes)
+
+export const FileEditTool = buildTool({
+  name: FILE_EDIT_TOOL_NAME,
+  searchHint: 'modify file contents in place',
+  maxResultSizeChars: 100_000,
+  strict: true,
+  async description() {
+    return 'A tool for editing files'
+  },
+  async prompt() {
+    return getEditToolDescription()
+  },
+  userFacingName,
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const summary = getToolUseSummary(input)
+    return summary ? `Editing ${summary}` : 'Editing file'
+  },
+  get inputSchema() {
+    return inputSchema()
+  },
+  get outputSchema() {
+    return outputSchema()
+  },
+  toAutoClassifierInput(input) {
+    return `${input.file_path}: ${input.new_string}`
+  },
+  getPath(input): string {
+    return input.file_path
+  },
+  backfillObservableInput(input) {
+    // hooks.mdx documents file_path as absolute; expand so hook allowlists
+    // can't be bypassed via ~ or relative paths.
+    if (typeof input.file_path === 'string') {
+      input.file_path = expandPath(input.file_path)
+    }
+  },
+  async preparePermissionMatcher({ file_path }) {
+    return pattern => matchWildcardPattern(pattern, file_path)
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkWritePermissionForTool(
+      FileEditTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  renderToolUseRejectedMessage,
+  renderToolUseErrorMessage,
+  async validateInput(input: FileEditInput, toolUseContext: ToolUseContext) {
+    const { file_path, old_string, new_string, replace_all = false } = input
+    // Use expandPath for consistent path normalization (especially on Windows
+    // where "/" vs "\" can cause readFileState lookup mismatches)
+    const fullFilePath = expandPath(file_path)
+
+    // Reject edits to team memory files that introduce secrets
+    const secretError = checkTeamMemSecrets(fullFilePath, new_string)
+    if (secretError) {
+      return { result: false, message: secretError, errorCode: 0 }
+    }
+    if (old_string === new_string) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message:
+          'No changes to make: old_string and new_string are exactly the same.',
+        errorCode: 1,
+      }
+    }
+
+    // Check if path should be ignored based on permission settings
+    const appState = toolUseContext.getAppState()
+    const denyRule = matchingRuleForInput(
+      fullFilePath,
+      appState.toolPermissionContext,
+      'edit',
+      'deny',
+    )
+    if (denyRule !== null) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message:
+          'File is in a directory that is denied by your permission settings.',
+        errorCode: 2,
+      }
+    }
+
+    // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+    // On Windows, fs.existsSync() on UNC paths triggers SMB authentication which could
+    // leak credentials to malicious servers. Let the permission check handle UNC paths.
+    if (fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')) {
+      return { result: true }
+    }
+
+    const fs = getFsImplementation()
+
+    // Prevent OOM on multi-GB files.
+    try {
+      const { size } = await fs.stat(fullFilePath)
+      if (size > MAX_EDIT_FILE_SIZE) {
+        return {
+          result: false,
+          behavior: 'ask',
+          message: `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+          errorCode: 10,
+        }
+      }
+    } catch (e) {
+      if (!isENOENT(e)) {
+        throw e
+      }
+    }
+
+    // Read the file as bytes first so we can detect encoding from the buffer
+    // instead of calling detectFileEncoding (which does its own sync readSync
+    // and would fail with a wasted ENOENT when the file doesn't exist).
+    let fileContent: string | null
+    try {
+      const fileBuffer = await fs.readFileBytes(fullFilePath)
+      const encoding: BufferEncoding =
+        fileBuffer.length >= 2 &&
+        fileBuffer[0] === 0xff &&
+        fileBuffer[1] === 0xfe
+          ? 'utf16le'
+          : 'utf8'
+      fileContent = fileBuffer.toString(encoding).replaceAll('\r\n', '\n')
+    } catch (e) {
+      if (isENOENT(e)) {
+        fileContent = null
+      } else {
+        throw e
+      }
+    }
+
+    // File doesn't exist
+    if (fileContent === null) {
+      // Empty old_string on nonexistent file means new file creation — valid
+      if (old_string === '') {
+        return { result: true }
+      }
+      // Try to find a similar file with a different extension
+      const similarFilename = findSimilarFile(fullFilePath)
+      const cwdSuggestion = await suggestPathUnderCwd(fullFilePath)
+      let message = `File does not exist. ${FILE_NOT_FOUND_CWD_NOTE} ${getCwd()}.`
+
+      if (cwdSuggestion) {
+        message += ` Did you mean ${cwdSuggestion}?`
+      } else if (similarFilename) {
+        message += ` Did you mean ${similarFilename}?`
+      }
+
+      return {
+        result: false,
+        behavior: 'ask',
+        message,
+        errorCode: 4,
+      }
+    }
+
+    // File exists with empty old_string — only valid if file is empty
+    if (old_string === '') {
+      // Only reject if the file has content (for file creation attempt)
+      if (fileContent.trim() !== '') {
+        return {
+          result: false,
+          behavior: 'ask',
+          message: 'Cannot create new file - file already exists.',
+          errorCode: 3,
+        }
+      }
+
+      // Empty file with empty old_string is valid - we're replacing empty with content
+      return {
+        result: true,
+      }
+    }
+
+    if (fullFilePath.endsWith('.ipynb')) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message: `File is a Jupyter Notebook. Use the ${NOTEBOOK_EDIT_TOOL_NAME} to edit this file.`,
+        errorCode: 5,
+      }
+    }
+
+    const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
+    if (!readTimestamp || readTimestamp.isPartialView) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message:
+          'File has not been read yet. Read it first before writing to it.',
+        meta: {
+          isFilePathAbsolute: String(isAbsolute(file_path)),
+        },
+        errorCode: 6,
+      }
+    }
+
+    // Check if file exists and get its last modified time
+    if (readTimestamp) {
+      const lastWriteTime = getFileModificationTime(fullFilePath)
+      if (lastWriteTime > readTimestamp.timestamp) {
+        // Timestamp indicates modification, but on Windows timestamps can change
+        // without content changes (cloud sync, antivirus, etc.). For full reads,
+        // compare content as a fallback to avoid false positives.
+        const isFullRead =
+          readTimestamp.offset === undefined &&
+          readTimestamp.limit === undefined
+        if (isFullRead && fileContent === readTimestamp.content) {
+          // Content unchanged, safe to proceed
+        } else {
+          return {
+            result: false,
+            behavior: 'ask',
+            message:
+              'File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.',
+            errorCode: 7,
+          }
+        }
+      }
+    }
+
+    const file = fileContent
+
+    // Use findActualString to handle quote normalization
+    const actualOldString = findActualString(file, old_string)
+    if (!actualOldString) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message: `String to replace not found in file.\nString: ${old_string}`,
+        meta: {
+          isFilePathAbsolute: String(isAbsolute(file_path)),
+        },
+        errorCode: 8,
+      }
+    }
+
+    const matches = file.split(actualOldString).length - 1
+
+    // Check if we have multiple matches but replace_all is false
+    if (matches > 1 && !replace_all) {
+      return {
+        result: false,
+        behavior: 'ask',
+        message: `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${old_string}`,
+        meta: {
+          isFilePathAbsolute: String(isAbsolute(file_path)),
+          actualOldString,
+        },
+        errorCode: 9,
+      }
+    }
+
+    // Additional validation for Claude settings files
+    const settingsValidationResult = validateInputForSettingsFileEdit(
+      fullFilePath,
+      file,
+      () => {
+        // Simulate the edit to get the final content using the exact same logic as the tool
+        return replace_all
+          ? file.replaceAll(actualOldString, new_string)
+          : file.replace(actualOldString, new_string)
+      },
+    )
+
+    if (settingsValidationResult !== null) {
+      return settingsValidationResult
+    }
+
+    return { result: true, meta: { actualOldString } }
+  },
+  inputsEquivalent(input1, input2) {
+    return areFileEditsInputsEquivalent(
+      {
+        file_path: input1.file_path,
+        edits: [
+          {
+            old_string: input1.old_string,
+            new_string: input1.new_string,
+            replace_all: input1.replace_all ?? false,
+          },
+        ],
+      },
+      {
+        file_path: input2.file_path,
+        edits: [
+          {
+            old_string: input2.old_string,
+            new_string: input2.new_string,
+            replace_all: input2.replace_all ?? false,
+          },
+        ],
+      },
+    )
+  },
+  async call(
+    input: FileEditInput,
+    {
+      readFileState,
+      userModified,
+      updateFileHistoryState,
+      dynamicSkillDirTriggers,
+    },
+    _,
+    parentMessage,
+  ) {
+    const { file_path, old_string, new_string, replace_all = false } = input
+
+    // 1. Get current state
+    const fs = getFsImplementation()
+    const absoluteFilePath = expandPath(file_path)
+
+    // Discover skills from this file's path (fire-and-forget, non-blocking)
+    // Skip in simple mode - no skills available
+    const cwd = getCwd()
+    if (!isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
+      const newSkillDirs = await discoverSkillDirsForPaths(
+        [absoluteFilePath],
+        cwd,
+      )
+      if (newSkillDirs.length > 0) {
+        // Store discovered dirs for attachment display
+        for (const dir of newSkillDirs) {
+          dynamicSkillDirTriggers?.add(dir)
+        }
+        // Don't await - let skill loading happen in the background
+        addSkillDirectories(newSkillDirs).catch(() => {})
+      }
+
+      // Activate conditional skills whose path patterns match this file
+      activateConditionalSkillsForPaths([absoluteFilePath], cwd)
+    }
+
+    await diagnosticTracker.beforeFileEdited(absoluteFilePath)
+
+    // Ensure parent directory exists before the atomic read-modify-write section.
+    // These awaits must stay OUTSIDE the critical section below — a yield between
+    // the staleness check and writeTextContent lets concurrent edits interleave.
+    await fs.mkdir(dirname(absoluteFilePath))
+    if (fileHistoryEnabled()) {
+      // Backup captures pre-edit content — safe to call before the staleness
+      // check (idempotent v1 backup keyed on content hash; if staleness fails
+      // later we just have an unused backup, not corrupt state).
+      await fileHistoryTrackEdit(
+        updateFileHistoryState,
+        absoluteFilePath,
+        parentMessage.uuid,
+      )
+    }
+
+    // 2. Load current state and confirm no changes since last read
+    // Please avoid async operations between here and writing to disk to preserve atomicity
+    const {
+      content: originalFileContents,
+      fileExists,
+      encoding,
+      lineEndings: endings,
+    } = readFileForEdit(absoluteFilePath)
+
+    if (fileExists) {
+      const lastWriteTime = getFileModificationTime(absoluteFilePath)
+      const lastRead = readFileState.get(absoluteFilePath)
+      if (!lastRead || lastWriteTime > lastRead.timestamp) {
+        // Timestamp indicates modification, but on Windows timestamps can change
+        // without content changes (cloud sync, antivirus, etc.). For full reads,
+        // compare content as a fallback to avoid false positives.
+        const isFullRead =
+          lastRead &&
+          lastRead.offset === undefined &&
+          lastRead.limit === undefined
+        const contentUnchanged =
+          isFullRead && originalFileContents === lastRead.content
+        if (!contentUnchanged) {
+          throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR)
+        }
+      }
+    }
+
+    // 3. Use findActualString to handle quote normalization
+    const actualOldString =
+      findActualString(originalFileContents, old_string) || old_string
+
+    // Preserve curly quotes in new_string when the file uses them
+    const actualNewString = preserveQuoteStyle(
+      old_string,
+      actualOldString,
+      new_string,
+    )
+
+    // 4. Generate patch
+    const { patch, updatedFile } = getPatchForEdit({
+      filePath: absoluteFilePath,
+      fileContents: originalFileContents,
+      oldString: actualOldString,
+      newString: actualNewString,
+      replaceAll: replace_all,
+    })
+
+    // 5. Write to disk
+    writeTextContent(absoluteFilePath, updatedFile, encoding, endings)
+
+    // Notify LSP servers about file modification (didChange) and save (didSave)
+    const lspManager = getLspServerManager()
+    if (lspManager) {
+      // Clear previously delivered diagnostics so new ones will be shown
+      clearDeliveredDiagnosticsForFile(`file://${absoluteFilePath}`)
+      // didChange: Content has been modified
+      lspManager
+        .changeFile(absoluteFilePath, updatedFile)
+        .catch((err: Error) => {
+          logForDebugging(
+            `LSP: Failed to notify server of file change for ${absoluteFilePath}: ${err.message}`,
+          )
+          logError(err)
+        })
+      // didSave: File has been saved to disk (triggers diagnostics in TypeScript server)
+      lspManager.saveFile(absoluteFilePath).catch((err: Error) => {
+        logForDebugging(
+          `LSP: Failed to notify server of file save for ${absoluteFilePath}: ${err.message}`,
+        )
+        logError(err)
+      })
+    }
+
+    // Notify VSCode about the file change for diff view
+    notifyVscodeFileUpdated(absoluteFilePath, originalFileContents, updatedFile)
+
+    // 6. Update read timestamp, to invalidate stale writes
+    readFileState.set(absoluteFilePath, {
+      content: updatedFile,
+      timestamp: getFileModificationTime(absoluteFilePath),
+      offset: undefined,
+      limit: undefined,
+    })
+
+    // 7. Log events
+    if (absoluteFilePath.endsWith(`${sep}CLAUDE.md`)) {
+      logEvent('tengu_write_claudemd', {})
+    }
+    countLinesChanged(patch)
+
+    logFileOperation({
+      operation: 'edit',
+      tool: 'FileEditTool',
+      filePath: absoluteFilePath,
+    })
+
+    logEvent('tengu_edit_string_lengths', {
+      oldStringBytes: Buffer.byteLength(old_string, 'utf8'),
+      newStringBytes: Buffer.byteLength(new_string, 'utf8'),
+      replaceAll: replace_all,
+    })
+
+    let gitDiff: ToolUseDiff | undefined
+    if (
+      isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) &&
+      getFeatureValue_CACHED_MAY_BE_STALE('tengu_quartz_lantern', false)
+    ) {
+      const startTime = Date.now()
+      const diff = await fetchSingleFileGitDiff(absoluteFilePath)
+      if (diff) gitDiff = diff
+      logEvent('tengu_tool_use_diff_computed', {
+        isEditTool: true,
+        durationMs: Date.now() - startTime,
+        hasDiff: !!diff,
+      })
+    }
+
+    // 8. Yield result
+    const data = {
+      filePath: file_path,
+      oldString: actualOldString,
+      newString: new_string,
+      originalFile: originalFileContents,
+      structuredPatch: patch,
+      userModified: userModified ?? false,
+      replaceAll: replace_all,
+      ...(gitDiff && { gitDiff }),
+    }
+    return {
+      data,
+    }
+  },
+  mapToolResultToToolResultBlockParam(data: FileEditOutput, toolUseID) {
+    const { filePath, userModified, replaceAll } = data
+    const modifiedNote = userModified
+      ? '.  The user modified your proposed changes before accepting them. '
+      : ''
+
+    if (replaceAll) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: `The file ${filePath} has been updated${modifiedNote}. All occurrences were successfully replaced.`,
+      }
+    }
+
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: `The file ${filePath} has been updated successfully${modifiedNote}.`,
+    }
+  },
+} satisfies ToolDef<ReturnType<typeof inputSchema>, FileEditOutput>)
+
+// --
+
+function readFileForEdit(absoluteFilePath: string): {
+  content: string
+  fileExists: boolean
+  encoding: BufferEncoding
+  lineEndings: LineEndingType
+} {
+  try {
+    // eslint-disable-next-line custom-rules/no-sync-fs
+    const meta = readFileSyncWithMetadata(absoluteFilePath)
+    return {
+      content: meta.content,
+      fileExists: true,
+      encoding: meta.encoding,
+      lineEndings: meta.lineEndings,
+    }
+  } catch (e) {
+    if (isENOENT(e)) {
+      return {
+        content: '',
+        fileExists: false,
+        encoding: 'utf8',
+        lineEndings: 'LF',
+      }
+    }
+    throw e
+  }
+}

src/tools/FileEditTool/constants.ts

@@ -0,0 +1,11 @@
+// In its own file to avoid circular dependencies
+export const FILE_EDIT_TOOL_NAME = 'Edit'
+
+// Permission pattern for granting session-level access to the project's .claude/ folder
+export const CLAUDE_FOLDER_PERMISSION_PATTERN = '/.claude/**'
+
+// Permission pattern for granting session-level access to the global ~/.claude/ folder
+export const GLOBAL_CLAUDE_FOLDER_PERMISSION_PATTERN = '~/.claude/**'
+
+export const FILE_UNEXPECTEDLY_MODIFIED_ERROR =
+  'File has been unexpectedly modified. Read it again before attempting to write it.'

src/tools/FileEditTool/prompt.ts

@@ -0,0 +1,28 @@
+import { isCompactLinePrefixEnabled } from '../../utils/file.js'
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
+
+function getPreReadInstruction(): string {
+  return `\n- You must use your \`${FILE_READ_TOOL_NAME}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. `
+}
+
+export function getEditToolDescription(): string {
+  return getDefaultEditDescription()
+}
+
+function getDefaultEditDescription(): string {
+  const prefixFormat = isCompactLinePrefixEnabled()
+    ? 'line number + tab'
+    : 'spaces + line number + arrow'
+  const minimalUniquenessHint =
+    process.env.USER_TYPE === 'ant'
+      ? `\n- Use the smallest old_string that's clearly unique — usually 2-4 adjacent lines is sufficient. Avoid including 10+ lines of context when less uniquely identifies the target.`
+      : ''
+  return `Performs exact string replacements in files.
+
+Usage:${getPreReadInstruction()}
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: ${prefixFormat}. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.${minimalUniquenessHint}
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`
+}

src/tools/FileEditTool/types.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod/v4'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { semanticBoolean } from '../../utils/semanticBoolean.js'
+
+// The input schema with optional replace_all
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    file_path: z.string().describe('The absolute path to the file to modify'),
+    old_string: z.string().describe('The text to replace'),
+    new_string: z
+      .string()
+      .describe(
+        'The text to replace it with (must be different from old_string)',
+      ),
+    replace_all: semanticBoolean(
+      z.boolean().default(false).optional(),
+    ).describe('Replace all occurrences of old_string (default false)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+// Parsed output — what call() receives. z.output not z.input: with
+// semanticBoolean the input side is unknown (preprocess accepts anything).
+export type FileEditInput = z.output<InputSchema>
+
+// Individual edit without file_path
+export type EditInput = Omit<FileEditInput, 'file_path'>
+
+// Runtime version where replace_all is always defined
+export type FileEdit = {
+  old_string: string
+  new_string: string
+  replace_all: boolean
+}
+
+export const hunkSchema = lazySchema(() =>
+  z.object({
+    oldStart: z.number(),
+    oldLines: z.number(),
+    newStart: z.number(),
+    newLines: z.number(),
+    lines: z.array(z.string()),
+  }),
+)
+
+export const gitDiffSchema = lazySchema(() =>
+  z.object({
+    filename: z.string(),
+    status: z.enum(['modified', 'added']),
+    additions: z.number(),
+    deletions: z.number(),
+    changes: z.number(),
+    patch: z.string(),
+    repository: z
+      .string()
+      .nullable()
+      .optional()
+      .describe('GitHub owner/repo when available'),
+  }),
+)
+
+// Output schema for FileEditTool
+const outputSchema = lazySchema(() =>
+  z.object({
+    filePath: z.string().describe('The file path that was edited'),
+    oldString: z.string().describe('The original string that was replaced'),
+    newString: z.string().describe('The new string that replaced it'),
+    originalFile: z
+      .string()
+      .describe('The original file contents before editing'),
+    structuredPatch: z
+      .array(hunkSchema())
+      .describe('Diff patch showing the changes'),
+    userModified: z
+      .boolean()
+      .describe('Whether the user modified the proposed changes'),
+    replaceAll: z.boolean().describe('Whether all occurrences were replaced'),
+    gitDiff: gitDiffSchema().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type FileEditOutput = z.infer<OutputSchema>
+
+export { inputSchema, outputSchema }

src/tools/FileEditTool/utils.ts

@@ -0,0 +1,775 @@
+import { type StructuredPatchHunk, structuredPatch } from 'diff'
+import { logError } from 'src/utils/log.js'
+import { expandPath } from 'src/utils/path.js'
+import { countCharInString } from 'src/utils/stringUtils.js'
+import {
+  DIFF_TIMEOUT_MS,
+  getPatchForDisplay,
+  getPatchFromContents,
+} from '../../utils/diff.js'
+import { errorMessage, isENOENT } from '../../utils/errors.js'
+import {
+  addLineNumbers,
+  convertLeadingTabsToSpaces,
+  readFileSyncCached,
+} from '../../utils/file.js'
+import type { EditInput, FileEdit } from './types.js'
+
+// Claude can't output curly quotes, so we define them as constants here for Claude to use
+// in the code. We do this because we normalize curly quotes to straight quotes
+// when applying edits.
+export const LEFT_SINGLE_CURLY_QUOTE = '‘'
+export const RIGHT_SINGLE_CURLY_QUOTE = '’'
+export const LEFT_DOUBLE_CURLY_QUOTE = '“'
+export const RIGHT_DOUBLE_CURLY_QUOTE = '”'
+
+/**
+ * Normalizes quotes in a string by converting curly quotes to straight quotes
+ * @param str The string to normalize
+ * @returns The string with all curly quotes replaced by straight quotes
+ */
+export function normalizeQuotes(str: string): string {
+  return str
+    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
+    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"')
+}
+
+/**
+ * Strips trailing whitespace from each line in a string while preserving line endings
+ * @param str The string to process
+ * @returns The string with trailing whitespace removed from each line
+ */
+export function stripTrailingWhitespace(str: string): string {
+  // Handle different line endings: CRLF, LF, CR
+  // Use a regex that matches line endings and captures them
+  const lines = str.split(/(\r\n|\n|\r)/)
+
+  let result = ''
+  for (let i = 0; i < lines.length; i++) {
+    const part = lines[i]
+    if (part !== undefined) {
+      if (i % 2 === 0) {
+        // Even indices are line content
+        result += part.replace(/\s+$/, '')
+      } else {
+        // Odd indices are line endings
+        result += part
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Finds the actual string in the file content that matches the search string,
+ * accounting for quote normalization
+ * @param fileContent The file content to search in
+ * @param searchString The string to search for
+ * @returns The actual string found in the file, or null if not found
+ */
+export function findActualString(
+  fileContent: string,
+  searchString: string,
+): string | null {
+  // First try exact match
+  if (fileContent.includes(searchString)) {
+    return searchString
+  }
+
+  // Try with normalized quotes
+  const normalizedSearch = normalizeQuotes(searchString)
+  const normalizedFile = normalizeQuotes(fileContent)
+
+  const searchIndex = normalizedFile.indexOf(normalizedSearch)
+  if (searchIndex !== -1) {
+    // Find the actual string in the file that matches
+    return fileContent.substring(searchIndex, searchIndex + searchString.length)
+  }
+
+  return null
+}
+
+/**
+ * When old_string matched via quote normalization (curly quotes in file,
+ * straight quotes from model), apply the same curly quote style to new_string
+ * so the edit preserves the file's typography.
+ *
+ * Uses a simple open/close heuristic: a quote character preceded by whitespace,
+ * start of string, or opening punctuation is treated as an opening quote;
+ * otherwise it's a closing quote.
+ */
+export function preserveQuoteStyle(
+  oldString: string,
+  actualOldString: string,
+  newString: string,
+): string {
+  // If they're the same, no normalization happened
+  if (oldString === actualOldString) {
+    return newString
+  }
+
+  // Detect which curly quote types were in the file
+  const hasDoubleQuotes =
+    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE)
+  const hasSingleQuotes =
+    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE)
+
+  if (!hasDoubleQuotes && !hasSingleQuotes) {
+    return newString
+  }
+
+  let result = newString
+
+  if (hasDoubleQuotes) {
+    result = applyCurlyDoubleQuotes(result)
+  }
+  if (hasSingleQuotes) {
+    result = applyCurlySingleQuotes(result)
+  }
+
+  return result
+}
+
+function isOpeningContext(chars: string[], index: number): boolean {
+  if (index === 0) {
+    return true
+  }
+  const prev = chars[index - 1]
+  return (
+    prev === ' ' ||
+    prev === '\t' ||
+    prev === '\n' ||
+    prev === '\r' ||
+    prev === '(' ||
+    prev === '[' ||
+    prev === '{' ||
+    prev === '\u2014' || // em dash
+    prev === '\u2013' // en dash
+  )
+}
+
+function applyCurlyDoubleQuotes(str: string): string {
+  const chars = [...str]
+  const result: string[] = []
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '"') {
+      result.push(
+        isOpeningContext(chars, i)
+          ? LEFT_DOUBLE_CURLY_QUOTE
+          : RIGHT_DOUBLE_CURLY_QUOTE,
+      )
+    } else {
+      result.push(chars[i]!)
+    }
+  }
+  return result.join('')
+}
+
+function applyCurlySingleQuotes(str: string): string {
+  const chars = [...str]
+  const result: string[] = []
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "'") {
+      // Don't convert apostrophes in contractions (e.g., "don't", "it's")
+      // An apostrophe between two letters is a contraction, not a quote
+      const prev = i > 0 ? chars[i - 1] : undefined
+      const next = i < chars.length - 1 ? chars[i + 1] : undefined
+      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev)
+      const nextIsLetter = next !== undefined && /\p{L}/u.test(next)
+      if (prevIsLetter && nextIsLetter) {
+        // Apostrophe in a contraction — use right single curly quote
+        result.push(RIGHT_SINGLE_CURLY_QUOTE)
+      } else {
+        result.push(
+          isOpeningContext(chars, i)
+            ? LEFT_SINGLE_CURLY_QUOTE
+            : RIGHT_SINGLE_CURLY_QUOTE,
+        )
+      }
+    } else {
+      result.push(chars[i]!)
+    }
+  }
+  return result.join('')
+}
+
+/**
+ * Transform edits to ensure replace_all always has a boolean value
+ * @param edits Array of edits with optional replace_all
+ * @returns Array of edits with replace_all guaranteed to be boolean
+ */
+export function applyEditToFile(
+  originalContent: string,
+  oldString: string,
+  newString: string,
+  replaceAll: boolean = false,
+): string {
+  const f = replaceAll
+    ? (content: string, search: string, replace: string) =>
+        content.replaceAll(search, () => replace)
+    : (content: string, search: string, replace: string) =>
+        content.replace(search, () => replace)
+
+  if (newString !== '') {
+    return f(originalContent, oldString, newString)
+  }
+
+  const stripTrailingNewline =
+    !oldString.endsWith('\n') && originalContent.includes(oldString + '\n')
+
+  return stripTrailingNewline
+    ? f(originalContent, oldString + '\n', newString)
+    : f(originalContent, oldString, newString)
+}
+
+/**
+ * Applies an edit to a file and returns the patch and updated file.
+ * Does not write the file to disk.
+ */
+export function getPatchForEdit({
+  filePath,
+  fileContents,
+  oldString,
+  newString,
+  replaceAll = false,
+}: {
+  filePath: string
+  fileContents: string
+  oldString: string
+  newString: string
+  replaceAll?: boolean
+}): { patch: StructuredPatchHunk[]; updatedFile: string } {
+  return getPatchForEdits({
+    filePath,
+    fileContents,
+    edits: [
+      { old_string: oldString, new_string: newString, replace_all: replaceAll },
+    ],
+  })
+}
+
+/**
+ * Applies a list of edits to a file and returns the patch and updated file.
+ * Does not write the file to disk.
+ *
+ * NOTE: The returned patch is to be used for display purposes only - it has spaces instead of tabs
+ */
+export function getPatchForEdits({
+  filePath,
+  fileContents,
+  edits,
+}: {
+  filePath: string
+  fileContents: string
+  edits: FileEdit[]
+}): { patch: StructuredPatchHunk[]; updatedFile: string } {
+  let updatedFile = fileContents
+  const appliedNewStrings: string[] = []
+
+  // Special case for empty files.
+  if (
+    !fileContents &&
+    edits.length === 1 &&
+    edits[0] &&
+    edits[0].old_string === '' &&
+    edits[0].new_string === ''
+  ) {
+    const patch = getPatchForDisplay({
+      filePath,
+      fileContents,
+      edits: [
+        {
+          old_string: fileContents,
+          new_string: updatedFile,
+          replace_all: false,
+        },
+      ],
+    })
+    return { patch, updatedFile: '' }
+  }
+
+  // Apply each edit and check if it actually changes the file
+  for (const edit of edits) {
+    // Strip trailing newlines from old_string before checking
+    const oldStringToCheck = edit.old_string.replace(/\n+$/, '')
+
+    // Check if old_string is a substring of any previously applied new_string
+    for (const previousNewString of appliedNewStrings) {
+      if (
+        oldStringToCheck !== '' &&
+        previousNewString.includes(oldStringToCheck)
+      ) {
+        throw new Error(
+          'Cannot edit file: old_string is a substring of a new_string from a previous edit.',
+        )
+      }
+    }
+
+    const previousContent = updatedFile
+    updatedFile =
+      edit.old_string === ''
+        ? edit.new_string
+        : applyEditToFile(
+            updatedFile,
+            edit.old_string,
+            edit.new_string,
+            edit.replace_all,
+          )
+
+    // If this edit didn't change anything, throw an error
+    if (updatedFile === previousContent) {
+      throw new Error('String not found in file. Failed to apply edit.')
+    }
+
+    // Track the new string that was applied
+    appliedNewStrings.push(edit.new_string)
+  }
+
+  if (updatedFile === fileContents) {
+    throw new Error(
+      'Original and edited file match exactly. Failed to apply edit.',
+    )
+  }
+
+  // We already have before/after content, so call getPatchFromContents directly.
+  // Previously this went through getPatchForDisplay with edits=[{old:fileContents,new:updatedFile}],
+  // which transforms fileContents twice (once as preparedFileContents, again as escapedOldString
+  // inside the reduce) and runs a no-op full-content .replace(). This saves ~20% on large files.
+  const patch = getPatchFromContents({
+    filePath,
+    oldContent: convertLeadingTabsToSpaces(fileContents),
+    newContent: convertLeadingTabsToSpaces(updatedFile),
+  })
+
+  return { patch, updatedFile }
+}
+
+// Cap on edited_text_file attachment snippets. Format-on-save of a large file
+// previously injected the entire file per turn (observed max 16.1KB, ~14K
+// tokens/session). 8KB preserves meaningful context while bounding worst case.
+const DIFF_SNIPPET_MAX_BYTES = 8192
+
+/**
+ * Used for attachments, to show snippets when files change.
+ *
+ * TODO: Unify this with the other snippet logic.
+ */
+export function getSnippetForTwoFileDiff(
+  fileAContents: string,
+  fileBContents: string,
+): string {
+  const patch = structuredPatch(
+    'file.txt',
+    'file.txt',
+    fileAContents,
+    fileBContents,
+    undefined,
+    undefined,
+    {
+      context: 8,
+      timeout: DIFF_TIMEOUT_MS,
+    },
+  )
+
+  if (!patch) {
+    return ''
+  }
+
+  const full = patch.hunks
+    .map(_ => ({
+      startLine: _.oldStart,
+      content: _.lines
+        // Filter out deleted lines AND diff metadata lines
+        .filter(_ => !_.startsWith('-') && !_.startsWith('\\'))
+        .map(_ => _.slice(1))
+        .join('\n'),
+    }))
+    .map(addLineNumbers)
+    .join('\n...\n')
+
+  if (full.length <= DIFF_SNIPPET_MAX_BYTES) {
+    return full
+  }
+
+  // Truncate at the last line boundary that fits within the cap.
+  // Marker format matches BashTool/utils.ts.
+  const cutoff = full.lastIndexOf('\n', DIFF_SNIPPET_MAX_BYTES)
+  const kept =
+    cutoff > 0 ? full.slice(0, cutoff) : full.slice(0, DIFF_SNIPPET_MAX_BYTES)
+  const remaining = countCharInString(full, '\n', kept.length) + 1
+  return `${kept}\n\n... [${remaining} lines truncated] ...`
+}
+
+const CONTEXT_LINES = 4
+
+/**
+ * Gets a snippet from a file showing the context around a patch with line numbers.
+ * @param originalFile The original file content before applying the patch
+ * @param patch The diff hunks to use for determining snippet location
+ * @param newFile The file content after applying the patch
+ * @returns The snippet text with line numbers and the starting line number
+ */
+export function getSnippetForPatch(
+  patch: StructuredPatchHunk[],
+  newFile: string,
+): { formattedSnippet: string; startLine: number } {
+  if (patch.length === 0) {
+    // No changes, return empty snippet
+    return { formattedSnippet: '', startLine: 1 }
+  }
+
+  // Find the first and last changed lines across all hunks
+  let minLine = Infinity
+  let maxLine = -Infinity
+
+  for (const hunk of patch) {
+    if (hunk.oldStart < minLine) {
+      minLine = hunk.oldStart
+    }
+    // For the end line, we need to consider the new lines count since we're showing the new file
+    const hunkEnd = hunk.oldStart + (hunk.newLines || 0) - 1
+    if (hunkEnd > maxLine) {
+      maxLine = hunkEnd
+    }
+  }
+
+  // Calculate the range with context
+  const startLine = Math.max(1, minLine - CONTEXT_LINES)
+  const endLine = maxLine + CONTEXT_LINES
+
+  // Split the new file into lines and get the snippet
+  const fileLines = newFile.split(/\r?\n/)
+  const snippetLines = fileLines.slice(startLine - 1, endLine)
+  const snippet = snippetLines.join('\n')
+
+  // Add line numbers
+  const formattedSnippet = addLineNumbers({
+    content: snippet,
+    startLine,
+  })
+
+  return { formattedSnippet, startLine }
+}
+
+/**
+ * Gets a snippet from a file showing the context around a single edit.
+ * This is a convenience function that uses the original algorithm.
+ * @param originalFile The original file content
+ * @param oldString The text to replace
+ * @param newString The text to replace it with
+ * @param contextLines The number of lines to show before and after the change
+ * @returns The snippet and the starting line number
+ */
+export function getSnippet(
+  originalFile: string,
+  oldString: string,
+  newString: string,
+  contextLines: number = 4,
+): { snippet: string; startLine: number } {
+  // Use the original algorithm from FileEditTool.tsx
+  const before = originalFile.split(oldString)[0] ?? ''
+  const replacementLine = before.split(/\r?\n/).length - 1
+  const newFileLines = applyEditToFile(
+    originalFile,
+    oldString,
+    newString,
+  ).split(/\r?\n/)
+
+  // Calculate the start and end line numbers for the snippet
+  const startLine = Math.max(0, replacementLine - contextLines)
+  const endLine =
+    replacementLine + contextLines + newString.split(/\r?\n/).length
+
+  // Get snippet
+  const snippetLines = newFileLines.slice(startLine, endLine)
+  const snippet = snippetLines.join('\n')
+
+  return { snippet, startLine: startLine + 1 }
+}
+
+export function getEditsForPatch(patch: StructuredPatchHunk[]): FileEdit[] {
+  return patch.map(hunk => {
+    // Extract the changes from this hunk
+    const contextLines: string[] = []
+    const oldLines: string[] = []
+    const newLines: string[] = []
+
+    // Parse each line and categorize it
+    for (const line of hunk.lines) {
+      if (line.startsWith(' ')) {
+        // Context line - appears in both versions
+        contextLines.push(line.slice(1))
+        oldLines.push(line.slice(1))
+        newLines.push(line.slice(1))
+      } else if (line.startsWith('-')) {
+        // Deleted line - only in old version
+        oldLines.push(line.slice(1))
+      } else if (line.startsWith('+')) {
+        // Added line - only in new version
+        newLines.push(line.slice(1))
+      }
+    }
+
+    return {
+      old_string: oldLines.join('\n'),
+      new_string: newLines.join('\n'),
+      replace_all: false,
+    }
+  })
+}
+
+/**
+ * Contains replacements to de-sanitize strings from Claude
+ * Since Claude can't see any of these strings (sanitized in the API)
+ * It'll output the sanitized versions in the edit response
+ */
+const DESANITIZATIONS: Record<string, string> = {
+  '<fnr>': '<function_results>',
+  '<n>': '<name>',
+  '</n>': '</name>',
+  '<o>': '<output>',
+  '</o>': '</output>',
+  '<e>': '<error>',
+  '</e>': '</error>',
+  '<s>': '<system>',
+  '</s>': '</system>',
+  '<r>': '<result>',
+  '</r>': '</result>',
+  '< META_START >': '<META_START>',
+  '< META_END >': '<META_END>',
+  '< EOT >': '<EOT>',
+  '< META >': '<META>',
+  '< SOS >': '<SOS>',
+  '\n\nH:': '\n\nHuman:',
+  '\n\nA:': '\n\nAssistant:',
+}
+
+/**
+ * Normalizes a match string by applying specific replacements
+ * This helps handle when exact matches fail due to formatting differences
+ * @returns The normalized string and which replacements were applied
+ */
+function desanitizeMatchString(matchString: string): {
+  result: string
+  appliedReplacements: Array<{ from: string; to: string }>
+} {
+  let result = matchString
+  const appliedReplacements: Array<{ from: string; to: string }> = []
+
+  for (const [from, to] of Object.entries(DESANITIZATIONS)) {
+    const beforeReplace = result
+    result = result.replaceAll(from, to)
+
+    if (beforeReplace !== result) {
+      appliedReplacements.push({ from, to })
+    }
+  }
+
+  return { result, appliedReplacements }
+}
+
+/**
+ * Normalize the input for the FileEditTool
+ * If the string to replace is not found in the file, try with a normalized version
+ * Returns the normalized input if successful, or the original input if not
+ */
+export function normalizeFileEditInput({
+  file_path,
+  edits,
+}: {
+  file_path: string
+  edits: EditInput[]
+}): {
+  file_path: string
+  edits: EditInput[]
+} {
+  if (edits.length === 0) {
+    return { file_path, edits }
+  }
+
+  // Markdown uses two trailing spaces as a hard line break — stripping would
+  // silently change semantics. Skip stripTrailingWhitespace for .md/.mdx.
+  const isMarkdown = /\.(md|mdx)$/i.test(file_path)
+
+  try {
+    const fullPath = expandPath(file_path)
+
+    // Use cached file read to avoid redundant I/O operations.
+    // If the file doesn't exist, readFileSyncCached throws ENOENT which the
+    // catch below handles by returning the original input (no TOCTOU pre-check).
+    const fileContent = readFileSyncCached(fullPath)
+
+    return {
+      file_path,
+      edits: edits.map(({ old_string, new_string, replace_all }) => {
+        const normalizedNewString = isMarkdown
+          ? new_string
+          : stripTrailingWhitespace(new_string)
+
+        // If exact string match works, keep it as is
+        if (fileContent.includes(old_string)) {
+          return {
+            old_string,
+            new_string: normalizedNewString,
+            replace_all,
+          }
+        }
+
+        // Try de-sanitize string if exact match fails
+        const { result: desanitizedOldString, appliedReplacements } =
+          desanitizeMatchString(old_string)
+
+        if (fileContent.includes(desanitizedOldString)) {
+          // Apply the same exact replacements to new_string
+          let desanitizedNewString = normalizedNewString
+          for (const { from, to } of appliedReplacements) {
+            desanitizedNewString = desanitizedNewString.replaceAll(from, to)
+          }
+
+          return {
+            old_string: desanitizedOldString,
+            new_string: desanitizedNewString,
+            replace_all,
+          }
+        }
+
+        return {
+          old_string,
+          new_string: normalizedNewString,
+          replace_all,
+        }
+      }),
+    }
+  } catch (error) {
+    // If there's any error reading the file, just return original input.
+    // ENOENT is expected when the file doesn't exist yet (e.g., new file).
+    if (!isENOENT(error)) {
+      logError(error)
+    }
+  }
+
+  return { file_path, edits }
+}
+
+/**
+ * Compare two sets of edits to determine if they are equivalent
+ * by applying both sets to the original content and comparing results.
+ * This handles cases where edits might be different but produce the same outcome.
+ */
+export function areFileEditsEquivalent(
+  edits1: FileEdit[],
+  edits2: FileEdit[],
+  originalContent: string,
+): boolean {
+  // Fast path: check if edits are literally identical
+  if (
+    edits1.length === edits2.length &&
+    edits1.every((edit1, index) => {
+      const edit2 = edits2[index]
+      return (
+        edit2 !== undefined &&
+        edit1.old_string === edit2.old_string &&
+        edit1.new_string === edit2.new_string &&
+        edit1.replace_all === edit2.replace_all
+      )
+    })
+  ) {
+    return true
+  }
+
+  // Try applying both sets of edits
+  let result1: { patch: StructuredPatchHunk[]; updatedFile: string } | null =
+    null
+  let error1: string | null = null
+  let result2: { patch: StructuredPatchHunk[]; updatedFile: string } | null =
+    null
+  let error2: string | null = null
+
+  try {
+    result1 = getPatchForEdits({
+      filePath: 'temp',
+      fileContents: originalContent,
+      edits: edits1,
+    })
+  } catch (e) {
+    error1 = errorMessage(e)
+  }
+
+  try {
+    result2 = getPatchForEdits({
+      filePath: 'temp',
+      fileContents: originalContent,
+      edits: edits2,
+    })
+  } catch (e) {
+    error2 = errorMessage(e)
+  }
+
+  // If both threw errors, they're equal only if the errors are the same
+  if (error1 !== null && error2 !== null) {
+    // Normalize error messages for comparison
+    return error1 === error2
+  }
+
+  // If one threw an error and the other didn't, they're not equal
+  if (error1 !== null || error2 !== null) {
+    return false
+  }
+
+  // Both succeeded - compare the results
+  return result1!.updatedFile === result2!.updatedFile
+}
+
+/**
+ * Unified function to check if two file edit inputs are equivalent.
+ * Handles file edits (FileEditTool).
+ */
+export function areFileEditsInputsEquivalent(
+  input1: {
+    file_path: string
+    edits: FileEdit[]
+  },
+  input2: {
+    file_path: string
+    edits: FileEdit[]
+  },
+): boolean {
+  // Fast path: different files
+  if (input1.file_path !== input2.file_path) {
+    return false
+  }
+
+  // Fast path: literal equality
+  if (
+    input1.edits.length === input2.edits.length &&
+    input1.edits.every((edit1, index) => {
+      const edit2 = input2.edits[index]
+      return (
+        edit2 !== undefined &&
+        edit1.old_string === edit2.old_string &&
+        edit1.new_string === edit2.new_string &&
+        edit1.replace_all === edit2.replace_all
+      )
+    })
+  ) {
+    return true
+  }
+
+  // Semantic comparison (requires file read). If the file doesn't exist,
+  // compare against empty content (no TOCTOU pre-check).
+  let fileContent = ''
+  try {
+    fileContent = readFileSyncCached(input1.file_path)
+  } catch (error) {
+    if (!isENOENT(error)) {
+      throw error
+    }
+  }
+
+  return areFileEditsEquivalent(input1.edits, input2.edits, fileContent)
+}

src/tools/FileReadTool/imageProcessor.ts

@@ -0,0 +1,94 @@
+import type { Buffer } from 'buffer'
+import { isInBundledMode } from '../../utils/bundledMode.js'
+
+export type SharpInstance = {
+  metadata(): Promise<{ width: number; height: number; format: string }>
+  resize(
+    width: number,
+    height: number,
+    options?: { fit?: string; withoutEnlargement?: boolean },
+  ): SharpInstance
+  jpeg(options?: { quality?: number }): SharpInstance
+  png(options?: {
+    compressionLevel?: number
+    palette?: boolean
+    colors?: number
+  }): SharpInstance
+  webp(options?: { quality?: number }): SharpInstance
+  toBuffer(): Promise<Buffer>
+}
+
+export type SharpFunction = (input: Buffer) => SharpInstance
+
+type SharpCreatorOptions = {
+  create: {
+    width: number
+    height: number
+    channels: 3 | 4
+    background: { r: number; g: number; b: number }
+  }
+}
+
+type SharpCreator = (options: SharpCreatorOptions) => SharpInstance
+
+let imageProcessorModule: { default: SharpFunction } | null = null
+let imageCreatorModule: { default: SharpCreator } | null = null
+
+export async function getImageProcessor(): Promise<SharpFunction> {
+  if (imageProcessorModule) {
+    return imageProcessorModule.default
+  }
+
+  if (isInBundledMode()) {
+    // Try to load the native image processor first
+    try {
+      // Use the native image processor module
+      const imageProcessor = await import('image-processor-napi')
+      const sharp = imageProcessor.sharp || imageProcessor.default
+      imageProcessorModule = { default: sharp }
+      return sharp
+    } catch {
+      // Fall back to sharp if native module is not available
+      // biome-ignore lint/suspicious/noConsole: intentional warning
+      console.warn(
+        'Native image processor not available, falling back to sharp',
+      )
+    }
+  }
+
+  // Use sharp for non-bundled builds or as fallback.
+  // Single structural cast: our SharpFunction is a subset of sharp's actual type surface.
+  const imported = (await import(
+    'sharp'
+  )) as unknown as MaybeDefault<SharpFunction>
+  const sharp = unwrapDefault(imported)
+  imageProcessorModule = { default: sharp }
+  return sharp
+}
+
+/**
+ * Get image creator for generating new images from scratch.
+ * Note: image-processor-napi doesn't support image creation,
+ * so this always uses sharp directly.
+ */
+export async function getImageCreator(): Promise<SharpCreator> {
+  if (imageCreatorModule) {
+    return imageCreatorModule.default
+  }
+
+  const imported = (await import(
+    'sharp'
+  )) as unknown as MaybeDefault<SharpCreator>
+  const sharp = unwrapDefault(imported)
+  imageCreatorModule = { default: sharp }
+  return sharp
+}
+
+// Dynamic import shape varies by module interop mode — ESM yields { default: fn }, CJS yields fn directly.
+type MaybeDefault<T> = T | { default: T }
+
+function unwrapDefault<T extends (...args: never[]) => unknown>(
+  mod: MaybeDefault<T>,
+): T {
+  return typeof mod === 'function' ? mod : mod.default
+}

src/tools/FileReadTool/limits.ts

@@ -0,0 +1,92 @@
+/**
+ * Read tool output limits.  Two caps apply to text reads:
+ *
+ *   | limit         | default | checks                    | cost          | on overflow     |
+ *   |---------------|---------|---------------------------|---------------|-----------------|
+ *   | maxSizeBytes  | 256 KB  | TOTAL FILE SIZE (not out) | 1 stat        | throws pre-read |
+ *   | maxTokens     | 25000   | actual output tokens      | API roundtrip | throws post-read|
+ *
+ * Known mismatch: maxSizeBytes gates on total file size, not the slice.
+ * Tested truncating instead of throwing for explicit-limit reads that
+ * exceed the byte cap (#21841, Mar 2026).  Reverted: tool error rate
+ * dropped but mean tokens rose — the throw path yields a ~100-byte error
+ * tool-result while truncation yields ~25K tokens of content at the cap.
+ */
+import memoize from 'lodash-es/memoize.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'
+import { MAX_OUTPUT_SIZE } from 'src/utils/file.js'
+export const DEFAULT_MAX_OUTPUT_TOKENS = 25000
+
+/**
+ * Env var override for max output tokens. Returns undefined when unset/invalid
+ * so the caller can fall through to the next precedence tier.
+ */
+function getEnvMaxTokens(): number | undefined {
+  const override = process.env.CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS
+  if (override) {
+    const parsed = parseInt(override, 10)
+    if (!isNaN(parsed) && parsed > 0) {
+      return parsed
+    }
+  }
+  return undefined
+}
+
+export type FileReadingLimits = {
+  maxTokens: number
+  maxSizeBytes: number
+  includeMaxSizeInPrompt?: boolean
+  targetedRangeNudge?: boolean
+}
+
+/**
+ * Default limits for Read tool when the ToolUseContext doesn't supply an
+ * override. Memoized so the GrowthBook value is fixed at first call — avoids
+ * the cap changing mid-session as the flag refreshes in the background.
+ *
+ * Precedence for maxTokens: env var > GrowthBook > DEFAULT_MAX_OUTPUT_TOKENS.
+ * (Env var is a user-set override, should beat experiment infrastructure.)
+ *
+ * Defensive: each field is individually validated; invalid values fall
+ * through to the hardcoded defaults (no route to cap=0).
+ */
+export const getDefaultFileReadingLimits = memoize((): FileReadingLimits => {
+  const override =
+    getFeatureValue_CACHED_MAY_BE_STALE<Partial<FileReadingLimits> | null>(
+      'tengu_amber_wren',
+      {},
+    )
+
+  const maxSizeBytes =
+    typeof override?.maxSizeBytes === 'number' &&
+    Number.isFinite(override.maxSizeBytes) &&
+    override.maxSizeBytes > 0
+      ? override.maxSizeBytes
+      : MAX_OUTPUT_SIZE
+
+  const envMaxTokens = getEnvMaxTokens()
+  const maxTokens =
+    envMaxTokens ??
+    (typeof override?.maxTokens === 'number' &&
+    Number.isFinite(override.maxTokens) &&
+    override.maxTokens > 0
+      ? override.maxTokens
+      : DEFAULT_MAX_OUTPUT_TOKENS)
+
+  const includeMaxSizeInPrompt =
+    typeof override?.includeMaxSizeInPrompt === 'boolean'
+      ? override.includeMaxSizeInPrompt
+      : undefined
+
+  const targetedRangeNudge =
+    typeof override?.targetedRangeNudge === 'boolean'
+      ? override.targetedRangeNudge
+      : undefined
+
+  return {
+    maxSizeBytes,
+    maxTokens,
+    includeMaxSizeInPrompt,
+    targetedRangeNudge,
+  }
+})

src/tools/FileReadTool/prompt.ts

@@ -0,0 +1,49 @@
+import { isPDFSupported } from '../../utils/pdfUtils.js'
+import { BASH_TOOL_NAME } from '../BashTool/toolName.js'
+
+// Use a string constant for tool names to avoid circular dependencies
+export const FILE_READ_TOOL_NAME = 'Read'
+
+export const FILE_UNCHANGED_STUB =
+  'File unchanged since last read. The content from the earlier Read tool_result in this conversation is still current — refer to that instead of re-reading.'
+
+export const MAX_LINES_TO_READ = 2000
+
+export const DESCRIPTION = 'Read a file from the local filesystem.'
+
+export const LINE_FORMAT_INSTRUCTION =
+  '- Results are returned using cat -n format, with line numbers starting at 1'
+
+export const OFFSET_INSTRUCTION_DEFAULT =
+  "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters"
+
+export const OFFSET_INSTRUCTION_TARGETED =
+  '- When you already know which part of the file you need, only read that part. This can be important for larger files.'
+
+/**
+ * Renders the Read tool prompt template.  The caller (FileReadTool) supplies
+ * the runtime-computed parts.
+ */
+export function renderPromptTemplate(
+  lineFormat: string,
+  maxSizeInstruction: string,
+  offsetInstruction: string,
+): string {
+  return `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to ${MAX_LINES_TO_READ} lines starting from the beginning of the file${maxSizeInstruction}
+${offsetInstruction}
+${lineFormat}
+- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.${
+    isPDFSupported()
+      ? '\n- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.'
+      : ''
+  }
+- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
+- This tool can only read files, not directories. To read a directory, use an ls command via the ${BASH_TOOL_NAME} tool.
+- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.`
+}

src/tools/FileWriteTool/FileWriteTool.ts

@@ -0,0 +1,434 @@
+import { dirname, sep } from 'path'
+import { logEvent } from 'src/services/analytics/index.js'
+import { z } from 'zod/v4'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import { diagnosticTracker } from '../../services/diagnosticTracking.js'
+import { clearDeliveredDiagnosticsForFile } from '../../services/lsp/LSPDiagnosticRegistry.js'
+import { getLspServerManager } from '../../services/lsp/manager.js'
+import { notifyVscodeFileUpdated } from '../../services/mcp/vscodeSdkMcp.js'
+import { checkTeamMemSecrets } from '../../services/teamMemorySync/teamMemSecretGuard.js'
+import {
+  activateConditionalSkillsForPaths,
+  addSkillDirectories,
+  discoverSkillDirsForPaths,
+} from '../../skills/loadSkillsDir.js'
+import type { ToolUseContext } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { countLinesChanged, getPatchForDisplay } from '../../utils/diff.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { isENOENT } from '../../utils/errors.js'
+import { getFileModificationTime, writeTextContent } from '../../utils/file.js'
+import {
+  fileHistoryEnabled,
+  fileHistoryTrackEdit,
+} from '../../utils/fileHistory.js'
+import { logFileOperation } from '../../utils/fileOperationAnalytics.js'
+import { readFileSyncWithMetadata } from '../../utils/fileRead.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import {
+  fetchSingleFileGitDiff,
+  type ToolUseDiff,
+} from '../../utils/gitDiff.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import { expandPath } from '../../utils/path.js'
+import {
+  checkWritePermissionForTool,
+  matchingRuleForInput,
+} from '../../utils/permissions/filesystem.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { matchWildcardPattern } from '../../utils/permissions/shellRuleMatching.js'
+import { FILE_UNEXPECTEDLY_MODIFIED_ERROR } from '../FileEditTool/constants.js'
+import { gitDiffSchema, hunkSchema } from '../FileEditTool/types.js'
+import { FILE_WRITE_TOOL_NAME, getWriteToolDescription } from './prompt.js'
+import {
+  getToolUseSummary,
+  isResultTruncated,
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+  userFacingName,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    file_path: z
+      .string()
+      .describe(
+        'The absolute path to the file to write (must be absolute, not relative)',
+      ),
+    content: z.string().describe('The content to write to the file'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    type: z
+      .enum(['create', 'update'])
+      .describe(
+        'Whether a new file was created or an existing file was updated',
+      ),
+    filePath: z.string().describe('The path to the file that was written'),
+    content: z.string().describe('The content that was written to the file'),
+    structuredPatch: z
+      .array(hunkSchema())
+      .describe('Diff patch showing the changes'),
+    originalFile: z
+      .string()
+      .nullable()
+      .describe(
+        'The original file content before the write (null for new files)',
+      ),
+    gitDiff: gitDiffSchema().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+export type FileWriteToolInput = InputSchema
+
+export const FileWriteTool = buildTool({
+  name: FILE_WRITE_TOOL_NAME,
+  searchHint: 'create or overwrite files',
+  maxResultSizeChars: 100_000,
+  strict: true,
+  async description() {
+    return 'Write a file to the local filesystem.'
+  },
+  userFacingName,
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const summary = getToolUseSummary(input)
+    return summary ? `Writing ${summary}` : 'Writing file'
+  },
+  async prompt() {
+    return getWriteToolDescription()
+  },
+  renderToolUseMessage,
+  isResultTruncated,
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  toAutoClassifierInput(input) {
+    return `${input.file_path}: ${input.content}`
+  },
+  getPath(input): string {
+    return input.file_path
+  },
+  backfillObservableInput(input) {
+    // hooks.mdx documents file_path as absolute; expand so hook allowlists
+    // can't be bypassed via ~ or relative paths.
+    if (typeof input.file_path === 'string') {
+      input.file_path = expandPath(input.file_path)
+    }
+  },
+  async preparePermissionMatcher({ file_path }) {
+    return pattern => matchWildcardPattern(pattern, file_path)
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkWritePermissionForTool(
+      FileWriteTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  renderToolUseRejectedMessage,
+  renderToolUseErrorMessage,
+  renderToolResultMessage,
+  extractSearchText() {
+    // Transcript render shows either content (create, via HighlightedCode)
+    // or a structured diff (update). The heuristic's 'content' allowlist key
+    // would index the raw content string even in update mode where it's NOT
+    // shown — phantom. Under-count: tool_use already indexes file_path.
+    return ''
+  },
+  async validateInput({ file_path, content }, toolUseContext: ToolUseContext) {
+    const fullFilePath = expandPath(file_path)
+
+    // Reject writes to team memory files that contain secrets
+    const secretError = checkTeamMemSecrets(fullFilePath, content)
+    if (secretError) {
+      return { result: false, message: secretError, errorCode: 0 }
+    }
+
+    // Check if path should be ignored based on permission settings
+    const appState = toolUseContext.getAppState()
+    const denyRule = matchingRuleForInput(
+      fullFilePath,
+      appState.toolPermissionContext,
+      'edit',
+      'deny',
+    )
+    if (denyRule !== null) {
+      return {
+        result: false,
+        message:
+          'File is in a directory that is denied by your permission settings.',
+        errorCode: 1,
+      }
+    }
+
+    // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+    // On Windows, fs.existsSync() on UNC paths triggers SMB authentication which could
+    // leak credentials to malicious servers. Let the permission check handle UNC paths.
+    if (fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')) {
+      return { result: true }
+    }
+
+    const fs = getFsImplementation()
+    let fileMtimeMs: number
+    try {
+      const fileStat = await fs.stat(fullFilePath)
+      fileMtimeMs = fileStat.mtimeMs
+    } catch (e) {
+      if (isENOENT(e)) {
+        return { result: true }
+      }
+      throw e
+    }
+
+    const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
+    if (!readTimestamp || readTimestamp.isPartialView) {
+      return {
+        result: false,
+        message:
+          'File has not been read yet. Read it first before writing to it.',
+        errorCode: 2,
+      }
+    }
+
+    // Reuse mtime from the stat above — avoids a redundant statSync via
+    // getFileModificationTime. The readTimestamp guard above ensures this
+    // block is always reached when the file exists.
+    const lastWriteTime = Math.floor(fileMtimeMs)
+    if (lastWriteTime > readTimestamp.timestamp) {
+      return {
+        result: false,
+        message:
+          'File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.',
+        errorCode: 3,
+      }
+    }
+
+    return { result: true }
+  },
+  async call(
+    { file_path, content },
+    { readFileState, updateFileHistoryState, dynamicSkillDirTriggers },
+    _,
+    parentMessage,
+  ) {
+    const fullFilePath = expandPath(file_path)
+    const dir = dirname(fullFilePath)
+
+    // Discover skills from this file's path (fire-and-forget, non-blocking)
+    const cwd = getCwd()
+    const newSkillDirs = await discoverSkillDirsForPaths([fullFilePath], cwd)
+    if (newSkillDirs.length > 0) {
+      // Store discovered dirs for attachment display
+      for (const dir of newSkillDirs) {
+        dynamicSkillDirTriggers?.add(dir)
+      }
+      // Don't await - let skill loading happen in the background
+      addSkillDirectories(newSkillDirs).catch(() => {})
+    }
+
+    // Activate conditional skills whose path patterns match this file
+    activateConditionalSkillsForPaths([fullFilePath], cwd)
+
+    await diagnosticTracker.beforeFileEdited(fullFilePath)
+
+    // Ensure parent directory exists before the atomic read-modify-write section.
+    // Must stay OUTSIDE the critical section below (a yield between the staleness
+    // check and writeTextContent lets concurrent edits interleave), and BEFORE the
+    // write (lazy-mkdir-on-ENOENT would fire a spurious tengu_atomic_write_error
+    // inside writeFileSyncAndFlush_DEPRECATED before ENOENT propagates back).
+    await getFsImplementation().mkdir(dir)
+    if (fileHistoryEnabled()) {
+      // Backup captures pre-edit content — safe to call before the staleness
+      // check (idempotent v1 backup keyed on content hash; if staleness fails
+      // later we just have an unused backup, not corrupt state).
+      await fileHistoryTrackEdit(
+        updateFileHistoryState,
+        fullFilePath,
+        parentMessage.uuid,
+      )
+    }
+
+    // Load current state and confirm no changes since last read.
+    // Please avoid async operations between here and writing to disk to preserve atomicity.
+    let meta: ReturnType<typeof readFileSyncWithMetadata> | null
+    try {
+      meta = readFileSyncWithMetadata(fullFilePath)
+    } catch (e) {
+      if (isENOENT(e)) {
+        meta = null
+      } else {
+        throw e
+      }
+    }
+
+    if (meta !== null) {
+      const lastWriteTime = getFileModificationTime(fullFilePath)
+      const lastRead = readFileState.get(fullFilePath)
+      if (!lastRead || lastWriteTime > lastRead.timestamp) {
+        // Timestamp indicates modification, but on Windows timestamps can change
+        // without content changes (cloud sync, antivirus, etc.). For full reads,
+        // compare content as a fallback to avoid false positives.
+        const isFullRead =
+          lastRead &&
+          lastRead.offset === undefined &&
+          lastRead.limit === undefined
+        // meta.content is CRLF-normalized — matches readFileState's normalized form.
+        if (!isFullRead || meta.content !== lastRead.content) {
+          throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR)
+        }
+      }
+    }
+
+    const enc = meta?.encoding ?? 'utf8'
+    const oldContent = meta?.content ?? null
+
+    // Write is a full content replacement — the model sent explicit line endings
+    // in `content` and meant them. Do not rewrite them. Previously we preserved
+    // the old file's line endings (or sampled the repo via ripgrep for new
+    // files), which silently corrupted e.g. bash scripts with \r on Linux when
+    // overwriting a CRLF file or when binaries in cwd poisoned the repo sample.
+    writeTextContent(fullFilePath, content, enc, 'LF')
+
+    // Notify LSP servers about file modification (didChange) and save (didSave)
+    const lspManager = getLspServerManager()
+    if (lspManager) {
+      // Clear previously delivered diagnostics so new ones will be shown
+      clearDeliveredDiagnosticsForFile(`file://${fullFilePath}`)
+      // didChange: Content has been modified
+      lspManager.changeFile(fullFilePath, content).catch((err: Error) => {
+        logForDebugging(
+          `LSP: Failed to notify server of file change for ${fullFilePath}: ${err.message}`,
+        )
+        logError(err)
+      })
+      // didSave: File has been saved to disk (triggers diagnostics in TypeScript server)
+      lspManager.saveFile(fullFilePath).catch((err: Error) => {
+        logForDebugging(
+          `LSP: Failed to notify server of file save for ${fullFilePath}: ${err.message}`,
+        )
+        logError(err)
+      })
+    }
+
+    // Notify VSCode about the file change for diff view
+    notifyVscodeFileUpdated(fullFilePath, oldContent, content)
+
+    // Update read timestamp, to invalidate stale writes
+    readFileState.set(fullFilePath, {
+      content,
+      timestamp: getFileModificationTime(fullFilePath),
+      offset: undefined,
+      limit: undefined,
+    })
+
+    // Log when writing to CLAUDE.md
+    if (fullFilePath.endsWith(`${sep}CLAUDE.md`)) {
+      logEvent('tengu_write_claudemd', {})
+    }
+
+    let gitDiff: ToolUseDiff | undefined
+    if (
+      isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) &&
+      getFeatureValue_CACHED_MAY_BE_STALE('tengu_quartz_lantern', false)
+    ) {
+      const startTime = Date.now()
+      const diff = await fetchSingleFileGitDiff(fullFilePath)
+      if (diff) gitDiff = diff
+      logEvent('tengu_tool_use_diff_computed', {
+        isWriteTool: true,
+        durationMs: Date.now() - startTime,
+        hasDiff: !!diff,
+      })
+    }
+
+    if (oldContent) {
+      const patch = getPatchForDisplay({
+        filePath: file_path,
+        fileContents: oldContent,
+        edits: [
+          {
+            old_string: oldContent,
+            new_string: content,
+            replace_all: false,
+          },
+        ],
+      })
+
+      const data = {
+        type: 'update' as const,
+        filePath: file_path,
+        content,
+        structuredPatch: patch,
+        originalFile: oldContent,
+        ...(gitDiff && { gitDiff }),
+      }
+      // Track lines added and removed for file updates, right before yielding result
+      countLinesChanged(patch)
+
+      logFileOperation({
+        operation: 'write',
+        tool: 'FileWriteTool',
+        filePath: fullFilePath,
+        type: 'update',
+      })
+
+      return {
+        data,
+      }
+    }
+
+    const data = {
+      type: 'create' as const,
+      filePath: file_path,
+      content,
+      structuredPatch: [],
+      originalFile: null,
+      ...(gitDiff && { gitDiff }),
+    }
+
+    // For creation of new files, count all lines as additions, right before yielding the result
+    countLinesChanged([], content)
+
+    logFileOperation({
+      operation: 'write',
+      tool: 'FileWriteTool',
+      filePath: fullFilePath,
+      type: 'create',
+    })
+
+    return {
+      data,
+    }
+  },
+  mapToolResultToToolResultBlockParam({ filePath, type }, toolUseID) {
+    switch (type) {
+      case 'create':
+        return {
+          tool_use_id: toolUseID,
+          type: 'tool_result',
+          content: `File created successfully at: ${filePath}`,
+        }
+      case 'update':
+        return {
+          tool_use_id: toolUseID,
+          type: 'tool_result',
+          content: `The file ${filePath} has been updated successfully.`,
+        }
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/FileWriteTool/prompt.ts

@@ -0,0 +1,18 @@
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
+
+export const FILE_WRITE_TOOL_NAME = 'Write'
+export const DESCRIPTION = 'Write a file to the local filesystem.'
+
+function getPreReadInstruction(): string {
+  return `\n- If this is an existing file, you MUST use the ${FILE_READ_TOOL_NAME} tool first to read the file's contents. This tool will fail if you did not read the file first.`
+}
+
+export function getWriteToolDescription(): string {
+  return `Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.${getPreReadInstruction()}
+- Prefer the Edit tool for modifying existing files \u2014 it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`
+}

src/tools/GlobTool/GlobTool.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod/v4'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { isENOENT } from '../../utils/errors.js'
+import {
+  FILE_NOT_FOUND_CWD_NOTE,
+  suggestPathUnderCwd,
+} from '../../utils/file.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import { glob } from '../../utils/glob.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { expandPath, toRelativePath } from '../../utils/path.js'
+import { checkReadPermissionForTool } from '../../utils/permissions/filesystem.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { matchWildcardPattern } from '../../utils/permissions/shellRuleMatching.js'
+import { DESCRIPTION, GLOB_TOOL_NAME } from './prompt.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+  userFacingName,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    pattern: z.string().describe('The glob pattern to match files against'),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        'The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.',
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    durationMs: z
+      .number()
+      .describe('Time taken to execute the search in milliseconds'),
+    numFiles: z.number().describe('Total number of files found'),
+    filenames: z
+      .array(z.string())
+      .describe('Array of file paths that match the pattern'),
+    truncated: z
+      .boolean()
+      .describe('Whether results were truncated (limited to 100 files)'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const GlobTool = buildTool({
+  name: GLOB_TOOL_NAME,
+  searchHint: 'find files by name pattern or wildcard',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  userFacingName,
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const summary = getToolUseSummary(input)
+    return summary ? `Finding ${summary}` : 'Finding files'
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.pattern
+  },
+  isSearchOrReadCommand() {
+    return { isSearch: true, isRead: false }
+  },
+  getPath({ path }): string {
+    return path ? expandPath(path) : getCwd()
+  },
+  async preparePermissionMatcher({ pattern }) {
+    return rulePattern => matchWildcardPattern(rulePattern, pattern)
+  },
+  async validateInput({ path }): Promise<ValidationResult> {
+    // If path is provided, validate that it exists and is a directory
+    if (path) {
+      const fs = getFsImplementation()
+      const absolutePath = expandPath(path)
+
+      // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+      if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
+        return { result: true }
+      }
+
+      let stats
+      try {
+        stats = await fs.stat(absolutePath)
+      } catch (e: unknown) {
+        if (isENOENT(e)) {
+          const cwdSuggestion = await suggestPathUnderCwd(absolutePath)
+          let message = `Directory does not exist: ${path}. ${FILE_NOT_FOUND_CWD_NOTE} ${getCwd()}.`
+          if (cwdSuggestion) {
+            message += ` Did you mean ${cwdSuggestion}?`
+          }
+          return {
+            result: false,
+            message,
+            errorCode: 1,
+          }
+        }
+        throw e
+      }
+
+      if (!stats.isDirectory()) {
+        return {
+          result: false,
+          message: `Path is not a directory: ${path}`,
+          errorCode: 2,
+        }
+      }
+    }
+
+    return { result: true }
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkReadPermissionForTool(
+      GlobTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  renderToolUseMessage,
+  renderToolUseErrorMessage,
+  renderToolResultMessage,
+  // Reuses Grep's render (UI.tsx:65) — shows filenames.join. durationMs/
+  // numFiles are "Found 3 files in 12ms" chrome (under-count, fine).
+  extractSearchText({ filenames }) {
+    return filenames.join('\n')
+  },
+  async call(input, { abortController, getAppState, globLimits }) {
+    const start = Date.now()
+    const appState = getAppState()
+    const limit = globLimits?.maxResults ?? 100
+    const { files, truncated } = await glob(
+      input.pattern,
+      GlobTool.getPath(input),
+      { limit, offset: 0 },
+      abortController.signal,
+      appState.toolPermissionContext,
+    )
+    // Relativize paths under cwd to save tokens (same as GrepTool)
+    const filenames = files.map(toRelativePath)
+    const output: Output = {
+      filenames,
+      durationMs: Date.now() - start,
+      numFiles: filenames.length,
+      truncated,
+    }
+    return {
+      data: output,
+    }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    if (output.filenames.length === 0) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: 'No files found',
+      }
+    }
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: [
+        ...output.filenames,
+        ...(output.truncated
+          ? [
+              '(Results are truncated. Consider using a more specific path or pattern.)',
+            ]
+          : []),
+      ].join('\n'),
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/GlobTool/prompt.ts

@@ -0,0 +1,7 @@
+export const GLOB_TOOL_NAME = 'Glob'
+
+export const DESCRIPTION = `- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead`

src/tools/GrepTool/GrepTool.ts

@@ -0,0 +1,577 @@
+import { z } from 'zod/v4'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { isENOENT } from '../../utils/errors.js'
+import {
+  FILE_NOT_FOUND_CWD_NOTE,
+  suggestPathUnderCwd,
+} from '../../utils/file.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { expandPath, toRelativePath } from '../../utils/path.js'
+import {
+  checkReadPermissionForTool,
+  getFileReadIgnorePatterns,
+  normalizePatternsToPath,
+} from '../../utils/permissions/filesystem.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { matchWildcardPattern } from '../../utils/permissions/shellRuleMatching.js'
+import { getGlobExclusionsForPluginCache } from '../../utils/plugins/orphanedPluginFilter.js'
+import { ripGrep } from '../../utils/ripgrep.js'
+import { semanticBoolean } from '../../utils/semanticBoolean.js'
+import { semanticNumber } from '../../utils/semanticNumber.js'
+import { plural } from '../../utils/stringUtils.js'
+import { GREP_TOOL_NAME, getDescription } from './prompt.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    pattern: z
+      .string()
+      .describe(
+        'The regular expression pattern to search for in file contents',
+      ),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        'File or directory to search in (rg PATH). Defaults to current working directory.',
+      ),
+    glob: z
+      .string()
+      .optional()
+      .describe(
+        'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") - maps to rg --glob',
+      ),
+    output_mode: z
+      .enum(['content', 'files_with_matches', 'count'])
+      .optional()
+      .describe(
+        'Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".',
+      ),
+    '-B': semanticNumber(z.number().optional()).describe(
+      'Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.',
+    ),
+    '-A': semanticNumber(z.number().optional()).describe(
+      'Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.',
+    ),
+    '-C': semanticNumber(z.number().optional()).describe('Alias for context.'),
+    context: semanticNumber(z.number().optional()).describe(
+      'Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.',
+    ),
+    '-n': semanticBoolean(z.boolean().optional()).describe(
+      'Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise. Defaults to true.',
+    ),
+    '-i': semanticBoolean(z.boolean().optional()).describe(
+      'Case insensitive search (rg -i)',
+    ),
+    type: z
+      .string()
+      .optional()
+      .describe(
+        'File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types.',
+      ),
+    head_limit: semanticNumber(z.number().optional()).describe(
+      'Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 250 when unspecified. Pass 0 for unlimited (use sparingly — large result sets waste context).',
+    ),
+    offset: semanticNumber(z.number().optional()).describe(
+      'Skip first N lines/entries before applying head_limit, equivalent to "| tail -n +N | head -N". Works across all output modes. Defaults to 0.',
+    ),
+    multiline: semanticBoolean(z.boolean().optional()).describe(
+      'Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false.',
+    ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+// Version control system directories to exclude from searches
+// These are excluded automatically because they create noise in search results
+const VCS_DIRECTORIES_TO_EXCLUDE = [
+  '.git',
+  '.svn',
+  '.hg',
+  '.bzr',
+  '.jj',
+  '.sl',
+] as const
+
+// Default cap on grep results when head_limit is unspecified. Unbounded content-mode
+// greps can fill up to the 20KB persist threshold (~6-24K tokens/grep-heavy session).
+// 250 is generous enough for exploratory searches while preventing context bloat.
+// Pass head_limit=0 explicitly for unlimited.
+const DEFAULT_HEAD_LIMIT = 250
+
+function applyHeadLimit<T>(
+  items: T[],
+  limit: number | undefined,
+  offset: number = 0,
+): { items: T[]; appliedLimit: number | undefined } {
+  // Explicit 0 = unlimited escape hatch
+  if (limit === 0) {
+    return { items: items.slice(offset), appliedLimit: undefined }
+  }
+  const effectiveLimit = limit ?? DEFAULT_HEAD_LIMIT
+  const sliced = items.slice(offset, offset + effectiveLimit)
+  // Only report appliedLimit when truncation actually occurred, so the model
+  // knows there may be more results and can paginate with offset.
+  const wasTruncated = items.length - offset > effectiveLimit
+  return {
+    items: sliced,
+    appliedLimit: wasTruncated ? effectiveLimit : undefined,
+  }
+}
+
+// Format limit/offset information for display in tool results.
+// appliedLimit is only set when truncation actually occurred (see applyHeadLimit),
+// so it may be undefined even when appliedOffset is set — build parts conditionally
+// to avoid "limit: undefined" appearing in user-visible output.
+function formatLimitInfo(
+  appliedLimit: number | undefined,
+  appliedOffset: number | undefined,
+): string {
+  const parts: string[] = []
+  if (appliedLimit !== undefined) parts.push(`limit: ${appliedLimit}`)
+  if (appliedOffset) parts.push(`offset: ${appliedOffset}`)
+  return parts.join(', ')
+}
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    mode: z.enum(['content', 'files_with_matches', 'count']).optional(),
+    numFiles: z.number(),
+    filenames: z.array(z.string()),
+    content: z.string().optional(),
+    numLines: z.number().optional(), // For content mode
+    numMatches: z.number().optional(), // For count mode
+    appliedLimit: z.number().optional(), // The limit that was applied (if any)
+    appliedOffset: z.number().optional(), // The offset that was applied
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+type Output = z.infer<OutputSchema>
+
+export const GrepTool = buildTool({
+  name: GREP_TOOL_NAME,
+  searchHint: 'search file contents with regex (ripgrep)',
+  // 20K chars - tool result persistence threshold
+  maxResultSizeChars: 20_000,
+  strict: true,
+  async description() {
+    return getDescription()
+  },
+  userFacingName() {
+    return 'Search'
+  },
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const summary = getToolUseSummary(input)
+    return summary ? `Searching for ${summary}` : 'Searching'
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.path ? `${input.pattern} in ${input.path}` : input.pattern
+  },
+  isSearchOrReadCommand() {
+    return { isSearch: true, isRead: false }
+  },
+  getPath({ path }): string {
+    return path || getCwd()
+  },
+  async preparePermissionMatcher({ pattern }) {
+    return rulePattern => matchWildcardPattern(rulePattern, pattern)
+  },
+  async validateInput({ path }): Promise<ValidationResult> {
+    // If path is provided, validate that it exists
+    if (path) {
+      const fs = getFsImplementation()
+      const absolutePath = expandPath(path)
+
+      // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+      if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
+        return { result: true }
+      }
+
+      try {
+        await fs.stat(absolutePath)
+      } catch (e: unknown) {
+        if (isENOENT(e)) {
+          const cwdSuggestion = await suggestPathUnderCwd(absolutePath)
+          let message = `Path does not exist: ${path}. ${FILE_NOT_FOUND_CWD_NOTE} ${getCwd()}.`
+          if (cwdSuggestion) {
+            message += ` Did you mean ${cwdSuggestion}?`
+          }
+          return {
+            result: false,
+            message,
+            errorCode: 1,
+          }
+        }
+        throw e
+      }
+    }
+
+    return { result: true }
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkReadPermissionForTool(
+      GrepTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  async prompt() {
+    return getDescription()
+  },
+  renderToolUseMessage,
+  renderToolUseErrorMessage,
+  renderToolResultMessage,
+  // SearchResultSummary shows content (mode=content) or filenames.join.
+  // numFiles/numLines/numMatches are chrome ("Found 3 files") — fine to
+  // skip (under-count, not phantom). Glob reuses this via UI.tsx:65.
+  extractSearchText({ mode, content, filenames }) {
+    if (mode === 'content' && content) return content
+    return filenames.join('\n')
+  },
+  mapToolResultToToolResultBlockParam(
+    {
+      mode = 'files_with_matches',
+      numFiles,
+      filenames,
+      content,
+      numLines: _numLines,
+      numMatches,
+      appliedLimit,
+      appliedOffset,
+    },
+    toolUseID,
+  ) {
+    if (mode === 'content') {
+      const limitInfo = formatLimitInfo(appliedLimit, appliedOffset)
+      const resultContent = content || 'No matches found'
+      const finalContent = limitInfo
+        ? `${resultContent}\n\n[Showing results with pagination = ${limitInfo}]`
+        : resultContent
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: finalContent,
+      }
+    }
+
+    if (mode === 'count') {
+      const limitInfo = formatLimitInfo(appliedLimit, appliedOffset)
+      const rawContent = content || 'No matches found'
+      const matches = numMatches ?? 0
+      const files = numFiles ?? 0
+      const summary = `\n\nFound ${matches} total ${matches === 1 ? 'occurrence' : 'occurrences'} across ${files} ${files === 1 ? 'file' : 'files'}.${limitInfo ? ` with pagination = ${limitInfo}` : ''}`
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: rawContent + summary,
+      }
+    }
+
+    // files_with_matches mode
+    const limitInfo = formatLimitInfo(appliedLimit, appliedOffset)
+    if (numFiles === 0) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: 'No files found',
+      }
+    }
+    // head_limit has already been applied in call() method, so just show all filenames
+    const result = `Found ${numFiles} ${plural(numFiles, 'file')}${limitInfo ? ` ${limitInfo}` : ''}\n${filenames.join('\n')}`
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: result,
+    }
+  },
+  async call(
+    {
+      pattern,
+      path,
+      glob,
+      type,
+      output_mode = 'files_with_matches',
+      '-B': context_before,
+      '-A': context_after,
+      '-C': context_c,
+      context,
+      '-n': show_line_numbers = true,
+      '-i': case_insensitive = false,
+      head_limit,
+      offset = 0,
+      multiline = false,
+    },
+    { abortController, getAppState },
+  ) {
+    const absolutePath = path ? expandPath(path) : getCwd()
+    const args = ['--hidden']
+
+    // Exclude VCS directories to avoid noise from version control metadata
+    for (const dir of VCS_DIRECTORIES_TO_EXCLUDE) {
+      args.push('--glob', `!${dir}`)
+    }
+
+    // Limit line length to prevent base64/minified content from cluttering output
+    args.push('--max-columns', '500')
+
+    // Only apply multiline flags when explicitly requested
+    if (multiline) {
+      args.push('-U', '--multiline-dotall')
+    }
+
+    // Add optional flags
+    if (case_insensitive) {
+      args.push('-i')
+    }
+
+    // Add output mode flags
+    if (output_mode === 'files_with_matches') {
+      args.push('-l')
+    } else if (output_mode === 'count') {
+      args.push('-c')
+    }
+
+    // Add line numbers if requested
+    if (show_line_numbers && output_mode === 'content') {
+      args.push('-n')
+    }
+
+    // Add context flags (-C/context takes precedence over context_before/context_after)
+    if (output_mode === 'content') {
+      if (context !== undefined) {
+        args.push('-C', context.toString())
+      } else if (context_c !== undefined) {
+        args.push('-C', context_c.toString())
+      } else {
+        if (context_before !== undefined) {
+          args.push('-B', context_before.toString())
+        }
+        if (context_after !== undefined) {
+          args.push('-A', context_after.toString())
+        }
+      }
+    }
+
+    // If pattern starts with dash, use -e flag to specify it as a pattern
+    // This prevents ripgrep from interpreting it as a command-line option
+    if (pattern.startsWith('-')) {
+      args.push('-e', pattern)
+    } else {
+      args.push(pattern)
+    }
+
+    // Add type filter if specified
+    if (type) {
+      args.push('--type', type)
+    }
+
+    if (glob) {
+      // Split on commas and spaces, but preserve patterns with braces
+      const globPatterns: string[] = []
+      const rawPatterns = glob.split(/\s+/)
+
+      for (const rawPattern of rawPatterns) {
+        // If pattern contains braces, don't split further
+        if (rawPattern.includes('{') && rawPattern.includes('}')) {
+          globPatterns.push(rawPattern)
+        } else {
+          // Split on commas for patterns without braces
+          globPatterns.push(...rawPattern.split(',').filter(Boolean))
+        }
+      }
+
+      for (const globPattern of globPatterns.filter(Boolean)) {
+        args.push('--glob', globPattern)
+      }
+    }
+
+    // Add ignore patterns
+    const appState = getAppState()
+    const ignorePatterns = normalizePatternsToPath(
+      getFileReadIgnorePatterns(appState.toolPermissionContext),
+      getCwd(),
+    )
+    for (const ignorePattern of ignorePatterns) {
+      // Note: ripgrep only applies gitignore patterns relative to the working directory
+      // So for non-absolute paths, we need to prefix them with '**'
+      // See: https://github.com/BurntSushi/ripgrep/discussions/2156#discussioncomment-2316335
+      //
+      // We also need to negate the pattern with `!` to exclude it
+      const rgIgnorePattern = ignorePattern.startsWith('/')
+        ? `!${ignorePattern}`
+        : `!**/${ignorePattern}`
+      args.push('--glob', rgIgnorePattern)
+    }
+
+    // Exclude orphaned plugin version directories
+    for (const exclusion of await getGlobExclusionsForPluginCache(
+      absolutePath,
+    )) {
+      args.push('--glob', exclusion)
+    }
+
+    // WSL has severe performance penalty for file reads (3-5x slower on WSL2)
+    // The timeout is handled by ripgrep itself via execFile timeout option
+    // We don't use AbortController for timeout to avoid interrupting the agent loop
+    // If ripgrep times out, it throws RipgrepTimeoutError which propagates up
+    // so Claude knows the search didn't complete (rather than thinking there were no matches)
+    const results = await ripGrep(args, absolutePath, abortController.signal)
+
+    if (output_mode === 'content') {
+      // For content mode, results are the actual content lines
+      // Convert absolute paths to relative paths to save tokens
+
+      // Apply head_limit first — relativize is per-line work, so
+      // avoid processing lines that will be discarded (broad patterns can
+      // return 10k+ lines with head_limit keeping only ~30-100).
+      const { items: limitedResults, appliedLimit } = applyHeadLimit(
+        results,
+        head_limit,
+        offset,
+      )
+
+      const finalLines = limitedResults.map(line => {
+        // Lines have format: /absolute/path:line_content or /absolute/path:num:content
+        const colonIndex = line.indexOf(':')
+        if (colonIndex > 0) {
+          const filePath = line.substring(0, colonIndex)
+          const rest = line.substring(colonIndex)
+          return toRelativePath(filePath) + rest
+        }
+        return line
+      })
+      const output = {
+        mode: 'content' as const,
+        numFiles: 0, // Not applicable for content mode
+        filenames: [],
+        content: finalLines.join('\n'),
+        numLines: finalLines.length,
+        ...(appliedLimit !== undefined && { appliedLimit }),
+        ...(offset > 0 && { appliedOffset: offset }),
+      }
+      return { data: output }
+    }
+
+    if (output_mode === 'count') {
+      // For count mode, pass through raw ripgrep output (filename:count format)
+      // Apply head_limit first to avoid relativizing entries that will be discarded.
+      const { items: limitedResults, appliedLimit } = applyHeadLimit(
+        results,
+        head_limit,
+        offset,
+      )
+
+      // Convert absolute paths to relative paths to save tokens
+      const finalCountLines = limitedResults.map(line => {
+        // Lines have format: /absolute/path:count
+        const colonIndex = line.lastIndexOf(':')
+        if (colonIndex > 0) {
+          const filePath = line.substring(0, colonIndex)
+          const count = line.substring(colonIndex)
+          return toRelativePath(filePath) + count
+        }
+        return line
+      })
+
+      // Parse count output to extract total matches and file count
+      let totalMatches = 0
+      let fileCount = 0
+      for (const line of finalCountLines) {
+        const colonIndex = line.lastIndexOf(':')
+        if (colonIndex > 0) {
+          const countStr = line.substring(colonIndex + 1)
+          const count = parseInt(countStr, 10)
+          if (!isNaN(count)) {
+            totalMatches += count
+            fileCount += 1
+          }
+        }
+      }
+
+      const output = {
+        mode: 'count' as const,
+        numFiles: fileCount,
+        filenames: [],
+        content: finalCountLines.join('\n'),
+        numMatches: totalMatches,
+        ...(appliedLimit !== undefined && { appliedLimit }),
+        ...(offset > 0 && { appliedOffset: offset }),
+      }
+      return { data: output }
+    }
+
+    // For files_with_matches mode (default)
+    // Use allSettled so a single ENOENT (file deleted between ripgrep's scan
+    // and this stat) does not reject the whole batch. Failed stats sort as mtime 0.
+    const stats = await Promise.allSettled(
+      results.map(_ => getFsImplementation().stat(_)),
+    )
+    const sortedMatches = results
+      // Sort by modification time
+      .map((_, i) => {
+        const r = stats[i]!
+        return [
+          _,
+          r.status === 'fulfilled' ? (r.value.mtimeMs ?? 0) : 0,
+        ] as const
+      })
+      .sort((a, b) => {
+        if (process.env.NODE_ENV === 'test') {
+          // In tests, we always want to sort by filename, so that results are deterministic
+          return a[0].localeCompare(b[0])
+        }
+        const timeComparison = b[1] - a[1]
+        if (timeComparison === 0) {
+          // Sort by filename as a tiebreaker
+          return a[0].localeCompare(b[0])
+        }
+        return timeComparison
+      })
+      .map(_ => _[0])
+
+    // Apply head_limit to sorted file list (like "| head -N")
+    const { items: finalMatches, appliedLimit } = applyHeadLimit(
+      sortedMatches,
+      head_limit,
+      offset,
+    )
+
+    // Convert absolute paths to relative paths to save tokens
+    const relativeMatches = finalMatches.map(toRelativePath)
+
+    const output = {
+      mode: 'files_with_matches' as const,
+      filenames: relativeMatches,
+      numFiles: relativeMatches.length,
+      ...(appliedLimit !== undefined && { appliedLimit }),
+      ...(offset > 0 && { appliedOffset: offset }),
+    }
+
+    return {
+      data: output,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/GrepTool/prompt.ts

@@ -0,0 +1,18 @@
+import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'
+import { BASH_TOOL_NAME } from '../BashTool/toolName.js'
+
+export const GREP_TOOL_NAME = 'Grep'
+
+export function getDescription(): string {
+  return `A powerful search tool built on ripgrep
+
+  Usage:
+  - ALWAYS use ${GREP_TOOL_NAME} for search tasks. NEVER invoke \`grep\` or \`rg\` as a ${BASH_TOOL_NAME} command. The ${GREP_TOOL_NAME} tool has been optimized for correct permissions and access.
+  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+  - Use ${AGENT_TOOL_NAME} tool for open-ended searches requiring multiple rounds
+  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use \`interface\\{\\}\` to find \`interface{}\` in Go code)
+  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like \`struct \\{[\\s\\S]*?field\`, use \`multiline: true\`
+`
+}

src/tools/LSPTool/LSPTool.ts

@@ -0,0 +1,860 @@
+import { open } from 'fs/promises'
+import * as path from 'path'
+import { pathToFileURL } from 'url'
+import type {
+  CallHierarchyIncomingCall,
+  CallHierarchyItem,
+  CallHierarchyOutgoingCall,
+  DocumentSymbol,
+  Hover,
+  Location,
+  LocationLink,
+  SymbolInformation,
+} from 'vscode-languageserver-types'
+import { z } from 'zod/v4'
+import {
+  getInitializationStatus,
+  getLspServerManager,
+  isLspConnected,
+  waitForInitialization,
+} from '../../services/lsp/manager.js'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { uniq } from '../../utils/array.js'
+import { getCwd } from '../../utils/cwd.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { isENOENT, toError } from '../../utils/errors.js'
+import { execFileNoThrowWithCwd } from '../../utils/execFileNoThrow.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import { expandPath } from '../../utils/path.js'
+import { checkReadPermissionForTool } from '../../utils/permissions/filesystem.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import {
+  formatDocumentSymbolResult,
+  formatFindReferencesResult,
+  formatGoToDefinitionResult,
+  formatHoverResult,
+  formatIncomingCallsResult,
+  formatOutgoingCallsResult,
+  formatPrepareCallHierarchyResult,
+  formatWorkspaceSymbolResult,
+} from './formatters.js'
+import { DESCRIPTION, LSP_TOOL_NAME } from './prompt.js'
+import { lspToolInputSchema } from './schemas.js'
+import {
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+  userFacingName,
+} from './UI.js'
+
+const MAX_LSP_FILE_SIZE_BYTES = 10_000_000
+
+/**
+ * Tool-compatible input schema (regular ZodObject instead of discriminated union)
+ * We validate against the discriminated union in validateInput for better error messages
+ */
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    operation: z
+      .enum([
+        'goToDefinition',
+        'findReferences',
+        'hover',
+        'documentSymbol',
+        'workspaceSymbol',
+        'goToImplementation',
+        'prepareCallHierarchy',
+        'incomingCalls',
+        'outgoingCalls',
+      ])
+      .describe('The LSP operation to perform'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    operation: z
+      .enum([
+        'goToDefinition',
+        'findReferences',
+        'hover',
+        'documentSymbol',
+        'workspaceSymbol',
+        'goToImplementation',
+        'prepareCallHierarchy',
+        'incomingCalls',
+        'outgoingCalls',
+      ])
+      .describe('The LSP operation that was performed'),
+    result: z.string().describe('The formatted result of the LSP operation'),
+    filePath: z
+      .string()
+      .describe('The file path the operation was performed on'),
+    resultCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe('Number of results (definitions, references, symbols)'),
+    fileCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe('Number of files containing results'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+export type Input = z.infer<InputSchema>
+
+export const LSPTool = buildTool({
+  name: LSP_TOOL_NAME,
+  searchHint: 'code intelligence (definitions, references, symbols, hover)',
+  maxResultSizeChars: 100_000,
+  isLsp: true,
+  async description() {
+    return DESCRIPTION
+  },
+  userFacingName,
+  shouldDefer: true,
+  isEnabled() {
+    return isLspConnected()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  getPath({ filePath }): string {
+    return expandPath(filePath)
+  },
+  async validateInput(input: Input): Promise<ValidationResult> {
+    // First validate against the discriminated union for better type safety
+    const parseResult = lspToolInputSchema().safeParse(input)
+    if (!parseResult.success) {
+      return {
+        result: false,
+        message: `Invalid input: ${parseResult.error.message}`,
+        errorCode: 3,
+      }
+    }
+
+    // Validate file exists and is a regular file
+    const fs = getFsImplementation()
+    const absolutePath = expandPath(input.filePath)
+
+    // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+    if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
+      return { result: true }
+    }
+
+    let stats
+    try {
+      stats = await fs.stat(absolutePath)
+    } catch (error) {
+      if (isENOENT(error)) {
+        return {
+          result: false,
+          message: `File does not exist: ${input.filePath}`,
+          errorCode: 1,
+        }
+      }
+      const err = toError(error)
+      // Log filesystem access errors for tracking
+      logError(
+        new Error(
+          `Failed to access file stats for LSP operation on ${input.filePath}: ${err.message}`,
+        ),
+      )
+      return {
+        result: false,
+        message: `Cannot access file: ${input.filePath}. ${err.message}`,
+        errorCode: 4,
+      }
+    }
+
+    if (!stats.isFile()) {
+      return {
+        result: false,
+        message: `Path is not a file: ${input.filePath}`,
+        errorCode: 2,
+      }
+    }
+
+    return { result: true }
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkReadPermissionForTool(
+      LSPTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  renderToolUseMessage,
+  renderToolUseErrorMessage,
+  renderToolResultMessage,
+  async call(input: Input, _context) {
+    const absolutePath = expandPath(input.filePath)
+    const cwd = getCwd()
+
+    // Wait for initialization if it's still pending
+    // This prevents returning "no server available" before init completes
+    const status = getInitializationStatus()
+    if (status.status === 'pending') {
+      await waitForInitialization()
+    }
+
+    // Get the LSP server manager
+    const manager = getLspServerManager()
+    if (!manager) {
+      // Log this system-level failure for tracking
+      logError(
+        new Error('LSP server manager not initialized when tool was called'),
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result:
+          'LSP server manager not initialized. This may indicate a startup issue.',
+        filePath: input.filePath,
+      }
+      return {
+        data: output,
+      }
+    }
+
+    // Map operation to LSP method and prepare params
+    const { method, params } = getMethodAndParams(input, absolutePath)
+
+    try {
+      // Ensure file is open in LSP server before making requests
+      // Most LSP servers require textDocument/didOpen before operations
+      // Only read the file if it's not already open to avoid unnecessary I/O
+      if (!manager.isFileOpen(absolutePath)) {
+        const handle = await open(absolutePath, 'r')
+        try {
+          const stats = await handle.stat()
+          if (stats.size > MAX_LSP_FILE_SIZE_BYTES) {
+            const output: Output = {
+              operation: input.operation,
+              result: `File too large for LSP analysis (${Math.ceil(stats.size / 1_000_000)}MB exceeds 10MB limit)`,
+              filePath: input.filePath,
+            }
+            return { data: output }
+          }
+          const fileContent = await handle.readFile({ encoding: 'utf-8' })
+          await manager.openFile(absolutePath, fileContent)
+        } finally {
+          await handle.close()
+        }
+      }
+
+      // Send request to LSP server
+      let result = await manager.sendRequest(absolutePath, method, params)
+
+      if (result === undefined) {
+        // Log for diagnostic purposes - helps track usage patterns and potential bugs
+        logForDebugging(
+          `No LSP server available for file type ${path.extname(absolutePath)} for operation ${input.operation} on file ${input.filePath}`,
+        )
+
+        const output: Output = {
+          operation: input.operation,
+          result: `No LSP server available for file type: ${path.extname(absolutePath)}`,
+          filePath: input.filePath,
+        }
+        return {
+          data: output,
+        }
+      }
+
+      // For incomingCalls and outgoingCalls, we need a two-step process:
+      // 1. First get CallHierarchyItem(s) from prepareCallHierarchy
+      // 2. Then request the actual calls using that item
+      if (
+        input.operation === 'incomingCalls' ||
+        input.operation === 'outgoingCalls'
+      ) {
+        const callItems = result as CallHierarchyItem[]
+        if (!callItems || callItems.length === 0) {
+          const output: Output = {
+            operation: input.operation,
+            result: 'No call hierarchy item found at this position',
+            filePath: input.filePath,
+            resultCount: 0,
+            fileCount: 0,
+          }
+          return { data: output }
+        }
+
+        // Use the first call hierarchy item to request calls
+        const callMethod =
+          input.operation === 'incomingCalls'
+            ? 'callHierarchy/incomingCalls'
+            : 'callHierarchy/outgoingCalls'
+
+        result = await manager.sendRequest(absolutePath, callMethod, {
+          item: callItems[0],
+        })
+
+        if (result === undefined) {
+          logForDebugging(
+            `LSP server returned undefined for ${callMethod} on ${input.filePath}`,
+          )
+          // Continue to formatter which will handle empty/null gracefully
+        }
+      }
+
+      // Filter out gitignored files from location-based results
+      if (
+        result &&
+        Array.isArray(result) &&
+        (input.operation === 'findReferences' ||
+          input.operation === 'goToDefinition' ||
+          input.operation === 'goToImplementation' ||
+          input.operation === 'workspaceSymbol')
+      ) {
+        if (input.operation === 'workspaceSymbol') {
+          // SymbolInformation has location.uri — filter by extracting locations
+          const symbols = result as SymbolInformation[]
+          const locations = symbols
+            .filter(s => s?.location?.uri)
+            .map(s => s.location)
+          const filteredLocations = await filterGitIgnoredLocations(
+            locations,
+            cwd,
+          )
+          const filteredUris = new Set(filteredLocations.map(l => l.uri))
+          result = symbols.filter(
+            s => !s?.location?.uri || filteredUris.has(s.location.uri),
+          )
+        } else {
+          // Location[] or (Location | LocationLink)[]
+          const locations = (result as (Location | LocationLink)[]).map(
+            toLocation,
+          )
+          const filteredLocations = await filterGitIgnoredLocations(
+            locations,
+            cwd,
+          )
+          const filteredUris = new Set(filteredLocations.map(l => l.uri))
+          result = (result as (Location | LocationLink)[]).filter(item => {
+            const loc = toLocation(item)
+            return !loc.uri || filteredUris.has(loc.uri)
+          })
+        }
+      }
+
+      // Format the result based on operation type
+      const { formatted, resultCount, fileCount } = formatResult(
+        input.operation,
+        result,
+        cwd,
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result: formatted,
+        filePath: input.filePath,
+        resultCount,
+        fileCount,
+      }
+
+      return {
+        data: output,
+      }
+    } catch (error) {
+      const err = toError(error)
+      const errorMessage = err.message
+
+      // Log error for tracking
+      logError(
+        new Error(
+          `LSP tool request failed for ${input.operation} on ${input.filePath}: ${errorMessage}`,
+        ),
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result: `Error performing ${input.operation}: ${errorMessage}`,
+        filePath: input.filePath,
+      }
+      return {
+        data: output,
+      }
+    }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: output.result,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)
+
+/**
+ * Maps LSPTool operation to LSP method and params
+ */
+function getMethodAndParams(
+  input: Input,
+  absolutePath: string,
+): { method: string; params: unknown } {
+  const uri = pathToFileURL(absolutePath).href
+  // Convert from 1-based (user-friendly) to 0-based (LSP protocol)
+  const position = {
+    line: input.line - 1,
+    character: input.character - 1,
+  }
+
+  switch (input.operation) {
+    case 'goToDefinition':
+      return {
+        method: 'textDocument/definition',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'findReferences':
+      return {
+        method: 'textDocument/references',
+        params: {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: true },
+        },
+      }
+    case 'hover':
+      return {
+        method: 'textDocument/hover',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'documentSymbol':
+      return {
+        method: 'textDocument/documentSymbol',
+        params: {
+          textDocument: { uri },
+        },
+      }
+    case 'workspaceSymbol':
+      return {
+        method: 'workspace/symbol',
+        params: {
+          query: '', // Empty query returns all symbols
+        },
+      }
+    case 'goToImplementation':
+      return {
+        method: 'textDocument/implementation',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'prepareCallHierarchy':
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'incomingCalls':
+      // For incoming/outgoing calls, we first need to prepare the call hierarchy
+      // The LSP server will return CallHierarchyItem(s) that we pass to the calls request
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'outgoingCalls':
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+  }
+}
+
+/**
+ * Counts the total number of symbols including nested children
+ */
+function countSymbols(symbols: DocumentSymbol[]): number {
+  let count = symbols.length
+  for (const symbol of symbols) {
+    if (symbol.children && symbol.children.length > 0) {
+      count += countSymbols(symbol.children)
+    }
+  }
+  return count
+}
+
+/**
+ * Counts unique files from an array of locations
+ */
+function countUniqueFiles(locations: Location[]): number {
+  return new Set(locations.map(loc => loc.uri)).size
+}
+
+/**
+ * Extracts a file path from a file:// URI, decoding percent-encoded characters.
+ */
+function uriToFilePath(uri: string): string {
+  let filePath = uri.replace(/^file:\/\//, '')
+  // On Windows, file:///C:/path becomes /C:/path — strip the leading slash
+  if (/^\/[A-Za-z]:/.test(filePath)) {
+    filePath = filePath.slice(1)
+  }
+  try {
+    filePath = decodeURIComponent(filePath)
+  } catch {
+    // Use un-decoded path if malformed
+  }
+  return filePath
+}
+
+/**
+ * Filters out locations whose file paths are gitignored.
+ * Uses `git check-ignore` with batched path arguments for efficiency.
+ */
+async function filterGitIgnoredLocations<T extends Location>(
+  locations: T[],
+  cwd: string,
+): Promise<T[]> {
+  if (locations.length === 0) {
+    return locations
+  }
+
+  // Collect unique file paths from URIs
+  const uriToPath = new Map<string, string>()
+  for (const loc of locations) {
+    if (loc.uri && !uriToPath.has(loc.uri)) {
+      uriToPath.set(loc.uri, uriToFilePath(loc.uri))
+    }
+  }
+
+  const uniquePaths = uniq(uriToPath.values())
+  if (uniquePaths.length === 0) {
+    return locations
+  }
+
+  // Batch check paths with git check-ignore
+  // Exit code 0 = at least one path is ignored, 1 = none ignored, 128 = not a git repo
+  const ignoredPaths = new Set<string>()
+  const BATCH_SIZE = 50
+  for (let i = 0; i < uniquePaths.length; i += BATCH_SIZE) {
+    const batch = uniquePaths.slice(i, i + BATCH_SIZE)
+    const result = await execFileNoThrowWithCwd(
+      'git',
+      ['check-ignore', ...batch],
+      {
+        cwd,
+        preserveOutputOnError: false,
+        timeout: 5_000,
+      },
+    )
+
+    if (result.code === 0 && result.stdout) {
+      for (const line of result.stdout.split('\n')) {
+        const trimmed = line.trim()
+        if (trimmed) {
+          ignoredPaths.add(trimmed)
+        }
+      }
+    }
+  }
+
+  if (ignoredPaths.size === 0) {
+    return locations
+  }
+
+  return locations.filter(loc => {
+    const filePath = uriToPath.get(loc.uri)
+    return !filePath || !ignoredPaths.has(filePath)
+  })
+}
+
+/**
+ * Checks if item is LocationLink (has targetUri) vs Location (has uri)
+ */
+function isLocationLink(item: Location | LocationLink): item is LocationLink {
+  return 'targetUri' in item
+}
+
+/**
+ * Converts LocationLink to Location format for uniform handling
+ */
+function toLocation(item: Location | LocationLink): Location {
+  if (isLocationLink(item)) {
+    return {
+      uri: item.targetUri,
+      range: item.targetSelectionRange || item.targetRange,
+    }
+  }
+  return item
+}
+
+/**
+ * Formats LSP result based on operation type and extracts summary counts
+ */
+function formatResult(
+  operation: Input['operation'],
+  result: unknown,
+  cwd: string,
+): { formatted: string; resultCount: number; fileCount: number } {
+  switch (operation) {
+    case 'goToDefinition': {
+      // Handle both Location and LocationLink formats
+      const rawResults = Array.isArray(result)
+        ? result
+        : result
+          ? [result as Location | LocationLink]
+          : []
+
+      // Convert LocationLinks to Locations for uniform handling
+      const locations = rawResults.map(toLocation)
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for goToDefinition on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        formatted: formatGoToDefinitionResult(
+          result as
+            | Location
+            | Location[]
+            | LocationLink
+            | LocationLink[]
+            | null,
+          cwd,
+        ),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'findReferences': {
+      const locations = (result as Location[]) || []
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for findReferences on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        formatted: formatFindReferencesResult(result as Location[] | null, cwd),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'hover': {
+      return {
+        formatted: formatHoverResult(result as Hover | null, cwd),
+        resultCount: result ? 1 : 0,
+        fileCount: result ? 1 : 0,
+      }
+    }
+    case 'documentSymbol': {
+      // LSP allows documentSymbol to return either DocumentSymbol[] or SymbolInformation[]
+      const symbols = (result as (DocumentSymbol | SymbolInformation)[]) || []
+      // Detect format: DocumentSymbol has 'range', SymbolInformation has 'location'
+      const isDocumentSymbol =
+        symbols.length > 0 && symbols[0] && 'range' in symbols[0]
+      // Count symbols - DocumentSymbol can have nested children, SymbolInformation is flat
+      const count = isDocumentSymbol
+        ? countSymbols(symbols as DocumentSymbol[])
+        : symbols.length
+      return {
+        formatted: formatDocumentSymbolResult(
+          result as (DocumentSymbol[] | SymbolInformation[]) | null,
+          cwd,
+        ),
+        resultCount: count,
+        fileCount: symbols.length > 0 ? 1 : 0,
+      }
+    }
+    case 'workspaceSymbol': {
+      const symbols = (result as SymbolInformation[]) || []
+
+      // Log and filter out symbols with undefined location.uri
+      const invalidSymbols = symbols.filter(
+        sym => !sym || !sym.location || !sym.location.uri,
+      )
+      if (invalidSymbols.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidSymbols.length} symbol(s) with undefined location URI for workspaceSymbol on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validSymbols = symbols.filter(
+        sym => sym && sym.location && sym.location.uri,
+      )
+      const locations = validSymbols.map(s => s.location)
+      return {
+        formatted: formatWorkspaceSymbolResult(
+          result as SymbolInformation[] | null,
+          cwd,
+        ),
+        resultCount: validSymbols.length,
+        fileCount: countUniqueFiles(locations),
+      }
+    }
+    case 'goToImplementation': {
+      // Handle both Location and LocationLink formats (same as goToDefinition)
+      const rawResults = Array.isArray(result)
+        ? result
+        : result
+          ? [result as Location | LocationLink]
+          : []
+
+      // Convert LocationLinks to Locations for uniform handling
+      const locations = rawResults.map(toLocation)
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for goToImplementation on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        // Reuse goToDefinition formatter since the result format is identical
+        formatted: formatGoToDefinitionResult(
+          result as
+            | Location
+            | Location[]
+            | LocationLink
+            | LocationLink[]
+            | null,
+          cwd,
+        ),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'prepareCallHierarchy': {
+      const items = (result as CallHierarchyItem[]) || []
+      return {
+        formatted: formatPrepareCallHierarchyResult(
+          result as CallHierarchyItem[] | null,
+          cwd,
+        ),
+        resultCount: items.length,
+        fileCount: items.length > 0 ? countUniqueFilesFromCallItems(items) : 0,
+      }
+    }
+    case 'incomingCalls': {
+      const calls = (result as CallHierarchyIncomingCall[]) || []
+      return {
+        formatted: formatIncomingCallsResult(
+          result as CallHierarchyIncomingCall[] | null,
+          cwd,
+        ),
+        resultCount: calls.length,
+        fileCount:
+          calls.length > 0 ? countUniqueFilesFromIncomingCalls(calls) : 0,
+      }
+    }
+    case 'outgoingCalls': {
+      const calls = (result as CallHierarchyOutgoingCall[]) || []
+      return {
+        formatted: formatOutgoingCallsResult(
+          result as CallHierarchyOutgoingCall[] | null,
+          cwd,
+        ),
+        resultCount: calls.length,
+        fileCount:
+          calls.length > 0 ? countUniqueFilesFromOutgoingCalls(calls) : 0,
+      }
+    }
+  }
+}
+
+/**
+ * Counts unique files from CallHierarchyItem array
+ * Filters out items with undefined URIs
+ */
+function countUniqueFilesFromCallItems(items: CallHierarchyItem[]): number {
+  const validUris = items.map(item => item.uri).filter(uri => uri)
+  return new Set(validUris).size
+}
+
+/**
+ * Counts unique files from CallHierarchyIncomingCall array
+ * Filters out calls with undefined URIs
+ */
+function countUniqueFilesFromIncomingCalls(
+  calls: CallHierarchyIncomingCall[],
+): number {
+  const validUris = calls.map(call => call.from?.uri).filter(uri => uri)
+  return new Set(validUris).size
+}
+
+/**
+ * Counts unique files from CallHierarchyOutgoingCall array
+ * Filters out calls with undefined URIs
+ */
+function countUniqueFilesFromOutgoingCalls(
+  calls: CallHierarchyOutgoingCall[],
+): number {
+  const validUris = calls.map(call => call.to?.uri).filter(uri => uri)
+  return new Set(validUris).size
+}

src/tools/LSPTool/formatters.ts

@@ -0,0 +1,592 @@
+import { relative } from 'path'
+import type {
+  CallHierarchyIncomingCall,
+  CallHierarchyItem,
+  CallHierarchyOutgoingCall,
+  DocumentSymbol,
+  Hover,
+  Location,
+  LocationLink,
+  MarkedString,
+  MarkupContent,
+  SymbolInformation,
+  SymbolKind,
+} from 'vscode-languageserver-types'
+import { logForDebugging } from '../../utils/debug.js'
+import { errorMessage } from '../../utils/errors.js'
+import { plural } from '../../utils/stringUtils.js'
+
+/**
+ * Formats a URI by converting it to a relative path if possible.
+ * Handles URI decoding and gracefully falls back to un-decoded path if malformed.
+ * Only uses relative paths when shorter and not starting with ../../
+ */
+function formatUri(uri: string | undefined, cwd?: string): string {
+  // Handle undefined/null URIs - this indicates malformed LSP data
+  if (!uri) {
+    // NOTE: This should ideally be caught earlier with proper error logging
+    // This is a defensive backstop in the formatting layer
+    logForDebugging(
+      'formatUri called with undefined URI - indicates malformed LSP server response',
+      { level: 'warn' },
+    )
+    return '<unknown location>'
+  }
+
+  // Remove file:// protocol if present
+  // On Windows, file:///C:/path becomes /C:/path after replacing file://
+  // We need to strip the leading slash for Windows drive-letter paths
+  let filePath = uri.replace(/^file:\/\//, '')
+  if (/^\/[A-Za-z]:/.test(filePath)) {
+    filePath = filePath.slice(1)
+  }
+
+  // Decode URI encoding - handle malformed URIs gracefully
+  try {
+    filePath = decodeURIComponent(filePath)
+  } catch (error) {
+    // Log for debugging but continue with un-decoded path
+    const errorMsg = errorMessage(error)
+    logForDebugging(
+      `Failed to decode LSP URI '${uri}': ${errorMsg}. Using un-decoded path: ${filePath}`,
+      { level: 'warn' },
+    )
+    // filePath already contains the un-decoded path, which is still usable
+  }
+
+  // Convert to relative path if cwd is provided
+  if (cwd) {
+    // Normalize separators to forward slashes for consistent display output
+    const relativePath = relative(cwd, filePath).replaceAll('\\', '/')
+    // Only use relative path if it's shorter and doesn't start with ../..
+    if (
+      relativePath.length < filePath.length &&
+      !relativePath.startsWith('../../')
+    ) {
+      return relativePath
+    }
+  }
+
+  // Normalize separators to forward slashes for consistent display output
+  return filePath.replaceAll('\\', '/')
+}
+
+/**
+ * Groups items by their file URI.
+ * Generic helper that works with both Location[] and SymbolInformation[]
+ */
+function groupByFile<T extends { uri: string } | { location: { uri: string } }>(
+  items: T[],
+  cwd?: string,
+): Map<string, T[]> {
+  const byFile = new Map<string, T[]>()
+  for (const item of items) {
+    const uri = 'uri' in item ? item.uri : item.location.uri
+    const filePath = formatUri(uri, cwd)
+    const existingItems = byFile.get(filePath)
+    if (existingItems) {
+      existingItems.push(item)
+    } else {
+      byFile.set(filePath, [item])
+    }
+  }
+  return byFile
+}
+
+/**
+ * Formats a Location with file path and line/character position
+ */
+function formatLocation(location: Location, cwd?: string): string {
+  const filePath = formatUri(location.uri, cwd)
+  const line = location.range.start.line + 1 // Convert to 1-based
+  const character = location.range.start.character + 1 // Convert to 1-based
+  return `${filePath}:${line}:${character}`
+}
+
+/**
+ * Converts LocationLink to Location format for consistent handling
+ */
+function locationLinkToLocation(link: LocationLink): Location {
+  return {
+    uri: link.targetUri,
+    range: link.targetSelectionRange || link.targetRange,
+  }
+}
+
+/**
+ * Checks if an object is a LocationLink (has targetUri) vs Location (has uri)
+ */
+function isLocationLink(item: Location | LocationLink): item is LocationLink {
+  return 'targetUri' in item
+}
+
+/**
+ * Formats goToDefinition result
+ * Can return Location, LocationLink, or arrays of either
+ */
+export function formatGoToDefinitionResult(
+  result: Location | Location[] | LocationLink | LocationLink[] | null,
+  cwd?: string,
+): string {
+  if (!result) {
+    return 'No definition found. This may occur if the cursor is not on a symbol, or if the definition is in an external library not indexed by the LSP server.'
+  }
+
+  if (Array.isArray(result)) {
+    // Convert LocationLinks to Locations for uniform handling
+    const locations: Location[] = result.map(item =>
+      isLocationLink(item) ? locationLinkToLocation(item) : item,
+    )
+
+    // Log and filter out any locations with undefined uris
+    const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+    if (invalidLocations.length > 0) {
+      logForDebugging(
+        `formatGoToDefinitionResult: Filtering out ${invalidLocations.length} invalid location(s) - this should have been caught earlier`,
+        { level: 'warn' },
+      )
+    }
+
+    const validLocations = locations.filter(loc => loc && loc.uri)
+
+    if (validLocations.length === 0) {
+      return 'No definition found. This may occur if the cursor is not on a symbol, or if the definition is in an external library not indexed by the LSP server.'
+    }
+    if (validLocations.length === 1) {
+      return `Defined in ${formatLocation(validLocations[0]!, cwd)}`
+    }
+    const locationList = validLocations
+      .map(loc => `  ${formatLocation(loc, cwd)}`)
+      .join('\n')
+    return `Found ${validLocations.length} definitions:\n${locationList}`
+  }
+
+  // Single result - convert LocationLink if needed
+  const location = isLocationLink(result)
+    ? locationLinkToLocation(result)
+    : result
+  return `Defined in ${formatLocation(location, cwd)}`
+}
+
+/**
+ * Formats findReferences result
+ */
+export function formatFindReferencesResult(
+  result: Location[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No references found. This may occur if the symbol has no usages, or if the LSP server has not fully indexed the workspace.'
+  }
+
+  // Log and filter out any locations with undefined uris
+  const invalidLocations = result.filter(loc => !loc || !loc.uri)
+  if (invalidLocations.length > 0) {
+    logForDebugging(
+      `formatFindReferencesResult: Filtering out ${invalidLocations.length} invalid location(s) - this should have been caught earlier`,
+      { level: 'warn' },
+    )
+  }
+
+  const validLocations = result.filter(loc => loc && loc.uri)
+
+  if (validLocations.length === 0) {
+    return 'No references found. This may occur if the symbol has no usages, or if the LSP server has not fully indexed the workspace.'
+  }
+
+  if (validLocations.length === 1) {
+    return `Found 1 reference:\n  ${formatLocation(validLocations[0]!, cwd)}`
+  }
+
+  // Group references by file
+  const byFile = groupByFile(validLocations, cwd)
+
+  const lines: string[] = [
+    `Found ${validLocations.length} references across ${byFile.size} files:`,
+  ]
+
+  for (const [filePath, locations] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const loc of locations) {
+      const line = loc.range.start.line + 1
+      const character = loc.range.start.character + 1
+      lines.push(`  Line ${line}:${character}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Extracts text content from MarkupContent or MarkedString
+ */
+function extractMarkupText(
+  contents: MarkupContent | MarkedString | MarkedString[],
+): string {
+  if (Array.isArray(contents)) {
+    return contents
+      .map(item => {
+        if (typeof item === 'string') {
+          return item
+        }
+        return item.value
+      })
+      .join('\n\n')
+  }
+
+  if (typeof contents === 'string') {
+    return contents
+  }
+
+  if ('kind' in contents) {
+    // MarkupContent
+    return contents.value
+  }
+
+  // MarkedString object
+  return contents.value
+}
+
+/**
+ * Formats hover result
+ */
+export function formatHoverResult(result: Hover | null, _cwd?: string): string {
+  if (!result) {
+    return 'No hover information available. This may occur if the cursor is not on a symbol, or if the LSP server has not fully indexed the file.'
+  }
+
+  const content = extractMarkupText(result.contents)
+
+  if (result.range) {
+    const line = result.range.start.line + 1
+    const character = result.range.start.character + 1
+    return `Hover info at ${line}:${character}:\n\n${content}`
+  }
+
+  return content
+}
+
+/**
+ * Maps SymbolKind enum to readable string
+ */
+function symbolKindToString(kind: SymbolKind): string {
+  const kinds: Record<SymbolKind, string> = {
+    [1]: 'File',
+    [2]: 'Module',
+    [3]: 'Namespace',
+    [4]: 'Package',
+    [5]: 'Class',
+    [6]: 'Method',
+    [7]: 'Property',
+    [8]: 'Field',
+    [9]: 'Constructor',
+    [10]: 'Enum',
+    [11]: 'Interface',
+    [12]: 'Function',
+    [13]: 'Variable',
+    [14]: 'Constant',
+    [15]: 'String',
+    [16]: 'Number',
+    [17]: 'Boolean',
+    [18]: 'Array',
+    [19]: 'Object',
+    [20]: 'Key',
+    [21]: 'Null',
+    [22]: 'EnumMember',
+    [23]: 'Struct',
+    [24]: 'Event',
+    [25]: 'Operator',
+    [26]: 'TypeParameter',
+  }
+  return kinds[kind] || 'Unknown'
+}
+
+/**
+ * Formats a single DocumentSymbol with indentation
+ */
+function formatDocumentSymbolNode(
+  symbol: DocumentSymbol,
+  indent: number = 0,
+): string[] {
+  const lines: string[] = []
+  const prefix = '  '.repeat(indent)
+  const kind = symbolKindToString(symbol.kind)
+
+  let line = `${prefix}${symbol.name} (${kind})`
+  if (symbol.detail) {
+    line += ` ${symbol.detail}`
+  }
+
+  const symbolLine = symbol.range.start.line + 1
+  line += ` - Line ${symbolLine}`
+
+  lines.push(line)
+
+  // Recursively format children
+  if (symbol.children && symbol.children.length > 0) {
+    for (const child of symbol.children) {
+      lines.push(...formatDocumentSymbolNode(child, indent + 1))
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Formats documentSymbol result (hierarchical outline)
+ * Handles both DocumentSymbol[] (hierarchical, with range) and SymbolInformation[] (flat, with location.range)
+ * per LSP spec which allows textDocument/documentSymbol to return either format
+ */
+export function formatDocumentSymbolResult(
+  result: DocumentSymbol[] | SymbolInformation[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No symbols found in document. This may occur if the file is empty, not supported by the LSP server, or if the server has not fully indexed the file.'
+  }
+
+  // Detect format: DocumentSymbol has 'range' directly, SymbolInformation has 'location.range'
+  // Check the first valid element to determine format
+  const firstSymbol = result[0]
+  const isSymbolInformation = firstSymbol && 'location' in firstSymbol
+
+  if (isSymbolInformation) {
+    // Delegate to workspace symbol formatter which handles SymbolInformation[]
+    return formatWorkspaceSymbolResult(result as SymbolInformation[], cwd)
+  }
+
+  // Handle DocumentSymbol[] format (hierarchical)
+  const lines: string[] = ['Document symbols:']
+
+  for (const symbol of result as DocumentSymbol[]) {
+    lines.push(...formatDocumentSymbolNode(symbol))
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats workspaceSymbol result (flat list of symbols)
+ */
+export function formatWorkspaceSymbolResult(
+  result: SymbolInformation[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No symbols found in workspace. This may occur if the workspace is empty, or if the LSP server has not finished indexing the project.'
+  }
+
+  // Log and filter out any symbols with undefined location.uri
+  const invalidSymbols = result.filter(
+    sym => !sym || !sym.location || !sym.location.uri,
+  )
+  if (invalidSymbols.length > 0) {
+    logForDebugging(
+      `formatWorkspaceSymbolResult: Filtering out ${invalidSymbols.length} invalid symbol(s) - this should have been caught earlier`,
+      { level: 'warn' },
+    )
+  }
+
+  const validSymbols = result.filter(
+    sym => sym && sym.location && sym.location.uri,
+  )
+
+  if (validSymbols.length === 0) {
+    return 'No symbols found in workspace. This may occur if the workspace is empty, or if the LSP server has not finished indexing the project.'
+  }
+
+  const lines: string[] = [
+    `Found ${validSymbols.length} ${plural(validSymbols.length, 'symbol')} in workspace:`,
+  ]
+
+  // Group by file
+  const byFile = groupByFile(validSymbols, cwd)
+
+  for (const [filePath, symbols] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const symbol of symbols) {
+      const kind = symbolKindToString(symbol.kind)
+      const line = symbol.location.range.start.line + 1
+      let symbolLine = `  ${symbol.name} (${kind}) - Line ${line}`
+
+      // Add container name if available
+      if (symbol.containerName) {
+        symbolLine += ` in ${symbol.containerName}`
+      }
+
+      lines.push(symbolLine)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats a CallHierarchyItem with its location
+ * Validates URI before formatting to handle malformed LSP data
+ */
+function formatCallHierarchyItem(
+  item: CallHierarchyItem,
+  cwd?: string,
+): string {
+  // Validate URI - handle undefined/null gracefully
+  if (!item.uri) {
+    logForDebugging(
+      'formatCallHierarchyItem: CallHierarchyItem has undefined URI',
+      { level: 'warn' },
+    )
+    return `${item.name} (${symbolKindToString(item.kind)}) - <unknown location>`
+  }
+
+  const filePath = formatUri(item.uri, cwd)
+  const line = item.range.start.line + 1
+  const kind = symbolKindToString(item.kind)
+  let result = `${item.name} (${kind}) - ${filePath}:${line}`
+  if (item.detail) {
+    result += ` [${item.detail}]`
+  }
+  return result
+}
+
+/**
+ * Formats prepareCallHierarchy result
+ * Returns the call hierarchy item(s) at the given position
+ */
+export function formatPrepareCallHierarchyResult(
+  result: CallHierarchyItem[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No call hierarchy item found at this position'
+  }
+
+  if (result.length === 1) {
+    return `Call hierarchy item: ${formatCallHierarchyItem(result[0]!, cwd)}`
+  }
+
+  const lines = [`Found ${result.length} call hierarchy items:`]
+  for (const item of result) {
+    lines.push(`  ${formatCallHierarchyItem(item, cwd)}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Formats incomingCalls result
+ * Shows all functions/methods that call the target
+ */
+export function formatIncomingCallsResult(
+  result: CallHierarchyIncomingCall[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No incoming calls found (nothing calls this function)'
+  }
+
+  const lines = [
+    `Found ${result.length} incoming ${plural(result.length, 'call')}:`,
+  ]
+
+  // Group by file
+  const byFile = new Map<string, CallHierarchyIncomingCall[]>()
+  for (const call of result) {
+    if (!call.from) {
+      logForDebugging(
+        'formatIncomingCallsResult: CallHierarchyIncomingCall has undefined from field',
+        { level: 'warn' },
+      )
+      continue
+    }
+    const filePath = formatUri(call.from.uri, cwd)
+    const existing = byFile.get(filePath)
+    if (existing) {
+      existing.push(call)
+    } else {
+      byFile.set(filePath, [call])
+    }
+  }
+
+  for (const [filePath, calls] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const call of calls) {
+      if (!call.from) {
+        continue // Already logged above
+      }
+      const kind = symbolKindToString(call.from.kind)
+      const line = call.from.range.start.line + 1
+      let callLine = `  ${call.from.name} (${kind}) - Line ${line}`
+
+      // Show call sites within the caller
+      if (call.fromRanges && call.fromRanges.length > 0) {
+        const callSites = call.fromRanges
+          .map(r => `${r.start.line + 1}:${r.start.character + 1}`)
+          .join(', ')
+        callLine += ` [calls at: ${callSites}]`
+      }
+
+      lines.push(callLine)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats outgoingCalls result
+ * Shows all functions/methods called by the target
+ */
+export function formatOutgoingCallsResult(
+  result: CallHierarchyOutgoingCall[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No outgoing calls found (this function calls nothing)'
+  }
+
+  const lines = [
+    `Found ${result.length} outgoing ${plural(result.length, 'call')}:`,
+  ]
+
+  // Group by file
+  const byFile = new Map<string, CallHierarchyOutgoingCall[]>()
+  for (const call of result) {
+    if (!call.to) {
+      logForDebugging(
+        'formatOutgoingCallsResult: CallHierarchyOutgoingCall has undefined to field',
+        { level: 'warn' },
+      )
+      continue
+    }
+    const filePath = formatUri(call.to.uri, cwd)
+    const existing = byFile.get(filePath)
+    if (existing) {
+      existing.push(call)
+    } else {
+      byFile.set(filePath, [call])
+    }
+  }
+
+  for (const [filePath, calls] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const call of calls) {
+      if (!call.to) {
+        continue // Already logged above
+      }
+      const kind = symbolKindToString(call.to.kind)
+      const line = call.to.range.start.line + 1
+      let callLine = `  ${call.to.name} (${kind}) - Line ${line}`
+
+      // Show call sites within the current function
+      if (call.fromRanges && call.fromRanges.length > 0) {
+        const callSites = call.fromRanges
+          .map(r => `${r.start.line + 1}:${r.start.character + 1}`)
+          .join(', ')
+        callLine += ` [called from: ${callSites}]`
+      }
+
+      lines.push(callLine)
+    }
+  }
+
+  return lines.join('\n')
+}

src/tools/LSPTool/prompt.ts

@@ -0,0 +1,21 @@
+export const LSP_TOOL_NAME = 'LSP' as const
+
+export const DESCRIPTION = `Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+Supported operations:
+- goToDefinition: Find where a symbol is defined
+- findReferences: Find all references to a symbol
+- hover: Get hover information (documentation, type info) for a symbol
+- documentSymbol: Get all symbols (functions, classes, variables) in a document
+- workspaceSymbol: Search for symbols across the entire workspace
+- goToImplementation: Find implementations of an interface or abstract method
+- prepareCallHierarchy: Get call hierarchy item at a position (functions/methods)
+- incomingCalls: Find all functions/methods that call the function at a position
+- outgoingCalls: Find all functions/methods called by the function at a position
+
+All operations require:
+- filePath: The file to operate on
+- line: The line number (1-based, as shown in editors)
+- character: The character offset (1-based, as shown in editors)
+
+Note: LSP servers must be configured for the file type. If no server is available, an error will be returned.`

src/tools/LSPTool/schemas.ts

@@ -0,0 +1,215 @@
+import { z } from 'zod/v4'
+import { lazySchema } from '../../utils/lazySchema.js'
+
+/**
+ * Discriminated union of all LSP operations
+ * Uses 'operation' as the discriminator field
+ */
+export const lspToolInputSchema = lazySchema(() => {
+  /**
+   * Go to Definition operation
+   * Finds the definition location of a symbol at the given position
+   */
+  const goToDefinitionSchema = z.strictObject({
+    operation: z.literal('goToDefinition'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Find References operation
+   * Finds all references to a symbol at the given position
+   */
+  const findReferencesSchema = z.strictObject({
+    operation: z.literal('findReferences'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Hover operation
+   * Gets hover information (documentation, type info) for a symbol at the given position
+   */
+  const hoverSchema = z.strictObject({
+    operation: z.literal('hover'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Document Symbol operation
+   * Gets all symbols (functions, classes, variables) in a document
+   */
+  const documentSymbolSchema = z.strictObject({
+    operation: z.literal('documentSymbol'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Workspace Symbol operation
+   * Searches for symbols across the entire workspace
+   */
+  const workspaceSymbolSchema = z.strictObject({
+    operation: z.literal('workspaceSymbol'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Go to Implementation operation
+   * Finds the implementation locations of an interface or abstract method
+   */
+  const goToImplementationSchema = z.strictObject({
+    operation: z.literal('goToImplementation'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Prepare Call Hierarchy operation
+   * Prepares a call hierarchy item at the given position (first step for call hierarchy)
+   */
+  const prepareCallHierarchySchema = z.strictObject({
+    operation: z.literal('prepareCallHierarchy'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Incoming Calls operation
+   * Finds all functions/methods that call the function at the given position
+   */
+  const incomingCallsSchema = z.strictObject({
+    operation: z.literal('incomingCalls'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Outgoing Calls operation
+   * Finds all functions/methods called by the function at the given position
+   */
+  const outgoingCallsSchema = z.strictObject({
+    operation: z.literal('outgoingCalls'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  return z.discriminatedUnion('operation', [
+    goToDefinitionSchema,
+    findReferencesSchema,
+    hoverSchema,
+    documentSymbolSchema,
+    workspaceSymbolSchema,
+    goToImplementationSchema,
+    prepareCallHierarchySchema,
+    incomingCallsSchema,
+    outgoingCallsSchema,
+  ])
+})
+
+/**
+ * TypeScript type for LSPTool input
+ */
+export type LSPToolInput = z.infer<ReturnType<typeof lspToolInputSchema>>
+
+/**
+ * Type guard to check if an operation is a valid LSP operation
+ */
+export function isValidLSPOperation(
+  operation: string,
+): operation is LSPToolInput['operation'] {
+  return [
+    'goToDefinition',
+    'findReferences',
+    'hover',
+    'documentSymbol',
+    'workspaceSymbol',
+    'goToImplementation',
+    'prepareCallHierarchy',
+    'incomingCalls',
+    'outgoingCalls',
+  ].includes(operation)
+}

src/tools/LSPTool/symbolContext.ts

@@ -0,0 +1,90 @@
+import { logForDebugging } from '../../utils/debug.js'
+import { truncate } from '../../utils/format.js'
+import { getFsImplementation } from '../../utils/fsOperations.js'
+import { expandPath } from '../../utils/path.js'
+
+const MAX_READ_BYTES = 64 * 1024
+
+/**
+ * Extracts the symbol/word at a specific position in a file.
+ * Used to show context in tool use messages.
+ *
+ * @param filePath - The file path (absolute or relative)
+ * @param line - 0-indexed line number
+ * @param character - 0-indexed character position on the line
+ *
+ * Note: This uses synchronous file I/O because it is called from
+ * renderToolUseMessage (a synchronous React render function). The read is
+ * wrapped in try/catch so ENOENT and other errors fall back gracefully.
+ * @returns The symbol at that position, or null if extraction fails
+ */
+export function getSymbolAtPosition(
+  filePath: string,
+  line: number,
+  character: number,
+): string | null {
+  try {
+    const fs = getFsImplementation()
+    const absolutePath = expandPath(filePath)
+
+    // Read only the first 64KB instead of the whole file. Most LSP hover/goto
+    // targets are near recent edits; 64KB covers ~1000 lines of typical code.
+    // If the target line is past this window we fall back to null (the UI
+    // already handles that by showing `position: line:char`).
+    // eslint-disable-next-line custom-rules/no-sync-fs -- called from sync React render (renderToolUseMessage)
+    const { buffer, bytesRead } = fs.readSync(absolutePath, {
+      length: MAX_READ_BYTES,
+    })
+    const content = buffer.toString('utf-8', 0, bytesRead)
+    const lines = content.split('\n')
+
+    if (line < 0 || line >= lines.length) {
+      return null
+    }
+    // If we filled the full buffer the file continues past our window,
+    // so the last split element may be truncated mid-line.
+    if (bytesRead === MAX_READ_BYTES && line === lines.length - 1) {
+      return null
+    }
+
+    const lineContent = lines[line]
+    if (!lineContent || character < 0 || character >= lineContent.length) {
+      return null
+    }
+
+    // Extract the word/symbol at the character position
+    // Pattern matches:
+    // - Standard identifiers: alphanumeric + underscore + dollar
+    // - Rust lifetimes: 'a, 'static
+    // - Rust macros: macro_name!
+    // - Operators and special symbols: +, -, *, etc.
+    // This is more inclusive to handle various programming languages
+    const symbolPattern = /[\w$'!]+|[+\-*/%&|^~<>=]+/g
+    let match: RegExpExecArray | null
+
+    while ((match = symbolPattern.exec(lineContent)) !== null) {
+      const start = match.index
+      const end = start + match[0].length
+
+      // Check if the character position falls within this match
+      if (character >= start && character < end) {
+        const symbol = match[0]
+        // Limit length to 30 characters to avoid overly long symbols
+        return truncate(symbol, 30)
+      }
+    }
+
+    return null
+  } catch (error) {
+    // Log unexpected errors for debugging (permission issues, encoding problems, etc.)
+    // Use logForDebugging since this is a display enhancement, not a critical error
+    if (error instanceof Error) {
+      logForDebugging(
+        `Symbol extraction failed for ${filePath}:${line}:${character}: ${error.message}`,
+        { level: 'warn' },
+      )
+    }
+    // Still return null for graceful fallback to position display
+    return null
+  }
+}

src/tools/ListMcpResourcesTool/ListMcpResourcesTool.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod/v4'
+import {
+  ensureConnectedClient,
+  fetchResourcesForClient,
+} from '../../services/mcp/client.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { errorMessage } from '../../utils/errors.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logMCPError } from '../../utils/log.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { isOutputLineTruncated } from '../../utils/terminal.js'
+import { DESCRIPTION, LIST_MCP_RESOURCES_TOOL_NAME, PROMPT } from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.object({
+    server: z
+      .string()
+      .optional()
+      .describe('Optional server name to filter resources by'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.array(
+    z.object({
+      uri: z.string().describe('Resource URI'),
+      name: z.string().describe('Resource name'),
+      mimeType: z.string().optional().describe('MIME type of the resource'),
+      description: z.string().optional().describe('Resource description'),
+      server: z.string().describe('Server that provides this resource'),
+    }),
+  ),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const ListMcpResourcesTool = buildTool({
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.server ?? ''
+  },
+  shouldDefer: true,
+  name: LIST_MCP_RESOURCES_TOOL_NAME,
+  searchHint: 'list resources from connected MCP servers',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return PROMPT
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  async call(input, { options: { mcpClients } }) {
+    const { server: targetServer } = input
+
+    const clientsToProcess = targetServer
+      ? mcpClients.filter(client => client.name === targetServer)
+      : mcpClients
+
+    if (targetServer && clientsToProcess.length === 0) {
+      throw new Error(
+        `Server "${targetServer}" not found. Available servers: ${mcpClients.map(c => c.name).join(', ')}`,
+      )
+    }
+
+    // fetchResourcesForClient is LRU-cached (by server name) and already
+    // warm from startup prefetch. Cache is invalidated on onclose and on
+    // resources/list_changed notifications, so results are never stale.
+    // ensureConnectedClient is a no-op when healthy (memoize hit), but after
+    // onclose it returns a fresh connection so the re-fetch succeeds.
+    const results = await Promise.all(
+      clientsToProcess.map(async client => {
+        if (client.type !== 'connected') return []
+        try {
+          const fresh = await ensureConnectedClient(client)
+          return await fetchResourcesForClient(fresh)
+        } catch (error) {
+          // One server's reconnect failure shouldn't sink the whole result.
+          logMCPError(client.name, errorMessage(error))
+          return []
+        }
+      }),
+    )
+
+    return {
+      data: results.flat(),
+    }
+  },
+  renderToolUseMessage,
+  userFacingName: () => 'listMcpResources',
+  renderToolResultMessage,
+  isResultTruncated(output: Output): boolean {
+    return isOutputLineTruncated(jsonStringify(output))
+  },
+  mapToolResultToToolResultBlockParam(content, toolUseID) {
+    if (!content || content.length === 0) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content:
+          'No resources found. MCP servers may still provide tools even if they have no resources.',
+      }
+    }
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: jsonStringify(content),
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/ListMcpResourcesTool/UI.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { MessageResponse } from '../../components/MessageResponse.js';
+import { OutputLine } from '../../components/shell/OutputLine.js';
+import { Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+import type { Output } from './ListMcpResourcesTool.js';
+export function renderToolUseMessage(input: Partial<{
+  server?: string;
+}>): React.ReactNode {
+  return input.server ? `List MCP resources from server "${input.server}"` : `List all MCP resources`;
+}
+export function renderToolResultMessage(output: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], {
+  verbose
+}: {
+  verbose: boolean;
+}): React.ReactNode {
+  if (!output || output.length === 0) {
+    return <MessageResponse height={1}>
+        <Text dimColor>(No resources found)</Text>
+      </MessageResponse>;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- human-facing UI, not tool_result
+  const formattedOutput = jsonStringify(output, null, 2);
+  return <OutputLine content={formattedOutput} verbose={verbose} />;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIk1lc3NhZ2VSZXNwb25zZSIsIk91dHB1dExpbmUiLCJUZXh0IiwiVG9vbFByb2dyZXNzRGF0YSIsIlByb2dyZXNzTWVzc2FnZSIsImpzb25TdHJpbmdpZnkiLCJPdXRwdXQiLCJyZW5kZXJUb29sVXNlTWVzc2FnZSIsImlucHV0IiwiUGFydGlhbCIsInNlcnZlciIsIlJlYWN0Tm9kZSIsInJlbmRlclRvb2xSZXN1bHRNZXNzYWdlIiwib3V0cHV0IiwiX3Byb2dyZXNzTWVzc2FnZXNGb3JNZXNzYWdlIiwidmVyYm9zZSIsImxlbmd0aCIsImZvcm1hdHRlZE91dHB1dCJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgKiBhcyBSZWFjdCBmcm9tICdyZWFjdCdcbmltcG9ydCB7IE1lc3NhZ2VSZXNwb25zZSB9IGZyb20gJy4uLy4uL2NvbXBvbmVudHMvTWVzc2FnZVJlc3BvbnNlLmpzJ1xuaW1wb3J0IHsgT3V0cHV0TGluZSB9IGZyb20gJy4uLy4uL2NvbXBvbmVudHMvc2hlbGwvT3V0cHV0TGluZS5qcydcbmltcG9ydCB7IFRleHQgfSBmcm9tICcuLi8uLi9pbmsuanMnXG5pbXBvcnQgdHlwZSB7IFRvb2xQcm9ncmVzc0RhdGEgfSBmcm9tICcuLi8uLi9Ub29sLmpzJ1xuaW1wb3J0IHR5cGUgeyBQcm9ncmVzc01lc3NhZ2UgfSBmcm9tICcuLi8uLi90eXBlcy9tZXNzYWdlLmpzJ1xuaW1wb3J0IHsganNvblN0cmluZ2lmeSB9IGZyb20gJy4uLy4uL3V0aWxzL3Nsb3dPcGVyYXRpb25zLmpzJ1xuaW1wb3J0IHR5cGUgeyBPdXRwdXQgfSBmcm9tICcuL0xpc3RNY3BSZXNvdXJjZXNUb29sLmpzJ1xuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZU1lc3NhZ2UoXG4gIGlucHV0OiBQYXJ0aWFsPHsgc2VydmVyPzogc3RyaW5nIH0+LFxuKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuIGlucHV0LnNlcnZlclxuICAgID8gYExpc3QgTUNQIHJlc291cmNlcyBmcm9tIHNlcnZlciBcIiR7aW5wdXQuc2VydmVyfVwiYFxuICAgIDogYExpc3QgYWxsIE1DUCByZXNvdXJjZXNgXG59XG5cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJUb29sUmVzdWx0TWVzc2FnZShcbiAgb3V0cHV0OiBPdXRwdXQsXG4gIF9wcm9ncmVzc01lc3NhZ2VzRm9yTWVzc2FnZTogUHJvZ3Jlc3NNZXNzYWdlPFRvb2xQcm9ncmVzc0RhdGE+W10sXG4gIHsgdmVyYm9zZSB9OiB7IHZlcmJvc2U6IGJvb2xlYW4gfSxcbik6IFJlYWN0LlJlYWN0Tm9kZSB7XG4gIGlmICghb3V0cHV0IHx8IG91dHB1dC5sZW5ndGggPT09IDApIHtcbiAgICByZXR1cm4gKFxuICAgICAgPE1lc3NhZ2VSZXNwb25zZSBoZWlnaHQ9ezF9PlxuICAgICAgICA8VGV4dCBkaW1Db2xvcj4oTm8gcmVzb3VyY2VzIGZvdW5kKTwvVGV4dD5cbiAgICAgIDwvTWVzc2FnZVJlc3BvbnNlPlxuICAgIClcbiAgfVxuXG4gIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1yZXN0cmljdGVkLXN5bnRheCAtLSBodW1hbi1mYWNpbmcgVUksIG5vdCB0b29sX3Jlc3VsdFxuICBjb25zdCBmb3JtYXR0ZWRPdXRwdXQgPSBqc29uU3RyaW5naWZ5KG91dHB1dCwgbnVsbCwgMilcblxuICByZXR1cm4gPE91dHB1dExpbmUgY29udGVudD17Zm9ybWF0dGVkT3V0cHV0fSB2ZXJib3NlPXt2ZXJib3NlfSAvPlxufVxuIl0sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUtBLEtBQUssTUFBTSxPQUFPO0FBQzlCLFNBQVNDLGVBQWUsUUFBUSxxQ0FBcUM7QUFDckUsU0FBU0MsVUFBVSxRQUFRLHNDQUFzQztBQUNqRSxTQUFTQyxJQUFJLFFBQVEsY0FBYztBQUNuQyxjQUFjQyxnQkFBZ0IsUUFBUSxlQUFlO0FBQ3JELGNBQWNDLGVBQWUsUUFBUSx3QkFBd0I7QUFDN0QsU0FBU0MsYUFBYSxRQUFRLCtCQUErQjtBQUM3RCxjQUFjQyxNQUFNLFFBQVEsMkJBQTJCO0FBRXZELE9BQU8sU0FBU0Msb0JBQW9CQSxDQUNsQ0MsS0FBSyxFQUFFQyxPQUFPLENBQUM7RUFBRUMsTUFBTSxDQUFDLEVBQUUsTUFBTTtBQUFDLENBQUMsQ0FBQyxDQUNwQyxFQUFFWCxLQUFLLENBQUNZLFNBQVMsQ0FBQztFQUNqQixPQUFPSCxLQUFLLENBQUNFLE1BQU0sR0FDZixtQ0FBbUNGLEtBQUssQ0FBQ0UsTUFBTSxHQUFHLEdBQ2xELHdCQUF3QjtBQUM5QjtBQUVBLE9BQU8sU0FBU0UsdUJBQXVCQSxDQUNyQ0MsTUFBTSxFQUFFUCxNQUFNLEVBQ2RRLDJCQUEyQixFQUFFVixlQUFlLENBQUNELGdCQUFnQixDQUFDLEVBQUUsRUFDaEU7RUFBRVk7QUFBOEIsQ0FBckIsRUFBRTtFQUFFQSxPQUFPLEVBQUUsT0FBTztBQUFDLENBQUMsQ0FDbEMsRUFBRWhCLEtBQUssQ0FBQ1ksU0FBUyxDQUFDO0VBQ2pCLElBQUksQ0FBQ0UsTUFBTSxJQUFJQSxNQUFNLENBQUNHLE1BQU0sS0FBSyxDQUFDLEVBQUU7SUFDbEMsT0FDRSxDQUFDLGVBQWUsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDakMsUUFBUSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsb0JBQW9CLEVBQUUsSUFBSTtBQUNqRCxNQUFNLEVBQUUsZUFBZSxDQUFDO0VBRXRCOztFQUVBO0VBQ0EsTUFBTUMsZUFBZSxHQUFHWixhQUFhLENBQUNRLE1BQU0sRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO0VBRXRELE9BQU8sQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDLENBQUNJLGVBQWUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxDQUFDRixPQUFPLENBQUMsR0FBRztBQUNuRSIsImlnbm9yZUxpc3QiOltdfQ==

src/tools/ListMcpResourcesTool/prompt.ts

@@ -0,0 +1,20 @@
+export const LIST_MCP_RESOURCES_TOOL_NAME = 'ListMcpResourcesTool'
+
+export const DESCRIPTION = `
+Lists available resources from configured MCP servers.
+Each resource object includes a 'server' field indicating which server it's from.
+
+Usage examples:
+- List all resources from all servers: \`listMcpResources\`
+- List resources from a specific server: \`listMcpResources({ server: "myserver" })\`
+`
+
+export const PROMPT = `
+List available resources from configured MCP servers.
+Each returned resource will include all standard MCP resource fields plus a 'server' field 
+indicating which server the resource belongs to.
+
+Parameters:
+- server (optional): The name of a specific MCP server to get resources from. If not provided,
+  resources from all servers will be returned.
+`

src/tools/MCPTool/MCPTool.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+import { isOutputLineTruncated } from '../../utils/terminal.js'
+import { DESCRIPTION, PROMPT } from './prompt.js'
+import {
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseProgressMessage,
+} from './UI.js'
+
+// Allow any input object since MCP tools define their own schemas
+export const inputSchema = lazySchema(() => z.object({}).passthrough())
+type InputSchema = ReturnType<typeof inputSchema>
+
+export const outputSchema = lazySchema(() =>
+  z.string().describe('MCP tool execution result'),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+// Re-export MCPProgress from centralized types to break import cycles
+export type { MCPProgress } from '../../types/tools.js'
+
+export const MCPTool = buildTool({
+  isMcp: true,
+  // Overridden in mcpClient.ts with the real MCP tool name + args
+  isOpenWorld() {
+    return false
+  },
+  // Overridden in mcpClient.ts
+  name: 'mcp',
+  maxResultSizeChars: 100_000,
+  // Overridden in mcpClient.ts
+  async description() {
+    return DESCRIPTION
+  },
+  // Overridden in mcpClient.ts
+  async prompt() {
+    return PROMPT
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  // Overridden in mcpClient.ts
+  async call() {
+    return {
+      data: '',
+    }
+  },
+  async checkPermissions(): Promise<PermissionResult> {
+    return {
+      behavior: 'passthrough',
+      message: 'MCPTool requires permission.',
+    }
+  },
+  renderToolUseMessage,
+  // Overridden in mcpClient.ts
+  userFacingName: () => 'mcp',
+  renderToolUseProgressMessage,
+  renderToolResultMessage,
+  isResultTruncated(output: Output): boolean {
+    return isOutputLineTruncated(output)
+  },
+  mapToolResultToToolResultBlockParam(content, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/MCPTool/classifyForCollapse.ts

@@ -0,0 +1,604 @@
+/**
+ * Classify an MCP tool as a search/read operation for UI collapsing.
+ * Returns { isSearch: false, isRead: false } for tools that should not
+ * collapse (e.g., send_message, create_*, update_*).
+ *
+ * Uses explicit per-tool allowlists for the most common MCP servers.
+ * Tool names are stable across installs (even when the server name varies,
+ * e.g., "slack" vs "claude_ai_Slack"), so matching is keyed on the tool
+ * name alone after normalizing camelCase/kebab-case to snake_case.
+ * Unknown tool names don't collapse (conservative).
+ */
+
+// prettier-ignore
+const SEARCH_TOOLS = new Set([
+  // Slack (hosted + @modelcontextprotocol/server-slack)
+  'slack_search_public',
+  'slack_search_public_and_private',
+  'slack_search_channels',
+  'slack_search_users',
+  // GitHub (github/github-mcp-server)
+  'search_code',
+  'search_repositories',
+  'search_issues',
+  'search_pull_requests',
+  'search_orgs',
+  'search_users',
+  // Linear (mcp.linear.app)
+  'search_documentation',
+  // Datadog (mcp.datadoghq.com)
+  'search_logs',
+  'search_spans',
+  'search_rum_events',
+  'search_audit_logs',
+  'search_monitors',
+  'search_monitor_groups',
+  'find_slow_spans',
+  'find_monitors_matching_pattern',
+  // Sentry (getsentry/sentry-mcp)
+  'search_docs',
+  'search_events',
+  'search_issue_events',
+  'find_organizations',
+  'find_teams',
+  'find_projects',
+  'find_releases',
+  'find_dsns',
+  // Notion (mcp.notion.com — kebab-case, normalized)
+  'search',
+  // Gmail (claude.ai hosted)
+  'gmail_search_messages',
+  // Google Drive (claude.ai hosted + @modelcontextprotocol/server-gdrive)
+  'google_drive_search',
+  // Google Calendar (claude.ai hosted)
+  'gcal_find_my_free_time',
+  'gcal_find_meeting_times',
+  'gcal_find_user_emails',
+  // Atlassian/Jira (mcp.atlassian.com — camelCase, normalized)
+  'search_jira_issues_using_jql',
+  'search_confluence_using_cql',
+  'lookup_jira_account_id',
+  // Community Atlassian (sooperset/mcp-atlassian)
+  'confluence_search',
+  'jira_search',
+  'jira_search_fields',
+  // Asana (mcp.asana.com)
+  'asana_search_tasks',
+  'asana_typeahead_search',
+  // Filesystem (@modelcontextprotocol/server-filesystem)
+  'search_files',
+  // Memory (@modelcontextprotocol/server-memory)
+  'search_nodes',
+  // Brave Search
+  'brave_web_search',
+  'brave_local_search',
+  // Git (mcp-server-git)
+  // (git has no search verbs)
+  // Grafana (grafana/mcp-grafana)
+  'search_dashboards',
+  'search_folders',
+  // PagerDuty
+  // (pagerduty reads all use get_/list_, no search verbs)
+  // Supabase
+  'search_docs',
+  // Stripe
+  'search_stripe_resources',
+  'search_stripe_documentation',
+  // PubMed (claude.ai hosted + community)
+  'search_articles',
+  'find_related_articles',
+  'lookup_article_by_citation',
+  'search_papers',
+  'search_pubmed',
+  'search_pubmed_key_words',
+  'search_pubmed_advanced',
+  'pubmed_search',
+  'pubmed_mesh_lookup',
+  // Firecrawl
+  'firecrawl_search',
+  // Exa
+  'web_search_exa',
+  'web_search_advanced_exa',
+  'people_search_exa',
+  'linkedin_search_exa',
+  'deep_search_exa',
+  // Perplexity
+  'perplexity_search',
+  'perplexity_search_web',
+  // Tavily
+  'tavily_search',
+  // Obsidian (MarkusPfundstein)
+  'obsidian_simple_search',
+  'obsidian_complex_search',
+  // MongoDB
+  'find',
+  'search_knowledge',
+  // Neo4j
+  'search_memories',
+  'find_memories_by_name',
+  // Airtable
+  'search_records',
+  // Todoist (Doist — kebab-case, normalized)
+  'find_tasks',
+  'find_tasks_by_date',
+  'find_completed_tasks',
+  'find_projects',
+  'find_sections',
+  'find_comments',
+  'find_project_collaborators',
+  'find_activity',
+  'find_labels',
+  'find_filters',
+  // AWS
+  'search_documentation',
+  'search_catalog',
+  // Terraform
+  'search_modules',
+  'search_providers',
+  'search_policies',
+])
+
+// prettier-ignore
+const READ_TOOLS = new Set([
+  // Slack (hosted + @modelcontextprotocol/server-slack)
+  'slack_read_channel',
+  'slack_read_thread',
+  'slack_read_canvas',
+  'slack_read_user_profile',
+  'slack_list_channels',
+  'slack_get_channel_history',
+  'slack_get_thread_replies',
+  'slack_get_users',
+  'slack_get_user_profile',
+  // GitHub (github/github-mcp-server)
+  'get_me',
+  'get_team_members',
+  'get_teams',
+  'get_commit',
+  'get_file_contents',
+  'get_repository_tree',
+  'list_branches',
+  'list_commits',
+  'list_releases',
+  'list_tags',
+  'get_latest_release',
+  'get_release_by_tag',
+  'get_tag',
+  'list_issues',
+  'issue_read',
+  'list_issue_types',
+  'get_label',
+  'list_label',
+  'pull_request_read',
+  'get_gist',
+  'list_gists',
+  'list_notifications',
+  'get_notification_details',
+  'projects_list',
+  'projects_get',
+  'actions_get',
+  'actions_list',
+  'get_job_logs',
+  'get_code_scanning_alert',
+  'list_code_scanning_alerts',
+  'get_dependabot_alert',
+  'list_dependabot_alerts',
+  'get_secret_scanning_alert',
+  'list_secret_scanning_alerts',
+  'get_global_security_advisory',
+  'list_global_security_advisories',
+  'list_org_repository_security_advisories',
+  'list_repository_security_advisories',
+  'get_discussion',
+  'get_discussion_comments',
+  'list_discussion_categories',
+  'list_discussions',
+  'list_starred_repositories',
+  'get_issue',
+  'get_pull_request',
+  'list_pull_requests',
+  'get_pull_request_files',
+  'get_pull_request_status',
+  'get_pull_request_comments',
+  'get_pull_request_reviews',
+  // Linear (mcp.linear.app)
+  'list_comments',
+  'list_cycles',
+  'get_document',
+  'list_documents',
+  'list_issue_statuses',
+  'get_issue_status',
+  'list_my_issues',
+  'list_issue_labels',
+  'list_projects',
+  'get_project',
+  'list_project_labels',
+  'list_teams',
+  'get_team',
+  'list_users',
+  'get_user',
+  // Datadog (mcp.datadoghq.com)
+  'aggregate_logs',
+  'list_spans',
+  'aggregate_spans',
+  'analyze_trace',
+  'trace_critical_path',
+  'query_metrics',
+  'aggregate_rum_events',
+  'list_rum_metrics',
+  'get_rum_metric',
+  'list_monitors',
+  'get_monitor',
+  'check_can_delete_monitor',
+  'validate_monitor',
+  'validate_existing_monitor',
+  'list_dashboards',
+  'get_dashboard',
+  'query_dashboard_widget',
+  'list_notebooks',
+  'get_notebook',
+  'query_notebook_cell',
+  'get_profiling_metrics',
+  'compare_profiling_metrics',
+  // Sentry (getsentry/sentry-mcp)
+  'whoami',
+  'get_issue_details',
+  'get_issue_tag_values',
+  'get_trace_details',
+  'get_event_attachment',
+  'get_doc',
+  'get_sentry_resource',
+  'list_events',
+  'list_issue_events',
+  'get_sentry_issue',
+  // Notion (mcp.notion.com — kebab-case, normalized)
+  'fetch',
+  'get_comments',
+  'get_users',
+  'get_self',
+  // Gmail (claude.ai hosted)
+  'gmail_get_profile',
+  'gmail_read_message',
+  'gmail_read_thread',
+  'gmail_list_drafts',
+  'gmail_list_labels',
+  // Google Drive (claude.ai hosted + @modelcontextprotocol/server-gdrive)
+  'google_drive_fetch',
+  'google_drive_export',
+  // Google Calendar (claude.ai hosted)
+  'gcal_list_calendars',
+  'gcal_list_events',
+  'gcal_get_event',
+  // Atlassian/Jira (mcp.atlassian.com — camelCase, normalized)
+  'atlassian_user_info',
+  'get_accessible_atlassian_resources',
+  'get_visible_jira_projects',
+  'get_jira_project_issue_types_metadata',
+  'get_jira_issue',
+  'get_transitions_for_jira_issue',
+  'get_jira_issue_remote_issue_links',
+  'get_confluence_spaces',
+  'get_confluence_page',
+  'get_pages_in_confluence_space',
+  'get_confluence_page_ancestors',
+  'get_confluence_page_descendants',
+  'get_confluence_page_footer_comments',
+  'get_confluence_page_inline_comments',
+  // Community Atlassian (sooperset/mcp-atlassian)
+  'confluence_get_page',
+  'confluence_get_page_children',
+  'confluence_get_comments',
+  'confluence_get_labels',
+  'jira_get_issue',
+  'jira_get_transitions',
+  'jira_get_worklog',
+  'jira_get_agile_boards',
+  'jira_get_board_issues',
+  'jira_get_sprints_from_board',
+  'jira_get_sprint_issues',
+  'jira_get_link_types',
+  'jira_download_attachments',
+  'jira_batch_get_changelogs',
+  'jira_get_user_profile',
+  'jira_get_project_issues',
+  'jira_get_project_versions',
+  // Asana (mcp.asana.com)
+  'asana_get_attachment',
+  'asana_get_attachments_for_object',
+  'asana_get_goal',
+  'asana_get_goals',
+  'asana_get_parent_goals_for_goal',
+  'asana_get_portfolio',
+  'asana_get_portfolios',
+  'asana_get_items_for_portfolio',
+  'asana_get_project',
+  'asana_get_projects',
+  'asana_get_project_sections',
+  'asana_get_project_status',
+  'asana_get_project_statuses',
+  'asana_get_project_task_counts',
+  'asana_get_projects_for_team',
+  'asana_get_projects_for_workspace',
+  'asana_get_task',
+  'asana_get_tasks',
+  'asana_get_stories_for_task',
+  'asana_get_teams_for_workspace',
+  'asana_get_teams_for_user',
+  'asana_get_team_users',
+  'asana_get_time_period',
+  'asana_get_time_periods',
+  'asana_get_user',
+  'asana_get_workspace_users',
+  'asana_list_workspaces',
+  // Filesystem (@modelcontextprotocol/server-filesystem)
+  'read_file',
+  'read_text_file',
+  'read_media_file',
+  'read_multiple_files',
+  'list_directory',
+  'list_directory_with_sizes',
+  'directory_tree',
+  'get_file_info',
+  'list_allowed_directories',
+  // Memory (@modelcontextprotocol/server-memory)
+  'read_graph',
+  'open_nodes',
+  // Postgres (@modelcontextprotocol/server-postgres)
+  'query',
+  // SQLite (@modelcontextprotocol/server-sqlite)
+  'read_query',
+  'list_tables',
+  'describe_table',
+  // Git (mcp-server-git)
+  'git_status',
+  'git_diff',
+  'git_diff_unstaged',
+  'git_diff_staged',
+  'git_log',
+  'git_show',
+  'git_branch',
+  // Grafana (grafana/mcp-grafana)
+  'list_teams',
+  'list_users_by_org',
+  'get_dashboard_by_uid',
+  'get_dashboard_summary',
+  'get_dashboard_property',
+  'get_dashboard_panel_queries',
+  'run_panel_query',
+  'list_datasources',
+  'get_datasource',
+  'get_query_examples',
+  'query_prometheus',
+  'query_prometheus_histogram',
+  'list_prometheus_metric_metadata',
+  'list_prometheus_metric_names',
+  'list_prometheus_label_names',
+  'list_prometheus_label_values',
+  'query_loki_logs',
+  'query_loki_stats',
+  'query_loki_patterns',
+  'list_loki_label_names',
+  'list_loki_label_values',
+  'list_incidents',
+  'get_incident',
+  'list_sift_investigations',
+  'get_sift_investigation',
+  'get_sift_analysis',
+  'list_oncall_schedules',
+  'get_oncall_shift',
+  'get_current_oncall_users',
+  'list_oncall_teams',
+  'list_oncall_users',
+  'list_alert_groups',
+  'get_alert_group',
+  'get_annotations',
+  'get_annotation_tags',
+  'get_panel_image',
+  // PagerDuty (PagerDuty/pagerduty-mcp-server)
+  'list_incidents',
+  'get_incident',
+  'get_outlier_incident',
+  'get_past_incidents',
+  'get_related_incidents',
+  'list_incident_notes',
+  'list_incident_workflows',
+  'get_incident_workflow',
+  'list_services',
+  'get_service',
+  'list_team_members',
+  'get_user_data',
+  'list_schedules',
+  'get_schedule',
+  'list_schedule_users',
+  'list_oncalls',
+  'list_log_entries',
+  'get_log_entry',
+  'list_escalation_policies',
+  'get_escalation_policy',
+  'list_event_orchestrations',
+  'get_event_orchestration',
+  'list_status_pages',
+  'get_status_page_post',
+  'list_alerts_from_incident',
+  'get_alert_from_incident',
+  'list_change_events',
+  'get_change_event',
+  // Supabase (supabase-community/supabase-mcp)
+  'list_organizations',
+  'get_organization',
+  'get_cost',
+  'list_extensions',
+  'list_migrations',
+  'get_logs',
+  'get_advisors',
+  'get_project_url',
+  'get_publishable_keys',
+  'generate_typescript_types',
+  'list_edge_functions',
+  'get_edge_function',
+  'list_storage_buckets',
+  'get_storage_config',
+  // Stripe (stripe/agent-toolkit)
+  'get_stripe_account_info',
+  'retrieve_balance',
+  'list_customers',
+  'list_products',
+  'list_prices',
+  'list_invoices',
+  'list_payment_intents',
+  'list_subscriptions',
+  'list_coupons',
+  'list_disputes',
+  'fetch_stripe_resources',
+  // PubMed (claude.ai hosted + community)
+  'get_article_metadata',
+  'get_full_text_article',
+  'convert_article_ids',
+  'get_copyright_status',
+  'download_paper',
+  'list_papers',
+  'read_paper',
+  'get_paper_fulltext',
+  'get_pubmed_article_metadata',
+  'download_pubmed_pdf',
+  'pubmed_fetch',
+  'pubmed_pmc_fetch',
+  'pubmed_spell',
+  'pubmed_cite',
+  'pubmed_related',
+  // BigQuery (claude.ai hosted + community)
+  'bigquery_query',
+  'bigquery_schema',
+  'list_dataset_ids',
+  'list_table_ids',
+  'get_dataset_info',
+  'get_table_info',
+  // Firecrawl
+  'firecrawl_scrape',
+  'firecrawl_map',
+  'firecrawl_crawl',
+  'firecrawl_check_crawl_status',
+  'firecrawl_extract',
+  // Exa
+  'get_code_context_exa',
+  'company_research_exa',
+  'crawling_exa',
+  'deep_researcher_check',
+  // Perplexity
+  'perplexity_ask',
+  'perplexity_research',
+  'perplexity_reason',
+  // Tavily
+  'tavily_extract',
+  'tavily_crawl',
+  'tavily_map',
+  'tavily_research',
+  // Obsidian (MarkusPfundstein)
+  'obsidian_list_files_in_vault',
+  'obsidian_list_files_in_dir',
+  'obsidian_get_file_contents',
+  'obsidian_batch_get_file_contents',
+  'obsidian_get_periodic_note',
+  'obsidian_get_recent_periodic_notes',
+  'obsidian_get_recent_changes',
+  // Figma (GLips/Figma-Context-MCP)
+  'get_figma_data',
+  'download_figma_images',
+  // Playwright (microsoft/playwright-mcp)
+  'browser_console_messages',
+  'browser_network_requests',
+  'browser_take_screenshot',
+  'browser_snapshot',
+  'browser_get_config',
+  'browser_route_list',
+  'browser_cookie_list',
+  'browser_cookie_get',
+  'browser_localstorage_list',
+  'browser_localstorage_get',
+  'browser_sessionstorage_list',
+  'browser_sessionstorage_get',
+  'browser_storage_state',
+  // Puppeteer (@modelcontextprotocol/server-puppeteer)
+  'puppeteer_screenshot',
+  // MongoDB
+  'list_databases',
+  'list_collections',
+  'collection_indexes',
+  'collection_schema',
+  'collection_storage_size',
+  'db_stats',
+  'explain',
+  'mongodb_logs',
+  'aggregate',
+  'count',
+  'export',
+  // Neo4j
+  'get_neo4j_schema',
+  'read_neo4j_cypher',
+  'list_instances',
+  'get_instance_details',
+  'get_instance_by_name',
+  // Elasticsearch (elastic)
+  'list_indices',
+  'get_mappings',
+  'esql',
+  'get_shards',
+  // Airtable
+  'list_records',
+  'list_bases',
+  'get_record',
+  // Todoist (Doist — kebab-case, normalized)
+  'get_productivity_stats',
+  'get_overview',
+  'fetch_object',
+  'user_info',
+  'list_workspaces',
+  'view_attachment',
+  // AWS (awslabs/mcp)
+  'get_available_services',
+  'read_documentation',
+  'read_sections',
+  'recommend',
+  'analyze_log_group',
+  'analyze_metric',
+  'describe_log_groups',
+  'get_active_alarms',
+  'get_alarm_history',
+  'get_metric_data',
+  'get_metric_metadata',
+  // Kubernetes
+  'kubectl_get',
+  'kubectl_describe',
+  'kubectl_logs',
+  'kubectl_context',
+  'explain_resource',
+  'list_api_resources',
+  'namespaces_list',
+  'nodes_log',
+  'nodes_top',
+  'pods_get',
+  'pods_list',
+  'pods_list_in_namespace',
+  'pods_log',
+  'pods_top',
+  'resources_get',
+  'resources_list',
+])
+
+function normalize(name: string): string {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/-/g, '_')
+    .toLowerCase()
+}
+
+export function classifyMcpToolForCollapse(
+  _serverName: string,
+  toolName: string,
+): { isSearch: boolean; isRead: boolean } {
+  const normalized = normalize(toolName)
+  return {
+    isSearch: SEARCH_TOOLS.has(normalized),
+    isRead: READ_TOOLS.has(normalized),
+  }
+}

src/tools/MCPTool/prompt.ts

@@ -0,0 +1,3 @@
+// Actual prompt and description are overridden in mcpClient.ts
+export const PROMPT = ''
+export const DESCRIPTION = ''

src/tools/McpAuthTool/McpAuthTool.ts

@@ -0,0 +1,215 @@
+import reject from 'lodash-es/reject.js'
+import { z } from 'zod/v4'
+import { performMCPOAuthFlow } from '../../services/mcp/auth.js'
+import {
+  clearMcpAuthCache,
+  reconnectMcpServerImpl,
+} from '../../services/mcp/client.js'
+import {
+  buildMcpToolName,
+  getMcpPrefix,
+} from '../../services/mcp/mcpStringUtils.js'
+import type {
+  McpHTTPServerConfig,
+  McpSSEServerConfig,
+  ScopedMcpServerConfig,
+} from '../../services/mcp/types.js'
+import type { Tool } from '../../Tool.js'
+import { errorMessage } from '../../utils/errors.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logMCPDebug, logMCPError } from '../../utils/log.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+
+const inputSchema = lazySchema(() => z.object({}))
+type InputSchema = ReturnType<typeof inputSchema>
+
+export type McpAuthOutput = {
+  status: 'auth_url' | 'unsupported' | 'error'
+  message: string
+  authUrl?: string
+}
+
+function getConfigUrl(config: ScopedMcpServerConfig): string | undefined {
+  if ('url' in config) return config.url
+  return undefined
+}
+
+/**
+ * Creates a pseudo-tool for an MCP server that is installed but not
+ * authenticated. Surfaced in place of the server's real tools so the model
+ * knows the server exists and can start the OAuth flow on the user's behalf.
+ *
+ * When called, starts performMCPOAuthFlow with skipBrowserOpen and returns
+ * the authorization URL. The OAuth callback completes in the background;
+ * once it fires, reconnectMcpServerImpl runs and the server's real tools
+ * are swapped into appState.mcp.tools via the existing prefix-based
+ * replacement (useManageMCPConnections.updateServer wipes anything matching
+ * mcp__<server>__*, so this pseudo-tool is removed automatically).
+ */
+export function createMcpAuthTool(
+  serverName: string,
+  config: ScopedMcpServerConfig,
+): Tool<InputSchema, McpAuthOutput> {
+  const url = getConfigUrl(config)
+  const transport = config.type ?? 'stdio'
+  const location = url ? `${transport} at ${url}` : transport
+
+  const description =
+    `The \`${serverName}\` MCP server (${location}) is installed but requires authentication. ` +
+    `Call this tool to start the OAuth flow — you'll receive an authorization URL to share with the user. ` +
+    `Once the user completes authorization in their browser, the server's real tools will become available automatically.`
+
+  return {
+    name: buildMcpToolName(serverName, 'authenticate'),
+    isMcp: true,
+    mcpInfo: { serverName, toolName: 'authenticate' },
+    isEnabled: () => true,
+    isConcurrencySafe: () => false,
+    isReadOnly: () => false,
+    toAutoClassifierInput: () => serverName,
+    userFacingName: () => `${serverName} - authenticate (MCP)`,
+    maxResultSizeChars: 10_000,
+    renderToolUseMessage: () => `Authenticate ${serverName} MCP server`,
+    async description() {
+      return description
+    },
+    async prompt() {
+      return description
+    },
+    get inputSchema(): InputSchema {
+      return inputSchema()
+    },
+    async checkPermissions(input): Promise<PermissionDecision> {
+      return { behavior: 'allow', updatedInput: input }
+    },
+    async call(_input, context) {
+      // claude.ai connectors use a separate auth flow (handleClaudeAIAuth in
+      // MCPRemoteServerMenu) that we don't invoke programmatically here —
+      // just point the user at /mcp.
+      if (config.type === 'claudeai-proxy') {
+        return {
+          data: {
+            status: 'unsupported' as const,
+            message: `This is a claude.ai MCP connector. Ask the user to run /mcp and select "${serverName}" to authenticate.`,
+          },
+        }
+      }
+
+      // performMCPOAuthFlow only accepts sse/http. needs-auth state is only
+      // set on HTTP 401 (UnauthorizedError) so other transports shouldn't
+      // reach here, but be defensive.
+      if (config.type !== 'sse' && config.type !== 'http') {
+        return {
+          data: {
+            status: 'unsupported' as const,
+            message: `Server "${serverName}" uses ${transport} transport which does not support OAuth from this tool. Ask the user to run /mcp and authenticate manually.`,
+          },
+        }
+      }
+
+      const sseOrHttpConfig = config as (
+        | McpSSEServerConfig
+        | McpHTTPServerConfig
+      ) & { scope: ScopedMcpServerConfig['scope'] }
+
+      // Mirror cli/print.ts mcp_authenticate: start the flow, capture the
+      // URL via onAuthorizationUrl, return it immediately. The flow's
+      // Promise resolves later when the browser callback fires.
+      let resolveAuthUrl: ((url: string) => void) | undefined
+      const authUrlPromise = new Promise<string>(resolve => {
+        resolveAuthUrl = resolve
+      })
+
+      const controller = new AbortController()
+      const { setAppState } = context
+
+      const oauthPromise = performMCPOAuthFlow(
+        serverName,
+        sseOrHttpConfig,
+        u => resolveAuthUrl?.(u),
+        controller.signal,
+        { skipBrowserOpen: true },
+      )
+
+      // Background continuation: once OAuth completes, reconnect and swap
+      // the real tools into appState. Prefix-based replacement removes this
+      // pseudo-tool since it shares the mcp__<server>__ prefix.
+      void oauthPromise
+        .then(async () => {
+          clearMcpAuthCache()
+          const result = await reconnectMcpServerImpl(serverName, config)
+          const prefix = getMcpPrefix(serverName)
+          setAppState(prev => ({
+            ...prev,
+            mcp: {
+              ...prev.mcp,
+              clients: prev.mcp.clients.map(c =>
+                c.name === serverName ? result.client : c,
+              ),
+              tools: [
+                ...reject(prev.mcp.tools, t => t.name?.startsWith(prefix)),
+                ...result.tools,
+              ],
+              commands: [
+                ...reject(prev.mcp.commands, c => c.name?.startsWith(prefix)),
+                ...result.commands,
+              ],
+              resources: result.resources
+                ? { ...prev.mcp.resources, [serverName]: result.resources }
+                : prev.mcp.resources,
+            },
+          }))
+          logMCPDebug(
+            serverName,
+            `OAuth complete, reconnected with ${result.tools.length} tool(s)`,
+          )
+        })
+        .catch(err => {
+          logMCPError(
+            serverName,
+            `OAuth flow failed after tool-triggered start: ${errorMessage(err)}`,
+          )
+        })
+
+      try {
+        // Race: get the URL, or the flow completes without needing one
+        // (e.g. XAA with cached IdP token — silent auth).
+        const authUrl = await Promise.race([
+          authUrlPromise,
+          oauthPromise.then(() => null as string | null),
+        ])
+
+        if (authUrl) {
+          return {
+            data: {
+              status: 'auth_url' as const,
+              authUrl,
+              message: `Ask the user to open this URL in their browser to authorize the ${serverName} MCP server:\n\n${authUrl}\n\nOnce they complete the flow, the server's tools will become available automatically.`,
+            },
+          }
+        }
+
+        return {
+          data: {
+            status: 'auth_url' as const,
+            message: `Authentication completed silently for ${serverName}. The server's tools should now be available.`,
+          },
+        }
+      } catch (err) {
+        return {
+          data: {
+            status: 'error' as const,
+            message: `Failed to start OAuth flow for ${serverName}: ${errorMessage(err)}. Ask the user to run /mcp and authenticate manually.`,
+          },
+        }
+      }
+    },
+    mapToolResultToToolResultBlockParam(data, toolUseID) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: data.message,
+      }
+    },
+  } satisfies Tool<InputSchema, McpAuthOutput>
+}