Documentation
¶
Overview ¶
Package claudesession implements agent.Adapter for Claude Code with deterministic session-id reuse (anthropic/claude-code-session). It is the PersistentSession counterpart to agent/claude (which is the fresh-per-launch, gate-safe adapter).
Design (M2 + the 2026-06-26 native-config-isolation revision):
- Session UUID is deterministic: sha256(runID|epoch|nodePath), first 16 bytes formatted as a UUID string. Same inputs → same UUID; different nodePath → different UUID. It is passed to claude's --session-id / --resume.
- Reuses the base claude.Adapter for all shared logic (env, backend, version, stream parsing). Launch appends --session-id <uuid> and drops --no-session-persistence so claude records the session journal.
- Per-run isolation: the engine computes a per-run CLAUDE_CONFIG_DIR (<staging-root>/claude-session/<run-id>) and threads it via inv.SessionConfigDir; Launch sets it on the exec env so claude relocates its whole config tree per run. The engine captures/restores the <CLAUDE_CONFIG_DIR>/projects subtree as the SessionRef (no path derivation here — the adapter no longer computes a transcript path).
- Capabilities(): NativeSchema:true, PersistentSession:true.
- The adapter is a container-backed CLI adapter (NOT Containerless) — subtree capture requires a container filesystem.
Index ¶
- Constants
- Variables
- type Adapter
- func (*Adapter) Capabilities() agent.Caps
- func (a *Adapter) Launch(ctx context.Context, handle container.Handle, inv agent.AgentInvocation) (<-chan agent.AgentEvent, <-chan agent.AgentOutcome, error)
- func (a *Adapter) PreflightResume(_ context.Context, _ agent.LiveResumePreflightRequest) error
- func (*Adapter) Ref() string
- func (*Adapter) RequiredEnv() []string
- func (a *Adapter) ValidateConfig(with ir.RawConfig) error
- func (a *Adapter) Version(ctx context.Context, handle container.Handle) (string, error)
- type ErrBareRequiresAPIKey
- type Option
Constants ¶
const AdapterRef = "anthropic/claude-code-session"
AdapterRef is the agent-runtime identifier this package's Adapter returns from Ref(). Constant so cli/agent_registry.go and unit tests can refer to it without typing the string literal.
Variables ¶
var DefaultEnvAllowlist = []string{
"ANTHROPIC_API_KEY",
"ANTHROPIC_AUTH_TOKEN",
"CLAUDE_CODE_OAUTH_TOKEN",
}
DefaultEnvAllowlist is the same credential set as agent/claude since claude-code-session launches the same `claude -p` binary with the same auth environment. Single source of truth for cli/agent_registry.go's adapterEnvAllowlists entry and the integ tests' skipIfNoAuthEnv helper.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter is the agent.Adapter implementation for Claude Code with deterministic session-id reuse. It wraps a *claude.Adapter for shared functionality (env passthrough, backend wiring, version, stream parsing) and adds:
- Capabilities().PersistentSession = true
- --session-id <deterministic-uuid> injected into every launch command
- --no-session-persistence is OMITTED (so the session journal is recorded under the per-run CLAUDE_CONFIG_DIR the engine injects via inv.SessionConfigDir)
The base *claude.Adapter is a named field (not embedded) used for delegation; Launch is overridden because the command construction differs (session-id flag, no --no-session-persistence). All other methods delegate to the base.
func New ¶
New constructs an Adapter. The base *claude.Adapter is constructed with the same env and backend options so that all shared logic (Version, stream parsing, env redaction) is delegated there.
func (*Adapter) Capabilities ¶
Capabilities returns Caps{NativeSchema: true, PersistentSession: true}. Not Containerless — this adapter requires a container (like the base claude adapter). Gate independence is enforced by the engine's PR0a guard that rejects PersistentSession adapters in gate.evaluate.
func (*Adapter) Launch ¶
func (a *Adapter) Launch(ctx context.Context, handle container.Handle, inv agent.AgentInvocation) (<-chan agent.AgentEvent, <-chan agent.AgentOutcome, error)
Launch runs `claude -p ... --session-id <uuid>` inside handle. It uses the same streaming Backend.Exec / io.Pipe / bufio.Scanner pattern as the base claude.Adapter.Launch (copied here because the command construction differs and the base launch function is not exported).
Key differences from base claude.Adapter.Launch:
- --session-id <sessionUUID(inv)> is appended
- --no-session-persistence is OMITTED (so Claude records the session)
func (*Adapter) PreflightResume ¶
PreflightResume is a no-op for now — session restore is driven by the engine's content-addressed SessionRef (transcript blob), not a live provider session, so there is nothing to preflight at this stage. Real preflight logic (if any) lands with the live-integration task (M2d).
func (*Adapter) RequiredEnv ¶
RequiredEnv implements agent.CredentialNamer.
func (*Adapter) ValidateConfig ¶
ValidateConfig enforces the same with-schema as the claude adapter (it accepts the same keys), but ALLOWS session_id / continue / resume — those keys are managed internally by the adapter via the deterministic UUID, not by the workflow author. Unknown keys and missing prompt are still rejected.
The difference from the base adapter: session reuse keys are NOT rejected (since this adapter IS the session adapter). We therefore reimplement validation rather than delegating to avoid the ErrSessionReuseAttempted path in the base.
type ErrBareRequiresAPIKey ¶
type ErrBareRequiresAPIKey struct {
AvailableKeys []string
}
ErrBareRequiresAPIKey is returned by ValidateConfig when `with.bare` is true but neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is present in the adapter's env allowlist. Mirrors the error from agent/claude for this adapter's Ref.
func (*ErrBareRequiresAPIKey) Error ¶
func (e *ErrBareRequiresAPIKey) Error() string
type Option ¶
type Option func(*Adapter)
Option configures the Adapter at construction time.
func WithBackend ¶
WithBackend supplies the container.Backend used for Version and Launch.
Source Files