chore: release 0.26.0

Update CHANGELOG, README, and bump all package versions to 0.26.0.

Changes:
- Update CHANGELOG.md with custom tools support and Codex default model
- Add Custom Tools section to root README with comprehensive example
- Copy updated README to core package for npm distribution
- Bump version to 0.26.0 across all packages
- Update peer dependencies to @headless-coder-sdk/core@^0.26.0

This release includes custom tools infrastructure, Claude adapter
automatic MCP server conversion, and Codex adapter default model
update to gpt-5.2.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: OhadAssulin

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.26.0] - 2025-12-13
+### ✨ Custom Tools Support
+- Added comprehensive custom tools infrastructure following Claude Agent SDK patterns.
+- Core package now includes `tool()`, `createMCPServer()`, and helper utilities for creating custom tools with type-safe schemas.
+- New types: `ToolDefinition`, `ToolHandler`, `ToolResult`, `MCPServer`, and `ToolInputSchema` for unified tool creation across adapters.
+- Claude adapter gained automatic MCP server conversion, bridging generic tools to Claude Agent SDK format seamlessly.
+- Export `getToolName()` and `getServerToolNames()` helpers to simplify tool name management (format: `mcp__{server}__{tool}`).
+- Enhanced `StartOpts.mcpServers` and `StartOpts.allowedTools` documentation with clear patterns and examples.
+- Added comprehensive examples: `claude-custom-tools.test.ts` (weather, calculator, formatter tools with streaming) and `custom-tools-simple.ts`.
+
+### 🛠 Codex Adapter
+- Default model is now `gpt-5.2` when no model is specified in `StartOpts`.
+- Exported `DEFAULT_MODEL` constant for easy reference.
+
+### 📚 Documentation
+- Added `CLAUDE.md` at repository root with architecture, build commands, and development guidance for Claude Code instances.
+- Updated root README with custom tools examples.
+- Core package README now documents tool creation patterns.
+
 ## [0.25.0] - 2025-11-25
 ### 📚 Adapter Guide & Provider Types
 - Widened the `Provider`/`AdapterName` types so third-party adapters can use custom provider strings without casts.

README.md

@@ -235,6 +235,70 @@ In this workflow two reviewers (Claude, Codex) analyze the same commit in parall
 
 ---
 
