diff --git a/extensions/copilot/.claude/CLAUDE.md b/extensions/copilot/.claude/CLAUDE.md index 999ceec9d4c..4867fb2c18d 100644 --- a/extensions/copilot/.claude/CLAUDE.md +++ b/extensions/copilot/.claude/CLAUDE.md @@ -1,35 +1,7 @@ -# Claude Agent SDK Documentation Index +# Claude Instructions ## General Repository Instructions -ALWAYS read [.github/copilot-instructions.md](../.github/copilot-instructions.md) -## Getting Started -- [Overview](https://platform.claude.com/docs/en/agent-sdk/overview) - Learn about the Agent SDK architecture and core concepts -- [Quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart) - Get up and running with your first agent in minutes +For all repository instructions, coding standards, and development guidelines, **ALWAYS** read: -## Core SDK Implementation -- [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) - Main TypeScript SDK reference for building agents -- [TypeScript v2 Preview](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) - Preview of upcoming v2 API with enhanced features -- [Streaming vs Single Mode](https://platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode) - Choose between streaming responses or single-turn completions - -## User Interaction & Control -- [Permissions](https://platform.claude.com/docs/en/agent-sdk/permissions) - Control what actions Claude can take with user approval flows -- [User Input](https://platform.claude.com/docs/en/agent-sdk/user-input) - Collect clarifications and decisions from users during execution -- [Hooks](https://platform.claude.com/docs/en/agent-sdk/hooks) - Execute custom logic at key points in the agent lifecycle - -## State & Session Management -- [Sessions](https://platform.claude.com/docs/en/agent-sdk/sessions) - Manage conversation history and context across interactions -- [File Checkpointing](https://platform.claude.com/docs/en/agent-sdk/file-checkpointing) - Save and restore file states for undo/redo functionality - -## Advanced Features -- [Structured Outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs) - Get reliable JSON responses with schema validation -- [Modifying System Prompts](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts) - Customize Claude's behavior and instructions -- [MCP](https://platform.claude.com/docs/en/agent-sdk/mcp) - Connect to Model Context Protocol servers for extended capabilities -- [Custom Tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools) - Build your own tools to extend Claude's functionality - -## Agent Composition & UX -- [Subagents](https://platform.claude.com/docs/en/agent-sdk/subagents) - Compose complex workflows by delegating to specialized agents -- [Slash Commands](https://platform.claude.com/docs/en/agent-sdk/slash-commands) - Add custom `/commands` for quick actions -- [Skills](https://platform.claude.com/docs/en/agent-sdk/skills) - Package reusable agent capabilities as installable modules -- [Todo Tracking](https://platform.claude.com/docs/en/agent-sdk/todo-tracking) - Help Claude manage and display task progress -- [Plugins](https://platform.claude.com/docs/en/agent-sdk/plugins) - Extend the SDK with community-built integrations \ No newline at end of file +**[.github/copilot-instructions.md](../.github/copilot-instructions.md)** \ No newline at end of file diff --git a/extensions/copilot/.github/copilot-instructions.md b/extensions/copilot/.github/copilot-instructions.md index e74be93d5f2..d6ec104a696 100644 --- a/extensions/copilot/.github/copilot-instructions.md +++ b/extensions/copilot/.github/copilot-instructions.md @@ -275,7 +275,7 @@ The extension uses numerous proposed VS Code APIs for advanced functionality: - **GitHub**: Authentication and API access - **Azure**: Cloud services and experimentation - **OpenAI**: Language model API -- **Anthropic**: Claude model integration +- **Anthropic**: Claude model integration - See **[src/extension/agents/claude/AGENTS.md](../src/extension/agents/claude/AGENTS.md)** for complete Claude Agent SDK integration documentation including architecture, components, and registries - **Telemetry**: Usage analytics and performance monitoring ## Development Workflow diff --git a/extensions/copilot/src/extension/agents/claude/AGENTS.md b/extensions/copilot/src/extension/agents/claude/AGENTS.md index f8c1f5f6fb7..08457669e1f 100644 --- a/extensions/copilot/src/extension/agents/claude/AGENTS.md +++ b/extensions/copilot/src/extension/agents/claude/AGENTS.md @@ -2,7 +2,7 @@ This folder contains the Claude Code integration for VS Code Chat. It enables users to open a new Chat window and interact with a Claude Code instance directly within VS Code. **VS Code provides the UI, Claude Code provides the smarts.** -## Official Documentation +## Official Claude Agent SDK Documentation > **Important:** For the most up-to-date information on the Claude Agent SDK, always refer to the official documentation: > @@ -13,6 +13,39 @@ This folder contains the Claude Code integration for VS Code Chat. It enables us > > The SDK package is `@anthropic-ai/claude-agent-sdk`. The official documentation covers tools, hooks, subagents, MCP integration, permissions, sessions, and more. +### Core SDK Features + +**Getting Started:** +- [Overview](https://platform.claude.com/docs/en/agent-sdk/overview) - Learn about the Agent SDK architecture and core concepts +- [Quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart) - Get up and running with your first agent in minutes + +**Core SDK Implementation:** +- [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) - Main TypeScript SDK reference for building agents +- [TypeScript v2 Preview](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) - Preview of upcoming v2 API with enhanced features +- [Streaming vs Single Mode](https://platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode) - Choose between streaming responses or single-turn completions + +**User Interaction & Control:** +- [Permissions](https://platform.claude.com/docs/en/agent-sdk/permissions) - Control what actions Claude can take with user approval flows +- [User Input](https://platform.claude.com/docs/en/agent-sdk/user-input) - Collect clarifications and decisions from users during execution +- [Hooks](https://platform.claude.com/docs/en/agent-sdk/hooks) - Execute custom logic at key points in the agent lifecycle + +**State & Session Management:** +- [Sessions](https://platform.claude.com/docs/en/agent-sdk/sessions) - Manage conversation history and context across interactions +- [File Checkpointing](https://platform.claude.com/docs/en/agent-sdk/file-checkpointing) - Save and restore file states for undo/redo functionality + +**Advanced Features:** +- [Structured Outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs) - Get reliable JSON responses with schema validation +- [Modifying System Prompts](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts) - Customize Claude's behavior and instructions +- [MCP](https://platform.claude.com/docs/en/agent-sdk/mcp) - Connect to Model Context Protocol servers for extended capabilities +- [Custom Tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools) - Build your own tools to extend Claude's functionality + +**Agent Composition & UX:** +- [Subagents](https://platform.claude.com/docs/en/agent-sdk/subagents) - Compose complex workflows by delegating to specialized agents +- [Slash Commands](https://platform.claude.com/docs/en/agent-sdk/slash-commands) - Add custom `/commands` for quick actions +- [Skills](https://platform.claude.com/docs/en/agent-sdk/skills) - Package reusable agent capabilities as installable modules +- [Todo Tracking](https://platform.claude.com/docs/en/agent-sdk/todo-tracking) - Help Claude manage and display task progress +- [Plugins](https://platform.claude.com/docs/en/agent-sdk/plugins) - Extend the SDK with community-built integrations + ## Overview The Claude Code integration allows VS Code's chat interface to communicate with Claude Code, Anthropic's agentic coding assistant. When a user sends a message in a VS Code Chat window using this integration, the message is routed to a Claude Code session that can: @@ -144,6 +177,116 @@ Unit tests are located in `node/test/`: - `mockClaudeCodeSdkService.ts`: Mock SDK service for testing - `fixtures/`: Sample `.jsonl` session files for testing +## Extension Registries + +The Claude integration uses several registries to organize and manage extensibility points: + +### Hook Registry + +**Location:** `node/hooks/claudeHookRegistry.ts` + +The hook registry allows registering custom hooks that execute at key points in the agent lifecycle. Hooks are organized by `HookEvent` type from the Claude SDK. + +**Key Features:** +- Register handlers using `registerClaudeHook(hookEvent, ctor)` +- Handlers are constructed via dependency injection using `IInstantiationService` +- Hook instances are built from the registry and passed to the Claude SDK +- Multiple handlers can be registered for the same event + +**Example Hook Events:** +- `'PreToolUse'` - Before a tool is executed +- `'PostToolUse'` - After a tool completes +- `'SubagentStart'` - When a subagent starts +- `'SubagentEnd'` - When a subagent completes +- `'SessionStart'` - When a session begins +- `'SessionEnd'` - When a session ends + +**Current Hook Handlers:** +- `loggingHooks.ts` - Logging hooks for debugging and telemetry +- `sessionHooks.ts` - Session lifecycle management +- `subagentHooks.ts` - Subagent lifecycle tracking +- `toolHooks.ts` - Tool execution tracking and processing + +### Slash Command Registry + +**Location:** `vscode-node/slashCommands/claudeSlashCommandRegistry.ts` + +The slash command registry manages custom slash commands available in Claude chat sessions. Commands allow users to trigger specific functionality via `/commandname` syntax. + +**Key Features:** +- Register handlers using `registerClaudeSlashCommand(handler)` +- Each handler implements `IClaudeSlashCommandHandler` interface +- Commands can optionally register with VS Code Command Palette +- Handlers receive arguments, response stream, and cancellation token + +**Handler Interface:** +```typescript +interface IClaudeSlashCommandHandler { + readonly commandName: string; // Command name (without /) + readonly description: string; // Human-readable description + readonly commandId?: string; // Optional VS Code command ID + handle(args: string, stream: ChatResponseStream | undefined, token: CancellationToken): Promise; +} +``` + +**Current Slash Commands:** +- `/hooks` - Display information about registered hooks (from `hooksCommand.ts`) +- `/memory` - Memory management commands (from `memoryCommand.ts`) + +### Tool Permission Handlers + +**Location:** `node/toolPermissionHandlers/` and `common/toolPermissionHandlers/` + +Tool permission handlers control what actions Claude can take without user confirmation. They define the approval logic for various tool operations. + +**Key Features:** +- Auto-approve safe operations (e.g., file edits within workspace) +- Request user confirmation for potentially dangerous operations +- Handlers are organized by platform (common, node, vscode-node) + +**Handler Types:** +- **Common handlers** (`common/toolPermissionHandlers/`): + - `bashToolHandler.ts` - Controls bash/shell command execution + - `exitPlanModeHandler.ts` - Manages plan mode transitions + +- **Node handlers** (`node/toolPermissionHandlers/`): + - `editToolHandler.ts` - Handles file edit operations (Edit, Write, MultiEdit) + +- **VS Code-Node handlers** (`vscode-node/toolPermissionHandlers/`): + - `askUserQuestionHandler.ts` - Handles user question prompts via VS Code QuickPick UI + +**Auto-approval Rules:** +- File edits are auto-approved if the file is within the workspace +- All other tools show a confirmation dialog via VS Code's chat API +- User denials send appropriate messages back to Claude + +**Extending the Registries:** + +To add new functionality: + +1. **New Hook Handler:** + - Create a class implementing `HookCallbackMatcher` + - Call `registerClaudeHook(hookEvent, YourHandler)` at module load time + - Import your handler module in `node/hooks/index.ts` + +2. **New Slash Command:** + - Create a class implementing `IClaudeSlashCommandHandler` + - Call `registerClaudeSlashCommand(YourHandler)` at module load time + - Import your command module in `vscode-node/slashCommands/index.ts` + - If providing a `commandId`, register the command in `package.json`: + ```json + { + "command": "copilot.claude.yourCommand", + "title": "Your Command Title", + "category": "Claude Agent" + } + ``` + +3. **New Tool Permission Handler:** + - Create handler in appropriate directory (common/node/vscode-node) + - Implement tool approval logic + - Import your handler module in `index.ts` to trigger registration + ## Configuration The integration respects VS Code settings: