TAP-1988: opt into Tool Search BETA in build_claude_command

[wtthornton]

Summary

TAP-1988 — Without the advanced-tool-use-2025-11-20 Anthropic beta header, the API hides every tool annotated defer_loading: true from the catalog entirely — the agent has no way to discover or fetch them via Tool Search. Adding the header turns deferral into "lazy load on demand," which is the recovery path the deferred-loading work in the parent TAP-1983 epic depends on.

build_claude_command now exports ANTHROPIC_BETA before every Claude CLI invocation (read by the Anthropic SDK, forwarded as the anthropic-beta HTTP header). Behavior is operator-friendly:

• Default on: RALPH_BETA_TOOL_SEARCH=true (unset = true) → header exported.
• Escape hatch: RALPH_BETA_TOOL_SEARCH=false → no export.
• Compose-safe: an operator-set ANTHROPIC_BETA="some-other-beta" is preserved; the tool-search token is appended with a comma. If the token is already present, the env var is left untouched (no duplication across repeated build_claude_command calls).

templates/ralphrc.template gains an "ANTHROPIC BETA FEATURES" section documenting the override.

Test plan

• bats tests/unit/test_build_claude_command.bats — 6 cases pass: default-on export, RALPH_BETA_TOOL_SEARCH=false skip, operator-set value preserved + appended, no-duplication across repeated calls, already-present-token noop, ralphrc.template documents the override
• bats tests/unit/test_plan_mode_high_risk.bats — 13 cases pass (no regression in the other build_claude_command surface area)
• bats tests/unit/test_hooks.bats — 94 cases pass (HOOKS-6 build_claude_command --agent assertions still green)
• Operator validation: one end-to-end Ralph loop demonstrates a deferred tool getting fetched via Tool Search (AC requires; defer to operator run since Tool Search depends on tools that ship in later TAP-1983 stories)

🤖 Generated with Claude Code