refactor(tools): unify tool APIs and result handling - #38367

What

Unifies the V2 tool stack from authored tools through provider schemas, local execution, hooks, clients, and persisted terminal results.

The canonical vocabulary is now:

• Tool.Tool for an authored tool and Tool.Any for its erased form.
• tool for runtime values, including registration.tool.
• execute as the sole local execution verb.
• LLM.ToolDefinition for the inert model-facing schema.

A terminal response separates schema-validated machine output, model-visible content, and compact UI metadata. One registry boundary validates and bounds those values, runs hooks, and returns a canonical completed | error result consumed by Code Mode, MCP, plugins, the runner, CLI, ACP, TUI, simulation, and durable session state.

Shell follows the same split: progress publishes compact metadata such as shellID; paginated shell output remains outside durable progress events; terminal completion or failure owns model content.

How

• Plugin API: aligns Effect and Promise tools around Tool.make({ description, input, output?, execute }), Tool.Tool, and Tool.Any. The standalone CLI exposes the same public tool facade to both plugin runtimes.
• Registration: keeps reusable tools separate from effective names, namespaces, Code Mode placement, and permission identity. Registrations are normalized, collision-checked, scoped, and captured per model request.
• Execution: validates decoded input and encoded output, converts responses into non-empty model content, validates compact JSON metadata, bounds stored content, and revalidates hook mutations.
• Code Mode: receives declared, schema-validated machine output instead of reconstructing values from model content or UI projections.
• Persistence: stores canonical terminal content, metadata, and errors in V2 session messages and events. The migration rewrites projected session_message rows only and leaves legacy durable events untouched.
• Bedrock: final steps retain tool definitions in toolConfig.tools while omitting unsupported toolChoice: none, preserving the tools -> system -> messages prompt-cache prefix.
• MCP: reconciles one registration batch per server while retaining the same namespaced permission identity per tool.

Scope

• Legacy session.tool.success.1 and session.tool.failed.1 durable rows are intentionally unchanged. Cleanup before V2 stable is tracked in V2: remove V1 event surface after cutover (tracking) #35054 (comment).
• Bedrock Converse still has no native none tool choice; this PR omits only that unsupported field rather than removing tool definitions.
• Broader resumable migration, binary payload bounding, and tool-display performance work are not included.

Testing

• Monorepo push-hook typecheck: 33 packages passed.
• Package typechecks: AI, Plugin, Code Mode, Core, CLI, SDK Next, and Simulation.
• Plugin declaration build: tsc -p tsconfig.build.json.
• Plugin tests: 8 passed.
• Code Mode tests: 1,086 passed.
• Focused Core tool, MCP, registry, and migration tests: 101 passed.
• CLI import-boundary tests: 4 passed.
• Bedrock Converse tests: 34 passed.
• Provider tests: 84 passed.
• Shell tool stress rerun: 300 passed across 20 reruns.
• Standalone Node build completed Linux arm64, Linux x64, and macOS arm64 bundles before the remaining target matrix exceeded the local command timeout.

Flow

flowchart LR
  A[Tool.make] --> B[Scoped registration]
  B --> C[Registry snapshot]
  C --> D[LLM.ToolDefinition]
  D --> E[Provider tool call]
  E --> F[Registry execute]
  F --> G[Validated output]
  F --> H[Bounded content]
  F --> I[Compact metadata]
  G --> J[Code Mode]
  H --> K[Model and durable state]
  I --> L[UI and clients]