Claude Code Harness Pattern 2: Tool Architecture and the Tool Contract

Key Takeaways

• Tool interface defines contract between model and harness
• Zod schemas enforce type‑safe input validation
• Behavioral flags enable concurrency safety and permission checks
• BuildTool factory standardizes tool creation
• Search hints improve model tool discovery

Summary

The post dissects Claude Code’s Tool architecture, focusing on the comprehensive Tool interface that governs how language models invoke external capabilities. It explains each field—from identity attributes like name and aliases to execution logic, Zod‑based schemas, concurrency safety, and permission checks—illustrating how the contract ensures safe, predictable tool usage. The article also highlights auxiliary features such as search hints, dynamic descriptions, and the buildTool factory that streamlines new tool creation. By the end, readers understand how to design tools that are both powerful and securely constrained within the harness.

Pulse Analysis

In modern agentic AI systems, the bridge between a language model’s textual reasoning and concrete actions is the tool layer. By abstracting capabilities—file I/O, web searches, command execution—into discrete, contract‑driven components, developers separate model cognition from operational safety. This separation allows the model to focus on planning while the harness validates inputs, enforces permissions, and manages execution, dramatically reducing the risk of unintended side effects in production environments.

Claude Code’s Tool interface exemplifies this disciplined approach. Each tool declares a name, optional aliases, and a concise search hint, enabling the harness to resolve calls efficiently. Input validation leverages Zod schemas, guaranteeing type safety before any operation runs. Behavioral methods such as isConcurrencySafe and isReadOnly inform the orchestrator whether tools can run in parallel or modify state, while interruptBehavior and permission checks provide granular control over potentially destructive actions. The call method’s rich context—including progress callbacks and parent message tracing—ensures transparent, observable execution pipelines.

For developers, the standardized buildTool factory and uniform interface mean new capabilities can be added without touching core harness code. This modularity accelerates iteration, supports dynamic tool discovery, and aligns with enterprise compliance requirements. As AI agents become more embedded in business workflows, adhering to a well‑defined tool contract will be essential for scaling safe, reliable automation across diverse domains.