@makaio/ai-adapters-claude-agent-sdk

Claude Agent SDK adapter using the three-layer architecture.

Quick Start

import { createClaudeAdapter, ClaudeCodeAdapter } from '@makaio/ai-adapters-claude-agent-sdk';
import { AdapterSubjects } from '@makaio/contracts';
import { MakaioBus } from '@makaio/bus-core';

// Using the factory (recommended)
const adapter = await createClaudeAdapter();

// Or instantiate directly
const directAdapter = new ClaudeCodeAdapter();
await directAdapter.init();

const result = await MakaioBus.request(AdapterSubjects.startAgent, {
  adapterId: adapter.adapterId,
  role: 'lead',
  initialMessage: 'Build a todo app',
  model: 'sonnet',
});

Architecture

The adapter follows a three-layer architecture:

ClaudeCodeAdapter extends AIAdapter
    -> creates via agentFactory
ClaudeCodeAgent extends AIAgent
    -> creates via connectorFactory
ClaudeSdkConnector extends AIAgentConnector

Layer Responsibilities

Layer	Class	Responsibility
Adapter	ClaudeCodeAdapter	Lifecycle, agent factory, model listing
Agent	ClaudeCodeAgent	Event wiring, tool approval routing, usage tracking
Connector	ClaudeSdkConnector	SDK query lifecycle, session management, message handling

Key Concepts

Event Flow

1. ClaudeSdkConnector emits SDK events to scoped bus (adapter:claude-code.*)
2. ClaudeCodeAgent processes and routes to global bus (agent.*)
3. Downstream consumers subscribe to normalized agent.* subjects

Namespace Subjects

The adapter registers adapter:claude-code namespace with typed subjects:

Subject	Description
sdk.event	Catch-all for raw SDK events
system	System messages (init, compact_boundary)
assistant	Assistant content blocks
user	User messages and tool results
result	Query completion (success/error)
stream_event	Streaming deltas
turn.*	Turn lifecycle events
can_use_tool	Tool approval RPC

Exports

Classes

Export	Description
ClaudeCodeAdapter	Main adapter class
ClaudeCodeAgent	Agent layer for event routing
ClaudeSdkConnector	SDK connector layer

Functions

Export	Description
createClaudeAdapter	Factory that creates and initializes adapter
createTestConfig	Conformance test configuration
registerToolApprovalHandler	Set up tool approval routing
requestToolApproval	Request approval for a tool call

Namespace

Export	Description
ClaudeCodeConnectorNamespace	Full namespace definition
ClaudeCodeConnectorSubjects	Subject definitions for typed subscriptions
ClaudeCodeAdapterName	Adapter identifier constant

Types

Export	Description
ClaudeCodeAdapterConfig	Adapter configuration options
ClaudeAgentConfig	Agent configuration
ClaudeCodeProviderConfig	Provider-specific settings
ClaudeCodeConnectorBus	Typed scoped bus
ClaudePermissionResult	Tool approval permission result
ToolApprovalContext	Tool approval context type

Session/Turn

Export	Description
ClaudeConnectorTurn	Turn state machine
ClaudeTurnState	Turn state type
UserMessageQueue	Internal connector queue from adapter core

Schemas

Export	Description
ClaudeCodeProviderConfigSchema	Zod schema for provider config
CONTENT_BLOCK_HANDLERS	Discriminated handlers for content blocks

Adapter Definition

Runtime registration is contributed by @makaio/ai-adapters-claude-agent-sdk/server. That entrypoint default-exports the claudeAgentSdkPackage MakaioExtension descriptor, whose adapters[] entry wraps the internal definition from src/definition.ts.

Supported Models

Name	Friendly Name	Reasoning Levels
sonnet	Sonnet 4.5	none, low, medium, high, extra-high
haiku	Haiku 4.5	none, low, medium, high, extra-high
opus	Opus 4.6	none, low, medium, high, extra-high

Capabilities

• tools - Tool use support
• vision - Image/vision input
• chatInTurnMessages - Multi-turn conversation
• structuredOutput - Native structured output support through the Agent SDK
• systemPrompt:override - Replace/set the system prompt

File Structure

src/
├── index.ts                       # Package exports
├── adapter.ts                     # ClaudeCodeAdapter
├── agent.ts                       # ClaudeCodeAgent
├── connector.ts                   # ClaudeSdkConnector
├── session.ts                     # Session abstraction
├── turn.ts                        # Turn state machine
├── config.ts                      # Configuration resolution
├── constants.ts                   # Adapter name constant
├── definition.ts                  # Internal adapter definition
├── package.ts                     # MakaioExtension package descriptor
├── provider.ts                    # Provider registration
├── provider.fetcher.ts            # Model fetcher
├── server.ts                      # Server entrypoint exporting the package descriptor
├── schemas.ts                     # Provider config schemas
├── mcp-integration.ts             # MCP tool integration
├── account-observation.ts         # Account observation
├── account-observation-requester.ts
├── on-turn-complete.ts            # Post-turn hooks
├── namespace/
│   └── index.ts                   # Namespace + subjects
├── types/
│   └── index.ts                   # Internal types
├── utils/                         # Helper functions
└── __tests__/                     # Unit tests + fixtures

---

Part of the Makaio AI Framework