feat(agent): one-shot ask_peer_claude (Phase-2 PR A)

[WiktorStarczewski]

Summary

First interactive tool of Phase 2: a calling Claude can spawn a parallel Claude session on a teammate's machine that reads / globs / greps the live filesystem. Returns a markdown transcript + {turnCount, toolCallCount, stopReason, elapsedMs}.

Off by default. A v0.1 install upgrading to this binary without --enable-agent behaves bit-for-bit like before.

This is PR A in the Phase-2 sequence (PR 0 merged in #6). PR B will add stateful conversations (start_peer_conversation / send_peer_message / etc.) on top of the same internal/agent/ package.

SDK-spike resolution

Plan called for verifying client.Beta.Sessions.* works as advertised before committing. Spike confirmed:

• ✅ The Managed-Agents API exists at anthropic-sdk-go v1.38.0 (released 2026-04-23, beta header managed-agents-2026-04-01 auto-applied by the SDK).
• ⚠️ The bundled agent_toolset_20260401 (which exposes read / glob / grep) executes inside an Anthropic-hosted Environment sandbox, not on Ivan's filesystem. The plan's whole point is for tools to read Ivan's box, so the bundled toolset is the wrong knob.
• ✅ Pivoted to custom tools + sync callback (Option 2 from the spike report). Define read/glob/grep as custom tools on BetaAgentNewParams. The session emits agent.custom_tool_use; we execute on Ivan's box and reply with user.custom_tool_result. Tools run on Ivan's machine; security posture is identical to what the plan originally specified.

Architecture

internal/agent/
├── agent.go          public types (Budget, Transcript, StopReason, ErrorSummary, Agent)
├── customtools.go    read / glob / grep handlers, sandboxed under the project root
├── loop.go           SDK-decoupled event loop (testable with canned events)
├── sdk.go            Managed-Agents wrapper: ensureInit + runOnce + pumpStream
├── audit.go          line-atomic JSONL audit log (sizes only, no content)
└── *_test.go

The adversarial defense (verification step 7a) has two legs:

• (a) buildCustomToolUnion() advertises only {read, glob, grep} as custom tools — never agent_toolset_20260401, never mcp_toolset. Asserted in sdk_test.go.
• (b) runEventLoop rejects any incoming agent.custom_tool_use for a name we didn't register, even if a compromised upstream emits one anyway. Asserted in loop_test.go (TestLoop_RejectsDisallowedTool).

Test plan

• go build ./... && go vet ./... — clean.
• go test ./... — green across all 9 packages.
• go test -race -coverpkg=./... -coverprofile=… — aggregate 90.4% (gate is 90%).
• Loop unit tests (loop_test.go): every StopReason enum value, budget exhaustion, disallowed-tool rejection, deadline timeout, shutdown cancellation, error categorization.
• Custom-tool unit tests (customtools_test.go): bounded reads, escape rejection, glob with **, grep skipping binary, max-results cap.
• Audit-log unit tests: line-atomic concurrent writes (20 goroutines × 50 lines each, all parse cleanly).
• SDK-translate unit tests (sdk_translate_test.go): every event type → LoopEvent, error / timeout paths via httptest stub.
• Tools-layer integration tests (tools_agent_test.go): ask_peer_claude only registered when ctx.Agent != nil, budget passes through, errors surface as isError: true.
• CLI tests (main_test.go): --enable-agent without ANTHROPIC_API_KEY refuses to start; --agent-api-key-env override works.
• End-to-end tests (hearsay_e2e_test.go): tool absent without flag, present with flag, binary refuses to start without key.
• Manual loopback against real Claude Code — covered separately as plan verification step 9. PR-A's automated tests prove the wiring; this PR doesn't bill the Anthropic API.

What this doesn't do (deferred to PR B)

• Stateful conversations (start_peer_conversation / send_peer_message / list_peer_conversations / end_peer_conversation).
• Conversation idle reaping, max-conversations cap.
• Full SDK-stubbed TestE2E_AskPeerClaude end-to-end (would require simulating the SSE event stream; loop-layer canned-event tests cover the same logic).