+## 🛠 Custom Tools (Claude)
+
+The SDK provides a unified interface for creating custom tools that extend Claude's capabilities, following the Claude Agent SDK's MCP (Model Context Protocol) pattern:
+
+```ts
+import { tool, createMCPServer, getToolName } from '@headless-coder-sdk/core';
+import { createHeadlessClaude } from '@headless-coder-sdk/claude-adapter';
+
+// Define a custom tool
+const weatherTool = tool(
+  'get_weather',
+  'Get current temperature for a location using coordinates',
+  {
+    latitude: { type: 'number', description: 'Latitude coordinate' },
+    longitude: { type: 'number', description: 'Longitude coordinate' }
+  },
+  async (args) => {
+    const response = await fetch(
+      `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`
+    );
+    const data = await response.json();
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Temperature: ${data.current.temperature_2m}°F`
+      }]
+    };
+  }
+);
+
+// Create an MCP server with your tools
+const weatherServer = createMCPServer({
+  name: 'weather-tools',
+  version: '1.0.0',
+  tools: [weatherTool]
+});
+
+// Use with Claude
+const claude = createHeadlessClaude({
+  workingDirectory: process.cwd(),
+  mcpServers: {
+    'weather-tools': weatherServer
+  },
+  allowedTools: [getToolName('weather-tools', 'get_weather')],
+  permissionMode: 'bypassPermissions'
+});
+
+const thread = await claude.startThread();
+const result = await thread.run("What's the weather in San Francisco? (37.7749, -122.4194)");
+console.log(result.text);
+```
+
+**Key Features:**
+- **Type-safe schemas** – Define input schemas with full TypeScript support
+- **Tool name management** – Use `getToolName(server, tool)` for proper MCP naming (`mcp__{server}__{tool}`)
+- **Selective permissions** – Control which tools Claude can use via `allowedTools`
+- **Streaming support** – Custom tools work seamlessly with `runStreamed()`
+- **Claude native** – Use Claude's native `tool()` and `createSdkMcpServer()` directly if preferred
+
+See `examples/src/claude-custom-tools.test.ts` for comprehensive examples including calculator, formatter, and multi-tool workflows.
+
+---
+
 ## ⚠️ Codex Adapter Runtime
 
 - The Codex adapter talks directly to the Codex CLI through Node APIs and **must run on the server**. It is safe to import in build tooling, but gate runtime usage to environments where `process.versions.node` exists.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "headless-coder-sdk",
   "private": true,
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "workspaces": [
     "packages/*",

packages/acp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/acp-server",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "scripts": {
     "dev": "next dev -p 8000",

packages/claude-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/claude-adapter",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -24,7 +24,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.50 <0.1.99",
-    "@headless-coder-sdk/core": "^0.25.0"
+    "@headless-coder-sdk/core": "^0.26.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/codex-adapter",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -22,7 +22,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.25.0",
+    "@headless-coder-sdk/core": "^0.26.0",
     "@openai/codex-sdk": ">=0.60.0 <0.80.0"
   },
   "devDependencies": {

packages/core/README.md

@@ -235,6 +235,70 @@ In this workflow two reviewers (Claude, Codex) analyze the same commit in parall
 
 ---
 
+## 🛠 Custom Tools (Claude)
+
+The SDK provides a unified interface for creating custom tools that extend Claude's capabilities, following the Claude Agent SDK's MCP (Model Context Protocol) pattern:
+
+```ts
+import { tool, createMCPServer, getToolName } from '@headless-coder-sdk/core';
+import { createHeadlessClaude } from '@headless-coder-sdk/claude-adapter';
+
+// Define a custom tool
+const weatherTool = tool(
+  'get_weather',
+  'Get current temperature for a location using coordinates',
+  {
+    latitude: { type: 'number', description: 'Latitude coordinate' },
+    longitude: { type: 'number', description: 'Longitude coordinate' }
+  },
+  async (args) => {
+    const response = await fetch(
+      `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`
+    );
+    const data = await response.json();
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Temperature: ${data.current.temperature_2m}°F`
+      }]
+    };
+  }
+);
+
+// Create an MCP server with your tools
+const weatherServer = createMCPServer({
+  name: 'weather-tools',
+  version: '1.0.0',
+  tools: [weatherTool]
+});
+
+// Use with Claude
+const claude = createHeadlessClaude({
+  workingDirectory: process.cwd(),
+  mcpServers: {
+    'weather-tools': weatherServer
+  },
+  allowedTools: [getToolName('weather-tools', 'get_weather')],
+  permissionMode: 'bypassPermissions'
+});
+
+const thread = await claude.startThread();
+const result = await thread.run("What's the weather in San Francisco? (37.7749, -122.4194)");
+console.log(result.text);
+```
+
+**Key Features:**
+- **Type-safe schemas** – Define input schemas with full TypeScript support
+- **Tool name management** – Use `getToolName(server, tool)` for proper MCP naming (`mcp__{server}__{tool}`)
+- **Selective permissions** – Control which tools Claude can use via `allowedTools`
+- **Streaming support** – Custom tools work seamlessly with `runStreamed()`
+- **Claude native** – Use Claude's native `tool()` and `createSdkMcpServer()` directly if preferred
+
+See `examples/src/claude-custom-tools.test.ts` for comprehensive examples including calculator, formatter, and multi-tool workflows.
+
+---
+
 ## ⚠️ Codex Adapter Runtime
 
 - The Codex adapter talks directly to the Codex CLI through Node APIs and **must run on the server**. It is safe to import in build tooling, but gate runtime usage to environments where `process.versions.node` exists.

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/core",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Unified SDK for headless AI coders (Codex, Claude, Gemini) with standardized threading, streaming, and sandboxing.",
   "type": "module",
   "main": "./dist/index.cjs",

packages/gemini-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/gemini-adapter",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -22,7 +22,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.25.0"
+    "@headless-coder-sdk/core": "^0.26.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",