Step-by-step, code-heavy guides for building AI agents.
61 posts
allowedTools auto-approves, tools restricts. That half is documented. What is not: an AgentDefinition has no allowedTools field, and the SDK forwards one verbatim to the CLI anyway, unvalidated.
A grep bisect tells you when today's code landed, not when the behaviour changed. Here is the argv-capture harness that dates it properly, and the worked example where grepping made a maintainer look wrong and running the versions proved him right.
The skills option validates every name before the session starts, and its wildcard guard tests for exactly two endings. Eight of eleven wildcard shapes get through, become a Skill(name) rule that names no skill, and say nothing. Measured first-party on 0.3.272, with the bisect.
Since @anthropic-ai/claude-agent-sdk 0.3.257 a malformed hook entry is deleted from settings.json and the rest of the file loads normally, so the hook just never runs. PreToolUse and PermissionRequest are the two exceptions, where the whole file is voided. Bisected against 0.3.252, with a runnable detector.
npm error notarget No matching version found for @anthropic-ai/sdk means you asked for a major that does not exist. Anthropic ships two SDKs on unrelated version lines: Python is on 1.5.0, npm has never left 0.x. Read from both registries, with the caret trap that follows.
TypeError: Invalid http_client argument means the anthropic Python SDK moved to httpx2 in 1.0.0. The rename is one import. The parts nobody mentions are that the guard printing that message only exists from 1.4.0, and that it cannot see your respx or OpenTelemetry layer at all (2026).
ImportError: cannot import name 'streamablehttp_client' means pip resolved MCP Python SDK 2.x against v1 client code. The rename is one underscore. The part nobody mentions is that passing your own httpx2 client silently drops the 300 second read timeout to 5 (2026).
Set _meta["anthropic/requiresUserInteraction"] to true and Claude Code prompts for that tool on every call, even in bypassPermissions, and even when an allow rule matches. It shipped in v2.1.199 with no changelog entry, which is why almost nobody has written about it.
Claude Code v2.1.260 narrowed strict sandbox mode so it no longer covers commands you type at the ! prompt. Anthropic documents two exceptions the changelog never mentions, and the variable that closes the gap is filed under credential scrubbing.
Claude Code v2.1.251 stopped project settings setting CLAUDE_CODE_TMPDIR, CLAUDE_CONFIG_DIR, HOME, TMPDIR and the XDG family from a .claude/settings.json env block. Nothing errors. Here is the full ignore list, the four scopes it splits into, and the debug flag that shows you the drop.
keybindingFlavor is deprecated and inert in Claude Code v2.1.261 and later. The readline word-editing behaviour it gated is now on for everyone. Ctrl+W deletes back to whitespace while the Alt keys stop at punctuation, and neither can be rebound: the keybindings reference documents 115 actions and none of them is a word-editing action.
permissions.blockReadsOutsideWorkingDirectories blocks reads outside your working directories in every permission mode, including bypassPermissions. Writing false does not turn it off, because the key is a logical OR across all settings sources. Plus the 53-hour macOS defect window, dated from the npm registry.
