feat: 工具层及 mcp 大重构 (#252)

* feat: 第一版大重构

* fix: 修复类型问题

* chore: 更新版本到 1.3.2

* Add brave as alternative WebSearchTool

* fix: 修正顺序

* fix: 修复对穷鬼模式的 auto dream 和 session memory 越过

* feat: 穷鬼模式去除 session-summary

* feat: 创建 builtin-tools 包，搬运所有工具实现

将 src/tools/ 下的全部 60 个工具目录迁移至 packages/builtin-tools/src/tools/，
内部导入路径已更新为 src/ alias 模式。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 更新 src/ 中所有工具引用至 builtin-tools 包，删除 src/tools/

- src/tools.ts 及 178 个 src/ 文件的 import 路径从 ./tools/ 改为 builtin-tools/tools/
- 删除 src/tools/ 整个目录（已迁移至 packages/builtin-tools/）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: 添加 builtin-tools 路径别名至 tsconfig，更新 bun.lock

- tsconfig.json 新增 builtin-tools/* 和 builtin-tools 路径映射
- 新增 packages/builtin-tools/src 至 include

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 为 builtin-tools、mcp-client、agent-tools 添加 @claude-code-best 作用域前缀

所有包名及 import 路径统一添加 @claude-code-best/ 前缀：
- builtin-tools → @claude-code-best/builtin-tools
- mcp-client → @claude-code-best/mcp-client
- agent-tools → @claude-code-best/agent-tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: 修复 node 环境没有 bun 的问题

---------

Co-authored-by: Eric-Guo <eric.guocz@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

packages/agent-tools/src/__tests__/compat.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import type { CoreTool, Tool, Tools, AnyObject, ToolResult, ValidationResult, PermissionResult } from '@claude-code-best/agent-tools'
+import type { Tool as HostTool } from '../../src/Tool.js'
+
+describe('agent-tools compatibility', () => {
+  test('CoreTool structural compatibility with host Tool', () => {
+    // The host's Tool should structurally satisfy CoreTool
+    // because it has all required fields (name, call, description, etc.)
+    // This test verifies the type-level compatibility at runtime
+    const mockHostTool: HostTool = {
+      name: 'test',
+      aliases: [],
+      searchHint: 'test tool',
+      inputSchema: {} as any,
+      async call() { return { data: 'ok' } as any },
+      async description() { return 'test' },
+      async prompt() { return 'test prompt' },
+      isConcurrencySafe: () => false,
+      isEnabled: () => true,
+      isReadOnly: () => false,
+      async checkPermissions() { return { behavior: 'allow' as const, updatedInput: {} } },
+      toAutoClassifierInput: () => '',
+      userFacingName: () => 'test',
+      maxResultSizeChars: 100000,
+      mapToolResultToToolResultBlockParam: () => ({ type: 'tool_result', tool_use_id: '1', content: 'ok' }),
+      renderToolUseMessage: () => null,
+    }
+
+    // This assignment should work if HostTool structurally extends CoreTool
+    const coreTool: CoreTool = mockHostTool as CoreTool
+    expect(coreTool.name).toBe('test')
+    expect(coreTool.isEnabled()).toBe(true)
+  })
+})

packages/agent-tools/src/__tests__/registry.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+import { findToolByName, toolMatchesName } from '../registry.js'
+import type { CoreTool, Tools } from '../types.js'
+
+describe('toolMatchesName', () => {
+  test('matches primary name', () => {
+    expect(toolMatchesName({ name: 'bash' }, 'bash')).toBe(true)
+  })
+
+  test('does not match different name', () => {
+    expect(toolMatchesName({ name: 'bash' }, 'read')).toBe(false)
+  })
+
+  test('matches alias', () => {
+    expect(toolMatchesName({ name: 'bash', aliases: ['shell', 'sh'] }, 'shell')).toBe(true)
+    expect(toolMatchesName({ name: 'bash', aliases: ['shell', 'sh'] }, 'sh')).toBe(true)
+  })
+
+  test('handles empty aliases', () => {
+    expect(toolMatchesName({ name: 'bash', aliases: [] }, 'bash')).toBe(true)
+    expect(toolMatchesName({ name: 'bash', aliases: [] }, 'shell')).toBe(false)
+  })
+
+  test('handles undefined aliases', () => {
+    expect(toolMatchesName({ name: 'bash' }, 'bash')).toBe(true)
+    expect(toolMatchesName({ name: 'bash' }, 'shell')).toBe(false)
+  })
+})
+
+describe('findToolByName', () => {
+  const tools: Tools = [
+    { name: 'bash' } as CoreTool,
+    { name: 'read', aliases: ['cat'] } as CoreTool,
+    { name: 'write', aliases: ['edit'] } as CoreTool,
+  ]
+
+  test('finds tool by primary name', () => {
+    expect(findToolByName(tools, 'bash')?.name).toBe('bash')
+  })
+
+  test('finds tool by alias', () => {
+    expect(findToolByName(tools, 'cat')?.name).toBe('read')
+    expect(findToolByName(tools, 'edit')?.name).toBe('write')
+  })
+
+  test('returns undefined for unknown name', () => {
+    expect(findToolByName(tools, 'unknown')).toBeUndefined()
+  })
+
+  test('handles empty tools array', () => {
+    expect(findToolByName([], 'bash')).toBeUndefined()
+  })
+
+  test('returns first match for duplicate names', () => {
+    const dupTools: Tools = [
+      { name: 'tool', aliases: ['a'] } as CoreTool,
+      { name: 'tool', aliases: ['b'] } as CoreTool,
+    ]
+    const found = findToolByName(dupTools, 'tool')
+    expect(found).toBeDefined()
+    expect(found!.aliases).toContain('a')
+  })
+})

packages/agent-tools/src/index.ts

@@ -0,0 +1,18 @@
+// agent-tools — Tool interface definitions and registry utilities
+// Pure types + pure functions, zero runtime dependencies
+
+export type {
+  AnyObject,
+  ToolInputJSONSchema,
+  ToolProgressData,
+  ToolProgress,
+  ToolCallProgress,
+  ToolResult,
+  ValidationResult,
+  PermissionResult,
+  CoreTool,
+  Tool,
+  Tools,
+} from './types.js'
+
+export { findToolByName, toolMatchesName } from './registry.js'

packages/agent-tools/src/registry.ts

@@ -0,0 +1,21 @@
+import type { CoreTool, Tools } from './types.js'
+
+/**
+ * Checks if a tool matches the given name (primary name or alias).
+ */
+export function toolMatchesName(
+  tool: { name: string; aliases?: string[] },
+  name: string,
+): boolean {
+  return tool.name === name || (tool.aliases?.includes(name) ?? false)
+}
+
+/**
+ * Finds a tool by name or alias from a list of tools.
+ */
+export function findToolByName(
+  tools: Tools,
+  name: string,
+): CoreTool | undefined {
+  return tools.find(t => toolMatchesName(t, name))
+}

packages/agent-tools/src/types.ts

@@ -0,0 +1,221 @@
+// agent-tools — Core Tool interface definitions
+// Protocol-level types, independent of any host framework
+
+import type { z } from 'zod/v4'
+
+// ============================================================================
+// Schema types
+// ============================================================================
+
+/**
+ * Zod schema type for any object with string keys.
+ * Used as the Input generic constraint for Tool.
+ */
+export type AnyObject = z.ZodType<{ [key: string]: unknown }>
+
+/**
+ * JSON Schema format for MCP tool input schemas.
+ * MCP servers provide this directly instead of Zod schemas.
+ */
+export type ToolInputJSONSchema = {
+  [x: string]: unknown
+  type: 'object'
+  properties?: {
+    [x: string]: unknown
+  }
+}
+
+// ============================================================================
+// Progress types
+// ============================================================================
+
+/**
+ * Progress data from a running tool. Host defines concrete subtypes.
+ * Typed as `any` at the protocol level — the host assigns real shapes.
+ */
+export type ToolProgressData = any
+
+/**
+ * A progress event from a tool execution.
+ */
+export type ToolProgress<P extends ToolProgressData = ToolProgressData> = {
+  toolUseID: string
+  data: P
+}
+
+/**
+ * Callback for receiving progress updates during tool execution.
+ */
+export type ToolCallProgress<P extends ToolProgressData = ToolProgressData> = (
+  progress: ToolProgress<P>,
+) => void
+
+// ============================================================================
+// Result types
+// ============================================================================
+
+/**
+ * Result returned by a tool's call() method.
+ * @template T - The output data type
+ * @template Message - The message type (host-specific, defaults to unknown)
+ */
+export type ToolResult<T, Message = unknown> = {
+  data: T
+  newMessages?: Message[]
+  contextModifier?: (context: any) => any
+  /** MCP protocol metadata (structuredContent, _meta) */
+  mcpMeta?: {
+    _meta?: Record<string, unknown>
+    structuredContent?: Record<string, unknown>
+  }
+}
+
+// ============================================================================
+// Validation & Permission types
+// ============================================================================
+
+/**
+ * Result of tool input validation.
+ */
+export type ValidationResult =
+  | { result: true }
+  | { result: false; message: string; errorCode: number }
+
+/**
+ * Result of a permission check for a tool invocation.
+ */
+export type PermissionResult =
+  | { behavior: 'allow'; updatedInput: Record<string, unknown> }
+  | { behavior: 'deny'; message: string }
+  | { behavior: 'passthrough' }
+
+// ============================================================================
+// Core Tool interface
+// ============================================================================
+
+/**
+ * The host-agnostic core Tool interface.
+ *
+ * This defines the protocol-level contract for any tool — independent of
+ * React rendering, specific context types, or host infrastructure.
+ *
+ * The host (Claude Code) extends this with render methods, richer context
+ * types, and other host-specific features. Host tools structurally satisfy
+ * this interface because they implement all required fields.
+ *
+ * @template Input - Zod schema type for tool input
+ * @template Output - Tool output data type
+ * @template P - Tool progress data type
+ * @template Context - Tool execution context type (host-specific)
+ */
+export interface CoreTool<
+  Input extends AnyObject = AnyObject,
+  Output = unknown,
+  P extends ToolProgressData = ToolProgressData,
+  Context = unknown,
+> {
+  // ── Identity ──
+  readonly name: string
+  aliases?: string[]
+  searchHint?: string
+
+  // ── Schema ──
+  readonly inputSchema: Input
+  readonly inputJSONSchema?: ToolInputJSONSchema
+  outputSchema?: z.ZodType<unknown>
+
+  // ── Execution ──
+  call(
+    args: z.infer<Input>,
+    context: Context,
+    canUseTool: (...args: any[]) => Promise<any>,
+    parentMessage: any,
+    onProgress?: ToolCallProgress<P>,
+  ): Promise<ToolResult<Output>>
+
+  // ── Description ──
+  description(
+    input: z.infer<Input>,
+    options: {
+      isNonInteractiveSession: boolean
+      toolPermissionContext: any
+      tools: readonly CoreTool[]
+    },
+  ): Promise<string>
+
+  prompt(options: {
+    getToolPermissionContext: () => Promise<any>
+    tools: readonly CoreTool[]
+    agents: any[]
+    allowedAgentTypes?: string[]
+  }): Promise<string>
+
+  // ── Behavioral properties ──
+  isConcurrencySafe(input: z.infer<Input>): boolean
+  isEnabled(): boolean
+  isReadOnly(input: z.infer<Input>): boolean
+  isDestructive?(input: z.infer<Input>): boolean
+  isOpenWorld?(input: z.infer<Input>): boolean
+  interruptBehavior?(): 'cancel' | 'block'
+  requiresUserInteraction?(): boolean
+
+  // ── MCP markers ──
+  isMcp?: boolean
+  isLsp?: boolean
+  readonly shouldDefer?: boolean
+  readonly alwaysLoad?: boolean
+  mcpInfo?: { serverName: string; toolName: string }
+
+  // ── Permissions ──
+  validateInput?(
+    input: z.infer<Input>,
+    context: Context,
+  ): Promise<ValidationResult>
+
+  checkPermissions(
+    input: z.infer<Input>,
+    context: Context,
+  ): Promise<PermissionResult>
+
+  // ── Utility ──
+  inputsEquivalent?(a: z.infer<Input>, b: z.infer<Input>): boolean
+  getPath?(input: z.infer<Input>): string
+  toAutoClassifierInput(input: z.infer<Input>): unknown
+  backfillObservableInput?(input: Record<string, unknown>): void
+
+  // ── Output ──
+  maxResultSizeChars: number
+  userFacingName(input: Partial<z.infer<Input>> | undefined): string
+  mapToolResultToToolResultBlockParam(
+    content: Output,
+    toolUseID: string,
+  ): any
+
+  // ── Optional output helpers ──
+  isResultTruncated?(output: Output): boolean
+  getToolUseSummary?(input: Partial<z.infer<Input>> | undefined): string | null
+  getActivityDescription?(
+    input: Partial<z.infer<Input>> | undefined,
+  ): string | null
+  isTransparentWrapper?(): boolean
+  isSearchOrReadCommand?(input: z.infer<Input>): {
+    isSearch: boolean
+    isRead: boolean
+    isList?: boolean
+  }
+}
+
+/**
+ * A tool with a generic context type.
+ * This is the default export — hosts can specify their own Context type.
+ */
+export type Tool<
+  Input extends AnyObject = AnyObject,
+  Output = unknown,
+  P extends ToolProgressData = ToolProgressData,
+> = CoreTool<Input, Output, P>
+
+/**
+ * A collection of tools.
+ */
+export type Tools = readonly CoreTool[]