tools CLAUDE.md

CLAUDE.md — @agent-sh/harness-* monorepo

Guidance for Claude Code working on this repo. The repo builds LLM-facing agent tools (Read, Write, Grep, Glob, ...) as a TypeScript-first npm library, with Rust ports coming later. The tools are consumed by real language models inside agent harnesses — not by deterministic callers.

The prime directive: treat LLM tools as a chaotic distributed system, not as kernel code

The user is a systems software engineer (Valkey, CRIU, ElastiCache). These tools look like regular functions — typed inputs, typed outputs, clean error enums — but that framing is a trap. The consumer is a probabilistic model, so the contract is not "given these args, produce this output." The contract is:

Given only the tool's textual surface (name, description, schema field names, error messages, output shape, pagination hints), does a real model, across many families (Qwen, Llama, GPT, Claude, DeepSeek), pick this tool, call it correctly, interpret the result, and make good next moves — without giving up and falling back to Bash?

That is the spec. Everything else is implementation detail.

Why this matters — the failure modes that unit tests never catch

1. Description-driven misuse. An ambiguous parameter name (path vs file_path, limit vs max_lines) causes the model to pass the wrong thing. The code is fine. The tool is broken.
2. Unrecoverable errors. ENOENT with no context leaves the model stuck. A NOT_FOUND that lists sibling candidates lets it self-correct.
3. Ignored hints. The output says next_offset: 2000 but the model re-reads from 0 and loops. The pagination design is the failure.
4. Silent non-invocation. The model reads the description, decides the tool doesn't fit, and shells out to cat / grep / ls via Bash instead. You will not see this in any unit test. You will only see it when you log real sessions and notice your tool is never called.
5. Hallucinated output. The tool returns JSON the model misparses, so the model confidently reports content that was never in the file.
6. Tool-as-friction. A well-intentioned safety rail (sensitive-path deny, forced pagination, mandatory ledger confirmation) makes the tool annoying enough that the model routes around it. The user has shipped many tools and watched exactly this happen — "too many to count."