Claude Agent SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Agent SDK is a core integration component within TDD Guard that enables the application to communicate with Anthropic's AI models specifically designed for agentic workflows. It serves as one of the primary IModelClient implementations, allowing the system to send formatted TDD context and prompts to Claude for validation decisions.
This module is essential for the "Analyze" and "Validate" phases of the TDD Guard workflow. It intercepts file operations (Edit, MultiEdit, Write) and uses the @anthropic-ai/claude-agent-sdk to determine if the proposed changes adhere to Test-Driven Development principles.
Sources: CLAUDE.md:8-13, src/validation/models/ClaudeAgentSdk.test.ts:13-16
Architecture and Integration
The Claude Agent SDK module is structured as a TypeScript class that implements the IModelClient interface. It is managed by the ModelClientProvider, which instantiates it when the configuration specifies sdk as the validation client.
The SDK integration is designed to be highly configurable, accepting an optional Config object and an injectable query function for testing or custom behavior.
Sources: src/validation/models/ClaudeAgentSdk.test.ts:11-37, src/providers/ModelClientProvider.test.ts:31-38
Query Configuration and Security
When invoking a query through the Claude Agent SDK, TDD Guard applies strict configurations to ensure the model behaves predictably as a validator rather than a general-purpose agent.
Restricted Tool Usage
To prevent the validation model from inadvertently performing file system modifications or side effects, the SDK client explicitly disables all tools. This creates a "sandboxed" environment for the validation logic.
| Configuration | Value | Purpose |
|---|---|---|
maxTurns | 1 | Ensures single-shot validation without multi-turn loops |
allowedTools | [] | Blocks all tool usage |
disallowedTools | ['Read', 'Edit', 'MultiEdit', 'Write', ...] | Specifically prevents recursive file operations |
maxThinkingTokens | 0 | Disables extended reasoning for faster response |
strictMcpConfig | true | Enforces strict Model Context Protocol settings |
cwd | config.dataDir | Isolates operations to the TDD Guard data directory |
Sources: src/validation/models/ClaudeAgentSdk.test.ts:60-99
Execution Flow
The following diagram illustrates how the ClaudeAgentSdk handles a validation request.
Dependency Management
The module relies on specific external libraries defined in the project's dependency manifest.
- @anthropic-ai/claude-agent-sdk: The primary library providing the
queryfunction and SDK types. - zod: Used for runtime validation of configurations and potentially model responses.
- Config: A local module that provides model versions (defaulting to
claude-sonnet-4-0) and API keys.
Sources: package.json:58-64, src/config/Config.ts:14-16
Error Handling
The SDK implementation includes robust error handling to prevent the validation process from failing silently. It distinguishes between API-level errors and empty responses:
- Subtype Errors: If the SDK returns a subtype like
error_max_turns, the client throws a specificClaude Agent SDK error. - Missing Results: If no result message is received, it throws a "No result message received" error.
- Validator Interception: The higher-level
validatorcatches these errors and defaults to ablockdecision to ensure no unvalidated code is committed.
Sources: src/validation/models/ClaudeAgentSdk.test.ts:113-125, src/validation/validator.test.ts:173-180
Conclusion
The Claude Agent SDK module provides a secure, single-turn interface for TDD validation. By strictly controlling the available tools and environment settings, it ensures that the AI model acts as a focused auditor of TDD principles without the risk of unintended side effects or excessive token consumption.