feat: built-in optional tool types + per-harness compatibility matrix

[espetro]

Summary

The framework currently provides no built-in/optional tool definitions. Plugin authors must re-declare harness-native capabilities (e.g. ask_question/ask_user, shell execution, notifications, confirmations) themselves. This issue tracks adding a typed registry of built-in tools plus a per-harness compatibility matrix so users can reference them straightaway.

Motivation

• Users want to invoke harness-native tools without manually declaring them in every plugin manifest.
• Plugin authors need to know which tools are available on which harnesses.
• A compatibility matrix prevents build-time surprises when targeting multiple platforms.

Current State

• ToolDefinition in packages/core/src/types.ts only covers user-declared tools.
• No built-in tool registry exists.
• PlatformConstraints in packages/core/src/validation.ts documents hook compatibility only.
• Harness-native capabilities vary widely:
  • Pi Mono: ctx.ui.notify, ctx.ui.confirm, ctx.ui.select, ctx.ui.input, pi.exec, etc.
  • OpenCode: $ (Bun shell), tui.toast.show, tui.prompt.append, tui.command.execute.
  • Claude Code: intercept built-in tools via matchers (Bash, Edit, Write, Read, Grep, Glob).
  • Codex, Copilot CLI, Gemini, Kimi: only interceptors and MCP servers.

Proposed Direction

Add a typed registry and compatibility helpers.

Core types

export type HarnessCapability =
  | 'native'
  | 'via-mcp'
  | 'via-matcher'
  | 'emulated'
  | 'unsupported';

export interface BuiltInToolDefinition {
  readonly name: string;
  readonly description: string;
  readonly parameters: ToolParameterSchema;
  readonly platforms: Partial<Record<TargetPlatform, HarnessCapability>>;
  readonly harnessApi?: Partial<Record<TargetPlatform, HarnessApiRef>>;
  readonly category?: 'ui' | 'shell' | 'io' | 'context' | 'navigation';
  readonly required?: boolean;
}

export interface HarnessApiRef {
  readonly method: string;
  readonly args?: string[];
}

export declare const BUILTIN_TOOLS: ReadonlyMap<string, BuiltInToolDefinition>;
export function getBuiltinTool(name: string): BuiltInToolDefinition | undefined;
export function isBuiltinAvailable(
  toolName: string,
  platform: TargetPlatform
): HarnessCapability | undefined;

Compatibility matrix

Add a public compatibility table (e.g. in docs-site/guide/tools.md) showing which built-in tools work on each harness and how they are invoked.

Validation

Extend PlatformConstraints with ToolConstraints:

export interface ToolConstraints {
  readonly builtinTools: Readonly<Record<string, HarnessCapability>>;
  readonly knownToolNames: readonly string[];
  readonly emitsToolDefinitions: boolean;
}

Add a lint rule that warns when a plugin references a built-in tool that is unsupported on a declared target.

Acceptance Criteria

• BuiltInToolDefinition, HarnessCapability, and HarnessApiRef types added to packages/core/src/types.ts.
• BUILTIN_TOOLS registry seeded with at least shell, notify, confirm, select, input.
• getBuiltinTool and isBuiltinAvailable helpers exported.
• PlatformConstraints extended with ToolConstraints.
• All 7 adapters updated with their built-in tool capabilities.
• New lint rule warns on unsupported built-in usage per target.
• Public docs include a cross-platform compatibility matrix.
• JSON schema updated.

Classification

• Type: feature
• Effort: M
• Status: Scheduled

Related

• Research plan: .agents/plans/2026-06-15-builtins-ui-research.md