Add Claude API behavioral guide: undocumented protocol observations from 95K+ messages

[heath-hunnicutt-ruach-tov]

What

Community-contributed documentation of undocumented behaviors, edge cases, and protocol nuances for the Claude Messages API.

Why

The existing content/anthropic/docs/claude-api entry covers SDK usage (initialization, basic inference, tool use syntax). This new entry complements it with operational knowledge — the things you only learn after processing tens of thousands of messages through the API.

These observations prevent subtle bugs that waste developer time and API credits.

Content Summary (351 lines, under 500-line limit)

1. Message Structure Constraints — Tool result ordering, role alternation rules, text-after-tool-results bug
2. Token Counting Edge Cases — System prompt token accounting, tool definition overhead, thinking token budget behavior
3. Streaming Protocol — input_json delta accumulation, event ordering guarantees, content_block_stop semantics
4. Tool Use Protocol — tool_use_id format requirements, multi-tool response handling, is_error behavior
5. Error Handling & Rate Limiting — Overloaded errors (529), retry-after header, input validation error patterns
6. System Prompt Effects — Behavioral modulation patterns, cache_control placement
7. Context Window Management — Progressive summarization patterns, spill-to-disk strategies

Source

Ruach Tov — An open research collective for human-AI collaboration. These observations come from building and operating dibbur, a multi-agent conversation engine (6+ AI agents, multiple model providers).

Placement

content/anthropic/docs/claude-api-behavioral/DOC.md — alongside the existing claude-api SDK doc, with a distinct name reflecting its focus on behavioral observations rather than SDK usage.

Checklist

• YAML frontmatter with name, description, metadata (languages, versions, source, tags, updated-on)
• Under 500 lines (351 lines)
• Source marked as community
• Practical code examples throughout
• Progressive disclosure structure
• MIT license compatible