dive: Instructions file for Claude Code

CLAUDE.md

Project Overview

Dive is a Go library for building AI agents and integrating with leading LLMs. Library-first approach — the CLI in experimental/cmd/dive/ is secondary.

Commands

• go test ./... — Run all tests
• cd experimental/cmd/dive && go build — Build the CLI (optional)
• Use github.com/deepnoodle-ai/wonton/assert for all tests

Architecture

Core Types

• Agent (agent.go): Created via NewAgent(AgentOptions), returns *Agent. Manages tool execution and conversation.
• Extension (agent.go): Extension interface (Tools, Hooks, Rules) for composable agent capabilities. Set on AgentOptions.Extensions. Extensions provide tools, hooks, and system prompt rules that are merged during NewAgent.
• Session (dive.go): Session interface (ID, Messages, SaveTurn). Set on AgentOptions.Session or per-call via WithSession. The session package provides New() (in-memory) and store-backed implementations.
• LLM (llm/llm.go): LLM and StreamingLLM interfaces abstract over providers.
• Tool (tool.go): Tool and TypedTool[T] interfaces. FuncTool[T]() creates tools from functions with auto-generated schemas. Toolset interface provides dynamic tool resolution per LLM request. Tool panics are auto-recovered. All toolkit constructors return *dive.TypedToolAdapter[T] (satisfies dive.Tool). ToolDeclarer (DeclaredTools) marks a provider-defined toolset such as anthropic.ComputerToolset: calls route to the declared tools by name, which are left out of the request while the declarer is present. ToolAnnotations.HaltsBatch (automatic for calls with ToolsetName) runs a batch in order and answers later halting calls after a failure with an error, ToolCallResult.Error == ErrBatchHalted.
• Hooks (hooks.go): Hooks struct groups hook slices on AgentOptions. Hook types: SessionStartHook, PreGenerationHook, PostGenerationHook, PreToolUseHook, PostToolUseHook, PostToolUseFailureHook, StopHook, PreIterationHook, OnSuspendHook. All hooks receive *HookContext. PreToolUse hooks can set HookContext.UpdatedInput to rewrite the tool args. SessionStartHook fires once at the start of a fresh conversation (no prior messages, non-resume) and returns a *SessionStartResult to seed it (durable or ephemeral via Persist).
• Tracer (tracer.go): Tracer interface for observation (tracing, metrics, audit logging). Three methods (StartAgentRun, StartChat, StartToolCall) return (ctx, span); the agent threads ctx through downstream calls so spans nest naturally. NopTracer (default) and MultiTracer live in core; the OpenTelemetry adapter is otel.NewTracer in the dive/otel module.
• Turn outcome (outcome.go, turn.go): once the turn begins (just before PreGeneration), every exit goes through turn.end, which reads one turnRecord. An error exit returns (resp, err) with Status == ResponseStatusIncomplete, resp.Turn.Outcome classifying the error, and err wrapping *GenerationError{Response: resp}; a failed partial resume returns (nil, err). Response.Turn (messages saved, usage, outcome or suspension, Persistence) is set for every status, and ResponseItemTypeTurnEnded is the last item emitted. A tool batch that stops early (toolbatch.go) returns its partial batch; closeToolBatch answers each call it did not finish as not run or unknown, Outcome.ToolCalls records their states, and a parallel call still running gets a BackgroundTaskHandle for its late result. WithSoftCancel (softcancel.go) stops at the next step boundary. The loop reads each response's stop reason (llm.ClassifyStopReason): an output or context limit, a refusal, a provider stop and the iteration limit run no tool call, and a pause is resent. An incomplete turn is closed (closeturn.go: every call answered, a turn-incomplete reminder whose details hold the outcome), passed to OnIncompleteTurn hooks and saved; WithContinue picks it up; IncompleteTurns.Discard restores the old error behaviour. Every turn has an ID (TurnID(ctx)), a status and per-call states on Turn; a TurnStore session (Load, CheckpointTurn, revisions; session.Session is one, in session/turns.go) stores the record, and the agent saves through it in place of the other writes, folding a WithContinue into the open turn. Agent.CancelSuspendedTurn closes a suspended turn without a model call. DurabilityOptions (durability.go) adds step checkpoints (a running record at each model response and tool call; a turn found running on load is closed with process_exit) and session claims (SessionClaimer, session/claims.go) for several processes on one session. Design: docs/design/incomplete-turns.md.
• Suspend/Resume (tool.go, response.go, dive.go): A tool can pause the agent mid-turn by returning NewSuspendResult(prompt, metadata) or NewSuspendResultWithReason(prompt, reason, metadata) (sets ToolResult.Suspend). SuspendReason classifies why: SuspendReasonInput (default) or SuspendReasonAuth. CreateResponse returns (*Response, nil) with Status == ResponseStatusSuspended and Response.Suspension *SuspensionState. Resume via WithToolResults (session-backed) or WithResume(state, results) (stateless). SuspendableSession is an optional Session extension for auto-persistence; Agent.CancelSuspendedTurn closes a suspended turn and session.Session.RemoveLastTurn deletes one. A resent result already accepted is skipped (ErrConflictingToolResult if it differs); WithResumeRequest checks the turn ID and revision first. OnSuspend hooks fire before persistence. See docs/guides/suspend-resume.md.