Use when editing src/types.ts, src/index.ts, src/models.ts, or adding a new adapter/event type to @inharness-ai/agent-adapters. Explains the RuntimeAdapter contract, the UnifiedEvent taxonomy, NormalizedMessage shape, RuntimeExecuteParams, the capability matrix across adapters, and the checklist for extending the unified layer without breaking adapters.
Use when editing src/adapters/claude-code.ts or src/testing/e2e/claude-code.e2e.test.ts, bumping @anthropic-ai/claude-agent-sdk in package.json, debugging missing/unexpected events from the Claude Code adapter (thinking, subagents, AskUserQuestion, MCP elicitation, resume), or extending UnifiedEvent and needing to know what claude-code can emit natively. Covers Opus 4.7 ADAPTIVE_THINKING_ONLY, claude_* architectureConfig keys, dual-channel user input, and preset system prompts.
Use when editing src/adapters/codex.ts or src/testing/e2e/codex.e2e.test.ts, bumping @openai/codex-sdk in package.json, debugging missing events (user input not firing, MCP tools not showing, command execution events), or extending UnifiedEvent and needing to know what Codex can and cannot do. Codex has no native user input, no dynamic MCP config (must pre-configure via `codex mcp add`), and hardcodes approvalPolicy='never' regardless of planMode.
Use when editing src/adapters/opencode.ts or src/testing/e2e/opencode.e2e.test.ts, bumping @opencode-ai/sdk in package.json, debugging SSE streaming issues, OpenCode CLI availability, provider/model string parsing, question.asked user-input flow, or MCP stdio-only limitation. Extending UnifiedEvent and need to know that OpenCode ignores planMode, only supports stdio MCP, and requires the OpenCode CLI binary in PATH.
Use when editing src/adapters/gemini.ts or src/testing/e2e/gemini.e2e.test.ts, bumping @google/gemini-cli-core in package.json, debugging missing thinking/usage events, ask_user partial support, session resumption from ~/.gemini/projects, MCP server wiring, or extending UnifiedEvent. Gemini thinking is non-delta (replace:true), ask_user uses MessageBus TOOL_CONFIRMATION_REQUEST (not ASK_USER_REQUEST), 2.5-flash sometimes reports 0 output tokens requiring char-length fallback.
Use when designing or implementing the google-adk adapter at src/adapters/google-adk.ts (NOT YET IMPLEMENTED — this is a design brief), evaluating @google/adk (Agent Development Kit for TypeScript) for multi-agent / code-first orchestration, or deciding whether to route a call to google-genai (single-agent Interactions API) vs google-adk (multi-agent framework). Covers pre-GA TS status, native MCP, FunctionTool extensibility, deployment-agnostic and model-agnostic design.
Use when designing or implementing the google-genai adapter at src/adapters/google-genai.ts (NOT YET IMPLEMENTED — this is a design brief), evaluating @google/genai Interactions API for paid Gemini use cases (API key / Workspace OAuth / Vertex), or deciding whether to route a Gemini call to gemini-cli-core (free-tier personal OAuth) vs google-genai (stable, documented, built-in MCP + SSE streaming + long-running tasks + Deep Research Agent). Covers Interactions API Beta status and design open questions.