Add files using upload-large-folder tool

internal/agent/.env.sample

@@ -0,0 +1,5 @@
+CRUSH_ANTHROPIC_API_KEY=
+CRUSH_HYPER_API_KEY=
+CRUSH_OPENAI_API_KEY=
+CRUSH_OPENROUTER_API_KEY=
+CRUSH_ZAI_API_KEY=

internal/agent/accepted_run_test.go

@@ -0,0 +1,231 @@
+package agent
+
+import (
+	"context"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// newCancelTestAgent builds a DB-backed sessionAgent with no model. The
+// tests here exercise the dispatch/cancel/persist paths, none of which
+// reach agent.Stream, so a model is unnecessary.
+func newCancelTestAgent(t *testing.T) (*sessionAgent, fakeEnv) {
+	t.Helper()
+	env := testEnv(t)
+	sa := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+	return sa, env
+}
+
+func (a *sessionAgent) acceptedCount(sessionID string) int {
+	c, _ := a.acceptedRuns.Get(sessionID)
+	return c
+}
+
+func (a *sessionAgent) hasPendingCancel(sessionID string) bool {
+	mark, ok := a.cancelMark.Get(sessionID)
+	return ok && mark > 0
+}
+
+func (a *sessionAgent) pendingCancelMark(sessionID string) uint64 {
+	mark, _ := a.cancelMark.Get(sessionID)
+	return mark
+}
+
+func TestAcceptedRun_CloseIsIdempotent(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	accept := sa.BeginAccepted("sid")
+	require.Equal(t, "sid", accept.SessionID())
+	require.Equal(t, 1, sa.acceptedCount("sid"))
+
+	accept.Close()
+	require.Equal(t, 0, sa.acceptedCount("sid"))
+
+	// Repeated Close must not underflow the counter.
+	accept.Close()
+	accept.Close()
+	require.Equal(t, 0, sa.acceptedCount("sid"))
+}
+
+func TestAcceptedRun_MultipleReservations(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	a1 := sa.BeginAccepted("sid")
+	a2 := sa.BeginAccepted("sid")
+	require.Equal(t, 2, sa.acceptedCount("sid"))
+
+	a1.Close()
+	require.Equal(t, 1, sa.acceptedCount("sid"))
+
+	a2.Close()
+	require.Equal(t, 0, sa.acceptedCount("sid"))
+}
+
+func TestAcceptedRun_NilSafe(t *testing.T) {
+	t.Parallel()
+	var accept *AcceptedRun
+	require.Equal(t, "", accept.SessionID())
+	// Must not panic.
+	accept.Close()
+}
+
+func TestCancel_IdleDoesNotRecordPendingCancel(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	// No accepted run, no active request: a true no-op.
+	sa.Cancel("sid")
+	require.False(t, sa.hasPendingCancel("sid"))
+}
+
+func TestCancel_AcceptedRecordsPendingCancel(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	accept := sa.BeginAccepted("sid")
+	defer accept.Close()
+
+	sa.Cancel("sid")
+	require.True(t, sa.hasPendingCancel("sid"))
+}
+
+func TestCancel_SecondCancelWhilePendingIsNoOp(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	accept := sa.BeginAccepted("sid")
+	defer accept.Close()
+
+	sa.Cancel("sid")
+	require.True(t, sa.hasPendingCancel("sid"))
+
+	// A second cancel while a pending cancel is already recorded must
+	// remain a single pending cancel; one Run consumes exactly one.
+	sa.Cancel("sid")
+	require.True(t, sa.hasPendingCancel("sid"))
+}
+
+func TestRun_CancelOnEntryPersistsCanceledTurn(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	accept := sa.BeginAccepted(sess.ID)
+	// A cancel arrives in the accepted-but-not-yet-active window.
+	sa.Cancel(sess.ID)
+	require.True(t, sa.hasPendingCancel(sess.ID))
+
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "hello",
+		Accepted:  accept,
+	})
+	require.NoError(t, err)
+	require.Nil(t, result)
+
+	// The pending cancel was consumed and the accept released.
+	require.False(t, sa.hasPendingCancel(sess.ID))
+	require.Equal(t, 0, sa.acceptedCount(sess.ID))
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.User, msgs[0].Role)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonCanceled, msgs[1].FinishReason())
+}
+
+func TestPersistCanceledTurn_WritesBothWhenUserMissing(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	err = sa.persistCanceledTurn(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "hello",
+	}, false)
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.User, msgs[0].Role)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonCanceled, msgs[1].FinishReason())
+}
+
+func TestPersistCanceledTurn_WritesAssistantOnlyWhenUserCreated(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// Simulate PrepareStep having already created the user message.
+	_, err = sa.createUserMessage(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "hello",
+	})
+	require.NoError(t, err)
+
+	err = sa.persistCanceledTurn(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "hello",
+	}, true)
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.User, msgs[0].Role)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonCanceled, msgs[1].FinishReason())
+}
+
+func TestPersistCanceledTurn_SucceedsWithCanceledContext(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// Simulate workspace shutdown having already canceled the run
+	// context. WithoutCancel must let the writes through.
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	err = sa.persistCanceledTurn(ctx, SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "hello",
+	}, false)
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+}
+
+func TestClearPendingCancel(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	accept := sa.BeginAccepted("sid")
+	defer accept.Close()
+	sa.Cancel("sid")
+	require.True(t, sa.hasPendingCancel("sid"))
+
+	sa.clearPendingCancel("sid")
+	require.False(t, sa.hasPendingCancel("sid"))
+}

internal/agent/agent.go

@@ -0,0 +1,2331 @@
+// Package agent is the core orchestration layer for Crush AI agents.
+//
+// It provides session-based AI agent functionality for managing
+// conversations, tool execution, and message handling. It coordinates
+// interactions between language models, messages, sessions, and tools while
+// handling features like automatic summarization, queuing, and token
+// management.
+package agent
+
+import (
+	"cmp"
+	"context"
+	_ "embed"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"math"
+	"net/http"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"charm.land/fantasy/providers/anthropic"
+	"charm.land/fantasy/providers/bedrock"
+	"charm.land/fantasy/providers/google"
+	"charm.land/fantasy/providers/openai"
+	"charm.land/fantasy/providers/openrouter"
+	"charm.land/fantasy/providers/vercel"
+	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/crush/internal/agent/hyper"
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/charmbracelet/crush/internal/stringext"
+	"github.com/charmbracelet/crush/internal/version"
+	"github.com/charmbracelet/x/ansi"
+	"github.com/charmbracelet/x/exp/charmtone"
+)
+
+const (
+	DefaultSessionName = "Untitled Session"
+
+	// Constants for auto-summarization thresholds
+	largeContextWindowThreshold = 200_000
+	largeContextWindowBuffer    = 20_000
+	smallContextWindowRatio     = 0.2
+)
+
+var userAgent = fmt.Sprintf("Charm-Crush/%s (https://charm.land/crush)", version.Version)
+
+//go:embed templates/title.md
+var titlePrompt []byte
+
+//go:embed templates/summary.md
+var summaryPrompt []byte
+
+// Used to remove <think> tags from generated titles.
+var (
+	thinkTagRegex       = regexp.MustCompile(`(?s)<think>.*?</think>`)
+	orphanThinkTagRegex = regexp.MustCompile(`</?think>`)
+)
+
+type SessionAgentCall struct {
+	SessionID string
+	// RunID, when non-empty, is the caller-supplied correlator that
+	// gets echoed back on the notify.RunComplete event emitted for
+	// this turn. It is preserved when the call is enqueued behind a
+	// busy session so the queued turn's terminal event is still
+	// recognisable to the original caller. Callers that need a
+	// reliable completion contract (e.g. `crush run` against a
+	// session that may be busy) MUST set it; SessionID alone is
+	// ambiguous when concurrent turns share the same session.
+	RunID            string
+	Prompt           string
+	ProviderOptions  fantasy.ProviderOptions
+	Attachments      []message.Attachment
+	MaxOutputTokens  int64
+	Temperature      *float64
+	TopP             *float64
+	TopK             *int64
+	FrequencyPenalty *float64
+	PresencePenalty  *float64
+	NonInteractive   bool
+	// OnComplete, when non-nil, replaces the default RunComplete
+	// publish path: the inner Run hands the terminal payload to this
+	// callback instead of emitting it on the RunComplete broker. The
+	// coordinator uses this hook to coalesce the unauthorized →
+	// re-auth → retry chain into a single user-visible terminal
+	// event, so non-interactive clients (e.g. `crush run`) don't
+	// exit on a stale failed-attempt RunComplete before the
+	// successful retry. It is intentionally stripped when queueing
+	// a busy-session call (see Run): the originating
+	// coordinator.Run has long returned by the time the queued
+	// recursion drains, so falling back to the default broker
+	// publish keeps the event visible to subscribers.
+	OnComplete func(notify.RunComplete)
+	// Accepted, when non-nil, is the accept reservation taken by
+	// BeginAccepted before the call was dispatched onto a goroutine
+	// (the client/server fire-and-forget path). Run consumes it under
+	// dispatchMu[SessionID] once the accepted -> (cancel-on-entry |
+	// queued | active) transition has been chosen. When nil
+	// (in-process / local callers like AppWorkspace), behavior is
+	// unchanged and no accept tracking applies.
+	Accepted *AcceptedRun
+	// acceptSeq carries the accept sequence of the handle that produced
+	// this call after it has been enqueued and its Accepted handle
+	// stripped. The queue-drain paths compare it against a session's
+	// cancel mark so a follow-up queued before a cancel is dropped while
+	// one queued after the cancel survives. 0 means untracked (an
+	// in-process enqueue with no accept reservation), which the drain
+	// paths treat as covered by any present mark, preserving the
+	// pre-sequence behavior.
+	acceptSeq uint64
+	// OnAuthRefresh, when non-nil, is called by fantasy when a stream
+	// fails with an authentication error (HTTP 401). The callback should
+	// refresh credentials and return nil on success, in which case
+	// fantasy retries the stream transparently. Returning an error
+	// surfaces the original auth error without retry.
+	OnAuthRefresh func(ctx context.Context, err *fantasy.ProviderError) error
+}
+
+type SessionAgent interface {
+	Run(context.Context, SessionAgentCall) (*fantasy.AgentResult, error)
+	BeginAccepted(sessionID string) *AcceptedRun
+	SetModels(large Model, small Model)
+	SetTools(tools []fantasy.AgentTool)
+	SetSystemPrompt(systemPrompt string)
+	Cancel(sessionID string)
+	CancelAll()
+	IsSessionBusy(sessionID string) bool
+	IsBusy() bool
+	QueuedPrompts(sessionID string) int
+	QueuedPromptsList(sessionID string) []string
+	ClearQueue(sessionID string)
+	Summarize(context.Context, string, fantasy.ProviderOptions, func(context.Context, *fantasy.ProviderError) error) error
+	Model() Model
+	GenerateTitle(ctx context.Context, sessionID, userPrompt string)
+}
+
+type Model struct {
+	Model      fantasy.LanguageModel
+	CatwalkCfg catwalk.Model
+	ModelCfg   config.SelectedModel
+	FlatRate   bool
+}
+
+// activeCancel wraps a context.CancelFunc with a unique pointer identity.
+// The pointer is used for compare-and-delete in the dispatch completion path:
+// when a finishing run's deferred cleanup fires, it must only remove its own
+// entry — not a newer run's entry that was installed in the window between
+// the explicit Del and the function return.
+type activeCancel struct {
+	cancel context.CancelFunc
+}
+
+type sessionAgent struct {
+	largeModel         *csync.Value[Model]
+	smallModel         *csync.Value[Model]
+	systemPromptPrefix *csync.Value[string]
+	systemPrompt       *csync.Value[string]
+	tools              *csync.Slice[fantasy.AgentTool]
+
+	isSubAgent           bool
+	sessions             session.Service
+	messages             message.Service
+	disableAutoSummarize bool
+	isYolo               bool
+	notify               pubsub.Publisher[notify.Notification]
+	runComplete          pubsub.Publisher[notify.RunComplete]
+
+	messageQueue   *csync.Map[string, []SessionAgentCall]
+	activeRequests *csync.Map[string, *activeCancel]
+
+	// dispatchMu holds a per-session mutex that serializes the
+	// accepted -> (cancel-on-entry | queued | active) transition in
+	// Run against a concurrent Cancel. The lock is held only during
+	// the brief handoff (no DB or LLM I/O under the lock).
+	dispatchMu *csync.Map[string, *sync.Mutex]
+	// acceptedRuns counts dispatched-but-not-yet-active runs per
+	// session. A counter > 0 means a dispatched prompt is in flight
+	// and has not yet completed the dispatch handoff in Run. Only
+	// BeginAccepted increments it; only AcceptedRun.Close decrements
+	// it.
+	acceptedRuns *csync.Map[string, int]
+	// cancelMark records, per session, a high-water accept sequence: an
+	// accepted handle is canceled by it iff the handle's sequence is at
+	// or below the mark. Cancel raises the mark to the latest sequence
+	// assigned at cancel time, so a single Cancel covers every prompt
+	// accepted-but-not-yet-active then, while a prompt accepted later
+	// (higher sequence) is never poisoned. Absent or 0 means no pending
+	// cancel. It is only raised by Cancel when acceptedRuns > 0, so an
+	// idle Escape never records a mark.
+	cancelMark *csync.Map[string, uint64]
+	// dispatchMuCreate guards lazy creation of per-session entries in
+	// dispatchMu so two goroutines can't race to lock different mutex
+	// instances for the same session.
+	dispatchMuCreate sync.Mutex
+	// acceptedMu serializes increments/decrements of acceptedRuns and
+	// the assignment of accept sequence numbers from acceptSeqGen. It
+	// is separate from dispatchMu so AcceptedRun.Close (which may run
+	// while Run holds dispatchMu for the same session) does not
+	// deadlock by re-entering the dispatch lock.
+	acceptedMu sync.Mutex
+	// acceptSeqGen is the monotonic source of accept sequence numbers.
+	// Each BeginAccepted increments it under acceptedMu and stamps the
+	// returned handle, so sequences strictly increase in accept order
+	// across the agent. Cancel uses its current value as the per-session
+	// high-water mark.
+	acceptSeqGen uint64
+}
+
+type SessionAgentOptions struct {
+	LargeModel           Model
+	SmallModel           Model
+	SystemPromptPrefix   string
+	SystemPrompt         string
+	IsSubAgent           bool
+	DisableAutoSummarize bool
+	IsYolo               bool
+	Sessions             session.Service
+	Messages             message.Service
+	Tools                []fantasy.AgentTool
+	Notify               pubsub.Publisher[notify.Notification]
+	RunComplete          pubsub.Publisher[notify.RunComplete]
+}
+
+func NewSessionAgent(
+	opts SessionAgentOptions,
+) SessionAgent {
+	return &sessionAgent{
+		largeModel:           csync.NewValue(opts.LargeModel),
+		smallModel:           csync.NewValue(opts.SmallModel),
+		systemPromptPrefix:   csync.NewValue(opts.SystemPromptPrefix),
+		systemPrompt:         csync.NewValue(opts.SystemPrompt),
+		isSubAgent:           opts.IsSubAgent,
+		sessions:             opts.Sessions,
+		messages:             opts.Messages,
+		disableAutoSummarize: opts.DisableAutoSummarize,
+		tools:                csync.NewSliceFrom(opts.Tools),
+		isYolo:               opts.IsYolo,
+		notify:               opts.Notify,
+		runComplete:          opts.RunComplete,
+		messageQueue:         csync.NewMap[string, []SessionAgentCall](),
+		activeRequests:       csync.NewMap[string, *activeCancel](),
+		dispatchMu:           csync.NewMap[string, *sync.Mutex](),
+		acceptedRuns:         csync.NewMap[string, int](),
+		cancelMark:           csync.NewMap[string, uint64](),
+	}
+}
+
+// AcceptedRun owns exactly one accept reservation taken by
+// BeginAccepted. It is the only carrier of accept-state across the
+// backend.runAgent / Coordinator.Run / sessionAgent.Run layers: a
+// counter > 0 means a dispatched prompt is in flight and has not yet
+// completed the dispatch handoff in Run. Close is the only way to
+// release the reservation and is idempotent.
+type AcceptedRun struct {
+	agent     *sessionAgent
+	sessionID string
+	// seq is the monotonic accept sequence stamped by BeginAccepted. A
+	// cancel covers this handle iff seq is at or below the session's
+	// cancel mark, so a handle accepted after a cancel (higher seq) is
+	// never poisoned by it.
+	seq  uint64
+	done atomic.Bool
+}
+
+// Close decrements the accept counter for this reservation. It is safe
+// to call multiple times; only the first call has effect.
+func (r *AcceptedRun) Close() {
+	if r == nil {
+		return
+	}
+	if !r.done.CompareAndSwap(false, true) {
+		return
+	}
+	r.agent.endAccepted(r.sessionID)
+}
+
+// SessionID exposes the session this reservation is for so the run path
+// can use it without an extra parameter.
+func (r *AcceptedRun) SessionID() string {
+	if r == nil {
+		return ""
+	}
+	return r.sessionID
+}
+
+// BeginAccepted increments the accept counter for sessionID and returns
+// a handle whose Close is the only way to decrement it. It is the only
+// entry point that mutates acceptedRuns.
+func (a *sessionAgent) BeginAccepted(sessionID string) *AcceptedRun {
+	a.acceptedMu.Lock()
+	defer a.acceptedMu.Unlock()
+	count, _ := a.acceptedRuns.Get(sessionID)
+	a.acceptedRuns.Set(sessionID, count+1)
+	a.acceptSeqGen++
+	return &AcceptedRun{agent: a, sessionID: sessionID, seq: a.acceptSeqGen}
+}
+
+// endAccepted decrements the accept counter for sessionID. It is only
+// called via AcceptedRun.Close. It uses a dedicated lock (not the
+// per-session dispatch mutex) so it can run while Run holds dispatchMu
+// for the same session without deadlocking.
+//
+// When the count reaches zero the session's cancel mark is dropped: no
+// accepted handle remains for it to cover, and any handle accepted later
+// gets a strictly higher sequence that the mark would not match anyway.
+// Handles canceled on entry never reach RunComplete, so this is the only
+// place that clears the mark for an all-canceled batch. Sibling handles
+// covered by the same mark are serialized on the per-session dispatch
+// mutex and read the mark before they Close, so this never clears it out
+// from under a covered handle still waiting to enter Run.
+func (a *sessionAgent) endAccepted(sessionID string) {
+	a.acceptedMu.Lock()
+	defer a.acceptedMu.Unlock()
+	count, ok := a.acceptedRuns.Get(sessionID)
+	if !ok || count <= 1 {
+		a.acceptedRuns.Del(sessionID)
+		a.cancelMark.Del(sessionID)
+		return
+	}
+	a.acceptedRuns.Set(sessionID, count-1)
+}
+
+// sessionMu returns the per-session dispatch mutex, creating it on first
+// use. Creation is guarded so concurrent callers always observe the same
+// mutex instance for a given session.
+func (a *sessionAgent) sessionMu(sessionID string) *sync.Mutex {
+	if mu, ok := a.dispatchMu.Get(sessionID); ok {
+		return mu
+	}
+	a.dispatchMuCreate.Lock()
+	defer a.dispatchMuCreate.Unlock()
+	if mu, ok := a.dispatchMu.Get(sessionID); ok {
+		return mu
+	}
+	mu := &sync.Mutex{}
+	a.dispatchMu.Set(sessionID, mu)
+	return mu
+}
+
+// enqueueCall appends call to the session's message queue. The
+// OnComplete hook is stripped: the caller that supplied it (typically
+// coordinator.Run) has its own retry/coalesce scope that ends when it
+// returns, so by the time the queue drains nobody is left to consume the
+// buffered terminal event. The recursive Run falls back to the default
+// broker publish, which is what existing subscribers expect for queued
+// turns.
+func (a *sessionAgent) enqueueCall(call SessionAgentCall) {
+	existing, ok := a.messageQueue.Get(call.SessionID)
+	if !ok {
+		existing = []SessionAgentCall{}
+	}
+	queued := call
+	if call.Accepted != nil {
+		// Preserve the accept sequence after the handle is stripped so
+		// the queue-drain paths can tell a follow-up queued before a
+		// cancel (covered by the mark) from one queued after it.
+		queued.acceptSeq = call.Accepted.seq
+	}
+	queued.OnComplete = nil
+	queued.Accepted = nil
+	existing = append(existing, queued)
+	a.messageQueue.Set(call.SessionID, existing)
+}
+
+// drainQueueForStep partitions the session's queued calls for the current
+// streaming step under the per-session dispatch mutex so the filtering is
+// atomic against a concurrent Cancel: canceledBySeq requires the caller to
+// hold that mutex, and evaluating it here (rather than after unlocking)
+// prevents a cancel recorded between the drain and the check from being
+// observed inconsistently.
+//
+// Calls covered by a pending cancel are dropped; the dropped ones that
+// carry a RunID are returned in canceledWithRunID so the caller can
+// publish their terminal cancelled RunComplete (a caller waiting on that
+// RunID, e.g. `crush run`, would otherwise hang). Uncanceled calls without
+// a RunID are returned in fold to be folded into the active turn,
+// preserving the existing follow-up behavior. Uncanceled calls that carry
+// a RunID are left in the queue so each runs as its own turn via the
+// recursive run path and publishes its own RunComplete, giving every
+// RunID-bearing prompt an explicit lifecycle instead of being silently
+// absorbed into another turn. fold is processed by the caller without the
+// lock held.
+func (a *sessionAgent) drainQueueForStep(sessionID string) (fold, canceledWithRunID []SessionAgentCall) {
+	dispatchLock := a.sessionMu(sessionID)
+	dispatchLock.Lock()
+	defer dispatchLock.Unlock()
+	queuedCalls, _ := a.messageQueue.Get(sessionID)
+	var keep []SessionAgentCall
+	for _, queued := range queuedCalls {
+		if a.canceledBySeq(sessionID, queued.acceptSeq) {
+			if queued.RunID != "" {
+				canceledWithRunID = append(canceledWithRunID, queued)
+			}
+			continue
+		}
+		if queued.RunID != "" {
+			keep = append(keep, queued)
+			continue
+		}
+		fold = append(fold, queued)
+	}
+	if len(keep) == 0 {
+		a.messageQueue.Del(sessionID)
+	} else {
+		a.messageQueue.Set(sessionID, keep)
+	}
+	return fold, canceledWithRunID
+}
+
+// publishCanceledQueueDrops emits a terminal cancelled RunComplete for
+// every dropped queued call that carries a RunID. A queued prompt removed
+// from the queue without ever running — covered by a pending cancel, or
+// cleared by Cancel/ClearQueue — would otherwise leave a caller blocked on
+// that RunID: `crush run` ignores live message events and exits only on a
+// RunComplete whose RunID matches. Calls without a RunID had no such waiter
+// and are dropped silently as before. A detached, bounded context keeps the
+// must-deliver publish alive even when the run context that triggered the
+// drop is already canceled.
+func (a *sessionAgent) publishCanceledQueueDrops(drops []SessionAgentCall) {
+	var hasRunID bool
+	for _, d := range drops {
+		if d.RunID != "" {
+			hasRunID = true
+			break
+		}
+	}
+	if !hasRunID {
+		return
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	for _, d := range drops {
+		if d.RunID == "" {
+			continue
+		}
+		a.publishRunComplete(ctx, d, notify.RunComplete{
+			SessionID: d.SessionID,
+			RunID:     d.RunID,
+			Cancelled: true,
+		})
+	}
+}
+
+// clearQueueAndNotify removes all queued prompts for the session and
+// publishes a terminal cancelled RunComplete for any that carried a RunID,
+// so callers waiting on those RunIDs (e.g. `crush run`) are not left
+// hanging when their queued prompt is discarded without running.
+func (a *sessionAgent) clearQueueAndNotify(sessionID string) {
+	queued, ok := a.messageQueue.Get(sessionID)
+	a.messageQueue.Del(sessionID)
+	if !ok {
+		return
+	}
+	a.publishCanceledQueueDrops(queued)
+}
+
+// clearPendingCancel removes any pending-cancel mark for sessionID. It
+// takes the per-session dispatch lock so it is ordered against Cancel
+// and the dispatch handoff.
+func (a *sessionAgent) clearPendingCancel(sessionID string) {
+	mu := a.sessionMu(sessionID)
+	mu.Lock()
+	defer mu.Unlock()
+	a.cancelMark.Del(sessionID)
+}
+
+// canceledBySeq reports whether an accepted handle or queued call with
+// the given accept sequence is covered by a pending cancel for the
+// session. Callers must hold the session's dispatch mutex. A tracked
+// sequence (seq > 0) is covered only when it is at or below the cancel
+// high-water mark, so a prompt accepted after the cancel (higher seq) is
+// never poisoned. An untracked sequence (seq == 0, an in-process enqueue
+// with no accept reservation) is covered whenever any mark is present,
+// preserving the pre-sequence behavior. The mark is not consumed: it
+// stays so every sibling handle it covers observes the same cancel, and
+// a later handle (higher seq) ignores it regardless.
+func (a *sessionAgent) canceledBySeq(sessionID string, seq uint64) bool {
+	mark, ok := a.cancelMark.Get(sessionID)
+	if !ok || mark == 0 {
+		return false
+	}
+	return seq == 0 || seq <= mark
+}
+
+// persistCanceledTurn writes the user/assistant records for a turn that
+// was canceled before (or just as) streaming would have produced them.
+// It creates the user message only when it was not already created by an
+// earlier createUserMessage call (userMsgCreated), then writes an
+// assistant message with FinishReasonCanceled. Both writes use
+// context.WithoutCancel(ctx) so workspace shutdown (which cancels the run
+// context) can't drop them.
+func (a *sessionAgent) persistCanceledTurn(ctx context.Context, call SessionAgentCall, userMsgCreated bool) error {
+	writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+	defer cancel()
+	if !userMsgCreated {
+		if _, err := a.createUserMessage(writeCtx, call); err != nil {
+			return err
+		}
+	}
+	largeModel := a.largeModel.Get()
+	assistant, err := a.messages.Create(writeCtx, call.SessionID, message.CreateMessageParams{
+		Role:     message.Assistant,
+		Parts:    []message.ContentPart{},
+		Model:    largeModel.ModelCfg.Model,
+		Provider: largeModel.ModelCfg.Provider,
+	})
+	if err != nil {
+		return err
+	}
+	assistant.AddFinish(message.FinishReasonCanceled, "User canceled request", "")
+	return a.messages.Update(writeCtx, assistant)
+}
+
+// publishRunComplete emits the authoritative terminal event for a turn.
+// It honors the per-call OnComplete hook when set (so the coordinator can
+// coalesce retries) and otherwise falls back to the RunComplete broker.
+// ctx is used only for the bounded-blocking must-deliver publish; the
+// terminal payload is supplied by the caller. This is the single emit path
+// shared by the streaming defer and the cancel-on-entry early return so a
+// caller waiting on RunComplete (e.g. `crush run` with a RunID) always
+// observes exactly one terminal event regardless of which Run branch ends
+// the turn.
+func (a *sessionAgent) publishRunComplete(ctx context.Context, call SessionAgentCall, complete notify.RunComplete) {
+	if call.OnComplete != nil {
+		call.OnComplete(complete)
+		return
+	}
+	if a.runComplete == nil {
+		return
+	}
+	a.runComplete.PublishMustDeliver(ctx, pubsub.UpdatedEvent, complete)
+}
+
+// ValidateCall performs the cheap structural validation that
+// sessionAgent.Run requires before a call can be dispatched: a call must
+// carry either a non-empty prompt or a text attachment, and it must name a
+// session. It is exported so callers that accept a run before dispatching it
+// (e.g. backend.SendMessage) can apply the same checks and keep the error
+// contract consistent.
+func ValidateCall(call SessionAgentCall) error {
+	if call.Prompt == "" && !message.ContainsTextAttachment(call.Attachments) {
+		return ErrEmptyPrompt
+	}
+	if call.SessionID == "" {
+		return ErrSessionMissing
+	}
+	return nil
+}
+
+func (a *sessionAgent) Run(ctx context.Context, call SessionAgentCall) (result *fantasy.AgentResult, retErr error) {
+	if err := ValidateCall(call); err != nil {
+		return nil, err
+	}
+
+	// genCtx/cancel are the run context and its cancel func, created under
+	// the per-session dispatch mutex below so a concurrent Cancel can observe
+	// the activeRequests entry before the assistant message exists.
+	var (
+		genCtx         context.Context
+		cancel         context.CancelFunc
+		userMsgCreated bool
+	)
+
+	// Serialize the dispatch decision (cancel-on-entry | queued | active)
+	// against a concurrent Cancel. Cancel takes the same per-session lock, so
+	// every cancel observes at least one of: a cancel mark, an activeRequests
+	// entry, or a messageQueue entry it then clears. Holding the lock across
+	// the busy check and the active registration also makes them atomic, so
+	// two concurrent in-process callers — a burst of channel events, or a
+	// channel event racing a typed prompt — cannot both pass the busy check
+	// and start two runs on the same session.
+	sessMu := a.sessionMu(call.SessionID)
+	sessMu.Lock()
+
+	if call.Accepted != nil && a.canceledBySeq(call.SessionID, call.Accepted.seq) {
+		// Cancel-on-entry: a cancel arrived while this accepted run was
+		// dispatched but not yet active, and this handle's accept sequence
+		// is at or below the session's cancel mark. The mark is left in
+		// place so sibling handles it also covers observe the same cancel;
+		// release the accept reservation, drop the lock, and persist a
+		// canceled turn without entering Stream.
+		//
+		// This path returns before the streaming defer that publishes
+		// RunComplete is installed, so emit the terminal event explicitly.
+		// Without it, a caller waiting on RunComplete for this RunID (e.g.
+		// `crush run`, which ignores message events and blocks on
+		// RunComplete) would hang on an immediately-canceled accepted run.
+		call.Accepted.Close()
+		sessMu.Unlock()
+		complete := notify.RunComplete{
+			SessionID: call.SessionID,
+			RunID:     call.RunID,
+			Cancelled: true,
+		}
+		if err := a.persistCanceledTurn(ctx, call, false); err != nil {
+			complete.Error = err.Error()
+			a.publishRunComplete(ctx, call, complete)
+			return nil, err
+		}
+		a.publishRunComplete(ctx, call, complete)
+		return nil, nil
+	}
+
+	if a.IsSessionBusy(call.SessionID) {
+		// Busy: an earlier prompt is active. Queue this call so it is
+		// folded into (or sequenced after) the active turn, and release any
+		// accept reservation. A Cancel arriving after this point sees the
+		// active entry and clears the queue.
+		//
+		// enqueueCall strips OnComplete: the caller that supplied the hook
+		// (typically coordinator.Run) has its own retry/coalesce scope that
+		// ends when it returns, so by the time the queue drains nobody is
+		// left to consume the buffered terminal event. The queued turn falls
+		// back to the default broker publish, which is what existing
+		// subscribers expect.
+		a.enqueueCall(call)
+		if call.Accepted != nil {
+			call.Accepted.Close()
+		}
+		sessMu.Unlock()
+		return nil, nil
+	}
+
+	// Idle: become the active run. Register the cancel func before dropping
+	// the lock so a Cancel that arrives between here and assistant creation
+	// is not lost.
+	runCtx := context.WithValue(ctx, tools.SessionIDContextKey, call.SessionID)
+	genCtx, cancel = context.WithCancel(runCtx)
+	ac := &activeCancel{cancel: cancel}
+	a.activeRequests.Set(call.SessionID, ac)
+	if call.Accepted != nil {
+		call.Accepted.Close()
+	}
+	sessMu.Unlock()
+
+	defer cancel()
+	// Conditional cleanup: only remove our entry if it hasn't been replaced
+	// by a newer run. Without this guard, the deferred Del fires after a
+	// concurrent run registers in the completion window, silently wiping
+	// the new run's cancel and breaking cancellation.
+	defer a.activeRequests.CompareAndDelete(call.SessionID, ac)
+
+	// Copy mutable fields under lock to avoid races with SetTools/SetModels.
+	agentTools := a.tools.Copy()
+	largeModel := a.largeModel.Get()
+	systemPrompt := a.systemPrompt.Get()
+	promptPrefix := a.systemPromptPrefix.Get()
+	var instructions strings.Builder
+
+	for _, server := range mcp.GetStates() {
+		if server.State != mcp.StateConnected {
+			continue
+		}
+		if s := server.Client.InitializeResult().Instructions; s != "" {
+			instructions.WriteString(s)
+			instructions.WriteString("\n\n")
+		}
+	}
+
+	if s := instructions.String(); s != "" {
+		systemPrompt += "\n\n<mcp-instructions>\n" + s + "\n</mcp-instructions>"
+	}
+
+	if len(agentTools) > 0 {
+		// Add Anthropic caching to the last tool.
+		agentTools[len(agentTools)-1].SetProviderOptions(a.getCacheControlOptions())
+	}
+
+	agent := fantasy.NewAgent(
+		largeModel.Model,
+		fantasy.WithSystemPrompt(systemPrompt),
+		fantasy.WithTools(agentTools...),
+		fantasy.WithUserAgent(userAgent),
+	)
+
+	sessionLock := sync.Mutex{}
+	currentSession, err := a.sessions.Get(ctx, call.SessionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get session: %w", err)
+	}
+
+	msgs, err := a.getSessionMessages(ctx, currentSession)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get session messages: %w", err)
+	}
+
+	// Generate title from the first real (non-shell) user prompt.
+	// can take tens of seconds. Blocking Run on it delays the
+	// response to the caller. Use a detached context so the title
+	// goroutine survives Run's cancel.
+	if !hasUserTextMessage(msgs) {
+		titleCtx := context.WithoutCancel(ctx)
+		go a.GenerateTitle(titleCtx, call.SessionID, call.Prompt)
+	}
+
+	// Add the user message to the session.
+	_, err = a.createUserMessage(ctx, call)
+	if err != nil {
+		return nil, err
+	}
+	userMsgCreated = true
+
+	// Add the session to the context. The run context (genCtx) and its
+	// cancel func were already created and registered under the dispatch
+	// mutex above for both the accepted and in-process paths.
+	ctx = context.WithValue(ctx, tools.SessionIDContextKey, call.SessionID)
+	// skipRunComplete is set just before the queued-recursion path so
+	// the outer Run doesn't publish a RunComplete that would race
+	// with — and be superseded by — the recursive call's own
+	// RunComplete (each queued user prompt is its own turn and
+	// publishes exactly one terminal event).
+	var skipRunComplete bool
+	// currentAssistant is declared here so the deferred RunComplete
+	// publish below can capture the pointer that PrepareStep will
+	// later (re)assign for each streaming step. The final assistant
+	// message of the turn is the value reachable through this
+	// pointer when the defer runs.
+	var currentAssistant *message.Message
+	// Drain any debounced message updates before returning. message.Service
+	// already flushes synchronously on terminal updates, but a defer here
+	// guarantees the contract at every Run exit (success, error, panic
+	// recovery upstream) without callers needing to know.
+	//
+	// After the flush completes — meaning all per-message
+	// Publish(UpdatedEvent) calls have fired and been buffered into
+	// every subscriber's channel — publish the authoritative
+	// RunComplete event for this turn. The flush-then-publish order
+	// gives well-behaved clients the best chance of seeing the final
+	// message event before RunComplete; the embedded Text field
+	// reconciles for clients that observe the events out of order
+	// (the pubsub broker fan-in does not serialize publishes from
+	// different upstream brokers).
+	defer func() {
+		// Use a context detached from the run context: workspace
+		// shutdown cancels ctx before this goroutine returns, but the
+		// buffered streaming deltas must still land before the DB is
+		// closed. A short timeout bounds the flush.
+		flushCtx, flushCancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+		defer flushCancel()
+		if flushErr := a.messages.FlushAll(flushCtx); flushErr != nil {
+			slog.Error("Failed to flush pending message updates after run", "error", flushErr)
+		}
+		if skipRunComplete {
+			return
+		}
+		complete := notify.RunComplete{SessionID: call.SessionID, RunID: call.RunID}
+		if currentAssistant != nil {
+			complete.MessageID = currentAssistant.ID
+			complete.Text = currentAssistant.Content().String()
+		}
+		if retErr != nil {
+			complete.Error = retErr.Error()
+			complete.Cancelled = errors.Is(retErr, context.Canceled)
+		} else if ctx.Err() != nil {
+			complete.Cancelled = true
+		}
+		// Prefer the per-call hook when supplied so the coordinator
+		// can coalesce retries (e.g. unauthorized → re-auth → retry)
+		// into a single user-visible terminal event. The fallback
+		// must-deliver publish applies bounded-blocking semantics to
+		// the authoritative terminal event so a momentarily-full
+		// subscriber channel can't silently drop it and hang
+		// non-interactive clients waiting on RunComplete.
+		a.publishRunComplete(ctx, call, complete)
+	}()
+
+	history, files := a.preparePrompt(msgs, largeModel.CatwalkCfg.SupportsImages, call.Attachments...)
+
+	startTime := time.Now()
+	a.eventPromptSent(call.SessionID)
+
+	var stepMessages []fantasy.Message
+	var shouldSummarize bool
+	sanitizedToolCalls := make(map[string]bool)
+	// Don't send MaxOutputTokens if 0 — some providers (e.g. LM Studio) reject it
+	var maxOutputTokens *int64
+	if call.MaxOutputTokens > 0 {
+		maxOutputTokens = &call.MaxOutputTokens
+	}
+	result, err = agent.Stream(genCtx, fantasy.AgentStreamCall{
+		Prompt:           message.PromptWithTextAttachments(call.Prompt, call.Attachments),
+		Files:            files,
+		Messages:         history,
+		Headers:          sessionHeaders(call.SessionID),
+		ProviderOptions:  call.ProviderOptions,
+		MaxOutputTokens:  maxOutputTokens,
+		TopP:             call.TopP,
+		Temperature:      call.Temperature,
+		PresencePenalty:  call.PresencePenalty,
+		TopK:             call.TopK,
+		FrequencyPenalty: call.FrequencyPenalty,
+		PrepareStep: func(callContext context.Context, options fantasy.PrepareStepFunctionOptions) (_ context.Context, prepared fantasy.PrepareStepResult, err error) {
+			prepared.Messages = options.Messages
+			for i := range prepared.Messages {
+				prepared.Messages[i].ProviderOptions = nil
+			}
+
+			// Use latest tools (updated by SetTools when MCP tools change).
+			prepared.Tools = a.tools.Copy()
+
+			// Drain queued follow-up prompts for this step. Calls covered
+			// by a cancel recorded while they sat in the queue are dropped:
+			// a cancel that arrived after a prompt was queued must not let
+			// it run as part of this step. Coverage is per-call by accept
+			// sequence so a follow-up queued after the cancel (higher seq)
+			// is not dropped. A dropped prompt carrying a RunID still gets
+			// its terminal cancelled RunComplete so a caller waiting on it
+			// does not hang. Uncanceled prompts without a RunID are folded
+			// into this turn; uncanceled prompts with a RunID are left
+			// queued so each runs as its own turn (with its own
+			// RunComplete) via the recursive run path below.
+			fold, canceledRunIDs := a.drainQueueForStep(call.SessionID)
+			a.publishCanceledQueueDrops(canceledRunIDs)
+			for _, queued := range fold {
+				userMessage, createErr := a.createUserMessage(callContext, queued)
+				if createErr != nil {
+					return callContext, prepared, createErr
+				}
+				prepared.Messages = append(prepared.Messages, userMessage.ToAIMessage()...)
+			}
+
+			prepared.Messages = a.workaroundProviderMediaLimitations(prepared.Messages, largeModel)
+
+			lastSystemRoleInx := 0
+			systemMessageUpdated := false
+			for i, msg := range prepared.Messages {
+				// Only add cache control to the last message.
+				if msg.Role == fantasy.MessageRoleSystem {
+					lastSystemRoleInx = i
+				} else if !systemMessageUpdated {
+					prepared.Messages[lastSystemRoleInx].ProviderOptions = a.getCacheControlOptions()
+					systemMessageUpdated = true
+				}
+				// Than add cache control to the last 2 messages.
+				if i > len(prepared.Messages)-3 {
+					prepared.Messages[i].ProviderOptions = a.getCacheControlOptions()
+				}
+			}
+
+			if promptPrefix != "" {
+				prepared.Messages = append([]fantasy.Message{fantasy.NewSystemMessage(promptPrefix)}, prepared.Messages...)
+			}
+
+			sessionLock.Lock()
+			stepMessages = cloneFantasyMessages(prepared.Messages)
+			sessionLock.Unlock()
+
+			var assistantMsg message.Message
+			assistantMsg, err = a.messages.Create(callContext, call.SessionID, message.CreateMessageParams{
+				Role:     message.Assistant,
+				Parts:    []message.ContentPart{},
+				Model:    largeModel.ModelCfg.Model,
+				Provider: largeModel.ModelCfg.Provider,
+			})
+			if err != nil {
+				return callContext, prepared, err
+			}
+			callContext = context.WithValue(callContext, tools.MessageIDContextKey, assistantMsg.ID)
+			callContext = context.WithValue(callContext, tools.SupportsImagesContextKey, largeModel.CatwalkCfg.SupportsImages)
+			callContext = context.WithValue(callContext, tools.ModelNameContextKey, largeModel.CatwalkCfg.Name)
+			currentAssistant = &assistantMsg
+			return callContext, prepared, err
+		},
+		OnReasoningStart: func(id string, reasoning fantasy.ReasoningContent) error {
+			currentAssistant.AppendReasoningContent(reasoning.Text)
+			return a.messages.Update(genCtx, *currentAssistant)
+		},
+		OnReasoningDelta: func(id string, text string) error {
+			currentAssistant.AppendReasoningContent(text)
+			return a.messages.Update(genCtx, *currentAssistant)
+		},
+		OnReasoningEnd: func(id string, reasoning fantasy.ReasoningContent) error {
+			// handle anthropic signature
+			if anthropicData, ok := reasoning.ProviderMetadata[anthropic.Name]; ok {
+				if reasoning, ok := anthropicData.(*anthropic.ReasoningOptionMetadata); ok {
+					currentAssistant.AppendReasoningSignature(reasoning.Signature)
+				}
+			}
+			if googleData, ok := reasoning.ProviderMetadata[google.Name]; ok {
+				if reasoning, ok := googleData.(*google.ReasoningMetadata); ok {
+					currentAssistant.AppendThoughtSignature(reasoning.Signature, reasoning.ToolID)
+				}
+			}
+			if openaiData, ok := reasoning.ProviderMetadata[openai.Name]; ok {
+				if reasoning, ok := openaiData.(*openai.ResponsesReasoningMetadata); ok {
+					currentAssistant.SetReasoningResponsesData(reasoning)
+				}
+			}
+			currentAssistant.FinishThinking()
+			return a.messages.Update(genCtx, *currentAssistant)
+		},
+		OnTextDelta: func(id string, text string) error {
+			// Strip leading newline from initial text content. This is is
+			// particularly important in non-interactive mode where leading
+			// newlines are very visible.
+			if len(currentAssistant.Parts) == 0 {
+				text = strings.TrimPrefix(text, "\n")
+			}
+
+			currentAssistant.AppendContent(text)
+			return a.messages.Update(genCtx, *currentAssistant)
+		},
+		OnToolInputStart: func(id string, toolName string) error {
+			toolCall := message.ToolCall{
+				ID:               id,
+				Name:             toolName,
+				ProviderExecuted: false,
+				Finished:         false,
+			}
+			currentAssistant.AddToolCall(toolCall)
+			// Use parent ctx instead of genCtx to ensure the update succeeds
+			// even if the request is canceled mid-stream
+			return a.messages.Update(ctx, *currentAssistant)
+		},
+		OnRetry: func(err *fantasy.ProviderError, delay time.Duration) {
+			slog.Warn("Provider request failed, retrying", providerRetryLogFields(err, delay)...)
+			// Reset streamed content so the retried response doesn't
+			// concatenate with partial content from the failed attempt.
+			// On the final attempt (no more retries), any partial content
+			// stays in the message as useful context beneath the error.
+			currentAssistant.ResetStreamedContent()
+			if updateErr := a.messages.Update(genCtx, *currentAssistant); updateErr != nil {
+				slog.Error("Failed to reset message on retry", "error", updateErr)
+			}
+		},
+		OnAuthRefresh: call.OnAuthRefresh,
+		ModelProvider: func() fantasy.LanguageModel {
+			m := a.largeModel.Get()
+			slog.Info("ModelProvider called",
+				"provider", m.ModelCfg.Provider,
+				"model", m.ModelCfg.Model)
+			return m.Model
+		},
+		OnToolCall: func(tc fantasy.ToolCallContent) error {
+			input, wasSanitized := sanitizeToolInput(tc.ToolName, tc.ToolCallID, tc.Input)
+			if wasSanitized {
+				sanitizedToolCalls[tc.ToolCallID] = true
+			}
+			toolCall := message.ToolCall{
+				ID:               tc.ToolCallID,
+				Name:             tc.ToolName,
+				Input:            input,
+				ProviderExecuted: false,
+				Finished:         true,
+			}
+			currentAssistant.AddToolCall(toolCall)
+			// Use parent ctx instead of genCtx to ensure the update succeeds
+			// even if the request is canceled mid-stream
+			return a.messages.Update(ctx, *currentAssistant)
+		},
+		OnToolResult: func(result fantasy.ToolResultContent) error {
+			toolResult := a.convertToToolResult(result)
+			if sanitizedToolCalls[result.ToolCallID] {
+				toolResult.Content = "Tool call failed: arguments were not valid JSON. Please check your tool call format and try again."
+				toolResult.IsError = true
+			}
+			// Use parent ctx instead of genCtx to ensure the message is created
+			// even if the request is canceled mid-stream
+			_, createMsgErr := a.messages.Create(ctx, currentAssistant.SessionID, message.CreateMessageParams{
+				Role: message.Tool,
+				Parts: []message.ContentPart{
+					toolResult,
+				},
+			})
+			return createMsgErr
+		},
+		OnStepFinish: func(stepResult fantasy.StepResult) error {
+			for _, w := range stepResult.Warnings {
+				slog.Warn("Provider warning", "type", w.Type, "message", w.Message)
+			}
+			finishReason := message.FinishReasonUnknown
+			switch stepResult.FinishReason {
+			case fantasy.FinishReasonLength:
+				finishReason = message.FinishReasonMaxTokens
+			case fantasy.FinishReasonStop:
+				finishReason = message.FinishReasonEndTurn
+			case fantasy.FinishReasonToolCalls:
+				finishReason = message.FinishReasonToolUse
+			case fantasy.FinishReasonContentFilter:
+				// Provider safety classifier stopped the model
+				// (Anthropic stop_reason=refusal, OpenAI content_filter).
+				// The TUI owns the display copy; we only persist the
+				// reason so the UI can show a REFUSED banner.
+				finishReason = message.FinishReasonContentFilter
+				slog.Warn(
+					"Provider content filter stopped the model",
+					"session_id", call.SessionID,
+					"finish_reason", string(stepResult.FinishReason),
+				)
+			}
+			// If a tool result halted the turn (e.g. a hook halt or a
+			// permission denial), the step ends on FinishReasonToolCalls but
+			// the model will not be called again. Treat it as the end of the
+			// turn so the UI can render the assistant footer.
+			if finishReason == message.FinishReasonToolUse {
+				for _, tr := range stepResult.Content.ToolResults() {
+					if tr.StopTurn {
+						finishReason = message.FinishReasonEndTurn
+						break
+					}
+				}
+			}
+			currentAssistant.AddFinish(finishReason, "", "")
+			currentAssistant.PrismModelID, currentAssistant.PrismModelName = extractPrismModel(stepResult.ProviderMetadata)
+			currentAssistant.PrismHypercreditSavings, currentAssistant.PrismDollarSavings = extractPrismSavings(stepResult.ProviderMetadata)
+			sessionLock.Lock()
+			defer sessionLock.Unlock()
+
+			updatedSession, getSessionErr := a.sessions.Get(ctx, call.SessionID)
+			if getSessionErr != nil {
+				return getSessionErr
+			}
+			usage, estimated := fallbackStepUsage(stepMessages, stepResult)
+			a.updateSessionUsage(largeModel, &updatedSession, usage, a.openrouterCost(stepResult.ProviderMetadata), estimated)
+			extractHyperCredits(stepResult.ProviderMetadata)
+			_, sessionErr := a.sessions.Save(ctx, updatedSession)
+			if sessionErr != nil {
+				return sessionErr
+			}
+			currentSession = updatedSession
+			return a.messages.Update(genCtx, *currentAssistant)
+		},
+		StopWhen: []fantasy.StopCondition{
+			func(_ []fantasy.StepResult) bool {
+				cw := int64(largeModel.CatwalkCfg.ContextWindow)
+				// If context window is unknown (0), skip auto-summarize
+				// to avoid immediately truncating custom/local models.
+				if cw == 0 {
+					return false
+				}
+				tokens := currentSession.CompletionTokens + currentSession.PromptTokens
+				remaining := cw - tokens
+				var threshold int64
+				if cw > largeContextWindowThreshold {
+					threshold = largeContextWindowBuffer
+				} else {
+					threshold = int64(float64(cw) * smallContextWindowRatio)
+				}
+				if (remaining <= threshold) && !a.disableAutoSummarize {
+					shouldSummarize = true
+					return true
+				}
+				return false
+			},
+			func(steps []fantasy.StepResult) bool {
+				return hasRepeatedToolCalls(steps, loopDetectionWindowSize, loopDetectionMaxRepeats)
+			},
+		},
+	})
+
+	a.eventPromptResponded(call.SessionID, time.Since(startTime).Truncate(time.Second))
+
+	if err != nil {
+		isHyper := largeModel.ModelCfg.Provider == hyper.Name
+		isCancelErr := errors.Is(err, context.Canceled)
+		slog.Info("Agent stream returned error",
+			"error", err.Error(),
+			"error_type", fmt.Sprintf("%T", err),
+			"is_hyper", isHyper,
+			"is_cancel", isCancelErr)
+		if currentAssistant == nil {
+			// Cancel-before-assistant-creation window: the run was
+			// canceled after activeRequests.Set but before PrepareStep
+			// created the assistant message. Without this, the turn
+			// would return with no FinishReasonCanceled marker and no
+			// user-visible record. The user message was already created
+			// above, so persistCanceledTurn only writes the assistant
+			// record.
+			if isCancelErr {
+				if persistErr := a.persistCanceledTurn(ctx, call, userMsgCreated); persistErr != nil {
+					return nil, persistErr
+				}
+			}
+			return result, err
+		}
+		// Persist final state with a context detached from the run
+		// context. The run context (ctx) is derived from the
+		// workspace context, which workspace shutdown cancels before
+		// agent goroutines finish; using ctx here would drop the
+		// final assistant state. WithoutCancel keeps the values
+		// (e.g. session ID) while ignoring cancellation, and a short
+		// timeout bounds the cleanup writes.
+		cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+		defer cleanupCancel()
+		// Ensure we finish thinking on error to close the reasoning state.
+		currentAssistant.FinishThinking()
+		toolCalls := currentAssistant.ToolCalls()
+		// INFO: we use the cleanup context here because the genCtx has been cancelled.
+		msgs, createErr := a.messages.List(cleanupCtx, currentAssistant.SessionID)
+		if createErr != nil {
+			return nil, createErr
+		}
+		for _, tc := range toolCalls {
+			if !tc.Finished {
+				tc.Finished = true
+				tc.Input = "{}"
+				currentAssistant.AddToolCall(tc)
+				updateErr := a.messages.Update(cleanupCtx, *currentAssistant)
+				if updateErr != nil {
+					return nil, updateErr
+				}
+			}
+
+			found := false
+			for _, msg := range msgs {
+				if msg.Role == message.Tool {
+					for _, tr := range msg.ToolResults() {
+						if tr.ToolCallID == tc.ID {
+							found = true
+							break
+						}
+					}
+				}
+				if found {
+					break
+				}
+			}
+			if found {
+				continue
+			}
+			content := "There was an error while executing the tool"
+			if isCancelErr {
+				content = "Error: user cancelled assistant tool calling"
+			}
+			toolResult := message.ToolResult{
+				ToolCallID: tc.ID,
+				Name:       tc.Name,
+				Content:    content,
+				IsError:    true,
+			}
+			_, createErr = a.messages.Create(cleanupCtx, currentAssistant.SessionID, message.CreateMessageParams{
+				Role: message.Tool,
+				Parts: []message.ContentPart{
+					toolResult,
+				},
+			})
+			if createErr != nil {
+				return nil, createErr
+			}
+		}
+		var fantasyErr *fantasy.Error
+		var providerErr *fantasy.ProviderError
+		var requestTimedOutErr *requestTimeoutError
+		const defaultTitle = "Provider Error"
+		linkStyle := lipgloss.NewStyle().Foreground(charmtone.Guac).Underline(true)
+		if isCancelErr {
+			currentAssistant.AddFinish(message.FinishReasonCanceled, "User canceled request", "")
+		} else if errors.As(err, &requestTimedOutErr) {
+			// Checked before the provider branches so a deadline our own
+			// request timeout imposed is never reported as a provider error.
+			currentAssistant.AddFinish(message.FinishReasonError, "Request timed out", requestTimedOutErr.userMessage())
+		} else if isHyper && errors.As(err, &providerErr) && providerErr.StatusCode == http.StatusUnauthorized {
+			currentAssistant.AddFinish(message.FinishReasonError, "Unauthorized", `Please re-authenticate with Hyper. You can also run "crush auth" to re-authenticate.`)
+		} else if errors.As(err, &providerErr) {
+			if providerErr.Message == "The requested model is not supported." {
+				url := "https://github.com/settings/copilot/features"
+				link := linkStyle.Hyperlink(url, "id=copilot").Render(url)
+				currentAssistant.AddFinish(
+					message.FinishReasonError,
+					"Copilot model not enabled",
+					fmt.Sprintf("%q is not enabled in Copilot. Go to the following page to enable it. Then, wait 5 minutes before trying again. %s", largeModel.CatwalkCfg.Name, link),
+				)
+			} else {
+				currentAssistant.AddFinish(message.FinishReasonError, cmp.Or(stringext.Capitalize(providerErr.Title), defaultTitle), providerErr.Message)
+			}
+		} else if errors.As(err, &fantasyErr) {
+			currentAssistant.AddFinish(message.FinishReasonError, cmp.Or(stringext.Capitalize(fantasyErr.Title), defaultTitle), fantasyErr.Message)
+		} else if fantasy.IsTransportError(err) {
+			wrapped := fantasy.NewTransportError(err)
+			currentAssistant.AddFinish(message.FinishReasonError, stringext.Capitalize(wrapped.Title), wrapped.Message)
+		} else {
+			currentAssistant.AddFinish(message.FinishReasonError, defaultTitle, err.Error())
+		}
+		// Note: we use the cleanup context here because the genCtx has been
+		// cancelled.
+		updateErr := a.messages.Update(cleanupCtx, *currentAssistant)
+		if updateErr != nil {
+			return nil, updateErr
+		}
+		return nil, err
+	}
+
+	if shouldSummarize {
+		a.activeRequests.Del(call.SessionID)
+		if summarizeErr := a.Summarize(genCtx, call.SessionID, call.ProviderOptions, call.OnAuthRefresh); summarizeErr != nil {
+			return nil, summarizeErr
+		}
+		// If the agent wasn't done...
+		if len(currentAssistant.ToolCalls()) > 0 {
+			existing, ok := a.messageQueue.Get(call.SessionID)
+			if !ok {
+				existing = []SessionAgentCall{}
+			}
+			call.Prompt = fmt.Sprintf("The previous session was interrupted because it got too long, the initial user request was: `%s`", call.Prompt)
+			existing = append(existing, call)
+			a.messageQueue.Set(call.SessionID, existing)
+		}
+	}
+
+	// Release active request before publishing the notification.
+	// TUI handlers poll IsSessionBusy() and only re-evaluate when a
+	// tea.Msg arrives, so the cleanup must precede the notify or
+	// subscribers see stale busy state at the moment of receipt.
+	a.activeRequests.Del(call.SessionID)
+	cancel()
+
+	// Send notification that agent has finished its turn (skip for
+	// nested/non-interactive sessions).
+	if !call.NonInteractive && a.notify != nil {
+		a.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+			SessionID:    call.SessionID,
+			SessionTitle: currentSession.Title,
+			Type:         notify.TypeAgentFinished,
+		})
+	}
+
+	// Hand off to the next queued prompt (if any) under dispatchMu so
+	// the transition from this finished run to the queued run is atomic
+	// against a concurrent Cancel. activeRequests for this session was
+	// just deleted above, so without the lock there is a window in
+	// which the session looks idle and a cancel becomes a no-op that
+	// fails to stop the queued prompt. Holding the lock lets us observe
+	// a pending cancel recorded against the session and drop the queue
+	// instead of running it, and (for the recursion) hand a fresh
+	// accept reservation to the dequeued call so acceptedRuns stays > 0
+	// across the recursive Run's own dispatch handoff — keeping the
+	// session observable to Cancel for the entire transition and
+	// closing the dequeue -> re-register window.
+	mu := a.sessionMu(call.SessionID)
+	mu.Lock()
+	queuedMessages, _ := a.messageQueue.Get(call.SessionID)
+	if mark, ok := a.cancelMark.Get(call.SessionID); ok && mark > 0 && len(queuedMessages) > 0 {
+		// A cancel was recorded for this session (e.g. it arrived while
+		// this run was active and follow-ups had been queued). Drop the
+		// queued prompts it covers (accept sequence at or below the
+		// mark, or untracked); keep any queued after the cancel (higher
+		// sequence) so they still run.
+		var kept []SessionAgentCall
+		var canceledRunIDDrops []SessionAgentCall
+		for _, q := range queuedMessages {
+			if q.acceptSeq == 0 || q.acceptSeq <= mark {
+				if q.RunID != "" {
+					canceledRunIDDrops = append(canceledRunIDDrops, q)
+				}
+				continue
+			}
+			kept = append(kept, q)
+		}
+		queuedMessages = kept
+		a.messageQueue.Set(call.SessionID, kept)
+		// A dropped prompt carrying a RunID must still publish its
+		// terminal cancelled RunComplete so a caller waiting on that
+		// RunID does not hang.
+		a.publishCanceledQueueDrops(canceledRunIDDrops)
+	}
+	if len(queuedMessages) == 0 {
+		// No queued work. Clear the cancel mark only when no accepted
+		// run remains in flight that it might still cover; otherwise a
+		// sibling prompt (sequence at or below the mark) waiting to
+		// enter Run would lose its cancellation. When accepted runs are
+		// gone, this also clears a stale mark so it can't catch a
+		// future run.
+		a.messageQueue.Del(call.SessionID)
+		a.acceptedMu.Lock()
+		inFlight, _ := a.acceptedRuns.Get(call.SessionID)
+		a.acceptedMu.Unlock()
+		if inFlight == 0 {
+			a.cancelMark.Del(call.SessionID)
+		}
+		mu.Unlock()
+		return result, err
+	}
+	// There are queued messages, restart the loop. Suppress the outer
+	// defer's emit: it would otherwise observe the recursive Run's retErr
+	// (named-return clobbering through the return below) against this
+	// turn's MessageID/Text and publish a mixed, racing event.
+	skipRunComplete = true
+	// Decide whether this turn still owes its own terminal RunComplete.
+	// Each submitted prompt with a RunID has its own lifecycle, so a turn
+	// that is finished and handing off to a *different* queued prompt must
+	// publish its own RunComplete here — leaving it to the recursive turn
+	// (which carries a different RunID) would hang a caller waiting on
+	// this turn's RunID. The exception is the summarize-continuation path,
+	// which re-queues this same call (same RunID) to resume after a
+	// summary; in that case the eventual terminal turn for this RunID
+	// publishes, so publishing now would double-emit.
+	outerOwesRunComplete := call.RunID != ""
+	if outerOwesRunComplete {
+		for _, q := range queuedMessages {
+			if q.RunID == call.RunID {
+				outerOwesRunComplete = false
+				break
+			}
+		}
+	}
+	firstQueuedMessage := queuedMessages[0]
+	a.messageQueue.Set(call.SessionID, queuedMessages[1:])
+	// Reserve a fresh accept for the dequeued prompt before dropping the
+	// lock so acceptedRuns > 0 across the handoff into the recursive
+	// Run. This closes the window between this dequeue and the recursive
+	// Run registering its activeRequests entry: a cancel arriving in
+	// that window now records a pending cancel (acceptedRuns > 0) that
+	// the recursive Run's accepted path observes as cancel-on-entry.
+	firstQueuedMessage.Accepted = a.BeginAccepted(call.SessionID)
+	mu.Unlock()
+	if outerOwesRunComplete {
+		complete := notify.RunComplete{SessionID: call.SessionID, RunID: call.RunID}
+		if currentAssistant != nil {
+			complete.MessageID = currentAssistant.ID
+			complete.Text = currentAssistant.Content().String()
+		}
+		if ctx.Err() != nil {
+			complete.Cancelled = true
+		}
+		a.publishRunComplete(ctx, call, complete)
+	}
+	return a.Run(ctx, firstQueuedMessage)
+}
+
+func (a *sessionAgent) Summarize(ctx context.Context, sessionID string, opts fantasy.ProviderOptions, onAuthRefresh func(context.Context, *fantasy.ProviderError) error) error {
+	if a.IsSessionBusy(sessionID) {
+		return ErrSessionBusy
+	}
+
+	// Copy mutable fields under lock to avoid races with SetModels.
+	largeModel := a.largeModel.Get()
+	systemPromptPrefix := a.systemPromptPrefix.Get()
+
+	currentSession, err := a.sessions.Get(ctx, sessionID)
+	if err != nil {
+		return fmt.Errorf("failed to get session: %w", err)
+	}
+	msgs, err := a.getSessionMessages(ctx, currentSession)
+	if err != nil {
+		return err
+	}
+	if len(msgs) == 0 {
+		// Nothing to summarize.
+		return nil
+	}
+
+	aiMsgs, _ := a.preparePrompt(msgs, largeModel.CatwalkCfg.SupportsImages)
+
+	genCtx, cancel := context.WithCancel(ctx)
+	ac := &activeCancel{cancel: cancel}
+	a.activeRequests.Set(sessionID, ac)
+	defer a.activeRequests.CompareAndDelete(sessionID, ac)
+	defer cancel()
+	defer func() {
+		if flushErr := a.messages.FlushAll(ctx); flushErr != nil {
+			slog.Error("Failed to flush pending message updates after summarize", "error", flushErr)
+		}
+	}()
+
+	agent := fantasy.NewAgent(
+		largeModel.Model,
+		fantasy.WithSystemPrompt(string(summaryPrompt)),
+		fantasy.WithUserAgent(userAgent),
+	)
+	summaryMessage, err := a.messages.Create(ctx, sessionID, message.CreateMessageParams{
+		Role:             message.Assistant,
+		Model:            largeModel.ModelCfg.Model,
+		Provider:         largeModel.ModelCfg.Provider,
+		IsSummaryMessage: true,
+	})
+	if err != nil {
+		return err
+	}
+
+	summaryPromptText := buildSummaryPrompt(currentSession.Todos)
+
+	resp, err := agent.Stream(genCtx, fantasy.AgentStreamCall{
+		Prompt:          summaryPromptText,
+		Messages:        aiMsgs,
+		Headers:         sessionHeaders(sessionID),
+		ProviderOptions: opts,
+		OnAuthRefresh:   onAuthRefresh,
+		ModelProvider: func() fantasy.LanguageModel {
+			return a.largeModel.Get().Model
+		},
+		PrepareStep: func(callContext context.Context, options fantasy.PrepareStepFunctionOptions) (_ context.Context, prepared fantasy.PrepareStepResult, err error) {
+			prepared.Messages = options.Messages
+			if systemPromptPrefix != "" {
+				prepared.Messages = append([]fantasy.Message{fantasy.NewSystemMessage(systemPromptPrefix)}, prepared.Messages...)
+			}
+			return callContext, prepared, nil
+		},
+		OnReasoningDelta: func(id string, text string) error {
+			summaryMessage.AppendReasoningContent(text)
+			return a.messages.Update(genCtx, summaryMessage)
+		},
+		OnReasoningEnd: func(id string, reasoning fantasy.ReasoningContent) error {
+			// Handle anthropic signature.
+			if anthropicData, ok := reasoning.ProviderMetadata["anthropic"]; ok {
+				if signature, ok := anthropicData.(*anthropic.ReasoningOptionMetadata); ok && signature.Signature != "" {
+					summaryMessage.AppendReasoningSignature(signature.Signature)
+				}
+			}
+			summaryMessage.FinishThinking()
+			return a.messages.Update(genCtx, summaryMessage)
+		},
+		OnTextDelta: func(id, text string) error {
+			summaryMessage.AppendContent(text)
+			return a.messages.Update(genCtx, summaryMessage)
+		},
+	})
+	if err != nil {
+		isCancelErr := errors.Is(err, context.Canceled)
+		if isCancelErr {
+			// User cancelled summarize we need to remove the summary message.
+			deleteErr := a.messages.Delete(ctx, summaryMessage.ID)
+			return deleteErr
+		}
+		// Mark the summary message as finished with an error so the UI
+		// stops spinning.
+		summaryMessage.AddFinish(message.FinishReasonError, "Summarization Error", err.Error())
+		if updateErr := a.messages.Update(ctx, summaryMessage); updateErr != nil {
+			return updateErr
+		}
+		return err
+	}
+
+	summaryMessage.AddFinish(message.FinishReasonEndTurn, "", "")
+	err = a.messages.Update(genCtx, summaryMessage)
+	if err != nil {
+		return err
+	}
+
+	var openrouterCost *float64
+	for _, step := range resp.Steps {
+		stepCost := a.openrouterCost(step.ProviderMetadata)
+		if stepCost != nil {
+			newCost := *stepCost
+			if openrouterCost != nil {
+				newCost += *openrouterCost
+			}
+			openrouterCost = &newCost
+		}
+		extractHyperCredits(step.ProviderMetadata)
+	}
+
+	a.updateSessionUsage(largeModel, &currentSession, resp.TotalUsage, openrouterCost, false)
+
+	// Just in case, get just the last usage info.
+	usage := resp.Response.Usage
+	currentSession.SummaryMessageID = summaryMessage.ID
+	currentSession.CompletionTokens = summaryCompletionTokens(usage, summaryMessage)
+	currentSession.PromptTokens = 0
+	currentSession.EstimatedUsage = usageIsZero(usage)
+	_, err = a.sessions.Save(genCtx, currentSession)
+	if err != nil {
+		return err
+	}
+
+	// Release the active request before processing queued messages so that
+	// Run() does not see the session as busy.
+	a.activeRequests.Del(sessionID)
+	cancel()
+
+	// Process any messages that were queued while summarizing.
+	queuedMessages, ok := a.messageQueue.Get(sessionID)
+	if !ok || len(queuedMessages) == 0 {
+		return nil
+	}
+	firstQueuedMessage := queuedMessages[0]
+	a.messageQueue.Set(sessionID, queuedMessages[1:])
+	_, qErr := a.Run(ctx, firstQueuedMessage)
+	return qErr
+}
+
+func (a *sessionAgent) getCacheControlOptions() fantasy.ProviderOptions {
+	if t, _ := strconv.ParseBool(os.Getenv("CRUSH_DISABLE_ANTHROPIC_CACHE")); t {
+		return fantasy.ProviderOptions{}
+	}
+	return fantasy.ProviderOptions{
+		anthropic.Name: &anthropic.ProviderCacheControlOptions{
+			CacheControl: anthropic.CacheControl{Type: "ephemeral"},
+		},
+		bedrock.Name: &anthropic.ProviderCacheControlOptions{
+			CacheControl: anthropic.CacheControl{Type: "ephemeral"},
+		},
+		vercel.Name: &anthropic.ProviderCacheControlOptions{
+			CacheControl: anthropic.CacheControl{Type: "ephemeral"},
+		},
+	}
+}
+
+// sessionHeaders returns the HTTP headers we use for cache affinity on
+// every LLM request for a given session.
+//
+// We use the session hash is used instead of the raw UUID so the header
+// value is deterministic and opaque.
+func sessionHeaders(sessionID string) map[string]string {
+	hash := session.HashID(sessionID)
+	return map[string]string{
+		"x-session-id":       hash,
+		"x-session-affinity": hash,
+	}
+}
+
+func (a *sessionAgent) createUserMessage(ctx context.Context, call SessionAgentCall) (message.Message, error) {
+	parts := []message.ContentPart{message.TextContent{Text: call.Prompt}}
+	var attachmentParts []message.ContentPart
+	for _, attachment := range call.Attachments {
+		attachmentParts = append(attachmentParts, message.BinaryContent{Path: attachment.FilePath, MIMEType: attachment.MimeType, Data: attachment.Content})
+	}
+	parts = append(parts, attachmentParts...)
+	msg, err := a.messages.Create(ctx, call.SessionID, message.CreateMessageParams{
+		Role:  message.User,
+		Parts: parts,
+	})
+	if err != nil {
+		return message.Message{}, fmt.Errorf("failed to create user message: %w", err)
+	}
+	return msg, nil
+}
+
+func (a *sessionAgent) preparePrompt(msgs []message.Message, supportsImages bool, attachments ...message.Attachment) ([]fantasy.Message, []fantasy.FilePart) {
+	var history []fantasy.Message
+	if !a.isSubAgent {
+		history = append(history, fantasy.NewUserMessage(
+			fmt.Sprintf(
+				"<system_reminder>%s</system_reminder>",
+				`This is a reminder that your todo list is currently empty. DO NOT mention this to the user explicitly because they are already aware.
+If you are working on tasks that would benefit from a todo list please use the "todos" tool to create one.
+If not, please feel free to ignore. Again do not mention this message to the user.`,
+			),
+		))
+	}
+	// Collect all tool call IDs present in assistant messages, then index
+	// every tool result by its call ID. Tool results are re-emitted right
+	// after the assistant message that requested them instead of at their
+	// stored position: messages can be written to a session concurrently
+	// (e.g. resuming while a tool is still running), which interleaves
+	// user messages between a tool call and its result. LLM APIs require
+	// every tool call to be followed by its results before any other
+	// message, and strict-adjacency providers (e.g. Kimi, DeepSeek) reject
+	// the request otherwise, permanently locking the session.
+	knownToolCallIDs := make(map[string]struct{})
+	for _, m := range msgs {
+		if m.Role != message.Assistant {
+			continue
+		}
+		for _, tc := range m.ToolCalls() {
+			knownToolCallIDs[tc.ID] = struct{}{}
+		}
+	}
+	toolResultsByCall := make(map[string][]fantasy.MessagePart)
+	for _, m := range msgs {
+		if m.Role != message.Tool {
+			continue
+		}
+		for _, aiMsg := range m.ToAIMessage() {
+			for _, part := range aiMsg.Content {
+				tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part)
+				if !ok {
+					// Tool-role ToAIMessage only emits ToolResultParts today;
+					// log so unexpected parts do not vanish silently.
+					slog.Warn(
+						"Dropping unexpected non-tool-result part from tool message",
+						"part_type", fmt.Sprintf("%T", part),
+					)
+					continue
+				}
+				if _, known := knownToolCallIDs[tr.ToolCallID]; !known {
+					slog.Warn(
+						"Dropping orphaned tool result with no matching tool call",
+						"tool_call_id", tr.ToolCallID,
+					)
+					continue
+				}
+				toolResultsByCall[tr.ToolCallID] = append(toolResultsByCall[tr.ToolCallID], part)
+			}
+		}
+	}
+
+	for _, m := range msgs {
+		if len(m.Parts) == 0 {
+			continue
+		}
+		// Assistant message without content or tool calls (cancelled before it returned anything).
+		if m.Role == message.Assistant && len(m.ToolCalls()) == 0 && m.Content().Text == "" && m.ReasoningContent().String() == "" {
+			continue
+		}
+		// Tool results are emitted right after their assistant message.
+		if m.Role == message.Tool {
+			continue
+		}
+		aiMsgs := m.ToAIMessage()
+		if !supportsImages {
+			for i := range aiMsgs {
+				if aiMsgs[i].Role == fantasy.MessageRoleUser {
+					aiMsgs[i].Content = filterFileParts(aiMsgs[i].Content)
+				}
+			}
+		}
+		history = append(history, aiMsgs...)
+
+		if m.Role == message.Assistant && len(m.ToolCalls()) > 0 {
+			history = append(history, toolResultsForCalls(m, toolResultsByCall))
+		}
+	}
+
+	var files []fantasy.FilePart
+	for _, attachment := range attachments {
+		if attachment.IsText() {
+			continue
+		}
+		if !supportsImages {
+			continue
+		}
+		files = append(files, fantasy.FilePart{
+			Filename:  attachment.FileName,
+			Data:      attachment.Content,
+			MediaType: attachment.MimeType,
+		})
+	}
+
+	return history, files
+}
+
+// filterFileParts removes fantasy.FilePart entries from a slice of message
+// parts. Used to strip image attachments from historical user messages when
+// the current model does not support them.
+func filterFileParts(parts []fantasy.MessagePart) []fantasy.MessagePart {
+	filtered := make([]fantasy.MessagePart, 0, len(parts))
+	for _, part := range parts {
+		if _, ok := fantasy.AsMessagePart[fantasy.FilePart](part); ok {
+			continue
+		}
+		filtered = append(filtered, part)
+	}
+	return filtered
+}
+
+// toolResultsForCalls builds the tool message that must immediately follow
+// an assistant message with tool calls. LLM APIs require every tool call to
+// be followed by its results before any other message; strict-adjacency
+// providers reject the request otherwise. Results are taken from
+// toolResultsByCall and consumed, so a result stored in a message that also
+// holds results for calls of other assistant messages is emitted exactly
+// once, next to the assistant that requested it. Tool calls without any
+// stored result (e.g. an interrupted session) receive a synthetic error
+// response so the conversation keeps working.
+func toolResultsForCalls(m message.Message, toolResultsByCall map[string][]fantasy.MessagePart) fantasy.Message {
+	content := make([]fantasy.MessagePart, 0, len(m.ToolCalls()))
+	for _, tc := range m.ToolCalls() {
+		parts := toolResultsByCall[tc.ID]
+		delete(toolResultsByCall, tc.ID)
+		if len(parts) > 0 {
+			content = append(content, parts...)
+			continue
+		}
+		slog.Warn(
+			"Injecting synthetic tool result for orphaned tool call",
+			"tool_call_id", tc.ID,
+			"tool_name", tc.Name,
+		)
+		content = append(content, fantasy.ToolResultPart{
+			ToolCallID: tc.ID,
+			Output: fantasy.ToolResultOutputContentError{
+				Error: errors.New("tool call was interrupted and did not produce a result, you may retry this call if the result is still needed"),
+			},
+		})
+	}
+	return fantasy.Message{
+		Role:    fantasy.MessageRoleTool,
+		Content: content,
+	}
+}
+
+func (a *sessionAgent) getSessionMessages(ctx context.Context, session session.Session) ([]message.Message, error) {
+	msgs, err := a.messages.List(ctx, session.ID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list messages: %w", err)
+	}
+
+	if session.SummaryMessageID != "" {
+		summaryMsgIndex := -1
+		for i, msg := range msgs {
+			if msg.ID == session.SummaryMessageID {
+				summaryMsgIndex = i
+				break
+			}
+		}
+		if summaryMsgIndex != -1 {
+			msgs = msgs[summaryMsgIndex:]
+			msgs[0].Role = message.User
+		}
+	}
+	return msgs, nil
+}
+
+// hasUserTextMessage reports whether any user message in msgs contains
+// text content (as opposed to only shell commands or other non-text parts).
+func hasUserTextMessage(msgs []message.Message) bool {
+	for _, msg := range msgs {
+		if msg.Role != message.User {
+			continue
+		}
+		for _, part := range msg.Parts {
+			if tc, ok := part.(message.TextContent); ok && tc.Text != "" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// GenerateTitle generates a session title based on the initial prompt.
+func (a *sessionAgent) GenerateTitle(ctx context.Context, sessionID string, userPrompt string) {
+	if userPrompt == "" {
+		return
+	}
+
+	// Ensure the session always gets a title even if every path below
+	// fails or the context is cancelled before we finish.
+	var titleSaved bool
+	defer func() {
+		if !titleSaved {
+			fallbackCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+			defer cancel()
+			if err := a.sessions.Rename(fallbackCtx, sessionID, DefaultSessionName); err != nil {
+				slog.Error("Failed to save fallback session title", "error", err)
+			}
+		}
+	}()
+
+	smallModel := a.smallModel.Get()
+	largeModel := a.largeModel.Get()
+	systemPromptPrefix := a.systemPromptPrefix.Get()
+
+	newAgent := func(m fantasy.LanguageModel, p []byte, tok int64) fantasy.Agent {
+		return fantasy.NewAgent(
+			m,
+			fantasy.WithSystemPrompt(string(p)+"\n /no_think"),
+			fantasy.WithMaxOutputTokens(tok),
+			fantasy.WithUserAgent(userAgent),
+		)
+	}
+
+	streamCall := fantasy.AgentStreamCall{
+		Prompt:  fmt.Sprintf("Generate a concise title for the following content:\n\n%s\n <think>\n\n</think>", userPrompt),
+		Headers: sessionHeaders(sessionID),
+		PrepareStep: func(callCtx context.Context, opts fantasy.PrepareStepFunctionOptions) (_ context.Context, prepared fantasy.PrepareStepResult, err error) {
+			prepared.Messages = opts.Messages
+			if systemPromptPrefix != "" {
+				prepared.Messages = append([]fantasy.Message{
+					fantasy.NewSystemMessage(systemPromptPrefix),
+				}, prepared.Messages...)
+			}
+			return callCtx, prepared, nil
+		},
+	}
+
+	type modelAttempt struct {
+		name  string
+		model Model
+	}
+	attempts := []modelAttempt{
+		{"small", smallModel},
+		{"large", largeModel},
+	}
+
+	var resp *fantasy.AgentResult
+	var err error
+	var model Model
+	var success bool
+	for _, attempt := range attempts {
+		tok := int64(40)
+		if attempt.model.CatwalkCfg.CanReason {
+			tok = attempt.model.CatwalkCfg.DefaultMaxTokens
+		}
+		agent := newAgent(attempt.model.Model, titlePrompt, tok)
+		resp, err = agent.Stream(ctx, streamCall)
+		if err == nil && resp.Response.FinishReason != fantasy.FinishReasonLength {
+			model = attempt.model
+			slog.Debug("Generated title with " + attempt.name + " model")
+			success = true
+			break
+		}
+		if err != nil {
+			slog.Error("Error generating title with "+attempt.name+" model; trying next", "err", err)
+		} else {
+			slog.Error("Title generation hit token limit with " + attempt.name + " model; trying next")
+		}
+	}
+	if !success {
+		// The deferred fallback will save the default session name.
+		return
+	}
+
+	// Clean up title.
+	var title string
+	title = strings.ReplaceAll(resp.Response.Content.Text(), "\n", " ")
+
+	// Remove thinking tags if present.
+	title = thinkTagRegex.ReplaceAllString(title, "")
+	title = orphanThinkTagRegex.ReplaceAllString(title, "")
+
+	title = strings.TrimSpace(title)
+	if title == "" {
+		// LLM returned empty content. Use the prompt itself as a
+		// fallback title, truncated to 50 chars, before resorting to
+		// the generic default.
+		fallback := strings.ReplaceAll(userPrompt, "\n", " ")
+		fallback = strings.TrimSpace(fallback)
+		if len(fallback) > 50 {
+			fallback = ansi.Truncate(fallback, 50, "…")
+		}
+		title = cmp.Or(fallback, DefaultSessionName)
+	}
+
+	// Calculate usage and cost.
+	var openrouterCost *float64
+	for _, step := range resp.Steps {
+		stepCost := a.openrouterCost(step.ProviderMetadata)
+		if stepCost != nil {
+			newCost := *stepCost
+			if openrouterCost != nil {
+				newCost += *openrouterCost
+			}
+			openrouterCost = &newCost
+		}
+		extractHyperCredits(step.ProviderMetadata)
+	}
+
+	modelConfig := model.CatwalkCfg
+	cost := modelConfig.CostPer1MInCached/1e6*float64(resp.TotalUsage.CacheCreationTokens) +
+		modelConfig.CostPer1MOutCached/1e6*float64(resp.TotalUsage.CacheReadTokens) +
+		modelConfig.CostPer1MIn/1e6*float64(resp.TotalUsage.InputTokens) +
+		modelConfig.CostPer1MOut/1e6*float64(resp.TotalUsage.OutputTokens)
+
+	// Use override cost if available (e.g., from OpenRouter).
+	if openrouterCost != nil {
+		cost = *openrouterCost
+	}
+
+	// Skip cost accumulation
+	if model.FlatRate {
+		cost = 0
+	}
+
+	promptTokens := resp.TotalUsage.InputTokens + resp.TotalUsage.CacheCreationTokens
+	completionTokens := resp.TotalUsage.OutputTokens
+
+	// Atomically update only title and usage fields to avoid overriding other
+	// concurrent session updates.
+	saveErr := a.sessions.UpdateTitleAndUsage(ctx, sessionID, title, promptTokens, completionTokens, cost)
+	if saveErr != nil {
+		slog.Error("Failed to save session title and usage", "error", saveErr)
+		return
+	}
+	titleSaved = true
+}
+
+func (a *sessionAgent) openrouterCost(metadata fantasy.ProviderMetadata) *float64 {
+	openrouterMetadata, ok := metadata[openrouter.Name]
+	if !ok {
+		return nil
+	}
+
+	opts, ok := openrouterMetadata.(*openrouter.ProviderMetadata)
+	if !ok {
+		return nil
+	}
+	return &opts.Usage.Cost
+}
+
+// extractHyperCredits reads usage.remaining.hypercredits from OpenAI
+// provider metadata and stores it for the next FetchCredits call.
+func extractHyperCredits(metadata fantasy.ProviderMetadata) {
+	openaiMeta, ok := metadata[openai.Name]
+	if !ok {
+		return
+	}
+	pm, ok := openaiMeta.(*openai.ProviderMetadata)
+	if !ok {
+		return
+	}
+	var remaining struct {
+		Hypercredits float64 `json:"hypercredits"`
+	}
+	if pm.ExtraField("remaining", &remaining) && remaining.Hypercredits > 0 {
+		hyper.SetBalance(int(math.Round(remaining.Hypercredits)))
+	}
+}
+
+// extractPrismModel returns the ID and name of the model that actually
+// served the turn, as reported by the Hyper Prism model router headers,
+// or empty strings when the turn was not routed through a Prism model.
+func extractPrismModel(metadata fantasy.ProviderMetadata) (modelID, modelName string) {
+	openaiMeta, ok := metadata[openai.Name]
+	if !ok {
+		return "", ""
+	}
+	pm, ok := openaiMeta.(*openai.ProviderMetadata)
+	if !ok {
+		return "", ""
+	}
+	_ = pm.ExtraField(hyper.PrismModelIDField, &modelID)
+	_ = pm.ExtraField(hyper.PrismModelNameField, &modelName)
+	return modelID, modelName
+}
+
+// extractPrismSavings returns the hypercredit and dollar savings from
+// routing the turn through the Hyper Prism model router, as reported by
+// its savings trailers, or nil when not reported or malformed.
+func extractPrismSavings(metadata fantasy.ProviderMetadata) (hypercredits, dollars *float64) {
+	openaiMeta, ok := metadata[openai.Name]
+	if !ok {
+		return nil, nil
+	}
+	pm, ok := openaiMeta.(*openai.ProviderMetadata)
+	if !ok {
+		return nil, nil
+	}
+	return extraFieldFloat(pm, hyper.PrismHypercreditSavingsField), extraFieldFloat(pm, hyper.PrismDollarSavingsField)
+}
+
+func extraFieldFloat(pm *openai.ProviderMetadata, key string) *float64 {
+	var value string
+	if !pm.ExtraField(key, &value) {
+		return nil
+	}
+	parsed, err := strconv.ParseFloat(value, 64)
+	if err != nil {
+		slog.Warn("Could not parse Prism savings", "key", key, "value", value, "error", err)
+		return nil
+	}
+	return &parsed
+}
+
+func (a *sessionAgent) updateSessionUsage(model Model, session *session.Session, usage fantasy.Usage, overrideCost *float64, estimated bool) {
+	if !usageIsZero(usage) {
+		session.EstimatedUsage = estimated
+	}
+
+	modelConfig := model.CatwalkCfg
+	cost := modelConfig.CostPer1MInCached/1e6*float64(usage.CacheCreationTokens) +
+		modelConfig.CostPer1MOutCached/1e6*float64(usage.CacheReadTokens) +
+		modelConfig.CostPer1MIn/1e6*float64(usage.InputTokens) +
+		modelConfig.CostPer1MOut/1e6*float64(usage.OutputTokens)
+
+	if !estimated {
+		a.eventTokensUsed(session.ID, model, usage, cost)
+	}
+
+	if estimated {
+		cost = 0
+	} else {
+		// Use override cost if available (e.g., from OpenRouter).
+		if overrideCost != nil {
+			cost = *overrideCost
+		}
+
+		// Skip cost accumulation
+		if model.FlatRate {
+			cost = 0
+		}
+	}
+
+	session.Cost += cost
+	updateSessionTokenCounters(session, usage)
+}
+
+func updateSessionTokenCounters(session *session.Session, usage fantasy.Usage) {
+	if usage.OutputTokens != 0 {
+		session.CompletionTokens = usage.OutputTokens
+	}
+	if promptTokens := usage.InputTokens + usage.CacheReadTokens; promptTokens != 0 {
+		session.PromptTokens = promptTokens
+	}
+}
+
+func summaryCompletionTokens(usage fantasy.Usage, summaryMessage message.Message) int64 {
+	if usage.OutputTokens != 0 {
+		return usage.OutputTokens
+	}
+	return approxTokenCount(summaryMessage.Content().Text) + approxTokenCount(summaryMessage.ReasoningContent().String())
+}
+
+func (a *sessionAgent) Cancel(sessionID string) {
+	// Serialize against the dispatch handoff in Run so the accepted ->
+	// (cancel-on-entry | queued | active) transition is atomic against
+	// this cancel. Every cancel observes at least one of: an active
+	// request, an accepted run (recorded as a pending cancel), or a
+	// queue entry it then clears. If none of those hold, an idle Escape
+	// is a true no-op and must not poison the next prompt.
+	mu := a.sessionMu(sessionID)
+	mu.Lock()
+	defer mu.Unlock()
+
+	// Cancel regular requests. Don't use Take() here - we need the entry to
+	// remain in activeRequests so IsBusy() returns true until the goroutine
+	// fully completes (including error handling that may access the DB).
+	// The defer in processRequest will clean up the entry.
+	if ac, ok := a.activeRequests.Get(sessionID); ok && ac != nil {
+		slog.Debug("Request cancellation initiated", "session_id", sessionID)
+		ac.cancel()
+	}
+
+	// Also check for summarize requests.
+	if ac, ok := a.activeRequests.Get(sessionID + "-summarize"); ok && ac != nil {
+		slog.Debug("Summarize cancellation initiated", "session_id", sessionID)
+		ac.cancel()
+	}
+
+	// Record a pending cancel only when a dispatched-but-not-yet-active
+	// run exists. This catches runs still in the goroutine scheduler or
+	// about to enter Run's busy-queue branch, while leaving an idle
+	// session untouched. Active and accepted are not mutually exclusive:
+	// when a run is active and a follow-up has been accepted, both the
+	// cancel above and this pending record fire.
+	//
+	// Raise the session's cancel mark to the latest accept sequence
+	// assigned so far. Every prompt currently accepted-but-not-yet-
+	// active has a sequence at or below that value, so one cancel covers
+	// all of them; a prompt accepted after this cancel gets a strictly
+	// higher sequence and is never poisoned. Using max keeps repeated
+	// cancels idempotent while the same prompts are in flight and lets a
+	// later cancel extend coverage to prompts accepted since.
+	a.acceptedMu.Lock()
+	count, ok := a.acceptedRuns.Get(sessionID)
+	mark := a.acceptSeqGen
+	a.acceptedMu.Unlock()
+	if ok && count > 0 {
+		slog.Debug("Recording cancel mark for accepted runs", "session_id", sessionID, "count", count, "mark", mark)
+		existing, _ := a.cancelMark.Get(sessionID)
+		a.cancelMark.Set(sessionID, max(existing, mark))
+	}
+
+	if a.QueuedPrompts(sessionID) > 0 {
+		slog.Debug("Clearing queued prompts", "session_id", sessionID)
+		a.clearQueueAndNotify(sessionID)
+	}
+}
+
+func (a *sessionAgent) ClearQueue(sessionID string) {
+	if a.QueuedPrompts(sessionID) > 0 {
+		slog.Debug("Clearing queued prompts", "session_id", sessionID)
+		a.clearQueueAndNotify(sessionID)
+	}
+}
+
+func (a *sessionAgent) CancelAll() {
+	if !a.IsBusy() {
+		return
+	}
+	for key := range a.activeRequests.Seq2() {
+		a.Cancel(key) // key is sessionID
+	}
+
+	timeout := time.After(5 * time.Second)
+	for a.IsBusy() {
+		select {
+		case <-timeout:
+			return
+		default:
+			time.Sleep(200 * time.Millisecond)
+		}
+	}
+}
+
+func (a *sessionAgent) IsBusy() bool {
+	var busy bool
+	for ac := range a.activeRequests.Seq() {
+		if ac != nil {
+			busy = true
+			break
+		}
+	}
+	return busy
+}
+
+func (a *sessionAgent) IsSessionBusy(sessionID string) bool {
+	_, busy := a.activeRequests.Get(sessionID)
+	return busy
+}
+
+func (a *sessionAgent) QueuedPrompts(sessionID string) int {
+	l, ok := a.messageQueue.Get(sessionID)
+	if !ok {
+		return 0
+	}
+	return len(l)
+}
+
+func (a *sessionAgent) QueuedPromptsList(sessionID string) []string {
+	l, ok := a.messageQueue.Get(sessionID)
+	if !ok {
+		return nil
+	}
+	prompts := make([]string, len(l))
+	for i, call := range l {
+		prompts[i] = call.Prompt
+	}
+	return prompts
+}
+
+func (a *sessionAgent) SetModels(large Model, small Model) {
+	a.largeModel.Set(large)
+	a.smallModel.Set(small)
+}
+
+func (a *sessionAgent) SetTools(tools []fantasy.AgentTool) {
+	a.tools.SetSlice(tools)
+}
+
+func (a *sessionAgent) SetSystemPrompt(systemPrompt string) {
+	a.systemPrompt.Set(systemPrompt)
+}
+
+func (a *sessionAgent) Model() Model {
+	return a.largeModel.Get()
+}
+
+// convertToToolResult converts a fantasy tool result to a message tool result.
+func (a *sessionAgent) convertToToolResult(result fantasy.ToolResultContent) message.ToolResult {
+	baseResult := message.ToolResult{
+		ToolCallID: result.ToolCallID,
+		Name:       result.ToolName,
+		Metadata:   result.ClientMetadata,
+	}
+
+	switch result.Result.GetType() {
+	case fantasy.ToolResultContentTypeText:
+		if r, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentText](result.Result); ok {
+			baseResult.Content = r.Text
+		}
+	case fantasy.ToolResultContentTypeError:
+		if r, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentError](result.Result); ok {
+			baseResult.Content = r.Error.Error()
+			baseResult.IsError = true
+		}
+	case fantasy.ToolResultContentTypeMedia:
+		if r, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentMedia](result.Result); ok {
+			if !stringext.IsValidBase64(r.Data) {
+				slog.Warn(
+					"Tool returned media with invalid base64 data, discarding image",
+					"tool", result.ToolName,
+					"tool_call_id", result.ToolCallID,
+				)
+				baseResult.Content = "Tool returned image data with invalid encoding"
+				baseResult.IsError = true
+			} else {
+				content := r.Text
+				if content == "" {
+					content = fmt.Sprintf("Loaded %s content", r.MediaType)
+				}
+				baseResult.Content = content
+				baseResult.Data = r.Data
+				baseResult.MIMEType = r.MediaType
+			}
+		}
+	}
+
+	return baseResult
+}
+
+// workaroundProviderMediaLimitations converts media content in tool results to
+// user messages for providers that don't natively support images in tool results.
+//
+// Problem: OpenAI, Google, OpenRouter, and other OpenAI-compatible providers
+// don't support sending images/media in tool result messages - they only accept
+// text in tool results. However, they DO support images in user messages.
+//
+// If we send media in tool results to these providers, the API returns an error.
+//
+// Solution: For these providers, we:
+//  1. Replace the media in the tool result with a text placeholder
+//  2. Inject a user message immediately after with the image as a file attachment
+//  3. This maintains the tool execution flow while working around API limitations
+//
+// Anthropic and Bedrock support images natively in tool results, so we skip
+// this workaround for them.
+//
+// Example transformation:
+//
+//	BEFORE: [tool result: image data]
+//	AFTER:  [tool result: "Image loaded - see attached"], [user: image attachment]
+func (a *sessionAgent) workaroundProviderMediaLimitations(messages []fantasy.Message, largeModel Model) []fantasy.Message {
+	providerSupportsMedia := largeModel.ModelCfg.Provider == string(catwalk.InferenceProviderAnthropic) ||
+		largeModel.ModelCfg.Provider == string(catwalk.InferenceProviderBedrock) ||
+		largeModel.ModelCfg.Provider == string(catwalk.InferenceProviderBedrockEurope)
+
+	if providerSupportsMedia {
+		return messages
+	}
+
+	supportsImages := largeModel.CatwalkCfg.SupportsImages
+
+	convertedMessages := make([]fantasy.Message, 0, len(messages))
+
+	for _, msg := range messages {
+		if msg.Role != fantasy.MessageRoleTool {
+			convertedMessages = append(convertedMessages, msg)
+			continue
+		}
+
+		textParts := make([]fantasy.MessagePart, 0, len(msg.Content))
+		var mediaFiles []fantasy.FilePart
+
+		for _, part := range msg.Content {
+			toolResult, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part)
+			if !ok {
+				textParts = append(textParts, part)
+				continue
+			}
+
+			if media, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentMedia](toolResult.Output); ok {
+				if !supportsImages {
+					// Model cannot process images. Replace with a text
+					// placeholder and skip creating a synthetic user
+					// message with FilePart, which would brick the
+					// session on text-only models.
+					textParts = append(textParts, fantasy.ToolResultPart{
+						ToolCallID: toolResult.ToolCallID,
+						Output: fantasy.ToolResultOutputContentText{
+							Text: "[Image/media content not supported by this model]",
+						},
+						ProviderOptions: toolResult.ProviderOptions,
+					})
+					continue
+				}
+
+				decoded, err := base64.StdEncoding.DecodeString(media.Data)
+				if err != nil {
+					slog.Warn("Failed to decode media data", "error", err)
+					textParts = append(textParts, part)
+					continue
+				}
+
+				mediaFiles = append(mediaFiles, fantasy.FilePart{
+					Data:      decoded,
+					MediaType: media.MediaType,
+					Filename:  fmt.Sprintf("tool-result-%s", toolResult.ToolCallID),
+				})
+
+				textParts = append(textParts, fantasy.ToolResultPart{
+					ToolCallID: toolResult.ToolCallID,
+					Output: fantasy.ToolResultOutputContentText{
+						Text: "[Image/media content loaded - see attached file]",
+					},
+					ProviderOptions: toolResult.ProviderOptions,
+				})
+			} else {
+				textParts = append(textParts, part)
+			}
+		}
+
+		convertedMessages = append(convertedMessages, fantasy.Message{
+			Role:    fantasy.MessageRoleTool,
+			Content: textParts,
+		})
+
+		if len(mediaFiles) > 0 {
+			convertedMessages = append(convertedMessages, fantasy.NewUserMessage(
+				"Here is the media content from the tool result:",
+				mediaFiles...,
+			))
+		}
+	}
+
+	return convertedMessages
+}
+
+// buildSummaryPrompt constructs the prompt text for session summarization.
+func buildSummaryPrompt(todos []session.Todo) string {
+	var sb strings.Builder
+	sb.WriteString("Provide a detailed summary of our conversation above.")
+	if len(todos) > 0 {
+		sb.WriteString("\n\n## Current Todo List\n\n")
+		for _, t := range todos {
+			fmt.Fprintf(&sb, "- [%s] %s\n", t.Status, t.Content)
+		}
+		sb.WriteString("\nInclude these tasks and their statuses in your summary. ")
+		sb.WriteString("Instruct the resuming assistant to use the `todos` tool to continue tracking progress on these tasks.")
+	}
+	return sb.String()
+}
+
+func providerRetryLogFields(err *fantasy.ProviderError, delay time.Duration) []any {
+	fields := []any{
+		"retry_delay", delay.String(),
+	}
+	if err == nil {
+		return fields
+	}
+	fields = append(fields, "status_code", err.StatusCode)
+	if err.Title != "" {
+		fields = append(fields, "title", err.Title)
+	}
+	if err.Message != "" {
+		fields = append(fields, "message", err.Message)
+	}
+	return fields
+}
+
+// sanitizeToolInput validates tool call JSON from the provider.
+// Malformed input is replaced with an empty object to prevent
+// stuck conversations from truncated or malformed model output.
+// The second return value indicates whether sanitization occurred.
+func sanitizeToolInput(toolName, toolCallID, input string) (string, bool) {
+	if !json.Valid([]byte(input)) {
+		slog.Warn(
+			"Malformed tool call JSON from provider, replacing with empty object",
+			"tool", toolName,
+			"id", toolCallID,
+			"input_len", len(input),
+		)
+		return "{}", true
+	}
+	return input, false
+}

internal/agent/agent_test.go

@@ -0,0 +1,1353 @@
+package agent
+
+import (
+	"encoding/base64"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"charm.land/x/vcr"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	_ "github.com/joho/godotenv/autoload"
+)
+
+func TestMain(m *testing.M) {
+	slog.SetLogLoggerLevel(slog.LevelError)
+	m.Run()
+}
+
+var modelPairs = []modelPair{
+	{"deepseek-v4", hyperBuilder("deepseek-v4-pro-0813"), hyperBuilder("deepseek-v4-flash-0731")},
+}
+
+func getModels(t *testing.T, r *vcr.Recorder, pair modelPair) (fantasy.LanguageModel, fantasy.LanguageModel) {
+	large, err := pair.largeModel(t, r)
+	require.NoError(t, err)
+	small, err := pair.smallModel(t, r)
+	require.NoError(t, err)
+	return large, small
+}
+
+func setupAgent(t *testing.T, pair modelPair) (SessionAgent, fakeEnv) {
+	r := vcr.NewRecorder(t)
+	large, small := getModels(t, r, pair)
+	env := testEnv(t)
+
+	createSimpleGoProject(t, env.workingDir)
+	agent, err := coderAgent(r, env, large, small)
+	require.NoError(t, err)
+	return agent, env
+}
+
+func TestCoderAgent(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping on windows for now")
+	}
+
+	for _, pair := range modelPairs {
+		t.Run(pair.name, func(t *testing.T) {
+			t.Run("simple test", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "Hello",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+				// Should have the agent and user message
+				assert.Equal(t, len(msgs), 2)
+			})
+			t.Run("read a file", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "Read the go mod",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+				foundFile := false
+				var tcID string
+			out:
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.ViewToolName {
+								tcID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == tcID {
+								if strings.Contains(tr.Content, "module example.com/testproject") {
+									foundFile = true
+									break out
+								}
+							}
+						}
+					}
+				}
+				require.True(t, foundFile)
+			})
+			t.Run("update a file", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "update the main.go file by changing the print to say hello from crush",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundRead := false
+				foundWrite := false
+				var readTCID, writeTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.ViewToolName {
+								readTCID = tc.ID
+							}
+							if tc.Name == tools.EditToolName || tc.Name == tools.WriteToolName {
+								writeTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == readTCID {
+								foundRead = true
+							}
+							if tr.ToolCallID == writeTCID {
+								foundWrite = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundRead, "Expected to find a read operation")
+				require.True(t, foundWrite, "Expected to find a write operation")
+
+				mainGoPath := filepath.Join(env.workingDir, "main.go")
+				content, err := os.ReadFile(mainGoPath)
+				require.NoError(t, err)
+				require.Contains(t, strings.ToLower(string(content)), "hello from crush")
+			})
+			t.Run("bash tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use bash to create a file named test.txt with content 'hello bash'. do not print its timestamp",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundBash := false
+				var bashTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.BashToolName {
+								bashTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == bashTCID {
+								foundBash = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundBash, "Expected to find a bash operation")
+
+				testFilePath := filepath.Join(env.workingDir, "test.txt")
+				content, err := os.ReadFile(testFilePath)
+				require.NoError(t, err)
+				require.Contains(t, string(content), "hello bash")
+			})
+			t.Run("download tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "download the file from https://example-files.online-convert.com/document/txt/example.txt and save it as example.txt",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundDownload := false
+				var downloadTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.DownloadToolName {
+								downloadTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == downloadTCID {
+								foundDownload = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundDownload, "Expected to find a download operation")
+
+				examplePath := filepath.Join(env.workingDir, "example.txt")
+				_, err = os.Stat(examplePath)
+				require.NoError(t, err, "Expected example.txt file to exist")
+			})
+			t.Run("fetch tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "fetch the content from https://example-files.online-convert.com/website/html/example.html and tell me if it contains the word 'John Doe'",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundFetch := false
+				var fetchTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.FetchToolName {
+								fetchTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == fetchTCID {
+								foundFetch = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundFetch, "Expected to find a fetch operation")
+			})
+			t.Run("glob tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use glob to find all .go files in the current directory",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundGlob := false
+				var globTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.GlobToolName {
+								globTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == globTCID {
+								foundGlob = true
+								require.Contains(t, tr.Content, "main.go", "Expected glob to find main.go")
+							}
+						}
+					}
+				}
+
+				require.True(t, foundGlob, "Expected to find a glob operation")
+			})
+			t.Run("grep tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use grep to search for the word 'package' in go files",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundGrep := false
+				var grepTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.GrepToolName {
+								grepTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == grepTCID {
+								foundGrep = true
+								require.Contains(t, tr.Content, "main.go", "Expected grep to find main.go")
+							}
+						}
+					}
+				}
+
+				require.True(t, foundGrep, "Expected to find a grep operation")
+			})
+			t.Run("ls tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use ls to list the files in the current directory",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundLS := false
+				var lsTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.LSToolName {
+								lsTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == lsTCID {
+								foundLS = true
+								require.Contains(t, tr.Content, "main.go", "Expected ls to list main.go")
+								require.Contains(t, tr.Content, "go.mod", "Expected ls to list go.mod")
+							}
+						}
+					}
+				}
+
+				require.True(t, foundLS, "Expected to find an ls operation")
+			})
+			t.Run("multiedit tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use multiedit to change 'Hello, World!' to 'Hello, Crush!' and add a comment '// Greeting' above the fmt.Println line in main.go",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundMultiEdit := false
+				var multiEditTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.MultiEditToolName {
+								multiEditTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == multiEditTCID {
+								foundMultiEdit = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundMultiEdit, "Expected to find a multiedit operation")
+
+				mainGoPath := filepath.Join(env.workingDir, "main.go")
+				content, err := os.ReadFile(mainGoPath)
+				require.NoError(t, err)
+				require.Contains(t, string(content), "Hello, Crush!", "Expected file to contain 'Hello, Crush!'")
+			})
+			t.Run("sourcegraph tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use sourcegraph to search for 'func main' in Go repositories",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundSourcegraph := false
+				var sourcegraphTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.SourcegraphToolName {
+								sourcegraphTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == sourcegraphTCID {
+								foundSourcegraph = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundSourcegraph, "Expected to find a sourcegraph operation")
+			})
+			t.Run("write tool", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use write to create a new file called config.json with content '{\"name\": \"test\", \"version\": \"1.0.0\"}'",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				foundWrite := false
+				var writeTCID string
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant {
+						for _, tc := range msg.ToolCalls() {
+							if tc.Name == tools.WriteToolName {
+								writeTCID = tc.ID
+							}
+						}
+					}
+					if msg.Role == message.Tool {
+						for _, tr := range msg.ToolResults() {
+							if tr.ToolCallID == writeTCID {
+								foundWrite = true
+							}
+						}
+					}
+				}
+
+				require.True(t, foundWrite, "Expected to find a write operation")
+
+				configPath := filepath.Join(env.workingDir, "config.json")
+				content, err := os.ReadFile(configPath)
+				require.NoError(t, err)
+				require.Contains(t, string(content), "test", "Expected config.json to contain 'test'")
+				require.Contains(t, string(content), "1.0.0", "Expected config.json to contain '1.0.0'")
+			})
+			t.Run("parallel tool calls", func(t *testing.T) {
+				agent, env := setupAgent(t, pair)
+
+				session, err := env.sessions.Create(t.Context(), "New Session")
+				require.NoError(t, err)
+
+				res, err := agent.Run(t.Context(), SessionAgentCall{
+					Prompt:          "use glob to find all .go files and use ls to list the current directory, it is very important that you run both tool calls in parallel",
+					SessionID:       session.ID,
+					MaxOutputTokens: 10000,
+				})
+				require.NoError(t, err)
+				assert.NotNil(t, res)
+
+				msgs, err := env.messages.List(t.Context(), session.ID)
+				require.NoError(t, err)
+
+				var assistantMsg *message.Message
+				var toolMsgs []message.Message
+
+				for _, msg := range msgs {
+					if msg.Role == message.Assistant && len(msg.ToolCalls()) > 0 {
+						assistantMsg = &msg
+					}
+					if msg.Role == message.Tool {
+						toolMsgs = append(toolMsgs, msg)
+					}
+				}
+
+				require.NotNil(t, assistantMsg, "Expected to find an assistant message with tool calls")
+				require.NotNil(t, toolMsgs, "Expected to find a tool message")
+
+				toolCalls := assistantMsg.ToolCalls()
+				require.GreaterOrEqual(t, len(toolCalls), 2, "Expected at least 2 tool calls in parallel")
+
+				foundGlob := false
+				foundLS := false
+				var globTCID, lsTCID string
+
+				for _, tc := range toolCalls {
+					if tc.Name == tools.GlobToolName {
+						foundGlob = true
+						globTCID = tc.ID
+					}
+					if tc.Name == tools.LSToolName {
+						foundLS = true
+						lsTCID = tc.ID
+					}
+				}
+
+				require.True(t, foundGlob, "Expected to find a glob tool call")
+				require.True(t, foundLS, "Expected to find an ls tool call")
+
+				require.GreaterOrEqual(t, len(toolMsgs), 2, "Expected at least 2 tool results in the same message")
+
+				foundGlobResult := false
+				foundLSResult := false
+
+				for _, msg := range toolMsgs {
+					for _, tr := range msg.ToolResults() {
+						if tr.ToolCallID == globTCID {
+							foundGlobResult = true
+							require.Contains(t, tr.Content, "main.go", "Expected glob result to contain main.go")
+							require.False(t, tr.IsError, "Expected glob result to not be an error")
+						}
+						if tr.ToolCallID == lsTCID {
+							foundLSResult = true
+							require.Contains(t, tr.Content, "main.go", "Expected ls result to contain main.go")
+							require.False(t, tr.IsError, "Expected ls result to not be an error")
+						}
+					}
+				}
+
+				require.True(t, foundGlobResult, "Expected to find glob tool result")
+				require.True(t, foundLSResult, "Expected to find ls tool result")
+			})
+		})
+	}
+}
+
+func makeTestTodos(n int) []session.Todo {
+	todos := make([]session.Todo, n)
+	for i := range n {
+		todos[i] = session.Todo{
+			Status:  session.TodoStatusPending,
+			Content: fmt.Sprintf("Task %d: Implement feature with some description that makes it realistic", i),
+		}
+	}
+	return todos
+}
+
+func BenchmarkBuildSummaryPrompt(b *testing.B) {
+	cases := []struct {
+		name     string
+		numTodos int
+	}{
+		{"0todos", 0},
+		{"5todos", 5},
+		{"10todos", 10},
+		{"50todos", 50},
+	}
+
+	for _, tc := range cases {
+		todos := makeTestTodos(tc.numTodos)
+
+		b.Run(tc.name, func(b *testing.B) {
+			b.ReportAllocs()
+			for range b.N {
+				_ = buildSummaryPrompt(todos)
+			}
+		})
+	}
+}
+
+func TestPreparePrompt_FiltersImageAttachments(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	// User message with text, a text attachment, and an image attachment.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "hello world"},
+			message.BinaryContent{Path: "notes.txt", MIMEType: "text/plain", Data: []byte("important notes")},
+			message.BinaryContent{Path: "image.png", MIMEType: "image/png", Data: []byte("fake-image-data")},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	// New-turn image attachment (not yet stored in the DB).
+	imageAtt := message.Attachment{
+		FileName: "screenshot.png",
+		MimeType: "image/png",
+		Content:  []byte("fake-screenshot"),
+	}
+
+	// When supportsImages is false, image attachments should be stripped
+	// from history AND from the files list.
+	history, files := agent.preparePrompt(msgs, false, imageAtt)
+	// First message is the system reminder, second is the user message.
+	require.Len(t, history, 2)
+	require.Len(t, history[1].Content, 1)
+	text, ok := fantasy.AsMessagePart[fantasy.TextPart](history[1].Content[0])
+	require.True(t, ok)
+	require.Contains(t, text.Text, "hello world")
+	require.Contains(t, text.Text, "important notes")
+	require.Empty(t, files, "image files should be excluded when model does not support images")
+
+	// When supportsImages is true, image attachments should remain in
+	// history and be included in the files list.
+	history, files = agent.preparePrompt(msgs, true, imageAtt)
+	require.Len(t, history, 2)
+	require.Len(t, history[1].Content, 2)
+	text, ok = fantasy.AsMessagePart[fantasy.TextPart](history[1].Content[0])
+	require.True(t, ok)
+	require.Contains(t, text.Text, "hello world")
+	file, ok := fantasy.AsMessagePart[fantasy.FilePart](history[1].Content[1])
+	require.True(t, ok)
+	require.Equal(t, "image.png", file.Filename)
+	require.Len(t, files, 1, "new-turn image attachment should be included when model supports images")
+	require.Equal(t, "screenshot.png", files[0].Filename)
+}
+
+func TestCreateUserMessage_RetainsAllAttachments(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	// Mix of text and image attachments — all should be stored.
+	call := SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "look at this image",
+		Attachments: []message.Attachment{
+			{FileName: "notes.txt", FilePath: "notes.txt", MimeType: "text/plain", Content: []byte("notes")},
+			{FileName: "photo.png", FilePath: "photo.png", MimeType: "image/png", Content: []byte("fake-png")},
+		},
+	}
+
+	msg, err := agent.createUserMessage(ctx, call)
+	require.NoError(t, err)
+
+	// All attachments should be present as BinaryContent parts.
+	binaryParts := msg.BinaryContent()
+	require.Len(t, binaryParts, 2, "both text and image attachments should be stored in the user message")
+	require.Equal(t, "notes.txt", binaryParts[0].Path)
+	require.Equal(t, "text/plain", binaryParts[0].MIMEType)
+	require.Equal(t, "photo.png", binaryParts[1].Path)
+	require.Equal(t, "image/png", binaryParts[1].MIMEType)
+
+	// Reload from DB to verify persistence.
+	reloaded, err := env.messages.Get(ctx, msg.ID)
+	require.NoError(t, err)
+	binaryParts = reloaded.BinaryContent()
+	require.Len(t, binaryParts, 2, "attachments should survive DB round-trip")
+	require.Equal(t, "photo.png", binaryParts[1].Path)
+}
+
+func TestPreparePrompt_OrphanedToolUse(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	// Create a user message.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "hello"},
+		},
+	})
+	require.NoError(t, err)
+
+	// Create an assistant message with a tool call but no tool result —
+	// this simulates a cancelled/interrupted agent tool call.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "let me check"},
+			message.ToolCall{
+				ID:       "call_orphaned_1",
+				Name:     "agent",
+				Input:    `{"prompt":"do something"}`,
+				Finished: true,
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	// Create the next user message (the one that interrupted the tool call).
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "Fix #2"},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	history, _ := agent.preparePrompt(msgs, true)
+
+	// The history must contain a synthetic tool result for the orphaned call.
+	found := false
+	for _, msg := range history {
+		if msg.Role != fantasy.MessageRoleTool {
+			continue
+		}
+		for _, part := range msg.Content {
+			if tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part); ok {
+				if tr.ToolCallID == "call_orphaned_1" {
+					found = true
+					_, isError := tr.Output.(fantasy.ToolResultOutputContentError)
+					require.True(t, isError, "orphaned tool result should be an error")
+				}
+			}
+		}
+	}
+	require.True(t, found, "expected synthetic tool result for orphaned tool call")
+}
+
+func TestPreparePrompt_OrphanedToolUseMixed(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "hello"},
+		},
+	})
+	require.NoError(t, err)
+
+	// Assistant with 2 tool calls: one has a result, one is orphaned.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.ToolCall{
+				ID:       "call_ok",
+				Name:     "view",
+				Input:    `{"path":"/foo"}`,
+				Finished: true,
+			},
+			message.ToolCall{
+				ID:       "call_orphaned",
+				Name:     "agent",
+				Input:    `{"prompt":"search"}`,
+				Finished: true,
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	// Only one tool result — for call_ok.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{
+				ToolCallID: "call_ok",
+				Name:       "view",
+				Content:    "file contents",
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	history, _ := agent.preparePrompt(msgs, true)
+
+	// Should have a synthetic result only for the orphaned call.
+	var syntheticCount int
+	for _, msg := range history {
+		if msg.Role != fantasy.MessageRoleTool {
+			continue
+		}
+		for _, part := range msg.Content {
+			if tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part); ok {
+				if tr.ToolCallID == "call_orphaned" {
+					syntheticCount++
+				}
+			}
+		}
+	}
+	require.Equal(t, 1, syntheticCount, "expected exactly one synthetic result for the orphaned call")
+}
+
+// requireToolCallAdjacency asserts that every assistant message in history
+// with tool calls is immediately followed by a tool message that responds to
+// each of those calls, with no other message in between. This is what
+// strict-adjacency providers (e.g. Kimi, DeepSeek) require.
+func requireToolCallAdjacency(t *testing.T, history []fantasy.Message) {
+	t.Helper()
+	for i, msg := range history {
+		if msg.Role != fantasy.MessageRoleAssistant {
+			continue
+		}
+		var callIDs []string
+		for _, part := range msg.Content {
+			if tc, ok := fantasy.AsMessagePart[fantasy.ToolCallPart](part); ok {
+				callIDs = append(callIDs, tc.ToolCallID)
+			}
+		}
+		if len(callIDs) == 0 {
+			continue
+		}
+		require.Less(t, i+1, len(history), "assistant with tool calls must be followed by a tool message")
+		next := history[i+1]
+		require.Equal(t, fantasy.MessageRoleTool, next.Role,
+			"assistant with tool calls %v must be immediately followed by a tool message, got %q", callIDs, next.Role)
+		responded := make(map[string]bool, len(callIDs))
+		for _, part := range next.Content {
+			if tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part); ok {
+				responded[tr.ToolCallID] = true
+			}
+		}
+		for _, id := range callIDs {
+			require.True(t, responded[id],
+				"tool result for call %q must immediately follow its assistant message", id)
+		}
+	}
+}
+
+func TestPreparePrompt_NonAdjacentToolResults(t *testing.T) {
+	// A user message written between an assistant's tool call and its
+	// result (e.g. resuming while a tool is still running) must not end up
+	// between the two in the built history.
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "run commands"},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.ToolCall{
+				ID:       "call_A",
+				Name:     "bash",
+				Input:    `{"command":"date"}`,
+				Finished: true,
+			},
+			message.ToolCall{
+				ID:       "call_B",
+				Name:     "bash",
+				Input:    `{"command":"uptime"}`,
+				Finished: true,
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	// Interleaved user message written while the tools were still running.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "are we done?"},
+		},
+	})
+	require.NoError(t, err)
+
+	// Results arrive late, after the interleaved user message.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{
+				ToolCallID: "call_A",
+				Name:       "bash",
+				Content:    "Fri May 2 21:00:00 UTC 2026",
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{
+				ToolCallID: "call_B",
+				Name:       "bash",
+				Content:    "21:00  up 3 days",
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	require.Equal(t, message.User, msgs[2].Role, "interleaved user should be between assistant and results in DB order")
+
+	history, _ := agent.preparePrompt(msgs, false)
+
+	requireToolCallAdjacency(t, history)
+
+	// The interleaved user message must still be present, after the results.
+	var foundInterleaved bool
+	for _, msg := range history {
+		if msg.Role != fantasy.MessageRoleUser {
+			continue
+		}
+		for _, part := range msg.Content {
+			if text, ok := fantasy.AsMessagePart[fantasy.TextPart](part); ok && text.Text == "are we done?" {
+				foundInterleaved = true
+			}
+		}
+	}
+	require.True(t, foundInterleaved, "interleaved user message must not be dropped")
+}
+
+func TestPreparePrompt_ResultBeforeAssistant(t *testing.T) {
+	// A tool result written before its assistant message (e.g. concurrent
+	// writes) must be emitted after the assistant, exactly once, not at its
+	// stored position.
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{ToolCallID: "call_X", Name: "bash", Content: "result"},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.ToolCall{ID: "call_X", Name: "bash", Input: `{}`, Finished: true},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	history, _ := agent.preparePrompt(msgs, false)
+
+	requireToolCallAdjacency(t, history)
+
+	resultCount := 0
+	for _, msg := range history {
+		if msg.Role != fantasy.MessageRoleTool {
+			continue
+		}
+		for _, part := range msg.Content {
+			if tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part); ok && tr.ToolCallID == "call_X" {
+				resultCount++
+			}
+		}
+	}
+	require.Equal(t, 1, resultCount, "result must be emitted exactly once")
+}
+
+func TestPreparePrompt_BundledResultsAcrossAssistants(t *testing.T) {
+	// A single tool message can hold results for calls issued by different
+	// assistant messages. Each assistant must be followed by its own
+	// results, and no result may be emitted twice.
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.ToolCall{ID: "call_1", Name: "bash", Input: `{}`, Finished: true},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "and now?"},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Assistant,
+		Parts: []message.ContentPart{
+			message.ToolCall{ID: "call_2", Name: "view", Input: `{"path":"/foo"}`, Finished: true},
+		},
+	})
+	require.NoError(t, err)
+
+	// Both results land in the same tool message, out of order.
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{ToolCallID: "call_2", Name: "view", Content: "file contents"},
+			message.ToolResult{ToolCallID: "call_1", Name: "bash", Content: "output"},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	history, _ := agent.preparePrompt(msgs, false)
+
+	requireToolCallAdjacency(t, history)
+
+	counts := make(map[string]int)
+	for _, msg := range history {
+		if msg.Role != fantasy.MessageRoleTool {
+			continue
+		}
+		for _, part := range msg.Content {
+			if tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](part); ok {
+				counts[tr.ToolCallID]++
+			}
+		}
+	}
+	require.Equal(t, map[string]int{"call_1": 1, "call_2": 1}, counts,
+		"each result must be emitted exactly once, next to its assistant")
+}
+
+func TestPreparePrompt_DropsOrphanedToolResults(t *testing.T) {
+	// A tool result whose call is not in the history (e.g. the assistant
+	// message was cut off by a session summary) must be dropped instead of
+	// producing an unanswerable tool message.
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	ctx := t.Context()
+	sess, err := env.sessions.Create(ctx, "test")
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.Tool,
+		Parts: []message.ContentPart{
+			message.ToolResult{ToolCallID: "call_gone", Name: "bash", Content: "output"},
+		},
+	})
+	require.NoError(t, err)
+
+	_, err = env.messages.Create(ctx, sess.ID, message.CreateMessageParams{
+		Role: message.User,
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "hello"},
+		},
+	})
+	require.NoError(t, err)
+
+	msgs, err := env.messages.List(ctx, sess.ID)
+	require.NoError(t, err)
+
+	history, _ := agent.preparePrompt(msgs, false)
+
+	for _, msg := range history {
+		require.NotEqual(t, fantasy.MessageRoleTool, msg.Role, "orphaned tool results must be dropped")
+	}
+}
+
+func TestWorkaroundProviderMediaLimitations_TextOnlyModel(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	pngBase64 := base64.StdEncoding.EncodeToString([]byte("fake-png-data"))
+
+	messages := []fantasy.Message{
+		{
+			Role: fantasy.MessageRoleTool,
+			Content: []fantasy.MessagePart{
+				fantasy.ToolResultPart{
+					ToolCallID: "call_1",
+					Output: fantasy.ToolResultOutputContentMedia{
+						Data:      pngBase64,
+						MediaType: "image/png",
+					},
+				},
+			},
+		},
+	}
+
+	// Non-Anthropic provider, no image support — should replace media with
+	// a text placeholder and not create a synthetic user message.
+	largeModel := Model{
+		ModelCfg: config.SelectedModel{Provider: "openai"},
+		CatwalkCfg: catwalk.Model{
+			SupportsImages: false,
+		},
+	}
+
+	result := agent.workaroundProviderMediaLimitations(messages, largeModel)
+
+	// Should produce exactly one message: the tool message with a text
+	// placeholder. No synthetic user message with FilePart.
+	require.Len(t, result, 1)
+	require.Equal(t, fantasy.MessageRoleTool, result[0].Role)
+
+	tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](result[0].Content[0])
+	require.True(t, ok)
+	_, ok = fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentText](tr.Output)
+	require.True(t, ok)
+}
+
+func TestWorkaroundProviderMediaLimitations_VisionModel(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	pngBase64 := base64.StdEncoding.EncodeToString([]byte("fake-png-data"))
+
+	messages := []fantasy.Message{
+		{
+			Role: fantasy.MessageRoleTool,
+			Content: []fantasy.MessagePart{
+				fantasy.ToolResultPart{
+					ToolCallID: "call_1",
+					Output: fantasy.ToolResultOutputContentMedia{
+						Data:      pngBase64,
+						MediaType: "image/png",
+					},
+				},
+			},
+		},
+	}
+
+	// Non-Anthropic provider, image support — should create a synthetic
+	// user message with FilePart.
+	largeModel := Model{
+		ModelCfg: config.SelectedModel{Provider: "openai"},
+		CatwalkCfg: catwalk.Model{
+			SupportsImages: true,
+		},
+	}
+
+	result := agent.workaroundProviderMediaLimitations(messages, largeModel)
+
+	// Should produce two messages: tool message with placeholder text,
+	// and synthetic user message with FilePart.
+	require.Len(t, result, 2)
+	require.Equal(t, fantasy.MessageRoleTool, result[0].Role)
+	require.Equal(t, fantasy.MessageRoleUser, result[1].Role)
+
+	// The tool message should have text placeholder.
+	tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](result[0].Content[0])
+	require.True(t, ok)
+	textOutput, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentText](tr.Output)
+	require.True(t, ok)
+	require.Contains(t, textOutput.Text, "see attached file")
+
+	// The synthetic user message should contain a TextPart and a FilePart.
+	require.Len(t, result[1].Content, 2)
+	file, ok := fantasy.AsMessagePart[fantasy.FilePart](result[1].Content[1])
+	require.True(t, ok)
+	require.Equal(t, "image/png", file.MediaType)
+}
+
+func TestWorkaroundProviderMediaLimitations_AnthropicProvider(t *testing.T) {
+	env := testEnv(t)
+	sa := testSessionAgent(env, nil, nil, "test prompt")
+	agent := sa.(*sessionAgent)
+
+	pngBase64 := base64.StdEncoding.EncodeToString([]byte("fake-png-data"))
+
+	messages := []fantasy.Message{
+		{
+			Role: fantasy.MessageRoleTool,
+			Content: []fantasy.MessagePart{
+				fantasy.ToolResultPart{
+					ToolCallID: "call_1",
+					Output: fantasy.ToolResultOutputContentMedia{
+						Data:      pngBase64,
+						MediaType: "image/png",
+					},
+				},
+			},
+		},
+	}
+
+	// Anthropic provider — should return messages unchanged regardless of
+	// SupportsImages, since Anthropic handles media in tool results natively.
+	largeModel := Model{
+		ModelCfg: config.SelectedModel{Provider: string(catwalk.InferenceProviderAnthropic)},
+		CatwalkCfg: catwalk.Model{
+			SupportsImages: true,
+		},
+	}
+
+	result := agent.workaroundProviderMediaLimitations(messages, largeModel)
+	require.Len(t, result, 1)
+	require.Equal(t, fantasy.MessageRoleTool, result[0].Role)
+
+	// The media should still be in the tool result, untouched.
+	tr, ok := fantasy.AsMessagePart[fantasy.ToolResultPart](result[0].Content[0])
+	require.True(t, ok)
+	media, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentMedia](tr.Output)
+	require.True(t, ok)
+	require.Equal(t, "image/png", media.MediaType)
+}
+
+func TestProviderRetryLogFields(t *testing.T) {
+	t.Run("nil provider error", func(t *testing.T) {
+		fields := providerRetryLogFields(nil, 2*time.Second)
+		require.Equal(t, []any{"retry_delay", "2s"}, fields)
+	})
+
+	t.Run("provider error with title and message", func(t *testing.T) {
+		fields := providerRetryLogFields(&fantasy.ProviderError{
+			StatusCode: 429,
+			Title:      "rate limit",
+			Message:    "too many requests",
+		}, 1500*time.Millisecond)
+		require.Equal(t, []any{
+			"retry_delay", "1.5s",
+			"status_code", 429,
+			"title", "rate limit",
+			"message", "too many requests",
+		}, fields)
+	})
+
+	t.Run("provider error without optional strings", func(t *testing.T) {
+		fields := providerRetryLogFields(&fantasy.ProviderError{
+			StatusCode: 503,
+		}, time.Second)
+		require.Equal(t, []any{
+			"retry_delay", "1s",
+			"status_code", 503,
+		}, fields)
+	})
+}

internal/agent/agent_tool.go

@@ -0,0 +1,68 @@
+package agent
+
+import (
+	"context"
+	_ "embed"
+	"errors"
+
+	"charm.land/fantasy"
+
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/config"
+)
+
+//go:embed templates/agent_tool.md
+var agentToolDescription string
+
+type AgentParams struct {
+	Prompt string `json:"prompt" description:"The task for the agent to perform"`
+}
+
+const (
+	AgentToolName = "agent"
+)
+
+func (c *coordinator) agentTool(ctx context.Context) (fantasy.AgentTool, error) {
+	agentCfg, ok := c.cfg.Config().Agents[config.AgentTask]
+	if !ok {
+		return nil, errors.New("task agent not configured")
+	}
+	prompt, err := taskPrompt(prompt.WithWorkingDir(c.cfg.WorkingDir()))
+	if err != nil {
+		return nil, err
+	}
+
+	agent, err := c.buildAgent(ctx, prompt, agentCfg, true)
+	if err != nil {
+		return nil, err
+	}
+	return fantasy.NewParallelAgentTool(
+		AgentToolName,
+		agentToolDescription,
+		func(ctx context.Context, params AgentParams, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if params.Prompt == "" {
+				return fantasy.NewTextErrorResponse("prompt is required"), nil
+			}
+
+			sessionID := tools.GetSessionFromContext(ctx)
+			if sessionID == "" {
+				return fantasy.ToolResponse{}, errors.New("session id missing from context")
+			}
+
+			agentMessageID := tools.GetMessageFromContext(ctx)
+			if agentMessageID == "" {
+				return fantasy.ToolResponse{}, errors.New("agent message id missing from context")
+			}
+
+			return c.runSubAgent(ctx, subAgentParams{
+				Agent:          agent,
+				SessionID:      sessionID,
+				AgentMessageID: agentMessageID,
+				ToolCallID:     call.ID,
+				Prompt:         params.Prompt,
+				SessionTitle:   "New Agent Session",
+			})
+		},
+	), nil
+}

internal/agent/agentic_fetch_tool.go

@@ -0,0 +1,206 @@
+package agent
+
+import (
+	"context"
+	_ "embed"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"time"
+
+	"charm.land/fantasy"
+
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/permission"
+)
+
+//go:embed templates/agentic_fetch.md
+var agenticFetchToolDescription string
+
+// agenticFetchValidationResult holds the validated parameters from the tool call context.
+type agenticFetchValidationResult struct {
+	SessionID      string
+	AgentMessageID string
+}
+
+// validateAgenticFetchParams validates the tool call parameters and extracts required context values.
+func validateAgenticFetchParams(ctx context.Context, params tools.AgenticFetchParams) (agenticFetchValidationResult, error) {
+	if params.Prompt == "" {
+		return agenticFetchValidationResult{}, errors.New("prompt is required")
+	}
+
+	sessionID := tools.GetSessionFromContext(ctx)
+	if sessionID == "" {
+		return agenticFetchValidationResult{}, errors.New("session id missing from context")
+	}
+
+	agentMessageID := tools.GetMessageFromContext(ctx)
+	if agentMessageID == "" {
+		return agenticFetchValidationResult{}, errors.New("agent message id missing from context")
+	}
+
+	return agenticFetchValidationResult{
+		SessionID:      sessionID,
+		AgentMessageID: agentMessageID,
+	}, nil
+}
+
+//go:embed templates/agentic_fetch_prompt.md.tpl
+var agenticFetchPromptTmpl []byte
+
+func (c *coordinator) agenticFetchTool(_ context.Context, client *http.Client) (fantasy.AgentTool, error) {
+	if client == nil {
+		transport := http.DefaultTransport.(*http.Transport).Clone()
+		transport.MaxIdleConns = 100
+		transport.MaxIdleConnsPerHost = 10
+		transport.IdleConnTimeout = 90 * time.Second
+
+		client = &http.Client{
+			Timeout:   30 * time.Second,
+			Transport: transport,
+		}
+	}
+
+	return fantasy.NewParallelAgentTool(
+		tools.AgenticFetchToolName,
+		agenticFetchToolDescription,
+		func(ctx context.Context, params tools.AgenticFetchParams, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			validationResult, err := validateAgenticFetchParams(ctx, params)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+
+			// Determine description based on mode.
+			var description string
+			if params.URL != "" {
+				description = fmt.Sprintf("Fetch and analyze content from URL: %s", params.URL)
+			} else {
+				description = "Search the web and analyze results"
+			}
+
+			p, err := c.permissions.Request(
+				ctx,
+				permission.CreatePermissionRequest{
+					SessionID:   validationResult.SessionID,
+					Path:        c.cfg.WorkingDir(),
+					ToolCallID:  call.ID,
+					ToolName:    tools.AgenticFetchToolName,
+					Action:      "fetch",
+					Description: description,
+					Params:      tools.AgenticFetchPermissionsParams(params),
+				},
+			)
+			if err != nil {
+				return fantasy.ToolResponse{}, err
+			}
+			if !p {
+				return tools.NewPermissionDeniedResponse(), nil
+			}
+
+			tmpDir, err := os.MkdirTemp(c.cfg.Config().Options.DataDirectory, "crush-fetch-*")
+			if err != nil {
+				return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to create temporary directory: %s", err)), nil
+			}
+			defer os.RemoveAll(tmpDir)
+
+			var fullPrompt string
+
+			if params.URL != "" {
+				// URL mode: fetch the URL content first.
+				content, err := tools.FetchURLAndConvert(ctx, client, params.URL)
+				if err != nil {
+					return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to fetch URL: %s", err)), nil
+				}
+
+				hasLargeContent := len(content) > tools.LargeContentThreshold
+
+				if hasLargeContent {
+					tempFile, err := os.CreateTemp(tmpDir, "page-*.md")
+					if err != nil {
+						return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to create temporary file: %s", err)), nil
+					}
+					tempFilePath := tempFile.Name()
+
+					if _, err := tempFile.WriteString(content); err != nil {
+						tempFile.Close()
+						return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to write content to file: %s", err)), nil
+					}
+					tempFile.Close()
+
+					fullPrompt = fmt.Sprintf("%s\n\nThe web page from %s has been saved to: %s\n\nUse the view and grep tools to analyze this file and extract the requested information.", params.Prompt, params.URL, tempFilePath)
+				} else {
+					fullPrompt = fmt.Sprintf("%s\n\nWeb page URL: %s\n\n<webpage_content>\n%s\n</webpage_content>", params.Prompt, params.URL, content)
+				}
+			} else {
+				// Search mode: let the sub-agent search and fetch as needed.
+				fullPrompt = fmt.Sprintf("%s\n\nUse the web_search tool to find relevant information. Break down the question into smaller, focused searches if needed. After searching, use web_fetch to get detailed content from the most relevant results.", params.Prompt)
+			}
+
+			promptOpts := []prompt.Option{
+				prompt.WithWorkingDir(tmpDir),
+			}
+
+			promptTemplate, err := prompt.NewPrompt("agentic_fetch", string(agenticFetchPromptTmpl), promptOpts...)
+			if err != nil {
+				return fantasy.ToolResponse{}, fmt.Errorf("error creating prompt: %s", err)
+			}
+
+			_, small, err := c.buildAgentModels(ctx, true)
+			if err != nil {
+				return fantasy.ToolResponse{}, fmt.Errorf("error building models: %s", err)
+			}
+
+			systemPrompt, err := promptTemplate.Build(ctx, small.Model.Provider(), small.Model.Model(), c.cfg)
+			if err != nil {
+				return fantasy.ToolResponse{}, fmt.Errorf("error building system prompt: %s", err)
+			}
+
+			smallProviderCfg, ok := c.cfg.Config().Providers.Get(small.ModelCfg.Provider)
+			if !ok {
+				return fantasy.ToolResponse{}, errors.New("small model provider not configured")
+			}
+
+			webFetchTool := tools.NewWebFetchTool(tmpDir, client)
+			webSearchTool := tools.NewWebSearchTool(client)
+			fetchTools := []fantasy.AgentTool{
+				webFetchTool,
+				webSearchTool,
+				tools.NewGlobTool(tmpDir, c.cfg.Config().Tools.Glob),
+				tools.NewGrepTool(tmpDir, c.cfg.Config().Tools.Grep),
+				tools.NewSourcegraphTool(client),
+				tools.NewViewTool(c.lspManager, c.permissions, c.filetracker, nil, tmpDir),
+			}
+
+			// Sub-agent tools run without hook interception. The top-level
+			// `agentic_fetch` call itself is already wrapped from the coder's
+			// side; firing hooks again for every inner tool call would run
+			// the user's hooks N times per delegated turn.
+
+			agent := NewSessionAgent(SessionAgentOptions{
+				LargeModel:           small, // Use small model for both (fetch doesn't need large)
+				SmallModel:           small,
+				SystemPromptPrefix:   smallProviderCfg.SystemPromptPrefix,
+				SystemPrompt:         systemPrompt,
+				DisableAutoSummarize: c.cfg.Config().Options.DisableAutoSummarize,
+				IsYolo:               c.permissions.SkipRequests(),
+				Sessions:             c.sessions,
+				Messages:             c.messages,
+				Tools:                fetchTools,
+			})
+
+			return c.runSubAgent(ctx, subAgentParams{
+				Agent:          agent,
+				SessionID:      validationResult.SessionID,
+				AgentMessageID: validationResult.AgentMessageID,
+				ToolCallID:     call.ID,
+				Prompt:         fullPrompt,
+				SessionTitle:   "Fetch Analysis",
+				SessionSetup: func(sessionID string) {
+					c.permissions.AutoApproveSession(sessionID)
+				},
+			})
+		},
+	), nil
+}

internal/agent/aws_sso_refresh.go

@@ -0,0 +1,158 @@
+package agent
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os/exec"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/pubsub"
+)
+
+// awsSSORefreshTimeout bounds how long the AWS SSO refresh command may run.
+// Browser-based SSO needs time, so it is generous, and it runs on a context
+// detached from the agent turn so a cancelled turn doesn't abort the login.
+const awsSSORefreshTimeout = 5 * time.Minute
+
+// awsSSOURLRe matches the https verification URL that `aws sso login` and
+// related commands print to stdout or stderr.
+var awsSSOURLRe = regexp.MustCompile(`https://[^\s]+`)
+
+// extractAWSSSOURL returns the first HTTPS URL in the given command output
+// line, or empty if none is present.
+func extractAWSSSOURL(line string) string {
+	return awsSSOURLRe.FindString(line)
+}
+
+// refreshAWSCredentials runs the provider's configured AWS SSO refresh
+// command (e.g. "aws sso login") on the machine that makes the Bedrock
+// calls, streaming the verification URL to the UI for display, then rebuilds
+// models so the AWS SDK re-reads the refreshed credentials. It returns nil to
+// signal that the failed request should be retried.
+//
+// The command runs here, in the coordinator, rather than in the UI dialog so
+// the refreshed credentials land where the model calls are made. This is
+// correct in both single-process and client/server deployments.
+func (c *coordinator) refreshAWSCredentials(ctx context.Context, providerCfg config.ProviderConfig) error {
+	if c.notify == nil {
+		return errNoInteractiveAuth
+	}
+	slog.Info("AWS credentials expired, running refresh command",
+		"provider", providerCfg.ID, "command", providerCfg.AWSAuthRefresh)
+
+	// Open the dialog immediately so the user sees progress even before the
+	// command prints its verification URL.
+	c.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+		Type:         notify.TypeAWSSSOAuth,
+		ProviderID:   providerCfg.ID,
+		AWSSOCommand: providerCfg.AWSAuthRefresh,
+	})
+
+	// Detach from the turn's context (with a generous timeout) so cancelling
+	// the turn doesn't kill an in-progress browser login.
+	runCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), awsSSORefreshTimeout)
+	defer cancel()
+
+	runErr := c.runAWSAuthRefresh(runCtx, providerCfg)
+
+	result := notify.Notification{Type: notify.TypeAWSSSOAuthResult, ProviderID: providerCfg.ID}
+	if runErr != nil {
+		result.Message = runErr.Error()
+	}
+	c.notify.Publish(pubsub.CreatedEvent, result)
+
+	if runErr != nil {
+		slog.Error("AWS SSO refresh command failed", "provider", providerCfg.ID, "error", runErr)
+		return runErr
+	}
+	// If the turn's context was cancelled while the command ran, fantasy's
+	// retry would fail immediately, so surface the cancellation instead.
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
+	// Rebuild models so the AWS SDK credential chain re-reads the refreshed
+	// SSO cache on the next attempt.
+	if err := c.UpdateModels(runCtx); err != nil {
+		slog.Error("Failed to update models after AWS SSO refresh", "provider", providerCfg.ID, "error", err)
+		return err
+	}
+	slog.Info("AWS SSO refresh complete, retrying request", "provider", providerCfg.ID)
+	return nil
+}
+
+// runAWSAuthRefresh executes the refresh command, publishing the SSO
+// verification URL to the UI as soon as it appears in the output and
+// returning any failure with captured stderr for context.
+func (c *coordinator) runAWSAuthRefresh(ctx context.Context, providerCfg config.ProviderConfig) error {
+	cmd := exec.CommandContext(ctx, "sh", "-c", providerCfg.AWSAuthRefresh)
+	cmd.Dir = c.cfg.WorkingDir()
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return err
+	}
+	stderrPipe, err := cmd.StderrPipe()
+	if err != nil {
+		return err
+	}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+
+	// Drain stdout and stderr concurrently so a command that fills one pipe
+	// buffer before closing the other can't deadlock. Both are scanned for
+	// the verification URL; stderr is also captured for error detail.
+	var (
+		stderrBuf bytes.Buffer
+		mu        sync.Mutex // Guards the single-shot URL publish across goroutines.
+		urlSent   bool
+	)
+	publishURL := func(line string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if urlSent {
+			return
+		}
+		if url := extractAWSSSOURL(line); url != "" {
+			urlSent = true
+			// Second phase of the two-part publish: the dialog is already
+			// open from refreshAWSCredentials; this fills in the URL on it.
+			c.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+				Type:         notify.TypeAWSSSOAuth,
+				ProviderID:   providerCfg.ID,
+				AWSSOCommand: providerCfg.AWSAuthRefresh,
+				AWSSOURL:     url,
+			})
+		}
+	}
+
+	var wg sync.WaitGroup
+	scan := func(r io.Reader) {
+		defer wg.Done()
+		scanner := bufio.NewScanner(r)
+		for scanner.Scan() {
+			publishURL(scanner.Text())
+		}
+	}
+	wg.Add(2)
+	go scan(stdout)
+	go scan(io.TeeReader(stderrPipe, &stderrBuf))
+	wg.Wait()
+
+	if err := cmd.Wait(); err != nil {
+		if stderr := strings.TrimSpace(stderrBuf.String()); stderr != "" {
+			return fmt.Errorf("%w: %s", err, stderr)
+		}
+		return err
+	}
+	return nil
+}

internal/agent/aws_sso_refresh_test.go

@@ -0,0 +1,44 @@
+package agent
+
+import "testing"
+
+func TestExtractAWSSSOURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		output string
+		want   string
+	}{
+		{
+			name: "standard aws sso login output",
+			output: `If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
+https://device.sso.us-east-1.amazonaws.com/?user_code=ABCD-EFGH`,
+			want: "https://device.sso.us-east-1.amazonaws.com/?user_code=ABCD-EFGH",
+		},
+		{
+			name:   "url only",
+			output: "https://device.sso.eu-west-1.amazonaws.com/?user_code=XXXX-YYYY",
+			want:   "https://device.sso.eu-west-1.amazonaws.com/?user_code=XXXX-YYYY",
+		},
+		{
+			name:   "no url",
+			output: "SSO session expired. Please run aws sso login.",
+			want:   "",
+		},
+		{
+			name:   "empty output",
+			output: "",
+			want:   "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := extractAWSSSOURL(tt.output); got != tt.want {
+				t.Errorf("extractAWSSSOURL() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

internal/agent/common_test.go

@@ -0,0 +1,206 @@
+package agent
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"charm.land/fantasy/providers/openaicompat"
+	"charm.land/x/vcr"
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/db"
+	"github.com/charmbracelet/crush/internal/filetracker"
+	"github.com/charmbracelet/crush/internal/history"
+	"github.com/charmbracelet/crush/internal/lsp"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/permission"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/stretchr/testify/require"
+
+	_ "github.com/joho/godotenv/autoload"
+)
+
+// fakeEnv is an environment for testing.
+type fakeEnv struct {
+	workingDir  string
+	sessions    session.Service
+	messages    message.Service
+	permissions permission.Service
+	history     history.Service
+	filetracker *filetracker.Service
+	lspClients  *csync.Map[string, *lsp.Client]
+}
+
+type builderFunc func(t *testing.T, r *vcr.Recorder) (fantasy.LanguageModel, error)
+
+type modelPair struct {
+	name       string
+	largeModel builderFunc
+	smallModel builderFunc
+}
+
+func hyperBuilder(model string) builderFunc {
+	return func(t *testing.T, r *vcr.Recorder) (fantasy.LanguageModel, error) {
+		provider, err := openaicompat.New(
+			openaicompat.WithBaseURL("https://hyper.charm.land/v1"),
+			openaicompat.WithAPIKey(os.Getenv("CRUSH_HYPER_API_KEY")),
+			openaicompat.WithHTTPClient(&http.Client{Transport: r}),
+		)
+		if err != nil {
+			return nil, err
+		}
+		return provider.LanguageModel(t.Context(), model)
+	}
+}
+
+func testEnv(t *testing.T) fakeEnv {
+	workingDir := filepath.Join("/tmp/crush-test/", t.Name())
+	os.RemoveAll(workingDir)
+
+	err := os.MkdirAll(workingDir, 0o755)
+	require.NoError(t, err)
+
+	conn, err := db.Connect(t.Context(), t.TempDir())
+	require.NoError(t, err)
+
+	q := db.New(conn)
+	sessions := session.NewService(q, conn)
+	messages := message.NewService(q)
+
+	permissions := permission.NewPermissionService(workingDir, true, []string{})
+	history := history.NewService(q, conn)
+	filetrackerService := filetracker.NewService(q)
+	lspClients := csync.NewMap[string, *lsp.Client]()
+
+	t.Cleanup(func() {
+		conn.Close()
+		os.RemoveAll(workingDir)
+	})
+
+	return fakeEnv{
+		workingDir,
+		sessions,
+		messages,
+		permissions,
+		history,
+		&filetrackerService,
+		lspClients,
+	}
+}
+
+func testSessionAgent(env fakeEnv, large, small fantasy.LanguageModel, systemPrompt string, tools ...fantasy.AgentTool) SessionAgent {
+	largeModel := Model{
+		Model: large,
+		CatwalkCfg: catwalk.Model{
+			ContextWindow:    200000,
+			DefaultMaxTokens: 10000,
+		},
+	}
+	smallModel := Model{
+		Model: small,
+		CatwalkCfg: catwalk.Model{
+			ContextWindow:    200000,
+			DefaultMaxTokens: 10000,
+		},
+	}
+	agent := NewSessionAgent(SessionAgentOptions{
+		LargeModel:   largeModel,
+		SmallModel:   smallModel,
+		SystemPrompt: systemPrompt,
+		IsYolo:       true,
+		Sessions:     env.sessions,
+		Messages:     env.messages,
+		Tools:        tools,
+	})
+	return agent
+}
+
+func coderAgent(r *vcr.Recorder, env fakeEnv, large, small fantasy.LanguageModel) (SessionAgent, error) {
+	fixedTime := func() time.Time {
+		t, _ := time.Parse("1/2/2006", "1/1/2025")
+		return t
+	}
+	prompt, err := coderPrompt(
+		prompt.WithTimeFunc(fixedTime),
+		prompt.WithPlatform("linux"),
+		prompt.WithWorkingDir(filepath.ToSlash(env.workingDir)),
+	)
+	if err != nil {
+		return nil, err
+	}
+	cfg, err := config.Init(env.workingDir, "", false)
+	if err != nil {
+		return nil, err
+	}
+
+	// NOTE(@andreynering): Set a fixed config to ensure cassettes match
+	// independently of user config on `$HOME/.config/crush/crush.json`.
+	cfg.Config().Options.Attribution = &config.Attribution{
+		TrailerStyle:  "co-authored-by",
+		GeneratedWith: true,
+	}
+
+	// Clear some fields to avoid issues with VCR cassette matching.
+	cfg.Config().Options.SkillsPaths = nil
+	cfg.Config().Options.DisabledSkills = []string{"crush-config"}
+	cfg.Config().Options.ContextPaths = nil
+	cfg.Config().Options.GlobalContextPaths = nil
+	cfg.Config().LSP = nil
+
+	systemPrompt, err := prompt.Build(context.TODO(), large.Provider(), large.Model(), cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	// Get the model name for the bash tool
+	modelName := large.Model() // fallback to ID if Name not available
+	if model := cfg.Config().GetModel(large.Provider(), large.Model()); model != nil {
+		modelName = model.Name
+	}
+
+	allTools := []fantasy.AgentTool{
+		tools.NewBashTool(env.permissions, env.workingDir, cfg.Config().Options.Attribution, modelName),
+		tools.NewDownloadTool(env.permissions, env.workingDir, r.GetDefaultClient()),
+		tools.NewEditTool(nil, env.permissions, env.history, *env.filetracker, env.workingDir),
+		tools.NewMultiEditTool(nil, env.permissions, env.history, *env.filetracker, env.workingDir),
+		tools.NewFetchTool(env.permissions, env.workingDir, r.GetDefaultClient()),
+		tools.NewGlobTool(env.workingDir, cfg.Config().Tools.Glob),
+		tools.NewGrepTool(env.workingDir, cfg.Config().Tools.Grep),
+		tools.NewLsTool(env.permissions, env.workingDir, cfg.Config().Tools.Ls),
+		tools.NewSourcegraphTool(r.GetDefaultClient()),
+		tools.NewViewTool(nil, env.permissions, *env.filetracker, nil, env.workingDir),
+		tools.NewWriteTool(nil, env.permissions, env.history, *env.filetracker, env.workingDir),
+	}
+
+	return testSessionAgent(env, large, small, systemPrompt, allTools...), nil
+}
+
+// createSimpleGoProject creates a simple Go project structure in the given directory.
+// It creates a go.mod file and a main.go file with a basic hello world program.
+func createSimpleGoProject(t *testing.T, dir string) {
+	goMod := `module example.com/testproject
+
+go 1.23
+`
+	err := os.WriteFile(dir+"/go.mod", []byte(goMod), 0o644)
+	require.NoError(t, err)
+
+	mainGo := `package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("Hello, World!")
+}
+`
+	err = os.WriteFile(dir+"/main.go", []byte(mainGo), 0o644)
+	require.NoError(t, err)
+}

internal/agent/convert_test.go

@@ -0,0 +1,94 @@
+package agent
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"charm.land/fantasy"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConvertToToolResult_InvalidBase64(t *testing.T) {
+	t.Parallel()
+
+	a := &sessionAgent{}
+	result := fantasy.ToolResultContent{
+		ToolCallID: "call_123",
+		ToolName:   "test_tool",
+		Result: fantasy.ToolResultOutputContentMedia{
+			Data:      "abc\x80def",
+			MediaType: "image/png",
+		},
+	}
+
+	tr := a.convertToToolResult(result)
+	require.True(t, tr.IsError)
+	require.Empty(t, tr.Data)
+	require.Contains(t, tr.Content, "invalid encoding")
+	require.Equal(t, "call_123", tr.ToolCallID)
+	require.Equal(t, "test_tool", tr.Name)
+}
+
+func TestConvertToToolResult_ValidMedia(t *testing.T) {
+	t.Parallel()
+
+	a := &sessionAgent{}
+	validData := base64.StdEncoding.EncodeToString([]byte("test image data"))
+
+	result := fantasy.ToolResultContent{
+		ToolCallID: "call_456",
+		ToolName:   "screenshot",
+		Result: fantasy.ToolResultOutputContentMedia{
+			Data:      validData,
+			MediaType: "image/png",
+			Text:      "Screenshot captured",
+		},
+	}
+
+	tr := a.convertToToolResult(result)
+	require.False(t, tr.IsError)
+	require.Equal(t, validData, tr.Data)
+	require.Equal(t, "image/png", tr.MIMEType)
+	require.Equal(t, "Screenshot captured", tr.Content)
+}
+
+func TestConvertToToolResult_ValidMediaNoText(t *testing.T) {
+	t.Parallel()
+
+	a := &sessionAgent{}
+	validData := base64.StdEncoding.EncodeToString([]byte("test image data"))
+
+	result := fantasy.ToolResultContent{
+		ToolCallID: "call_789",
+		ToolName:   "view",
+		Result: fantasy.ToolResultOutputContentMedia{
+			Data:      validData,
+			MediaType: "image/jpeg",
+		},
+	}
+
+	tr := a.convertToToolResult(result)
+	require.False(t, tr.IsError)
+	require.Equal(t, validData, tr.Data)
+	require.Equal(t, "image/jpeg", tr.MIMEType)
+	require.Equal(t, "Loaded image/jpeg content", tr.Content)
+}
+
+func TestConvertToToolResult_ASCIIButInvalidBase64(t *testing.T) {
+	t.Parallel()
+
+	a := &sessionAgent{}
+	result := fantasy.ToolResultContent{
+		ToolCallID: "call_abc",
+		ToolName:   "mcp_tool",
+		Result: fantasy.ToolResultOutputContentMedia{
+			Data:      "not-valid-base64!!!",
+			MediaType: "image/png",
+		},
+	}
+
+	tr := a.convertToToolResult(result)
+	require.True(t, tr.IsError)
+	require.Empty(t, tr.Data)
+	require.Contains(t, tr.Content, "invalid encoding")
+}

internal/agent/coordinator.go

@@ -0,0 +1,1757 @@
+package agent
+
+import (
+	"bytes"
+	"cmp"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"maps"
+	"net/http"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent/hyper"
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/discover"
+	"github.com/charmbracelet/crush/internal/event"
+	"github.com/charmbracelet/crush/internal/filetracker"
+	"github.com/charmbracelet/crush/internal/history"
+	"github.com/charmbracelet/crush/internal/hooks"
+	"github.com/charmbracelet/crush/internal/log"
+	"github.com/charmbracelet/crush/internal/lsp"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/charmbracelet/crush/internal/oauth/copilot"
+	openaioauth "github.com/charmbracelet/crush/internal/oauth/openai"
+	"github.com/charmbracelet/crush/internal/permission"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/charmbracelet/crush/internal/question"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/charmbracelet/crush/internal/skills"
+	"golang.org/x/sync/errgroup"
+
+	"charm.land/fantasy/providers/anthropic"
+	"charm.land/fantasy/providers/azure"
+	"charm.land/fantasy/providers/bedrock"
+	"charm.land/fantasy/providers/google"
+	"charm.land/fantasy/providers/openai"
+	"charm.land/fantasy/providers/openaicompat"
+	"charm.land/fantasy/providers/openrouter"
+	"charm.land/fantasy/providers/vercel"
+	openaisdk "github.com/openai/openai-go/v3/option"
+	"github.com/qjebbs/go-jsons"
+)
+
+// Coordinator errors.
+var (
+	errCoderAgentNotConfigured         = errors.New("coder agent not configured")
+	errModelProviderNotConfigured      = errors.New("model provider not configured")
+	errLargeModelNotSelected           = errors.New("large model not selected")
+	errSmallModelNotSelected           = errors.New("small model not selected")
+	errLargeModelProviderNotConfigured = errors.New("large model provider not configured")
+	errSmallModelProviderNotConfigured = errors.New("small model provider not configured")
+	errLargeModelNotFound              = errors.New("large model not found in provider config")
+	errSmallModelNotFound              = errors.New("small model not found in provider config")
+)
+
+// Copilot models that use the Responses API instead of Chat Completions.
+var copilotResponsesModels = map[string]bool{
+	"gpt-5.2":       true,
+	"gpt-5.2-codex": true,
+	"gpt-5.3-codex": true,
+	"gpt-5.4":       true,
+	"gpt-5.4-mini":  true,
+	"gpt-5.5":       true,
+	"gpt-5-mini":    true,
+	"gpt-5.6-luna":  true,
+	"gpt-5.6-terra": true,
+	"gpt-5.6-sol":   true,
+	"gpt-6-astra":   true,
+	"grok-4.5":      true,
+	"grok-4.6":      true,
+}
+
+// OpenCode models that use the Anthropic Messages API instead of Chat
+// Completions. Which endpoint serves each model differs per provider, see
+// https://opencode.ai/docs/zen and https://opencode.ai/docs/go.
+func isOpenCodeMessagesModel(providerID, modelID string) bool {
+	switch providerID {
+	case string(catwalk.InferenceProviderOpenCodeGo):
+		return strings.HasPrefix(modelID, "minimax-") ||
+			strings.HasPrefix(modelID, "qwen3.6-") ||
+			strings.HasPrefix(modelID, "qwen3.7-") ||
+			strings.HasPrefix(modelID, "qwen3.8-")
+	case string(catwalk.InferenceProviderOpenCodeZen):
+		return strings.HasPrefix(modelID, "claude-") ||
+			strings.HasPrefix(modelID, "qwen3.5-") ||
+			strings.HasPrefix(modelID, "qwen3.6-") ||
+			strings.HasPrefix(modelID, "qwen3.7-") ||
+			strings.HasPrefix(modelID, "qwen3.8-")
+	}
+	return false
+}
+
+// OpenCode models that use the OpenAI Responses API instead of Chat
+// Completions. See https://opencode.ai/docs/zen and https://opencode.ai/docs/go.
+func isOpenCodeResponsesModel(modelID string) bool {
+	return strings.HasPrefix(modelID, "gpt-") ||
+		strings.HasPrefix(modelID, "grok-") ||
+		strings.HasPrefix(modelID, "muse-spark-")
+}
+
+type Coordinator interface {
+	// INFO: (kujtim) this is not used yet we will use this when we have multiple agents
+	// SetMainAgent(string)
+	Run(ctx context.Context, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error)
+	// RunAccepted runs a call that was already accepted via
+	// BeginAccepted on the fire-and-forget dispatch path. The handle is
+	// the only carrier of accept-state across the backend.runAgent /
+	// Coordinator / sessionAgent.Run layers: it reaches
+	// sessionAgent.Run as SessionAgentCall.Accepted, where it is
+	// consumed under dispatchMu once the accepted -> (cancel-on-entry |
+	// queued | active) transition is chosen.
+	RunAccepted(ctx context.Context, accept *AcceptedRun, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error)
+	BeginAccepted(sessionID string) *AcceptedRun
+	Cancel(sessionID string)
+	CancelAll()
+	IsSessionBusy(sessionID string) bool
+	IsBusy() bool
+	QueuedPrompts(sessionID string) int
+	QueuedPromptsList(sessionID string) []string
+	ClearQueue(sessionID string)
+	Summarize(context.Context, string) error
+	Model() Model
+	UpdateModels(ctx context.Context) error
+	GenerateTitle(ctx context.Context, sessionID, prompt string)
+}
+
+type coordinator struct {
+	cfg         *config.ConfigStore
+	sessions    session.Service
+	messages    message.Service
+	permissions permission.Service
+	questions   question.Service
+	history     history.Service
+	filetracker filetracker.Service
+	lspManager  *lsp.Manager
+	notify      pubsub.Publisher[notify.Notification]
+	runComplete pubsub.Publisher[notify.RunComplete]
+	interactive bool
+
+	currentAgent SessionAgent
+	agents       map[string]SessionAgent
+
+	// Skills discovery results (session-start snapshot).
+	allSkills    []*skills.Skill // Pre-filter: all discovered after dedup.
+	activeSkills []*skills.Skill // Post-filter: active skills only.
+	skillTracker *skills.Tracker
+
+	readyWg errgroup.Group
+}
+
+// CoordinatorOptions holds the dependencies for NewCoordinator. Using a
+// struct keeps the constructor self-documenting and avoids a long
+// positional parameter list.
+type CoordinatorOptions struct {
+	Config      *config.ConfigStore
+	Sessions    session.Service
+	Messages    message.Service
+	Permissions permission.Service
+	Questions   question.Service
+	History     history.Service
+	FileTracker filetracker.Service
+	LSPManager  *lsp.Manager
+	Notify      pubsub.Publisher[notify.Notification]
+	RunComplete pubsub.Publisher[notify.RunComplete]
+	Skills      *skills.Manager
+	Interactive bool
+}
+
+func NewCoordinator(ctx context.Context, opts CoordinatorOptions) (Coordinator, error) {
+	// Skills are pre-discovered by the caller (see app.New /
+	// backend.CreateWorkspace) and passed in via the manager. If no
+	// manager was provided (legacy callers), fall back to an in-line
+	// discovery so the coordinator still works.
+	var allSkills, activeSkills []*skills.Skill
+	if opts.Skills != nil {
+		allSkills = opts.Skills.AllSkills()
+		activeSkills = opts.Skills.ActiveSkills()
+	} else {
+		allSkills, activeSkills = discoverSkills(opts.Config)
+	}
+	skillTracker := skills.NewTracker(activeSkills)
+
+	c := &coordinator{
+		cfg:          opts.Config,
+		sessions:     opts.Sessions,
+		messages:     opts.Messages,
+		permissions:  opts.Permissions,
+		questions:    opts.Questions,
+		history:      opts.History,
+		filetracker:  opts.FileTracker,
+		lspManager:   opts.LSPManager,
+		notify:       opts.Notify,
+		runComplete:  opts.RunComplete,
+		agents:       make(map[string]SessionAgent),
+		allSkills:    allSkills,
+		activeSkills: activeSkills,
+		skillTracker: skillTracker,
+		interactive:  opts.Interactive,
+	}
+
+	agentCfg, ok := opts.Config.Config().Agents[config.AgentCoder]
+	if !ok {
+		return nil, errCoderAgentNotConfigured
+	}
+
+	// TODO: make this dynamic when we support multiple agents
+	prompt, err := coderPrompt(prompt.WithWorkingDir(c.cfg.WorkingDir()))
+	if err != nil {
+		return nil, err
+	}
+
+	agent, err := c.buildAgent(ctx, prompt, agentCfg, false)
+	if err != nil {
+		return nil, err
+	}
+	c.currentAgent = agent
+	c.agents[config.AgentCoder] = agent
+	return c, nil
+}
+
+// Run implements Coordinator.
+func (c *coordinator) Run(ctx context.Context, sessionID string, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	return c.run(ctx, nil, sessionID, prompt, attachments...)
+}
+
+// RunAccepted implements Coordinator.
+func (c *coordinator) RunAccepted(ctx context.Context, accept *AcceptedRun, sessionID string, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	return c.run(ctx, accept, sessionID, prompt, attachments...)
+}
+
+// run is the shared implementation behind Run and RunAccepted. When
+// accept is non-nil it is threaded onto the SessionAgentCall as
+// Accepted so sessionAgent.Run can consume the accept reservation under
+// dispatchMu; when nil (the in-process/local path) no accept tracking
+// applies.
+func (c *coordinator) run(ctx context.Context, accept *AcceptedRun, sessionID string, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	if err := c.readyWg.Wait(); err != nil {
+		return nil, err
+	}
+
+	// MCP servers connect asynchronously (see mcp.Initialize).
+	//
+	// Interactive runs never wait for that to finish: the tool list below
+	// is built from whatever is registered right now, servers still
+	// connecting are simply absent from this run's palette, and they are
+	// picked up by later runs once they register and publish
+	// EventToolsListChanged. Blocking here froze the TUI for the duration
+	// of the slowest server's connect timeout whenever a prompt was sent
+	// before initialization finished — most visibly on the first message.
+	//
+	// Non-interactive runs get a single shot at the tool palette, so they
+	// do wait for initialization to settle — but bounded by InitWaitBudget
+	// rather than each server's connect timeout, so a server wedged
+	// mid-handshake cannot stall a headless run for minutes. Past the
+	// budget the turn proceeds without the stragglers; their tools simply
+	// stay absent from this run.
+	if !c.interactive {
+		if err := mcp.WaitForInitBudget(ctx, mcp.InitWaitBudget); err != nil {
+			return nil, fmt.Errorf("failed to wait for MCP initialization: %w", err)
+		}
+	}
+
+	// refresh models before each run
+	if err := c.UpdateModels(ctx); err != nil {
+		return nil, fmt.Errorf("failed to update models: %w", err)
+	}
+
+	model := c.currentAgent.Model()
+	maxTokens := model.CatwalkCfg.DefaultMaxTokens
+	if model.ModelCfg.MaxTokens != 0 {
+		maxTokens = model.ModelCfg.MaxTokens
+	}
+
+	providerCfg, ok := c.cfg.Config().Providers.Get(model.ModelCfg.Provider)
+	if !ok {
+		return nil, errModelProviderNotConfigured
+	}
+
+	mergedOptions, temp, topP, topK, freqPenalty, presPenalty := mergeCallOptions(model, providerCfg)
+
+	if err := c.refreshTokenIfExpired(ctx, providerCfg); err != nil {
+		// NOTE(@andreynering): We don't return here because the event handling to ask the user to reauthenticate
+		// depends on the flow below. If refresh fails, proceed with the token we have.
+		slog.Error("Failed to refresh OAuth2 token. Proceeding with existing token.", "error", err)
+	}
+
+	// Coalesce per-attempt RunComplete payloads so only the final
+	// outcome reaches subscribers. Without this, the first attempt's
+	// failed RunComplete (unauthorized) would race ahead of the
+	// retry's success, and `crush run` would exit on the stale error
+	// before ever seeing the retry result. Each attempt's
+	// SessionAgentCall.OnComplete hook overwrites latest; we publish
+	// exactly once after retries resolve, via PublishMustDeliver, so
+	// a momentarily-full subscriber buffer can't silently drop the
+	// terminal event.
+	var (
+		latest    notify.RunComplete
+		hasLatest bool
+	)
+	onComplete := func(rc notify.RunComplete) {
+		latest = rc
+		hasLatest = true
+	}
+	// Propagate the caller-supplied RunID (set via agent.WithRunID
+	// at the HTTP boundary in backend.SendMessage) onto the
+	// SessionAgentCall so the terminal RunComplete event echoes it
+	// back. Both attempts in the retry chain reuse the same RunID;
+	// the coalesce closure publishes the final outcome under that
+	// same correlator.
+	runID := RunIDFromContext(ctx)
+	run := func() (*fantasy.AgentResult, error) {
+		return c.currentAgent.Run(ctx, SessionAgentCall{
+			SessionID:        sessionID,
+			RunID:            runID,
+			Prompt:           prompt,
+			Attachments:      attachments,
+			MaxOutputTokens:  maxTokens,
+			ProviderOptions:  mergedOptions,
+			Temperature:      temp,
+			TopP:             topP,
+			TopK:             callTopK(providerCfg, topK),
+			FrequencyPenalty: freqPenalty,
+			PresencePenalty:  presPenalty,
+			OnComplete:       onComplete,
+			Accepted:         accept,
+			OnAuthRefresh:    c.makeAuthRefreshCallback(providerCfg),
+		})
+	}
+	beforeLoaded := c.skillTracker.LoadedNames()
+	result, originalErr := run()
+	logTurnSkillUsage(sessionID, prompt, c.activeSkills, c.skillTracker, beforeLoaded)
+
+	// Notify only if still unauthorized after retry — a successful
+	// retry means the user doesn't need to re-authenticate. AWS SSO is
+	// handled transparently inside OnAuthRefresh, so it needs no post-run
+	// notification here.
+	if originalErr != nil && isUnauthorized(originalErr) && c.notify != nil && model.ModelCfg.Provider == hyper.Name {
+		c.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+			Type:       notify.TypeReAuthenticate,
+			ProviderID: model.ModelCfg.Provider,
+		})
+	}
+
+	if hasLatest && c.runComplete != nil {
+		c.runComplete.PublishMustDeliver(ctx, pubsub.UpdatedEvent, latest)
+		// Signal to the dispatcher (backend.runAgent) that the
+		// authoritative terminal RunComplete for this run was already
+		// emitted, so it does not publish a duplicate fallback for the
+		// error it is about to receive.
+		MarkRunCompletePublished(ctx)
+	}
+	return result, originalErr
+}
+
+// effectiveReasoningEffort returns the reasoning effort to apply for provider calls.
+// It prefers the user-selected effort when valid, otherwise the model default when
+// valid, and finally falls back to the first configured reasoning level.
+func effectiveReasoningEffort(model Model) string {
+	if !model.CatwalkCfg.CanReason {
+		return ""
+	}
+
+	if effort := model.ModelCfg.ReasoningEffort; effort != "" && slices.Contains(model.CatwalkCfg.ReasoningLevels, effort) {
+		return effort
+	}
+	if effort := model.CatwalkCfg.DefaultReasoningEffort; effort != "" && slices.Contains(model.CatwalkCfg.ReasoningLevels, effort) {
+		return effort
+	}
+	if len(model.CatwalkCfg.ReasoningLevels) > 0 {
+		return model.CatwalkCfg.ReasoningLevels[0]
+	}
+	return ""
+}
+
+func getProviderOptions(model Model, providerCfg config.ProviderConfig) fantasy.ProviderOptions {
+	options := fantasy.ProviderOptions{}
+
+	cfgOpts := []byte("{}")
+	providerCfgOpts := []byte("{}")
+	catwalkOpts := []byte("{}")
+
+	if model.ModelCfg.ProviderOptions != nil {
+		data, err := json.Marshal(model.ModelCfg.ProviderOptions)
+		if err == nil {
+			cfgOpts = data
+		}
+	}
+
+	if providerCfg.ProviderOptions != nil {
+		data, err := json.Marshal(providerCfg.ProviderOptions)
+		if err == nil {
+			providerCfgOpts = data
+		}
+	}
+
+	if model.CatwalkCfg.Options.ProviderOptions != nil {
+		data, err := json.Marshal(model.CatwalkCfg.Options.ProviderOptions)
+		if err == nil {
+			catwalkOpts = data
+		}
+	}
+
+	readers := []io.Reader{
+		bytes.NewReader(catwalkOpts),
+		bytes.NewReader(providerCfgOpts),
+		bytes.NewReader(cfgOpts),
+	}
+
+	got, err := jsons.Merge(readers)
+	if err != nil {
+		slog.Error("Could not merge call config", "err", err)
+		return options
+	}
+
+	mergedOptions := make(map[string]any)
+
+	err = json.Unmarshal([]byte(got), &mergedOptions)
+	if err != nil {
+		slog.Error("Could not create config for call", "err", err)
+		return options
+	}
+
+	reasoningEffort := effectiveReasoningEffort(model)
+	shouldSetEffort := model.CatwalkCfg.CanReason &&
+		reasoningEffort != "" &&
+		slices.Contains(model.CatwalkCfg.ReasoningLevels, reasoningEffort)
+
+	switch providerCfg.Type {
+	case openai.Name, azure.Name:
+		_, hasReasoningEffort := mergedOptions["reasoning_effort"]
+		if !hasReasoningEffort && shouldSetEffort {
+			mergedOptions["reasoning_effort"] = reasoningEffort
+		}
+		if openai.IsResponsesModel(model.CatwalkCfg.ID) {
+			if openai.IsResponsesReasoningModel(model.CatwalkCfg.ID) {
+				mergedOptions["reasoning_summary"] = "auto"
+				mergedOptions["include"] = []openai.IncludeType{openai.IncludeReasoningEncryptedContent}
+			}
+			parsed, err := openai.ParseResponsesOptions(mergedOptions)
+			if err == nil {
+				options[openai.Name] = parsed
+			}
+		} else {
+			parsed, err := openai.ParseOptions(mergedOptions)
+			if err == nil {
+				options[openai.Name] = parsed
+			}
+		}
+
+	case anthropic.Name, bedrock.Name:
+		var (
+			_, hasEffort = mergedOptions["effort"]
+			_, hasThink  = mergedOptions["thinking"]
+			extraBody    = make(map[string]any)
+		)
+
+		switch providerCfg.ID {
+		case string(catwalk.InferenceProviderAlibabaSingapore), string(catwalk.InferenceProviderAlibabaUS):
+			switch {
+			case !hasEffort && shouldSetEffort:
+				extraBody["reasoning_effort"] = reasoningEffort
+			case !hasThink && model.CatwalkCfg.CanReason:
+				if model.ModelCfg.Think {
+					extraBody["thinking"] = map[string]any{"type": "enabled"}
+				} else {
+					extraBody["thinking"] = map[string]any{"type": "disabled"}
+				}
+			}
+			mergedOptions["extra_body"] = extraBody
+
+		default:
+			switch {
+			case !hasEffort && shouldSetEffort:
+				mergedOptions["effort"] = reasoningEffort
+			case !hasThink && model.ModelCfg.Think:
+				mergedOptions["thinking"] = map[string]any{"budget_tokens": 2000}
+			}
+		}
+
+		parsed, err := anthropic.ParseOptions(mergedOptions)
+		if err == nil {
+			options[anthropic.Name] = parsed
+		}
+
+	case openrouter.Name:
+		_, hasReasoning := mergedOptions["reasoning"]
+		if !hasReasoning && shouldSetEffort {
+			mergedOptions["reasoning"] = map[string]any{
+				"enabled": true,
+				"effort":  reasoningEffort,
+			}
+		}
+		parsed, err := openrouter.ParseOptions(mergedOptions)
+		if err == nil {
+			options[openrouter.Name] = parsed
+		}
+
+	case vercel.Name:
+		_, hasReasoning := mergedOptions["reasoning"]
+		if !hasReasoning && shouldSetEffort {
+			mergedOptions["reasoning"] = map[string]any{
+				"enabled": true,
+				"effort":  reasoningEffort,
+			}
+		}
+		parsed, err := vercel.ParseOptions(mergedOptions)
+		if err == nil {
+			options[vercel.Name] = parsed
+		}
+
+	case google.Name:
+		_, hasReasoning := mergedOptions["thinking_config"]
+		if !hasReasoning {
+			if strings.HasPrefix(model.CatwalkCfg.ID, "gemini-2") {
+				mergedOptions["thinking_config"] = map[string]any{
+					"thinking_budget":  2000,
+					"include_thoughts": true,
+				}
+			} else {
+				mergedOptions["thinking_config"] = map[string]any{
+					"thinking_level":   reasoningEffort,
+					"include_thoughts": true,
+				}
+			}
+		}
+		parsed, err := google.ParseOptions(mergedOptions)
+		if err == nil {
+			options[google.Name] = parsed
+		}
+
+	case openaicompat.Name, hyper.Name:
+		extraBody := make(map[string]any)
+
+		_, hasReasoningEffort := mergedOptions["reasoning_effort"]
+		if !hasReasoningEffort && shouldSetEffort {
+			switch providerCfg.ID {
+			case string(catwalk.InferenceProviderIoNet):
+				extraBody["reasoning"] = map[string]string{"effort": reasoningEffort}
+			case string(catwalk.InferenceProviderOpenCodeGo), string(catwalk.InferenceProviderOpenCodeZen):
+				// MiniMax models use the "thinking" parameter instead of
+				// "reasoning_effort". Other models on these providers still
+				// use the standard field.
+				if !strings.HasPrefix(strings.ToLower(model.CatwalkCfg.ID), "minimax") {
+					mergedOptions["reasoning_effort"] = reasoningEffort
+				}
+			default:
+				mergedOptions["reasoning_effort"] = reasoningEffort
+			}
+		}
+
+		// "reasoning effort" is a standard OpenAI field, but "thinking" is not.
+		// Setting it in the right way for each provider.
+		// TODO: Abstract this in Fantasy somehow?
+		// TODO: Allow custom providers to specify how to set this?
+		switch providerCfg.ID {
+		case hyper.Name:
+			extraBody["thinking"] = model.ModelCfg.Think
+		case string(catwalk.InferenceProviderIoNet):
+			if _, ok := extraBody["reasoning"]; !ok && model.CatwalkCfg.CanReason {
+				if model.ModelCfg.Think {
+					extraBody["reasoning"] = map[string]string{"effort": "medium"}
+				} else {
+					extraBody["reasoning"] = map[string]string{"effort": "none"}
+				}
+			}
+
+		case string(catwalk.InferenceProviderZAI), string(catwalk.InferenceProviderDeepSeek):
+			if model.ModelCfg.Think || reasoningEffort != "" {
+				extraBody["thinking"] = map[string]any{"type": "enabled"}
+			} else {
+				extraBody["thinking"] = map[string]any{"type": "disabled"}
+			}
+
+		case string(catwalk.InferenceProviderFireworks):
+			// NOTE: Fireworks break if we set both `reasoning_effort` and `thinking`.
+			if reasoningEffort == "" {
+				if model.ModelCfg.Think {
+					extraBody["thinking"] = map[string]any{"type": "enabled"}
+				} else {
+					extraBody["thinking"] = map[string]any{"type": "disabled"}
+				}
+			}
+
+		case string(catwalk.InferenceProviderBaseten):
+			extraBody["chat_template_args"] = map[string]any{
+				"enable_thinking": model.ModelCfg.Think || reasoningEffort != "" && reasoningEffort != "none",
+			}
+
+		case string(catwalk.InferenceProviderOpenCodeGo), string(catwalk.InferenceProviderOpenCodeZen):
+			// MiniMax M3 uses the "thinking" parameter to control reasoning.
+			// "reasoning_split" must be true so thinking content is returned
+			// in the "reasoning_content" field instead of inline in "content".
+			if strings.HasPrefix(strings.ToLower(model.CatwalkCfg.ID), "minimax") {
+				if model.CatwalkCfg.CanReason && (model.ModelCfg.Think || reasoningEffort != "") {
+					extraBody["thinking"] = map[string]any{"type": "adaptive"}
+					extraBody["reasoning_split"] = true
+				} else {
+					extraBody["thinking"] = map[string]any{"type": "disabled"}
+				}
+			}
+
+		case string(catwalk.InferenceProviderAlibabaSingapore), string(catwalk.InferenceProviderAlibabaUS):
+			if model.CatwalkCfg.CanReason && !shouldSetEffort {
+				extraBody["enable_thinking"] = model.ModelCfg.Think
+			}
+		}
+
+		mergedOptions["extra_body"] = extraBody
+
+		parsed, err := openaicompat.ParseOptions(mergedOptions)
+		if err == nil {
+			options[openaicompat.Name] = parsed
+		}
+
+	default:
+		// Known custom providers (litellm, llamacpp, lmstudio, ollama,
+		// omlx) are openai-compat under the hood.
+		if discover.IsKnownCustomProvider(string(providerCfg.Type)) {
+			// Set "top_k" under "extra_body", as it is not part of the OpenAI protocol
+			// and will be explicitly omitted by Fantasy downstream.
+			topK := cmp.Or(model.ModelCfg.TopK, model.CatwalkCfg.Options.TopK)
+			if topK != nil {
+				extraBody, hasExtraBody := mergedOptions["extra_body"].(map[string]any)
+				if !hasExtraBody {
+					extraBody = make(map[string]any)
+					mergedOptions["extra_body"] = extraBody
+				}
+				if _, hasTopK := extraBody["top_k"]; !hasTopK {
+					extraBody["top_k"] = *topK
+				}
+			}
+
+			_, hasReasoningEffort := mergedOptions["reasoning_effort"]
+			if !hasReasoningEffort && shouldSetEffort {
+				mergedOptions["reasoning_effort"] = reasoningEffort
+			}
+
+			parsed, err := openaicompat.ParseOptions(mergedOptions)
+			if err == nil {
+				options[openaicompat.Name] = parsed
+			} else {
+				if topK != nil {
+					slog.Warn(
+						"Failed to parse provider_options, falling back to top_k only",
+						"provider", providerCfg.ID,
+						"error", err,
+					)
+
+					fallbackMergeOptions := map[string]any{
+						"extra_body": map[string]any{"top_k": *topK},
+					}
+					parsed, err := openaicompat.ParseOptions(fallbackMergeOptions)
+					if err == nil {
+						options[openaicompat.Name] = parsed
+					} else {
+						slog.Warn(
+							"Failed to parse fallback provider options, this should never happen",
+							"provider", providerCfg.ID,
+							"error", err,
+						)
+					}
+				}
+			}
+		}
+	}
+
+	return options
+}
+
+func mergeCallOptions(model Model, cfg config.ProviderConfig) (fantasy.ProviderOptions, *float64, *float64, *int64, *float64, *float64) {
+	modelOptions := getProviderOptions(model, cfg)
+	temp := cmp.Or(model.ModelCfg.Temperature, model.CatwalkCfg.Options.Temperature)
+	topP := cmp.Or(model.ModelCfg.TopP, model.CatwalkCfg.Options.TopP)
+	topK := cmp.Or(model.ModelCfg.TopK, model.CatwalkCfg.Options.TopK)
+	freqPenalty := cmp.Or(model.ModelCfg.FrequencyPenalty, model.CatwalkCfg.Options.FrequencyPenalty)
+	presPenalty := cmp.Or(model.ModelCfg.PresencePenalty, model.CatwalkCfg.Options.PresencePenalty)
+	return modelOptions, temp, topP, topK, freqPenalty, presPenalty
+}
+
+func (c *coordinator) buildAgent(ctx context.Context, prompt *prompt.Prompt, agent config.Agent, isSubAgent bool) (SessionAgent, error) {
+	large, small, err := c.buildAgentModels(ctx, isSubAgent)
+	if err != nil {
+		return nil, err
+	}
+
+	largeProviderCfg, _ := c.cfg.Config().Providers.Get(large.ModelCfg.Provider)
+	result := NewSessionAgent(SessionAgentOptions{
+		LargeModel:           large,
+		SmallModel:           small,
+		SystemPromptPrefix:   largeProviderCfg.SystemPromptPrefix,
+		SystemPrompt:         "",
+		IsSubAgent:           isSubAgent,
+		DisableAutoSummarize: c.cfg.Config().Options.DisableAutoSummarize,
+		IsYolo:               c.permissions.SkipRequests(),
+		Sessions:             c.sessions,
+		Messages:             c.messages,
+		Tools:                nil,
+		Notify:               c.notify,
+		RunComplete:          c.runComplete,
+	})
+
+	// The readiness goroutines below perform one-time setup — building the
+	// system prompt and the initial tool list — whose results the
+	// coordinator needs for its whole lifetime, so they must survive the
+	// caller's context being canceled. Several entry points build an agent
+	// from a short-lived HTTP request context: the server's
+	// InitAgent/UpdateAgent handlers, and UpdateModels -> buildTools ->
+	// agentTool -> buildAgent for the sub-agent. The tool-list build reads
+	// the MCP registry as it stands; servers still connecting are picked up
+	// by later runs. WithoutCancel drops cancellation while keeping context
+	// values; the work is local and always completes.
+	initCtx := context.WithoutCancel(ctx)
+
+	c.readyWg.Go(func() error {
+		systemPrompt, err := prompt.Build(initCtx, large.Model.Provider(), large.Model.Model(), c.cfg)
+		if err != nil {
+			return err
+		}
+		result.SetSystemPrompt(systemPrompt)
+		return nil
+	})
+
+	c.readyWg.Go(func() error {
+		tools, err := c.buildTools(initCtx, agent, isSubAgent)
+		if err != nil {
+			return err
+		}
+		result.SetTools(tools)
+		return nil
+	})
+
+	return result, nil
+}
+
+func (c *coordinator) buildTools(ctx context.Context, agent config.Agent, isSubAgent bool) ([]fantasy.AgentTool, error) {
+	var allTools []fantasy.AgentTool
+	if slices.Contains(agent.AllowedTools, AgentToolName) {
+		agentTool, err := c.agentTool(ctx)
+		if err != nil {
+			return nil, err
+		}
+		allTools = append(allTools, agentTool)
+	}
+
+	if slices.Contains(agent.AllowedTools, tools.AgenticFetchToolName) {
+		agenticFetchTool, err := c.agenticFetchTool(ctx, nil)
+		if err != nil {
+			return nil, err
+		}
+		allTools = append(allTools, agenticFetchTool)
+	}
+
+	// Get the model name for the agent
+	modelID := ""
+	if modelCfg, ok := c.cfg.Config().Models[agent.Model]; ok {
+		if model := c.cfg.Config().GetModel(modelCfg.Provider, modelCfg.Model); model != nil {
+			modelID = model.ID
+		}
+	}
+
+	logFile := filepath.Join(c.cfg.Config().Options.DataDirectory, "logs", "crush.log")
+
+	// Build hook runner if PreToolUse hooks are configured.
+	var hookRunner *hooks.Runner
+	if preToolHooks := c.cfg.Config().Hooks[hooks.EventPreToolUse]; len(preToolHooks) > 0 {
+		hookRunner = hooks.NewRunner(preToolHooks, c.cfg.WorkingDir(), c.cfg.WorkingDir())
+	}
+
+	allTools = append(
+		allTools,
+		tools.NewBashTool(c.permissions, c.cfg.WorkingDir(), c.cfg.Config().Options.Attribution, modelID),
+		tools.NewCrushInfoTool(c.cfg, c.lspManager, c.allSkills, c.activeSkills, c.skillTracker),
+		tools.NewCrushLogsTool(logFile),
+		tools.NewJobOutputTool(),
+		tools.NewJobKillTool(),
+		tools.NewDownloadTool(c.permissions, c.cfg.WorkingDir(), nil),
+		tools.NewEditTool(c.lspManager, c.permissions, c.history, c.filetracker, c.cfg.WorkingDir()),
+		tools.NewMultiEditTool(c.lspManager, c.permissions, c.history, c.filetracker, c.cfg.WorkingDir()),
+		tools.NewFetchTool(c.permissions, c.cfg.WorkingDir(), nil),
+		tools.NewGlobTool(c.cfg.WorkingDir(), c.cfg.Config().Tools.Glob),
+		tools.NewGrepTool(c.cfg.WorkingDir(), c.cfg.Config().Tools.Grep),
+		tools.NewLsTool(c.permissions, c.cfg.WorkingDir(), c.cfg.Config().Tools.Ls),
+		tools.NewSourcegraphTool(nil),
+		tools.NewTodosTool(c.sessions),
+		tools.NewViewTool(c.lspManager, c.permissions, c.filetracker, c.skillTracker, c.cfg.WorkingDir(), c.cfg.Config().Options.SkillsPaths...),
+		tools.NewWriteTool(c.lspManager, c.permissions, c.history, c.filetracker, c.cfg.WorkingDir()),
+	)
+
+	// Question tool is interactive-only and not available to sub-agents.
+	if !isSubAgent && c.interactive {
+		allTools = append(allTools, tools.NewQuestionTool(c.questions))
+	}
+
+	// Add LSP tools if user has configured LSPs or auto_lsp is enabled (nil or true).
+	if len(c.cfg.Config().LSP) > 0 || c.cfg.Config().Options.AutoLSP == nil || *c.cfg.Config().Options.AutoLSP {
+		allTools = append(
+			allTools,
+			tools.NewDiagnosticsTool(c.lspManager),
+			tools.NewReferencesTool(c.lspManager),
+			tools.NewLSPRestartTool(c.lspManager),
+			tools.NewSymbolsTool(c.lspManager),
+			tools.NewDefinitionTool(c.lspManager),
+			tools.NewCallHierarchyTool(c.lspManager),
+			tools.NewRenameTool(c.lspManager, c.permissions, c.history, c.filetracker),
+			tools.NewReplaceSymbolTool(c.lspManager, c.permissions, c.history, c.filetracker),
+		)
+	}
+
+	if len(c.cfg.Config().MCP) > 0 {
+		allTools = append(
+			allTools,
+			tools.NewListMCPResourcesTool(c.cfg, c.permissions),
+			tools.NewReadMCPResourceTool(c.cfg, c.permissions),
+		)
+	}
+
+	var filteredTools []fantasy.AgentTool
+	for _, tool := range allTools {
+		if slices.Contains(agent.AllowedTools, tool.Info().Name) {
+			filteredTools = append(filteredTools, tool)
+		}
+	}
+
+	for _, tool := range tools.GetMCPTools(c.permissions, c.cfg, c.cfg.WorkingDir()) {
+		if agent.AllowedMCP == nil {
+			// No MCP restrictions
+			filteredTools = append(filteredTools, tool)
+			continue
+		}
+		if len(agent.AllowedMCP) == 0 {
+			// No MCPs allowed
+			slog.Debug("No MCPs allowed", "tool", tool.Name(), "agent", agent.Name)
+			break
+		}
+
+		for mcp, tools := range agent.AllowedMCP {
+			if mcp != tool.MCP() {
+				continue
+			}
+			if len(tools) == 0 || slices.Contains(tools, tool.MCPToolName()) {
+				filteredTools = append(filteredTools, tool)
+				break
+			}
+			slog.Debug("MCP not allowed", "tool", tool.Name(), "agent", agent.Name)
+		}
+	}
+	slices.SortFunc(filteredTools, func(a, b fantasy.AgentTool) int {
+		return strings.Compare(a.Info().Name, b.Info().Name)
+	})
+
+	// Wrap tools with hook interception for the top-level agent only.
+	// Sub-agents (the `agent` task tool, `agentic_fetch`, etc.) run
+	// without hook interception to avoid firing the user's hook N times
+	// per delegated turn. The top-level invocation of the sub-agent tool
+	// itself is still wrapped from the coder's side.
+	filteredTools = wrapToolsWithHooks(filteredTools, hookRunner, isSubAgent)
+
+	return filteredTools, nil
+}
+
+// TODO: when we support multiple agents we need to change this so that we pass in the agent specific model config
+func (c *coordinator) buildAgentModels(ctx context.Context, isSubAgent bool) (Model, Model, error) {
+	largeModelCfg, ok := c.cfg.Config().Models[config.SelectedModelTypeLarge]
+	if !ok {
+		return Model{}, Model{}, errLargeModelNotSelected
+	}
+	smallModelCfg, ok := c.cfg.Config().Models[config.SelectedModelTypeSmall]
+	if !ok {
+		return Model{}, Model{}, errSmallModelNotSelected
+	}
+
+	largeProviderCfg, ok := c.cfg.Config().Providers.Get(largeModelCfg.Provider)
+	if !ok {
+		return Model{}, Model{}, errLargeModelProviderNotConfigured
+	}
+
+	largeProvider, err := c.buildProvider(largeProviderCfg, largeModelCfg, isSubAgent)
+	if err != nil {
+		return Model{}, Model{}, err
+	}
+
+	smallProviderCfg, ok := c.cfg.Config().Providers.Get(smallModelCfg.Provider)
+	if !ok {
+		return Model{}, Model{}, errSmallModelProviderNotConfigured
+	}
+
+	smallProvider, err := c.buildProvider(smallProviderCfg, smallModelCfg, true)
+	if err != nil {
+		return Model{}, Model{}, err
+	}
+
+	var largeCatwalkModel *catwalk.Model
+	var smallCatwalkModel *catwalk.Model
+
+	for _, m := range largeProviderCfg.Models {
+		if m.ID == largeModelCfg.Model {
+			largeCatwalkModel = &m
+		}
+	}
+	for _, m := range smallProviderCfg.Models {
+		if m.ID == smallModelCfg.Model {
+			smallCatwalkModel = &m
+		}
+	}
+
+	if largeCatwalkModel == nil {
+		return Model{}, Model{}, errLargeModelNotFound
+	}
+
+	if smallCatwalkModel == nil {
+		return Model{}, Model{}, errSmallModelNotFound
+	}
+
+	largeModelID := largeModelCfg.Model
+	smallModelID := smallModelCfg.Model
+
+	if largeModelCfg.Provider == openrouter.Name && isExactoSupported(largeModelID) {
+		largeModelID += ":exacto"
+	}
+
+	if smallModelCfg.Provider == openrouter.Name && isExactoSupported(smallModelID) {
+		smallModelID += ":exacto"
+	}
+
+	largeModel, err := largeProvider.LanguageModel(ctx, largeModelID)
+	if err != nil {
+		return Model{}, Model{}, err
+	}
+	smallModel, err := smallProvider.LanguageModel(ctx, smallModelID)
+	if err != nil {
+		return Model{}, Model{}, err
+	}
+
+	// Bound each request with the configured timeout so unreachable or hung
+	// providers fail instead of blocking a session forever. The wrapper is
+	// applied per request, so retries get a fresh budget each attempt.
+	requestTimeout := c.cfg.Config().Options.GetRequestTimeout()
+	largeModel = newRequestTimeoutModel(largeModel, requestTimeout)
+	smallModel = newRequestTimeoutModel(smallModel, requestTimeout)
+
+	return Model{
+			Model:      largeModel,
+			CatwalkCfg: *largeCatwalkModel,
+			ModelCfg:   largeModelCfg,
+			FlatRate:   largeProviderCfg.FlatRate,
+		}, Model{
+			Model:      smallModel,
+			CatwalkCfg: *smallCatwalkModel,
+			ModelCfg:   smallModelCfg,
+			FlatRate:   smallProviderCfg.FlatRate,
+		}, nil
+}
+
+func (c *coordinator) buildAnthropicProvider(baseURL, apiKey string, headers map[string]string, providerID string) (fantasy.Provider, error) {
+	var opts []anthropic.Option
+
+	switch {
+	case strings.HasPrefix(apiKey, "Bearer "):
+		// NOTE: Prevent the SDK from picking up the API key from env.
+		os.Setenv("ANTHROPIC_API_KEY", "")
+		headers["Authorization"] = apiKey
+	case providerID == string(catwalk.InferenceProviderMiniMax) || providerID == string(catwalk.InferenceProviderMiniMaxChina):
+		// NOTE: Prevent the SDK from picking up the API key from env.
+		os.Setenv("ANTHROPIC_API_KEY", "")
+		headers["Authorization"] = "Bearer " + apiKey
+	case apiKey != "":
+		// X-Api-Key header
+		opts = append(opts, anthropic.WithAPIKey(apiKey))
+	}
+
+	if len(headers) > 0 {
+		opts = append(opts, anthropic.WithHeaders(headers))
+	}
+
+	if baseURL != "" {
+		opts = append(opts, anthropic.WithBaseURL(baseURL))
+	}
+
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, anthropic.WithHTTPClient(httpClient))
+	}
+	return anthropic.New(opts...)
+}
+
+func (c *coordinator) buildOpenaiProvider(baseURL, apiKey string, headers map[string]string, token *oauth.Token) (fantasy.Provider, error) {
+	opts := []openai.Option{
+		openai.WithAPIKey(apiKey),
+		openai.WithUseResponsesAPI(),
+	}
+	var httpClient *http.Client
+	if c.cfg.Config().Options.Debug {
+		httpClient = log.NewHTTPClient()
+	}
+	if token != nil {
+		// ChatGPT OAuth: requests go through the Codex backend, which
+		// expects account headers and rejects some request fields, so
+		// they pass through the Codex transport.
+		if httpClient == nil {
+			httpClient = &http.Client{}
+		}
+		httpClient.Transport = &openaioauth.Transport{
+			Base:  httpClient.Transport,
+			Token: token,
+		}
+	}
+	if httpClient != nil {
+		opts = append(opts, openai.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, openai.WithHeaders(headers))
+	}
+	if baseURL != "" {
+		opts = append(opts, openai.WithBaseURL(baseURL))
+	}
+	return openai.New(opts...)
+}
+
+func (c *coordinator) buildOpenrouterProvider(_, apiKey string, headers map[string]string) (fantasy.Provider, error) {
+	opts := []openrouter.Option{
+		openrouter.WithAPIKey(apiKey),
+	}
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, openrouter.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, openrouter.WithHeaders(headers))
+	}
+	return openrouter.New(opts...)
+}
+
+func (c *coordinator) buildVercelProvider(_, apiKey string, headers map[string]string) (fantasy.Provider, error) {
+	opts := []vercel.Option{
+		vercel.WithAPIKey(apiKey),
+	}
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, vercel.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, vercel.WithHeaders(headers))
+	}
+	return vercel.New(opts...)
+}
+
+func (c *coordinator) buildOpenaiCompatProvider(baseURL, apiKey string, headers map[string]string, extraBody map[string]any, providerID string, isSubAgent bool) (fantasy.Provider, error) {
+	opts := []openaicompat.Option{
+		openaicompat.WithBaseURL(baseURL),
+		openaicompat.WithAPIKey(apiKey),
+	}
+
+	// Set HTTP client based on provider and debug mode.
+	var httpClient *http.Client
+	switch providerID {
+	case string(catwalk.InferenceProviderCopilot):
+		opts = append(
+			opts,
+			openaicompat.WithUseResponsesAPI(),
+			openaicompat.WithResponsesAPIFunc(func(modelID string) bool {
+				return copilotResponsesModels[modelID]
+			}),
+		)
+		httpClient = copilot.NewClient(isSubAgent, c.cfg.Config().Options.Debug)
+
+	case string(catwalk.InferenceProviderOpenCodeGo), string(catwalk.InferenceProviderOpenCodeZen):
+		opts = append(
+			opts,
+			openaicompat.WithUseResponsesAPI(),
+			openaicompat.WithResponsesAPIFunc(isOpenCodeResponsesModel),
+		)
+
+	case hyper.Name:
+		// Hyper may route requests through a Prism model; capture the
+		// router headers so the UI can show which model answered.
+		opts = append(
+			opts,
+			openaicompat.WithLanguageModelOptions(
+				openai.WithLanguageModelHeaderFunc(hyper.HeaderFunc),
+			),
+		)
+	}
+	if httpClient == nil && c.cfg.Config().Options.Debug {
+		httpClient = log.NewHTTPClient()
+	}
+	if httpClient != nil {
+		opts = append(opts, openaicompat.WithHTTPClient(httpClient))
+	}
+
+	if len(headers) > 0 {
+		opts = append(opts, openaicompat.WithHeaders(headers))
+	}
+
+	for extraKey, extraValue := range extraBody {
+		opts = append(opts, openaicompat.WithSDKOptions(openaisdk.WithJSONSet(extraKey, extraValue)))
+	}
+
+	return openaicompat.New(opts...)
+}
+
+func (c *coordinator) buildAzureProvider(baseURL, apiKey string, headers map[string]string, options map[string]string) (fantasy.Provider, error) {
+	opts := []azure.Option{
+		azure.WithBaseURL(baseURL),
+		azure.WithAPIKey(apiKey),
+		azure.WithUseResponsesAPI(),
+	}
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, azure.WithHTTPClient(httpClient))
+	}
+	if options == nil {
+		options = make(map[string]string)
+	}
+	if apiVersion, ok := options["apiVersion"]; ok {
+		opts = append(opts, azure.WithAPIVersion(apiVersion))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, azure.WithHeaders(headers))
+	}
+
+	return azure.New(opts...)
+}
+
+func (c *coordinator) buildBedrockProvider(apiKey string, headers map[string]string, providerID string) (fantasy.Provider, error) {
+	var opts []bedrock.Option
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, bedrock.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, bedrock.WithHeaders(headers))
+	}
+
+	switch {
+	case apiKey != "":
+		opts = append(opts, bedrock.WithAPIKey(apiKey))
+	case os.Getenv("AWS_BEARER_TOKEN_BEDROCK") != "":
+		opts = append(opts, bedrock.WithAPIKey(os.Getenv("AWS_BEARER_TOKEN_BEDROCK")))
+	default:
+		// Skip, let the SDK do authentication.
+	}
+
+	switch providerID {
+	case string(catwalk.InferenceProviderBedrockEurope):
+		opts = append(opts, bedrock.WithRegion("eu-west-1"))
+	default:
+		opts = append(opts, bedrock.WithRegion("us-east-1"))
+	}
+
+	return bedrock.New(opts...)
+}
+
+func (c *coordinator) buildGoogleProvider(baseURL, apiKey string, headers map[string]string) (fantasy.Provider, error) {
+	opts := []google.Option{
+		google.WithBaseURL(baseURL),
+		google.WithGeminiAPIKey(apiKey),
+	}
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, google.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, google.WithHeaders(headers))
+	}
+	return google.New(opts...)
+}
+
+func (c *coordinator) buildGoogleVertexProvider(headers map[string]string, options map[string]string) (fantasy.Provider, error) {
+	opts := []google.Option{}
+	if c.cfg.Config().Options.Debug {
+		httpClient := log.NewHTTPClient()
+		opts = append(opts, google.WithHTTPClient(httpClient))
+	}
+	if len(headers) > 0 {
+		opts = append(opts, google.WithHeaders(headers))
+	}
+
+	project := options["project"]
+	location := options["location"]
+
+	opts = append(opts, google.WithVertex(project, location))
+
+	return google.New(opts...)
+}
+
+func (c *coordinator) isAnthropicThinking(model config.SelectedModel) bool {
+	if model.Think {
+		return true
+	}
+	opts, err := anthropic.ParseOptions(model.ProviderOptions)
+	return err == nil && opts.Thinking != nil
+}
+
+func (c *coordinator) buildProvider(providerCfg config.ProviderConfig, model config.SelectedModel, isSubAgent bool) (fantasy.Provider, error) {
+	headers := maps.Clone(providerCfg.ExtraHeaders)
+	if headers == nil {
+		headers = make(map[string]string)
+	}
+
+	// handle special headers for anthropic
+	if providerCfg.Type == anthropic.Name && c.isAnthropicThinking(model) {
+		if v, ok := headers["anthropic-beta"]; ok {
+			headers["anthropic-beta"] = v + ",interleaved-thinking-2025-05-14"
+		} else {
+			headers["anthropic-beta"] = "interleaved-thinking-2025-05-14"
+		}
+	}
+
+	apiKey, _ := c.cfg.Resolve(providerCfg.APIKey)
+	baseURL, _ := c.cfg.Resolve(providerCfg.BaseURL)
+
+	switch providerCfg.ID {
+	case string(catwalk.InferenceProviderOpenCodeGo), string(catwalk.InferenceProviderOpenCodeZen):
+		if isOpenCodeMessagesModel(providerCfg.ID, model.Model) {
+			baseURL = strings.TrimSuffix(baseURL, "/v1")
+			return c.buildAnthropicProvider(baseURL, apiKey, headers, providerCfg.ID)
+		}
+	}
+
+	switch providerCfg.Type {
+	case openai.Name:
+		// A ChatGPT login is the provider's single credential: every
+		// request goes through the Codex backend with the OAuth token.
+		token := providerCfg.OAuthToken
+		if token != nil {
+			baseURL = openaioauth.CodexBaseURL
+			apiKey = token.AccessToken
+			headers["originator"] = "crush"
+			if token.AccountID != "" {
+				headers["chatgpt-account-id"] = token.AccountID
+			}
+		}
+		return c.buildOpenaiProvider(baseURL, apiKey, headers, token)
+	case anthropic.Name:
+		return c.buildAnthropicProvider(baseURL, apiKey, headers, providerCfg.ID)
+	case openrouter.Name:
+		return c.buildOpenrouterProvider(baseURL, apiKey, headers)
+	case vercel.Name:
+		return c.buildVercelProvider(baseURL, apiKey, headers)
+	case azure.Name:
+		return c.buildAzureProvider(baseURL, apiKey, headers, providerCfg.ExtraParams)
+	case bedrock.Name:
+		return c.buildBedrockProvider(apiKey, headers, providerCfg.ID)
+	case google.Name:
+		return c.buildGoogleProvider(baseURL, apiKey, headers)
+	case "google-vertex":
+		return c.buildGoogleVertexProvider(headers, providerCfg.ExtraParams)
+	case openaicompat.Name, hyper.Name:
+		switch providerCfg.ID {
+		case hyper.Name:
+			baseURL = hyper.BaseURL() + "/v1"
+			headers["x-crush-id"] = event.GetID()
+		case string(catwalk.InferenceProviderZAI):
+			if providerCfg.ExtraBody == nil {
+				providerCfg.ExtraBody = map[string]any{}
+			}
+			providerCfg.ExtraBody["tool_stream"] = true
+		}
+		return c.buildOpenaiCompatProvider(baseURL, apiKey, headers, providerCfg.ExtraBody, providerCfg.ID, isSubAgent)
+	default:
+		// Known custom providers (litellm, llamacpp, lmstudio, ollama,
+		// omlx) are openai-compat under the hood.
+		if discover.IsKnownCustomProvider(string(providerCfg.Type)) {
+			return c.buildOpenaiCompatProvider(baseURL, apiKey, headers, providerCfg.ExtraBody, providerCfg.ID, isSubAgent)
+		}
+		return nil, fmt.Errorf("provider type not supported: %q", providerCfg.Type)
+	}
+}
+
+func isExactoSupported(modelID string) bool {
+	supportedModels := []string{
+		"moonshotai/kimi-k2-0905",
+		"deepseek/deepseek-v3.1-terminus",
+		"z-ai/glm-4.6",
+		"openai/gpt-oss-120b",
+		"qwen/qwen3-coder",
+	}
+	return slices.Contains(supportedModels, modelID)
+}
+
+// BeginAccepted reserves an accept slot for sessionID on the active
+// agent and returns the ownership handle. It is the fire-and-forget
+// dispatch path's only way to mark a run as accepted-but-not-yet-active
+// so a cancel arriving before the run registers in activeRequests is not
+// lost.
+func (c *coordinator) BeginAccepted(sessionID string) *AcceptedRun {
+	return c.currentAgent.BeginAccepted(sessionID)
+}
+
+func (c *coordinator) Cancel(sessionID string) {
+	c.currentAgent.Cancel(sessionID)
+}
+
+func (c *coordinator) CancelAll() {
+	c.currentAgent.CancelAll()
+}
+
+func (c *coordinator) ClearQueue(sessionID string) {
+	c.currentAgent.ClearQueue(sessionID)
+}
+
+func (c *coordinator) IsBusy() bool {
+	return c.currentAgent.IsBusy()
+}
+
+func (c *coordinator) IsSessionBusy(sessionID string) bool {
+	return c.currentAgent.IsSessionBusy(sessionID)
+}
+
+func (c *coordinator) Model() Model {
+	return c.currentAgent.Model()
+}
+
+func (c *coordinator) UpdateModels(ctx context.Context) error {
+	// A ChatGPT login without its model catalog — the fetch at login
+	// failed, or the credentials predate it — would leave the models
+	// dialog's ChatGPT section empty. Fill it in lazily; the guard makes
+	// this a no-op once the catalog exists.
+	c.cfg.RefetchOpenAIChatGPTModels(ctx)
+
+	// build the models again so we make sure we get the latest config
+	large, small, err := c.buildAgentModels(ctx, false)
+	if err != nil {
+		return err
+	}
+	c.currentAgent.SetModels(large, small)
+
+	agentCfg, ok := c.cfg.Config().Agents[config.AgentCoder]
+	if !ok {
+		return errCoderAgentNotConfigured
+	}
+
+	tools, err := c.buildTools(ctx, agentCfg, false)
+	if err != nil {
+		return err
+	}
+	c.currentAgent.SetTools(tools)
+	return nil
+}
+
+func (c *coordinator) QueuedPrompts(sessionID string) int {
+	return c.currentAgent.QueuedPrompts(sessionID)
+}
+
+func (c *coordinator) QueuedPromptsList(sessionID string) []string {
+	return c.currentAgent.QueuedPromptsList(sessionID)
+}
+
+func (c *coordinator) Summarize(ctx context.Context, sessionID string) error {
+	providerCfg, ok := c.cfg.Config().Providers.Get(c.currentAgent.Model().ModelCfg.Provider)
+	if !ok {
+		return errModelProviderNotConfigured
+	}
+
+	if err := c.refreshTokenIfExpired(ctx, providerCfg); err != nil {
+		slog.Error("Failed to refresh OAuth2 token before summarize. Proceeding with existing token.", "error", err)
+	}
+
+	// Auth failures during summarize flow through fantasy's OnAuthRefresh,
+	// the same path used by regular turns.
+	return c.currentAgent.Summarize(ctx, sessionID, getProviderOptions(c.currentAgent.Model(), providerCfg), c.makeAuthRefreshCallback(providerCfg))
+}
+
+// GenerateTitle generates a session title using the current agent.
+func (c *coordinator) GenerateTitle(ctx context.Context, sessionID, prompt string) {
+	if c.currentAgent == nil {
+		return
+	}
+	c.currentAgent.GenerateTitle(ctx, sessionID, prompt)
+}
+
+// refreshTokenIfExpired proactively refreshes the OAuth token if it has expired.
+func (c *coordinator) refreshTokenIfExpired(ctx context.Context, providerCfg config.ProviderConfig) error {
+	if providerCfg.OAuthToken == nil || !providerCfg.OAuthToken.IsExpired() {
+		return nil
+	}
+	slog.Debug("Token needs to be refreshed", "provider", providerCfg.ID)
+	return c.refreshOAuth2Token(ctx, providerCfg)
+}
+
+// retryAfterUnauthorized attempts to refresh credentials after an auth error
+// and returns nil if the request should be retried. For OAuth providers whose
+// refresh token is revoked, and for Bedrock providers whose AWS SSO session
+// has expired, it triggers interactive re-authentication and blocks until the
+// user completes it (or the context is cancelled).
+func (c *coordinator) retryAfterUnauthorized(ctx context.Context, providerCfg config.ProviderConfig) error {
+	switch {
+	case providerCfg.OAuthToken != nil:
+		slog.Debug("Received 401. Refreshing token and retrying", "provider", providerCfg.ID)
+		if err := c.refreshOAuth2Token(ctx, providerCfg); err != nil {
+			// If the refresh token was revoked, trigger interactive
+			// re-auth and wait for the user to complete it.
+			var exchangeErr *oauth.TokenExchangeError
+			if c.notify != nil && errors.As(err, &exchangeErr) && exchangeErr.IsRefreshTokenRevoked() {
+				slog.Info("Refresh token revoked, waiting for re-authentication", "provider", providerCfg.ID)
+				c.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+					Type:       notify.TypeReAuthenticate,
+					ProviderID: providerCfg.ID,
+				})
+				return c.waitForInteractiveReauth(ctx, providerCfg.ID)
+			}
+			return err
+		}
+		return nil
+	case providerCfg.AWSAuthRefresh != "":
+		return c.refreshAWSCredentials(ctx, providerCfg)
+	case strings.Contains(providerCfg.APIKeyTemplate, "$"):
+		slog.Debug("Received 401. Refreshing API Key template and retrying", "provider", providerCfg.ID)
+		return c.refreshApiKeyTemplate(ctx, providerCfg)
+	default:
+		return nil
+	}
+}
+
+// errNoInteractiveAuth is returned by an OnAuthRefresh callback when a
+// provider needs interactive re-authentication but no notifier is available
+// to drive it (e.g. headless runs). Returning it surfaces the original auth
+// error rather than retrying.
+var errNoInteractiveAuth = errors.New("interactive authentication unavailable")
+
+// waitForInteractiveReauth blocks until interactive re-authentication for the
+// provider completes (signalled via SignalAuthComplete) or the context is
+// cancelled, then rebuilds models so the next attempt picks up fresh
+// credentials. Returns nil when the caller should retry.
+func (c *coordinator) waitForInteractiveReauth(ctx context.Context, providerID string) error {
+	// Use a detached context with a generous timeout so the wait survives
+	// agent run cancellation. The user needs time to complete browser-based
+	// authentication.
+	waitCtx, waitCancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Minute)
+	defer waitCancel()
+	slog.Info("Blocking on WaitForTokenChange", "provider", providerID)
+	if waitErr := c.cfg.WaitForTokenChange(waitCtx, providerID); waitErr != nil {
+		slog.Info("WaitForTokenChange returned error", "provider", providerID, "error", waitErr)
+		return waitErr
+	}
+	// If the original context was cancelled during the wait, fantasy's retry
+	// would fail immediately, so surface the cancellation instead.
+	if ctx.Err() != nil {
+		slog.Warn("Original context cancelled during auth wait, cannot retry",
+			"provider", providerID, "ctx_err", ctx.Err())
+		return ctx.Err()
+	}
+	// Rebuild models so ModelProvider picks up the fresh credentials.
+	if updateErr := c.UpdateModels(waitCtx); updateErr != nil {
+		slog.Error("Failed to update models after re-authentication", "error", updateErr)
+		return updateErr
+	}
+	slog.Info("Models updated, returning nil to retry", "provider", providerID)
+	return nil
+}
+
+// isUnauthorized reports whether err is an HTTP 401 from a provider.
+func isUnauthorized(err error) bool {
+	var providerErr *fantasy.ProviderError
+	return errors.As(err, &providerErr) && providerErr.StatusCode == http.StatusUnauthorized
+}
+
+// makeAuthRefreshCallback returns an OnAuthRefresh callback for fantasy that
+// delegates to the coordinator's existing credential refresh logic. Returns
+// nil if no refresh mechanism is configured for the provider.
+func (c *coordinator) makeAuthRefreshCallback(providerCfg config.ProviderConfig) func(context.Context, *fantasy.ProviderError) error {
+	if providerCfg.OAuthToken == nil &&
+		!strings.Contains(providerCfg.APIKeyTemplate, "$") &&
+		providerCfg.AWSAuthRefresh == "" {
+		return nil
+	}
+	return func(ctx context.Context, _ *fantasy.ProviderError) error {
+		return c.retryAfterUnauthorized(ctx, providerCfg)
+	}
+}
+
+func (c *coordinator) refreshOAuth2Token(ctx context.Context, providerCfg config.ProviderConfig) error {
+	if err := c.cfg.RefreshOAuthToken(ctx, config.ScopeGlobal, providerCfg.ID); err != nil {
+		slog.Error("Failed to refresh OAuth token after 401 error", "provider", providerCfg.ID, "error", err)
+		return err
+	}
+	if err := c.UpdateModels(ctx); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (c *coordinator) refreshApiKeyTemplate(ctx context.Context, providerCfg config.ProviderConfig) error {
+	newAPIKey, err := c.cfg.Resolve(providerCfg.APIKeyTemplate)
+	if err != nil {
+		slog.Error("Failed to re-resolve API key after 401 error", "provider", providerCfg.ID, "error", err)
+		return err
+	}
+
+	providerCfg.APIKey = newAPIKey
+	c.cfg.Config().Providers.Set(providerCfg.ID, providerCfg)
+
+	if err := c.UpdateModels(ctx); err != nil {
+		return err
+	}
+	return nil
+}
+
+// subAgentParams holds the parameters for running a sub-agent.
+type subAgentParams struct {
+	Agent          SessionAgent
+	SessionID      string
+	AgentMessageID string
+	ToolCallID     string
+	Prompt         string
+	SessionTitle   string
+	// SessionSetup is an optional callback invoked after session creation
+	// but before agent execution, for custom session configuration.
+	SessionSetup func(sessionID string)
+}
+
+// callTopK returns topK for use on fantasy.Call.TopK, suppressing it for
+// known custom providers: getProviderOptions already carries top_k for
+// them via extra_body, and passing it here too makes Fantasy emit a
+// spurious "top_k unsupported" warning for every turn.
+func callTopK(providerCfg config.ProviderConfig, topK *int64) *int64 {
+	if discover.IsKnownCustomProvider(string(providerCfg.Type)) {
+		return nil
+	}
+	return topK
+}
+
+// runSubAgent runs a sub-agent and handles session management and cost accumulation.
+// It creates a sub-session, runs the agent with the given prompt, and propagates
+// the cost to the parent session.
+func (c *coordinator) runSubAgent(ctx context.Context, params subAgentParams) (fantasy.ToolResponse, error) {
+	// Create sub-session
+	agentToolSessionID := c.sessions.CreateAgentToolSessionID(params.AgentMessageID, params.ToolCallID)
+	session, err := c.sessions.CreateTaskSession(ctx, agentToolSessionID, params.SessionID, params.SessionTitle)
+	if err != nil {
+		return fantasy.ToolResponse{}, fmt.Errorf("create session: %w", err)
+	}
+
+	// Call session setup function if provided
+	if params.SessionSetup != nil {
+		params.SessionSetup(session.ID)
+	}
+
+	// Get model configuration
+	model := params.Agent.Model()
+	maxTokens := model.CatwalkCfg.DefaultMaxTokens
+	if model.ModelCfg.MaxTokens != 0 {
+		maxTokens = model.ModelCfg.MaxTokens
+	}
+
+	providerCfg, ok := c.cfg.Config().Providers.Get(model.ModelCfg.Provider)
+	if !ok {
+		return fantasy.ToolResponse{}, errModelProviderNotConfigured
+	}
+
+	// Run the agent
+	run := func() (*fantasy.AgentResult, error) {
+		return params.Agent.Run(ctx, SessionAgentCall{
+			SessionID:        session.ID,
+			Prompt:           params.Prompt,
+			MaxOutputTokens:  maxTokens,
+			ProviderOptions:  getProviderOptions(model, providerCfg),
+			Temperature:      model.ModelCfg.Temperature,
+			TopP:             model.ModelCfg.TopP,
+			TopK:             callTopK(providerCfg, model.ModelCfg.TopK),
+			FrequencyPenalty: model.ModelCfg.FrequencyPenalty,
+			PresencePenalty:  model.ModelCfg.PresencePenalty,
+			NonInteractive:   true,
+			OnAuthRefresh:    c.makeAuthRefreshCallback(providerCfg),
+		})
+	}
+	result, err := run()
+	// Notify only if still unauthorized after retry. AWS SSO is handled
+	// transparently inside OnAuthRefresh, so it needs no post-run notice.
+	if err != nil && isUnauthorized(err) && c.notify != nil && model.ModelCfg.Provider == hyper.Name {
+		c.notify.Publish(pubsub.CreatedEvent, notify.Notification{
+			Type:       notify.TypeReAuthenticate,
+			ProviderID: model.ModelCfg.Provider,
+		})
+	}
+	if err != nil {
+		return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to generate response: %s", err)), nil
+	}
+
+	// Update parent session cost on a best-effort basis. A failure here must
+	// not discard the sub-agent output that was already produced.
+	if err := c.updateParentSessionCost(ctx, session.ID, params.SessionID); err != nil {
+		slog.Warn(
+			"Failed to update parent session cost",
+			"child_session", session.ID,
+			"parent_session", params.SessionID,
+			"error", err,
+		)
+	}
+
+	output := subAgentOutput(result)
+	if output == "" {
+		return fantasy.NewTextErrorResponse("Sub-agent completed but produced no text output."), nil
+	}
+	return fantasy.NewTextResponse(output), nil
+}
+
+func subAgentOutput(result *fantasy.AgentResult) string {
+	if result == nil {
+		return ""
+	}
+	return result.Response.Content.Text()
+}
+
+// updateParentSessionCost accumulates the cost from a child session to its parent session.
+func (c *coordinator) updateParentSessionCost(ctx context.Context, childSessionID, parentSessionID string) error {
+	childSession, err := c.sessions.Get(ctx, childSessionID)
+	if err != nil {
+		return fmt.Errorf("get child session: %w", err)
+	}
+
+	parentSession, err := c.sessions.Get(ctx, parentSessionID)
+	if err != nil {
+		return fmt.Errorf("get parent session: %w", err)
+	}
+
+	parentSession.Cost += childSession.Cost
+
+	if _, err := c.sessions.Save(ctx, parentSession); err != nil {
+		return fmt.Errorf("save parent session: %w", err)
+	}
+
+	return nil
+}
+
+// discoverSkills is a thin fallback wrapper used only when no
+// skills.Manager has been threaded through to the coordinator. All
+// production call sites (backend.CreateWorkspace, setupLocalWorkspace)
+// run discovery in advance and pass the results via the manager;
+// reaching this path means a caller bypassed both. It deliberately does
+// NOT publish to the package-level broker — there are no subscribers in
+// that case, so doing so would be misleading without delivering the
+// snapshot anywhere useful.
+func discoverSkills(cfg *config.ConfigStore) (allSkills, activeSkills []*skills.Skill) {
+	opts := cfg.Config().Options
+	var paths, disabled []string
+	if opts != nil {
+		paths = opts.SkillsPaths
+		disabled = opts.DisabledSkills
+	}
+	var resolver func(string) (string, error)
+	if r := cfg.Resolver(); r != nil {
+		resolver = r.ResolveValue
+	}
+	allSkills, activeSkills, states := skills.DiscoverFromConfig(skills.DiscoveryConfig{
+		SkillsPaths:    paths,
+		DisabledSkills: disabled,
+		Resolver:       resolver,
+	})
+	logDiscoveryStats(states, paths, allSkills, activeSkills, disabled)
+	return allSkills, activeSkills
+}
+
+// logTurnSkillUsage emits a per-turn diagnostic line showing which skills
+// (if any) were loaded during this turn and which looked relevant based on
+// a cheap keyword match against the user prompt. The goal is to surface
+// "should-have-loaded but didn't" situations for later analysis.
+//
+// Logged at Info level under component=skills; heavy fields are elided when
+// there is nothing interesting to report.
+func logTurnSkillUsage(
+	sessionID string,
+	prompt string,
+	activeSkills []*skills.Skill,
+	tracker *skills.Tracker,
+	before []string,
+) {
+	if tracker == nil || len(activeSkills) == 0 {
+		return
+	}
+
+	after := tracker.LoadedNames()
+
+	beforeSet := make(map[string]bool, len(before))
+	for _, n := range before {
+		beforeSet[n] = true
+	}
+	var loadedThisTurn []string
+	for _, n := range after {
+		if !beforeSet[n] {
+			loadedThisTurn = append(loadedThisTurn, n)
+		}
+	}
+
+	slog.Info(
+		"Skill turn summary",
+		"component", "skills",
+		"session_id", sessionID,
+		"prompt_len", len(prompt),
+		"active_total", len(activeSkills),
+		"loaded_total", len(after),
+		"loaded_this_turn", loadedThisTurn,
+	)
+}
+
+// logDiscoveryStats emits a single structured log line summarising skill
+// discovery for the current session. It is intentionally low-volume: one
+// line per session start. Builtin vs user counts are derived from the
+// SkillState.Path — builtin states use the "builtin/" embed prefix.
+func logDiscoveryStats(
+	states []*skills.SkillState,
+	userPaths []string,
+	allSkills, activeSkills []*skills.Skill,
+	disabled []string,
+) {
+	var builtinOK, builtinErr, userOK, userErr int
+	for _, s := range states {
+		isBuiltin := strings.HasPrefix(s.Path, "builtin/")
+		switch {
+		case isBuiltin && s.State == skills.StateNormal:
+			builtinOK++
+		case isBuiltin && s.State == skills.StateError:
+			builtinErr++
+		case !isBuiltin && s.State == skills.StateNormal:
+			userOK++
+		case !isBuiltin && s.State == skills.StateError:
+			userErr++
+		}
+	}
+
+	activeNames := make([]string, 0, len(activeSkills))
+	for _, s := range activeSkills {
+		activeNames = append(activeNames, s.Name)
+	}
+
+	xml := skills.ToPromptXML(activeSkills)
+
+	slog.Info(
+		"Skill discovery complete",
+		"component", "skills",
+		"builtin_ok", builtinOK,
+		"builtin_errors", builtinErr,
+		"user_ok", userOK,
+		"user_errors", userErr,
+		"user_paths", len(userPaths),
+		"deduped_total", len(allSkills),
+		"active", len(activeSkills),
+		"disabled", len(disabled),
+		"prompt_bytes", len(xml),
+		"prompt_tok_est", skills.ApproxTokenCount(xml),
+		"active_names", activeNames,
+	)
+}

internal/agent/coordinator_mcp_gate_test.go

@@ -0,0 +1,115 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+// newGateTestCoordinator builds a minimal coordinator against a hermetic
+// config: one openai-typed provider pointed at a closed port, with large and
+// small models selected so model resolution and the system-prompt build both
+// succeed without any network access.
+func newGateTestCoordinator(t *testing.T, interactive bool) *coordinator {
+	t.Helper()
+
+	env := testEnv(t)
+
+	crushJSON := `{
+  "options": {"disable_default_providers": true, "disable_provider_auto_update": true},
+  "providers": {"mock": {"id": "mock", "name": "Mock", "type": "openai",
+    "base_url": "http://127.0.0.1:9/v1", "api_key": "test-key",
+    "models": [{"id": "mock-model", "name": "Mock", "context_window": 8192, "default_max_tokens": 128}]}},
+  "models": {"large": {"provider": "mock", "model": "mock-model"},
+             "small": {"provider": "mock", "model": "mock-model"}}
+}`
+	require.NoError(t, os.WriteFile(filepath.Join(env.workingDir, "crush.json"), []byte(crushJSON), 0o644))
+
+	cfg, err := config.Init(env.workingDir, "", false)
+	require.NoError(t, err)
+	cfg.SetupAgents()
+
+	coord := &coordinator{
+		cfg:         cfg,
+		sessions:    env.sessions,
+		messages:    env.messages,
+		permissions: env.permissions,
+		history:     env.history,
+		filetracker: *env.filetracker,
+		agents:      make(map[string]SessionAgent),
+		interactive: interactive,
+	}
+
+	p, err := coderPrompt(prompt.WithWorkingDir(env.workingDir))
+	require.NoError(t, err)
+	agentCfg := cfg.Config().Agents[config.AgentCoder]
+
+	agent, err := coord.buildAgent(context.Background(), p, agentCfg, false)
+	require.NoError(t, err)
+	coord.currentAgent = agent
+	coord.agents[config.AgentCoder] = agent
+
+	return coord
+}
+
+// TestRunWaitsForMCPOnlyWhenNonInteractive pins the split behavior for
+// in-flight MCP initialization.
+//
+// MCP servers connect asynchronously. Interactive runs must not wait for them:
+// blocking the send path meant a slow stdio server (e.g. Python via uv) froze
+// the TUI for the length of its connect timeout, most visibly on the first
+// message of a session. Tools from late servers simply miss that run's palette
+// and show up on the next one.
+//
+// Non-interactive runs (`crush run`, both local and client/server) get a single
+// shot at the palette, so they still wait for initialization to settle.
+func TestRunWaitsForMCPOnlyWhenNonInteractive(t *testing.T) {
+	t.Run("non-interactive waits", func(t *testing.T) {
+		coord := newGateTestCoordinator(t, false)
+
+		// Arm the gate and never complete initialization, standing in for an
+		// MCP server that is still connecting.
+		mcp.ArmInit()
+		t.Cleanup(mcp.DisarmInit)
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+
+		_, err := coord.run(ctx, nil, "test-session", "hello")
+		require.ErrorContains(t, err, "MCP initialization",
+			"non-interactive run must block on MCP initialization")
+	})
+
+	t.Run("interactive does not wait", func(t *testing.T) {
+		coord := newGateTestCoordinator(t, true)
+
+		mcp.ArmInit()
+		t.Cleanup(mcp.DisarmInit)
+
+		done := make(chan error, 1)
+		go func() {
+			_, err := coord.run(context.Background(), nil, "test-session", "hello")
+			done <- err
+		}()
+
+		select {
+		case err := <-done:
+			// The run fails for unrelated reasons (no such session, closed
+			// provider port); all that matters is that it got past the gate
+			// instead of parking on MCP initialization.
+			if err != nil {
+				require.NotContains(t, err.Error(), "MCP initialization",
+					"interactive run must not block on MCP initialization")
+			}
+		case <-time.After(10 * time.Second):
+			t.Fatal("interactive run blocked; it must not wait for MCP initialization")
+		}
+	})
+}

internal/agent/coordinator_readiness_test.go

@@ -0,0 +1,97 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBuildAgentReadinessSurvivesCallerCancellation is a regression test for
+// the CRUSH_CLIENT_SERVER=1 "new session hangs" bug.
+//
+// buildAgent starts readiness goroutines that build the system prompt and the
+// initial tool list. Several server entry points build an agent from a
+// short-lived HTTP request context — the InitAgent/UpdateAgent handlers, and
+// the sub-agent build reached through UpdateModels -> buildTools -> agentTool.
+// When that request context was canceled the moment the handler returned, the
+// readyWg errgroup recorded context.Canceled and every later coordinator.run
+// failed at readyWg.Wait() before emitting anything — the session hung with
+// no visible LLM response. (This was made worse while the tool-list goroutine
+// also blocked in mcp.WaitForInit, which kept it parked long enough to
+// observe the cancellation; the readiness work no longer waits on MCP init —
+// see coordinator.run — but the cancellation detachment still matters.)
+//
+// The fix detaches the readiness work from the caller context via
+// context.WithoutCancel, so canceling the context that triggered the build no
+// longer poisons readyWg. Here we build an agent with a cancelable context,
+// cancel it, and require that readyWg still completes cleanly.
+func TestBuildAgentReadinessSurvivesCallerCancellation(t *testing.T) {
+	env := testEnv(t)
+
+	// Minimal hermetic config: one openai-typed provider with selected large
+	// and small models so buildAgentModels and the system-prompt build both
+	// succeed. No MCP servers are configured, so initialization would complete
+	// instantly if we let it — we arm the gate anyway to prove the readiness
+	// goroutines no longer block on it.
+	crushJSON := `{
+  "options": {"disable_default_providers": true, "disable_provider_auto_update": true},
+  "providers": {"mock": {"id": "mock", "name": "Mock", "type": "openai",
+    "base_url": "http://127.0.0.1:9/v1", "api_key": "test-key",
+    "models": [{"id": "mock-model", "name": "Mock", "context_window": 8192, "default_max_tokens": 128}]}},
+  "models": {"large": {"provider": "mock", "model": "mock-model"},
+             "small": {"provider": "mock", "model": "mock-model"}}
+}`
+	require.NoError(t, os.WriteFile(filepath.Join(env.workingDir, "crush.json"), []byte(crushJSON), 0o644))
+
+	cfg, err := config.Init(env.workingDir, "", false)
+	require.NoError(t, err)
+	cfg.SetupAgents()
+
+	coord := &coordinator{
+		cfg:         cfg,
+		sessions:    env.sessions,
+		messages:    env.messages,
+		permissions: env.permissions,
+		history:     env.history,
+		filetracker: *env.filetracker,
+	}
+
+	// Arm the MCP init gate. We never complete init; the readiness goroutines
+	// must not care, since they build the tool list from the registry as it
+	// stands rather than waiting for initialization to finish.
+	mcp.ArmInit()
+	t.Cleanup(mcp.DisarmInit)
+
+	p, err := coderPrompt(prompt.WithWorkingDir(env.workingDir))
+	require.NoError(t, err)
+	agentCfg := cfg.Config().Agents[config.AgentCoder]
+
+	ctx, cancel := context.WithCancel(context.Background())
+	_, err = coord.buildAgent(ctx, p, agentCfg, false)
+	require.NoError(t, err)
+
+	// The caller goes away, mirroring an HTTP handler returning and canceling
+	// its request context.
+	cancel()
+
+	done := make(chan error, 1)
+	go func() { done <- coord.readyWg.Wait() }()
+
+	select {
+	case err := <-done:
+		// context.Canceled is the regression: the caller's cancellation
+		// leaked into the readiness work and poisoned the errgroup.
+		require.NotErrorIs(t, err, context.Canceled,
+			"readyWg was poisoned by caller cancellation (client/server new-session hang regression)")
+		require.NoError(t, err, "unexpected buildAgent readiness error")
+	case <-time.After(2 * time.Second):
+		t.Fatal("readyWg did not complete; the readiness goroutines must not block on MCP init")
+	}
+}

internal/agent/coordinator_test.go

@@ -0,0 +1,792 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"testing"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"charm.land/fantasy/providers/anthropic"
+	"charm.land/fantasy/providers/bedrock"
+	"charm.land/fantasy/providers/openaicompat"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/discover"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mockSessionAgent is a minimal mock for the SessionAgent interface.
+type mockSessionAgent struct {
+	model     Model
+	runFunc   func(ctx context.Context, call SessionAgentCall) (*fantasy.AgentResult, error)
+	cancelled []string
+}
+
+func (m *mockSessionAgent) Run(ctx context.Context, call SessionAgentCall) (*fantasy.AgentResult, error) {
+	return m.runFunc(ctx, call)
+}
+
+func (m *mockSessionAgent) BeginAccepted(sessionID string) *AcceptedRun {
+	return &AcceptedRun{sessionID: sessionID}
+}
+
+func (m *mockSessionAgent) Model() Model                        { return m.model }
+func (m *mockSessionAgent) SetModels(large, small Model)        {}
+func (m *mockSessionAgent) SetTools(tools []fantasy.AgentTool)  {}
+func (m *mockSessionAgent) SetSystemPrompt(systemPrompt string) {}
+func (m *mockSessionAgent) Cancel(sessionID string) {
+	m.cancelled = append(m.cancelled, sessionID)
+}
+func (m *mockSessionAgent) CancelAll()                                  {}
+func (m *mockSessionAgent) IsSessionBusy(sessionID string) bool         { return false }
+func (m *mockSessionAgent) IsBusy() bool                                { return false }
+func (m *mockSessionAgent) QueuedPrompts(sessionID string) int          { return 0 }
+func (m *mockSessionAgent) QueuedPromptsList(sessionID string) []string { return nil }
+func (m *mockSessionAgent) ClearQueue(sessionID string)                 {}
+func (m *mockSessionAgent) Summarize(context.Context, string, fantasy.ProviderOptions, func(context.Context, *fantasy.ProviderError) error) error {
+	return nil
+}
+func (m *mockSessionAgent) GenerateTitle(context.Context, string, string) {}
+
+// newTestCoordinator creates a minimal coordinator for unit testing runSubAgent.
+func newTestCoordinator(t *testing.T, env fakeEnv, providerID string, providerCfg config.ProviderConfig) *coordinator {
+	cfg, err := config.Init(env.workingDir, "", false)
+	require.NoError(t, err)
+	cfg.Config().Providers.Set(providerID, providerCfg)
+	return &coordinator{
+		cfg:      cfg,
+		sessions: env.sessions,
+		messages: env.messages,
+	}
+}
+
+// newMockAgent creates a mockSessionAgent with the given provider and run function.
+func newMockAgent(providerID string, maxTokens int64, runFunc func(context.Context, SessionAgentCall) (*fantasy.AgentResult, error)) *mockSessionAgent {
+	return &mockSessionAgent{
+		model: Model{
+			CatwalkCfg: catwalk.Model{
+				DefaultMaxTokens: maxTokens,
+			},
+			ModelCfg: config.SelectedModel{
+				Provider: providerID,
+			},
+		},
+		runFunc: runFunc,
+	}
+}
+
+// agentResultWithText creates a minimal AgentResult with the given text response.
+func agentResultWithText(text string) *fantasy.AgentResult {
+	return &fantasy.AgentResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.TextContent{Text: text},
+			},
+		},
+	}
+}
+
+func TestCopilotResponsesModels(t *testing.T) {
+	t.Parallel()
+
+	for _, modelID := range []string{"gpt-6-astra", "grok-4.5", "grok-4.6"} {
+		assert.True(t, copilotResponsesModels[modelID], modelID)
+	}
+	assert.False(t, copilotResponsesModels["gpt-4.1"])
+}
+
+func TestRunSubAgent(t *testing.T) {
+	const providerID = "test-provider"
+	providerCfg := config.ProviderConfig{ID: providerID}
+
+	t.Run("happy path", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, call SessionAgentCall) (*fantasy.AgentResult, error) {
+			assert.Equal(t, "do something", call.Prompt)
+			assert.Equal(t, int64(4096), call.MaxOutputTokens)
+			return agentResultWithText("done"), nil
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "do something",
+			SessionTitle:   "Test Session",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, "done", resp.Content)
+		assert.False(t, resp.IsError)
+	})
+
+	t.Run("cost update failure preserves output", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return agentResultWithText("output before cost failure"), nil
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      "missing-parent-session",
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+		assert.False(t, resp.IsError)
+		assert.Equal(t, "output before cost failure", resp.Content)
+	})
+
+	t.Run("response with text returns it", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return agentResultWithText("the answer"), nil
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+		assert.False(t, resp.IsError)
+		assert.Equal(t, "the answer", resp.Content)
+	})
+
+	t.Run("nil result returns error response", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return nil, nil
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Equal(t, "Sub-agent completed but produced no text output.", resp.Content)
+	})
+
+	t.Run("empty result returns error response", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return &fantasy.AgentResult{}, nil
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Equal(t, "Sub-agent completed but produced no text output.", resp.Content)
+	})
+
+	t.Run("ModelCfg.MaxTokens overrides default", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := &mockSessionAgent{
+			model: Model{
+				CatwalkCfg: catwalk.Model{
+					DefaultMaxTokens: 4096,
+				},
+				ModelCfg: config.SelectedModel{
+					Provider:  providerID,
+					MaxTokens: 8192,
+				},
+			},
+			runFunc: func(_ context.Context, call SessionAgentCall) (*fantasy.AgentResult, error) {
+				assert.Equal(t, int64(8192), call.MaxOutputTokens)
+				return agentResultWithText("ok"), nil
+			},
+		}
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, "ok", resp.Content)
+	})
+
+	t.Run("session creation failure with canceled context", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, nil)
+
+		// Use a canceled context to trigger CreateTaskSession failure.
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+
+		_, err = coord.runSubAgent(ctx, subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.Error(t, err)
+	})
+
+	t.Run("provider not configured", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		// Agent references a provider that doesn't exist in config.
+		agent := newMockAgent("unknown-provider", 4096, nil)
+
+		_, err = coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "model provider not configured")
+	})
+
+	t.Run("agent run error returns error response", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return nil, errors.New("provider request failed")
+		})
+
+		resp, err := coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		// runSubAgent returns (errorResponse, nil) when agent.Run fails — not a Go error.
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Equal(t, "Failed to generate response: provider request failed", resp.Content)
+	})
+
+	t.Run("session setup callback is invoked", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		var setupCalledWith string
+		agent := newMockAgent(providerID, 4096, func(_ context.Context, _ SessionAgentCall) (*fantasy.AgentResult, error) {
+			return agentResultWithText("ok"), nil
+		})
+
+		_, err = coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+			SessionSetup: func(sessionID string) {
+				setupCalledWith = sessionID
+			},
+		})
+		require.NoError(t, err)
+		assert.NotEmpty(t, setupCalledWith, "SessionSetup should have been called")
+	})
+
+	t.Run("cost propagation to parent session", func(t *testing.T) {
+		env := testEnv(t)
+		coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+		parentSession, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		agent := newMockAgent(providerID, 4096, func(ctx context.Context, call SessionAgentCall) (*fantasy.AgentResult, error) {
+			// Simulate the agent incurring cost by updating the child session.
+			childSession, err := env.sessions.Get(ctx, call.SessionID)
+			if err != nil {
+				return nil, err
+			}
+			childSession.Cost = 0.05
+			_, err = env.sessions.Save(ctx, childSession)
+			if err != nil {
+				return nil, err
+			}
+			return agentResultWithText("ok"), nil
+		})
+
+		_, err = coord.runSubAgent(t.Context(), subAgentParams{
+			Agent:          agent,
+			SessionID:      parentSession.ID,
+			AgentMessageID: "msg-1",
+			ToolCallID:     "call-1",
+			Prompt:         "test",
+			SessionTitle:   "Test",
+		})
+		require.NoError(t, err)
+
+		updated, err := env.sessions.Get(t.Context(), parentSession.ID)
+		require.NoError(t, err)
+		assert.InDelta(t, 0.05, updated.Cost, 1e-9)
+	})
+}
+
+func TestUpdateParentSessionCost(t *testing.T) {
+	t.Run("accumulates cost correctly", func(t *testing.T) {
+		env := testEnv(t)
+		cfg, err := config.Init(env.workingDir, "", false)
+		require.NoError(t, err)
+		coord := &coordinator{cfg: cfg, sessions: env.sessions}
+
+		parent, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		child, err := env.sessions.CreateTaskSession(t.Context(), "tool-1", parent.ID, "Child")
+		require.NoError(t, err)
+
+		// Set child cost.
+		child.Cost = 0.10
+		_, err = env.sessions.Save(t.Context(), child)
+		require.NoError(t, err)
+
+		err = coord.updateParentSessionCost(t.Context(), child.ID, parent.ID)
+		require.NoError(t, err)
+
+		updated, err := env.sessions.Get(t.Context(), parent.ID)
+		require.NoError(t, err)
+		assert.InDelta(t, 0.10, updated.Cost, 1e-9)
+	})
+
+	t.Run("accumulates multiple child costs", func(t *testing.T) {
+		env := testEnv(t)
+		cfg, err := config.Init(env.workingDir, "", false)
+		require.NoError(t, err)
+		coord := &coordinator{cfg: cfg, sessions: env.sessions}
+
+		parent, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		child1, err := env.sessions.CreateTaskSession(t.Context(), "tool-1", parent.ID, "Child1")
+		require.NoError(t, err)
+		child1.Cost = 0.05
+		_, err = env.sessions.Save(t.Context(), child1)
+		require.NoError(t, err)
+
+		child2, err := env.sessions.CreateTaskSession(t.Context(), "tool-2", parent.ID, "Child2")
+		require.NoError(t, err)
+		child2.Cost = 0.03
+		_, err = env.sessions.Save(t.Context(), child2)
+		require.NoError(t, err)
+
+		err = coord.updateParentSessionCost(t.Context(), child1.ID, parent.ID)
+		require.NoError(t, err)
+		err = coord.updateParentSessionCost(t.Context(), child2.ID, parent.ID)
+		require.NoError(t, err)
+
+		updated, err := env.sessions.Get(t.Context(), parent.ID)
+		require.NoError(t, err)
+		assert.InDelta(t, 0.08, updated.Cost, 1e-9)
+	})
+
+	t.Run("child session not found", func(t *testing.T) {
+		env := testEnv(t)
+		cfg, err := config.Init(env.workingDir, "", false)
+		require.NoError(t, err)
+		coord := &coordinator{cfg: cfg, sessions: env.sessions}
+
+		parent, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+
+		err = coord.updateParentSessionCost(t.Context(), "non-existent", parent.ID)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "get child session")
+	})
+
+	t.Run("parent session not found", func(t *testing.T) {
+		env := testEnv(t)
+		cfg, err := config.Init(env.workingDir, "", false)
+		require.NoError(t, err)
+		coord := &coordinator{cfg: cfg, sessions: env.sessions}
+
+		parent, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+		child, err := env.sessions.CreateTaskSession(t.Context(), "tool-1", parent.ID, "Child")
+		require.NoError(t, err)
+
+		err = coord.updateParentSessionCost(t.Context(), child.ID, "non-existent")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "get parent session")
+	})
+
+	t.Run("zero cost handled correctly", func(t *testing.T) {
+		env := testEnv(t)
+		cfg, err := config.Init(env.workingDir, "", false)
+		require.NoError(t, err)
+		coord := &coordinator{cfg: cfg, sessions: env.sessions}
+
+		parent, err := env.sessions.Create(t.Context(), "Parent")
+		require.NoError(t, err)
+		child, err := env.sessions.CreateTaskSession(t.Context(), "tool-1", parent.ID, "Child")
+		require.NoError(t, err)
+
+		err = coord.updateParentSessionCost(t.Context(), child.ID, parent.ID)
+		require.NoError(t, err)
+
+		updated, err := env.sessions.Get(t.Context(), parent.ID)
+		require.NoError(t, err)
+		assert.InDelta(t, 0.0, updated.Cost, 1e-9)
+	})
+}
+
+func TestGetProviderOptionsReasoningEffort(t *testing.T) {
+	// Bedrock is Fantasy's Anthropic under a different provider name; options
+	// must land under anthropic.Name so the Anthropic language model picks them up.
+	tests := []struct {
+		name         string
+		providerType catwalk.Type
+	}{
+		{"anthropic honors reasoning_effort", catwalk.Type(anthropic.Name)},
+		{"bedrock honors reasoning_effort", catwalk.Type(bedrock.Name)},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			model := Model{
+				CatwalkCfg: catwalk.Model{
+					ID:              "claude-opus-4-7",
+					CanReason:       true,
+					ReasoningLevels: []string{"max"},
+				},
+				ModelCfg: config.SelectedModel{
+					Provider:        "test",
+					ReasoningEffort: "max",
+				},
+			}
+			providerCfg := config.ProviderConfig{ID: "test", Type: tc.providerType}
+
+			opts := getProviderOptions(model, providerCfg)
+
+			raw, ok := opts[anthropic.Name]
+			require.True(t, ok, "options should be keyed under anthropic.Name for type %q", tc.providerType)
+			parsed, ok := raw.(*anthropic.ProviderOptions)
+			require.True(t, ok)
+			require.NotNil(t, parsed.Effort)
+			assert.Equal(t, anthropic.Effort("max"), *parsed.Effort)
+		})
+	}
+}
+
+func TestIsUnauthorized(t *testing.T) {
+	t.Run("nil error", func(t *testing.T) {
+		assert.False(t, isUnauthorized(nil))
+	})
+
+	t.Run("non-provider error", func(t *testing.T) {
+		assert.False(t, isUnauthorized(errors.New("something broke")))
+	})
+
+	t.Run("provider error with 401", func(t *testing.T) {
+		err := &fantasy.ProviderError{StatusCode: http.StatusUnauthorized, Message: "unauthorized"}
+		assert.True(t, isUnauthorized(err))
+	})
+
+	t.Run("provider error with non-401", func(t *testing.T) {
+		err := &fantasy.ProviderError{StatusCode: http.StatusForbidden, Message: "forbidden"}
+		assert.False(t, isUnauthorized(err))
+	})
+
+	t.Run("wrapped provider error with 401", func(t *testing.T) {
+		inner := &fantasy.ProviderError{StatusCode: http.StatusUnauthorized, Message: "expired"}
+		err := fmt.Errorf("request failed: %w", inner)
+		assert.True(t, isUnauthorized(err))
+	})
+}
+
+func TestGetProviderOptionsReasoningEffortCustomProvider(t *testing.T) {
+	// Custom local providers (lmstudio, ollama, omlx, litellm, llamacpp)
+	// go through the OpenAI-compat client and must receive the selected
+	// reasoning effort like any other OpenAI-compatible provider.
+	for _, providerType := range discover.RegisteredProviderTypes() {
+		t.Run(providerType, func(t *testing.T) {
+			model := Model{
+				CatwalkCfg: catwalk.Model{
+					ID:              "qwen/qwen3-8b",
+					CanReason:       true,
+					ReasoningLevels: []string{"low", "medium", "high"},
+				},
+				ModelCfg: config.SelectedModel{
+					Provider:        "local",
+					Model:           "qwen/qwen3-8b",
+					ReasoningEffort: "high",
+				},
+			}
+			providerCfg := config.ProviderConfig{ID: "local", Type: catwalk.Type(providerType)}
+
+			opts := getProviderOptions(model, providerCfg)
+
+			raw, ok := opts[openaicompat.Name]
+			require.True(t, ok, "options should be keyed under openaicompat.Name for type %q", providerType)
+			parsed, ok := raw.(*openaicompat.ProviderOptions)
+			require.True(t, ok)
+			require.NotNil(t, parsed.ReasoningEffort)
+			assert.Equal(t, "high", string(*parsed.ReasoningEffort))
+		})
+	}
+}
+
+func TestGetProviderOptionsReasoningEffortFallback(t *testing.T) {
+	model := Model{
+		CatwalkCfg: catwalk.Model{
+			ID:              "glm-5.2",
+			CanReason:       true,
+			ReasoningLevels: []string{"high", "max"},
+		},
+		ModelCfg: config.SelectedModel{
+			Provider: "zai",
+		},
+	}
+	providerCfg := config.ProviderConfig{
+		ID:   string(catwalk.InferenceProviderZAI),
+		Type: openaicompat.Name,
+	}
+
+	opts := getProviderOptions(model, providerCfg)
+
+	raw, ok := opts[openaicompat.Name]
+	require.True(t, ok)
+	parsed, ok := raw.(*openaicompat.ProviderOptions)
+	require.True(t, ok)
+	require.NotNil(t, parsed.ReasoningEffort)
+	assert.Equal(t, "high", string(*parsed.ReasoningEffort))
+
+	thinking, ok := parsed.ExtraBody["thinking"].(map[string]any)
+	require.True(t, ok)
+	assert.Equal(t, "enabled", thinking["type"])
+}
+
+func TestGetProviderOptionsTopKExtraBody(t *testing.T) {
+	// "ollama" has a registered discover.Enricher, so it is treated as a
+	// known custom provider speaking openai-compat.
+	knownCustomProviderCfg := config.ProviderConfig{ID: "ollama", Type: "ollama"}
+
+	t.Run("model top_k is injected into extra_body for known custom providers", func(t *testing.T) {
+		model := Model{
+			CatwalkCfg: catwalk.Model{ID: "llama3"},
+			ModelCfg:   config.SelectedModel{Provider: "ollama", TopK: ptr(int64(40))},
+		}
+
+		opts := getProviderOptions(model, knownCustomProviderCfg)
+
+		raw, ok := opts[openaicompat.Name]
+		require.True(t, ok)
+		parsed, ok := raw.(*openaicompat.ProviderOptions)
+		require.True(t, ok)
+		topK, ok := parsed.ExtraBody["top_k"].(int64)
+		require.True(t, ok)
+		assert.Equal(t, int64(40), topK)
+	})
+
+	t.Run("falls back to catwalk top_k when the model config has none", func(t *testing.T) {
+		model := Model{
+			CatwalkCfg: catwalk.Model{
+				ID:      "llama3",
+				Options: catwalk.ModelOptions{TopK: ptr(int64(64))},
+			},
+			ModelCfg: config.SelectedModel{Provider: "ollama"},
+		}
+
+		opts := getProviderOptions(model, knownCustomProviderCfg)
+
+		raw, ok := opts[openaicompat.Name]
+		require.True(t, ok)
+		parsed, ok := raw.(*openaicompat.ProviderOptions)
+		require.True(t, ok)
+		topK, ok := parsed.ExtraBody["top_k"].(int64)
+		require.True(t, ok)
+		assert.Equal(t, int64(64), topK)
+	})
+
+	t.Run("does not set extra_body when no top_k is configured anywhere", func(t *testing.T) {
+		model := Model{
+			CatwalkCfg: catwalk.Model{ID: "llama3"},
+			ModelCfg:   config.SelectedModel{Provider: "ollama"},
+		}
+
+		opts := getProviderOptions(model, knownCustomProviderCfg)
+
+		raw, ok := opts[openaicompat.Name]
+		require.True(t, ok)
+		parsed, ok := raw.(*openaicompat.ProviderOptions)
+		require.True(t, ok)
+		_, hasTopK := parsed.ExtraBody["top_k"]
+		assert.False(t, hasTopK)
+	})
+
+	t.Run("does not overwrite an explicitly configured extra_body.top_k", func(t *testing.T) {
+		model := Model{
+			CatwalkCfg: catwalk.Model{ID: "llama3"},
+			ModelCfg: config.SelectedModel{
+				Provider: "ollama",
+				TopK:     ptr(int64(40)),
+				ProviderOptions: map[string]any{
+					"extra_body": map[string]any{"top_k": 7},
+				},
+			},
+		}
+
+		opts := getProviderOptions(model, knownCustomProviderCfg)
+
+		raw, ok := opts[openaicompat.Name]
+		require.True(t, ok)
+		parsed, ok := raw.(*openaicompat.ProviderOptions)
+		require.True(t, ok)
+		assert.EqualValues(t, 7, parsed.ExtraBody["top_k"])
+	})
+
+	t.Run("is not injected for providers outside the known-custom-provider default branch", func(t *testing.T) {
+		model := Model{
+			CatwalkCfg: catwalk.Model{ID: "glm-5.2"},
+			ModelCfg:   config.SelectedModel{Provider: "zai", TopK: ptr(int64(40))},
+		}
+		providerCfg := config.ProviderConfig{ID: string(catwalk.InferenceProviderZAI), Type: openaicompat.Name}
+
+		opts := getProviderOptions(model, providerCfg)
+
+		raw, ok := opts[openaicompat.Name]
+		require.True(t, ok)
+		parsed, ok := raw.(*openaicompat.ProviderOptions)
+		require.True(t, ok)
+		_, hasTopK := parsed.ExtraBody["top_k"]
+		assert.False(t, hasTopK)
+	})
+}
+
+func TestGetProviderOptionsMalformedFallback(t *testing.T) {
+	model := Model{
+		CatwalkCfg: catwalk.Model{ID: "llama3"},
+		ModelCfg: config.SelectedModel{
+			Provider:        "ollama",
+			TopK:            ptr(int64(40)),
+			ProviderOptions: map[string]any{"user": 5.0},
+		},
+	}
+	providerCfg := config.ProviderConfig{ID: "test", Type: "ollama"}
+
+	opts := getProviderOptions(model, providerCfg)
+
+	raw, ok := opts[openaicompat.Name]
+	require.True(t, ok, "malformed provider_options should still fall back to top_k")
+	parsed, ok := raw.(*openaicompat.ProviderOptions)
+	require.True(t, ok)
+
+	// The malformed fields are dropped; only the injected top_k survives.
+	assert.Nil(t, parsed.User)
+	assert.Nil(t, parsed.ReasoningEffort)
+	require.Len(t, parsed.ExtraBody, 1)
+	topK, ok := parsed.ExtraBody["top_k"].(int64)
+	require.True(t, ok)
+	assert.Equal(t, int64(40), topK)
+}
+
+func TestCallTopK(t *testing.T) {
+	knownCustomProviderCfg := config.ProviderConfig{ID: "ollama", Type: "ollama"}
+
+	tests := []struct {
+		name        string
+		providerCfg config.ProviderConfig
+		want        *int64
+	}{
+		{
+			name:        "suppressed for known custom providers",
+			providerCfg: knownCustomProviderCfg,
+			want:        nil,
+		},
+		{
+			name:        "passed through for openai-compat hosted providers",
+			providerCfg: config.ProviderConfig{ID: "zai", Type: openaicompat.Name},
+			want:        ptr(int64(40)),
+		},
+		{
+			name:        "passed through for anthropic",
+			providerCfg: config.ProviderConfig{ID: "anthropic", Type: catwalk.Type(anthropic.Name)},
+			want:        ptr(int64(40)),
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := callTopK(tc.providerCfg, ptr(int64(40)))
+			if tc.want == nil {
+				assert.Nil(t, got)
+				return
+			}
+			require.NotNil(t, got)
+			assert.Equal(t, *tc.want, *got)
+		})
+	}
+
+	t.Run("nil input stays nil regardless of provider", func(t *testing.T) {
+		assert.Nil(t, callTopK(knownCustomProviderCfg, nil))
+		assert.Nil(t, callTopK(config.ProviderConfig{Type: openaicompat.Name}, nil))
+	})
+}
+
+func ptr[T any](v T) *T { return &v }

internal/agent/dispatch_cancel_test.go

@@ -0,0 +1,447 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// finishStreamModel is a minimal fantasy.LanguageModel that streams a
+// single text part followed by a normal (FinishReasonStop) finish. It
+// is enough to drive sessionAgent.Run through PrepareStep and a clean
+// completion without a recorded provider cassette.
+type finishStreamModel struct {
+	text string
+}
+
+func (m *finishStreamModel) Provider() string { return "fake" }
+func (m *finishStreamModel) Model() string    { return "fake-model" }
+
+func (m *finishStreamModel) Generate(ctx context.Context, call fantasy.Call) (*fantasy.Response, error) {
+	return &fantasy.Response{
+		Content:      fantasy.ResponseContent{fantasy.TextContent{Text: m.text}},
+		FinishReason: fantasy.FinishReasonStop,
+	}, nil
+}
+
+func (m *finishStreamModel) Stream(ctx context.Context, call fantasy.Call) (fantasy.StreamResponse, error) {
+	text := m.text
+	return func(yield func(fantasy.StreamPart) bool) {
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextStart, ID: "1"}) {
+			return
+		}
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextDelta, ID: "1", Delta: text}) {
+			return
+		}
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextEnd, ID: "1"}) {
+			return
+		}
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeFinish, FinishReason: fantasy.FinishReasonStop})
+	}, nil
+}
+
+func (m *finishStreamModel) GenerateObject(ctx context.Context, call fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (m *finishStreamModel) StreamObject(ctx context.Context, call fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+func newStreamTestAgent(t *testing.T) (*sessionAgent, fakeEnv) {
+	t.Helper()
+	env := testEnv(t)
+	model := &finishStreamModel{text: "done"}
+	sa := testSessionAgent(env, model, model, "system").(*sessionAgent)
+	return sa, env
+}
+
+// TestCancel_ActiveAndAcceptedFiresBothBranches covers the case where a
+// session is actively running (activeRequests set) AND a follow-up has
+// been accepted (acceptedRuns > 0). A single Cancel must fire both: it
+// invokes the active cancel func and records a pending cancel for the
+// accepted follow-up.
+func TestCancel_ActiveAndAcceptedFiresBothBranches(t *testing.T) {
+	t.Parallel()
+	sa, _ := newCancelTestAgent(t)
+
+	const sid = "sid"
+	var activeCanceled atomic.Bool
+	sa.activeRequests.Set(sid, &activeCancel{cancel: func() { activeCanceled.Store(true) }})
+
+	accept := sa.BeginAccepted(sid)
+	defer accept.Close()
+
+	sa.Cancel(sid)
+
+	require.True(t, activeCanceled.Load(), "active cancel func must fire")
+	require.True(t, sa.hasPendingCancel(sid), "accepted follow-up must record a pending cancel")
+}
+
+// TestRun_BusyWithPendingCancelTakesCancelOnEntry covers the busy-queue
+// branch consulting pendingCancels: when the session is busy AND a
+// cancel has been recorded for an accepted follow-up, Run must take the
+// cancel-on-entry path (persist a canceled turn) instead of enqueueing
+// the call behind the active run.
+func TestRun_BusyWithPendingCancelTakesCancelOnEntry(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// Make the session look busy: an earlier prompt is active.
+	sa.activeRequests.Set(sess.ID, &activeCancel{cancel: func() {}})
+
+	accept := sa.BeginAccepted(sess.ID)
+	// A cancel arrives while this follow-up is accepted-but-not-active.
+	sa.Cancel(sess.ID)
+	require.True(t, sa.hasPendingCancel(sess.ID))
+
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "follow-up",
+		Accepted:  accept,
+	})
+	require.NoError(t, err)
+	require.Nil(t, result)
+
+	// The follow-up was canceled on entry, not enqueued.
+	require.Equal(t, 0, sa.QueuedPrompts(sess.ID),
+		"cancel-on-entry must not enqueue the follow-up behind the active run")
+	require.False(t, sa.hasPendingCancel(sess.ID), "pending cancel must be consumed")
+	require.Equal(t, 0, sa.acceptedCount(sess.ID), "accept reservation must be released")
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.User, msgs[0].Role)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonCanceled, msgs[1].FinishReason())
+}
+
+// TestRun_PrepareStepDrainSkipsQueuedOnPendingCancel verifies that the
+// queue drain inside PrepareStep skips queued follow-up prompts when a
+// cancel has been recorded for the session: the queued prompt must not
+// be folded into the active turn as an extra user message.
+func TestRun_PrepareStepDrainSkipsQueuedOnPendingCancel(t *testing.T) {
+	t.Parallel()
+	sa, env := newStreamTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// A follow-up prompt sits queued for the session.
+	sa.enqueueCall(SessionAgentCall{SessionID: sess.ID, Prompt: "queued-followup"})
+	// A cancel was recorded for the session while it sat in the queue.
+	sa.cancelMark.Set(sess.ID, 1)
+
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "main",
+	})
+	require.NoError(t, err)
+	require.NotNil(t, result)
+
+	// Only the main prompt produced a user message; the queued
+	// follow-up was skipped, not folded into the turn.
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	var userMsgs []message.Message
+	for _, m := range msgs {
+		if m.Role == message.User {
+			userMsgs = append(userMsgs, m)
+		}
+	}
+	require.Len(t, userMsgs, 1, "queued follow-up must not create a user message")
+	assert.Equal(t, "main", userMsgs[0].Content().String())
+
+	// The queue was drained and the pending cancel consumed.
+	require.Equal(t, 0, sa.QueuedPrompts(sess.ID))
+	require.False(t, sa.hasPendingCancel(sess.ID))
+}
+
+// TestRun_NormalCompletionClearsStalePendingCancel verifies that a Run
+// which completes normally clears any stale pending-cancel entry for the
+// session, so it cannot catch a future run.
+func TestRun_NormalCompletionClearsStalePendingCancel(t *testing.T) {
+	t.Parallel()
+	sa, env := newStreamTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// A stale cancel mark lingers (no queued work, no accepted run).
+	sa.cancelMark.Set(sess.ID, 1)
+
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "main",
+	})
+	require.NoError(t, err)
+	require.NotNil(t, result)
+
+	require.False(t, sa.hasPendingCancel(sess.ID),
+		"normal completion must clear the stale pending cancel")
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonEndTurn, msgs[1].FinishReason())
+}
+
+// newCancelTestAgentWithRunComplete builds a DB-backed sessionAgent wired
+// to a RunComplete broker so tests can observe the terminal event a
+// RunID-bearing caller (e.g. `crush run`) blocks on.
+func newCancelTestAgentWithRunComplete(t *testing.T) (*sessionAgent, fakeEnv, *pubsub.Broker[notify.RunComplete]) {
+	t.Helper()
+	env := testEnv(t)
+	broker := pubsub.NewBroker[notify.RunComplete]()
+	t.Cleanup(broker.Shutdown)
+	sa := NewSessionAgent(SessionAgentOptions{
+		Sessions:    env.sessions,
+		Messages:    env.messages,
+		RunComplete: broker,
+	}).(*sessionAgent)
+	return sa, env, broker
+}
+
+// TestRun_CancelOnEntryPublishesRunComplete covers the first review
+// finding: the cancel-on-entry path returned before the streaming defer
+// that publishes RunComplete was installed. A caller that dispatches a
+// run with a RunID and blocks on RunComplete (ignoring message events,
+// like `crush run`) would hang on an immediately-canceled accepted run.
+// The cancel-on-entry path must publish a terminal RunComplete carrying
+// the originating RunID.
+func TestRun_CancelOnEntryPublishesRunComplete(t *testing.T) {
+	t.Parallel()
+	sa, env, broker := newCancelTestAgentWithRunComplete(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	ch := broker.Subscribe(ctx)
+
+	accept := sa.BeginAccepted(sess.ID)
+	// A cancel arrives in the accepted-but-not-yet-active window.
+	sa.Cancel(sess.ID)
+	require.True(t, sa.hasPendingCancel(sess.ID))
+
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		RunID:     "run-cancel-on-entry",
+		Prompt:    "hello",
+		Accepted:  accept,
+	})
+	require.NoError(t, err)
+	require.Nil(t, result)
+
+	select {
+	case got := <-ch:
+		assert.Equal(t, "run-cancel-on-entry", got.Payload.RunID,
+			"RunComplete must echo the originating RunID")
+		assert.Equal(t, sess.ID, got.Payload.SessionID)
+		assert.True(t, got.Payload.Cancelled,
+			"cancel-on-entry RunComplete must be marked cancelled")
+	case <-time.After(2 * time.Second):
+		t.Fatal("cancel-on-entry must publish RunComplete; a RunID caller would hang otherwise")
+	}
+}
+
+// TestCancel_TwoAcceptedBothObserveCancellation covers the second review
+// finding: a single cancel with two accepted-not-yet-active prompts must
+// cancel both. The cancel raises the session's high-water mark to the
+// latest accept sequence, so every prompt accepted-but-not-yet-active at
+// cancel time is covered and both take the cancel-on-entry path.
+func TestCancel_TwoAcceptedBothObserveCancellation(t *testing.T) {
+	t.Parallel()
+	sa, env := newCancelTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// Two prompts are accepted-but-not-yet-active for the same session.
+	accept1 := sa.BeginAccepted(sess.ID)
+	accept2 := sa.BeginAccepted(sess.ID)
+	require.Equal(t, 2, sa.acceptedCount(sess.ID))
+
+	// A single cancel arrives before either becomes active.
+	sa.Cancel(sess.ID)
+	require.Equal(t, accept2.seq, sa.pendingCancelMark(sess.ID),
+		"one cancel must mark every currently-accepted prompt as canceled")
+	require.GreaterOrEqual(t, sa.pendingCancelMark(sess.ID), accept1.seq,
+		"the mark must cover the earlier accepted prompt too")
+
+	// Both prompts enter Run; each must take cancel-on-entry, not run.
+	r1, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "first",
+		Accepted:  accept1,
+	})
+	require.NoError(t, err)
+	require.Nil(t, r1)
+
+	r2, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "second",
+		Accepted:  accept2,
+	})
+	require.NoError(t, err)
+	require.Nil(t, r2)
+
+	require.False(t, sa.hasPendingCancel(sess.ID),
+		"both reserved units must be consumed")
+	require.Equal(t, 0, sa.acceptedCount(sess.ID),
+		"both accept reservations must be released")
+
+	// Each canceled-on-entry turn writes a user + canceled assistant
+	// message, and neither prompt was enqueued to run normally.
+	require.Equal(t, 0, sa.QueuedPrompts(sess.ID),
+		"neither accepted prompt may be enqueued to run normally")
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 4, "two canceled turns produce two user + two assistant messages")
+	var canceled int
+	for _, m := range msgs {
+		if m.Role == message.Assistant {
+			assert.Equal(t, message.FinishReasonCanceled, m.FinishReason())
+			canceled++
+		}
+	}
+	require.Equal(t, 2, canceled, "both turns must finish canceled")
+}
+
+// TestRun_IdleCancelDoesNotPoisonNextPrompt covers the idle-cancel
+// no-op guarantee end-to-end: an Escape on an idle session must not
+// record a pending cancel that leaks into the next accepted prompt, which
+// must run normally to completion.
+func TestRun_IdleCancelDoesNotPoisonNextPrompt(t *testing.T) {
+	t.Parallel()
+	sa, env := newStreamTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// Idle Escape: no accepted run, no active request.
+	sa.Cancel(sess.ID)
+	require.False(t, sa.hasPendingCancel(sess.ID),
+		"idle cancel must not record a pending cancel")
+
+	// The next accepted prompt must run normally, not cancel on entry.
+	accept := sa.BeginAccepted(sess.ID)
+	result, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "next",
+		Accepted:  accept,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, result, "next prompt must run normally after an idle cancel")
+
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	assert.Equal(t, message.User, msgs[0].Role)
+	assert.Equal(t, message.Assistant, msgs[1].Role)
+	assert.Equal(t, message.FinishReasonEndTurn, msgs[1].FinishReason(),
+		"the prompt must finish normally, not canceled")
+}
+
+// TestCancel_AcceptedAfterCancelIsNotPoisoned is the regression test for
+// the reviewer's finding: a counted session-level pending cancel let a
+// prompt accepted after the cancel enter Run first and consume a unit
+// reserved for the earlier prompts. With a sequence high-water mark, a
+// single cancel covers exactly the prompts accepted-but-not-yet-active at
+// cancel time (A and B); a prompt accepted afterwards (C) gets a higher
+// sequence and must run normally without consuming A or B's cancellation.
+// C is run first to prove it neither cancels nor drains the mark, then A
+// and B are run and must both cancel on entry.
+func TestCancel_AcceptedAfterCancelIsNotPoisoned(t *testing.T) {
+	t.Parallel()
+	sa, env := newStreamTestAgent(t)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	// A and B are accepted-but-not-yet-active.
+	acceptA := sa.BeginAccepted(sess.ID)
+	acceptB := sa.BeginAccepted(sess.ID)
+
+	// One cancel arrives covering both A and B.
+	sa.Cancel(sess.ID)
+	require.True(t, sa.hasPendingCancel(sess.ID))
+	require.Equal(t, acceptB.seq, sa.pendingCancelMark(sess.ID),
+		"the mark must cover every prompt accepted before the cancel")
+
+	// C is accepted AFTER the cancel; its sequence is above the mark.
+	acceptC := sa.BeginAccepted(sess.ID)
+	require.Greater(t, acceptC.seq, sa.pendingCancelMark(sess.ID),
+		"a prompt accepted after the cancel must not be covered by the mark")
+
+	// Run C first. It must run normally to completion and must not
+	// consume or clear the cancellation reserved for A and B.
+	rc, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "C",
+		Accepted:  acceptC,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, rc, "C was accepted after the cancel and must run normally")
+	require.True(t, sa.hasPendingCancel(sess.ID),
+		"running C must not drain the cancellation reserved for A and B")
+
+	// Now A and B run. Both were accepted before the cancel and must
+	// take the cancel-on-entry path.
+	ra, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "A",
+		Accepted:  acceptA,
+	})
+	require.NoError(t, err)
+	require.Nil(t, ra, "A must cancel on entry, not run")
+
+	rb, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		Prompt:    "B",
+		Accepted:  acceptB,
+	})
+	require.NoError(t, err)
+	require.Nil(t, rb, "B must cancel on entry, not run")
+
+	require.False(t, sa.hasPendingCancel(sess.ID),
+		"the mark clears once all covered handles are resolved")
+	require.Equal(t, 0, sa.acceptedCount(sess.ID))
+	require.Equal(t, 0, sa.QueuedPrompts(sess.ID),
+		"neither A nor B may be enqueued to run normally")
+
+	// C produced a normal turn; A and B each produced a canceled turn.
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 6, "C normal + A canceled + B canceled = 3 user + 3 assistant")
+
+	var normal, canceled int
+	for _, m := range msgs {
+		if m.Role != message.Assistant {
+			continue
+		}
+		switch m.FinishReason() {
+		case message.FinishReasonEndTurn:
+			normal++
+		case message.FinishReasonCanceled:
+			canceled++
+		}
+	}
+	require.Equal(t, 1, normal, "only C finished normally")
+	require.Equal(t, 2, canceled, "both A and B finished canceled")
+}

internal/agent/dispatch_race_test.go

@@ -0,0 +1,155 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/stretchr/testify/require"
+)
+
+// concurrencyProbeModel records the maximum number of Stream iterators in
+// flight at once. Each stream blocks on release, so a second dispatch that
+// wrongly started a concurrent run for the same session is observable as an
+// in-flight count above one.
+type concurrencyProbeModel struct {
+	inFlight atomic.Int32
+	maxSeen  atomic.Int32
+	entered  chan struct{}
+	release  chan struct{}
+}
+
+func (m *concurrencyProbeModel) Provider() string { return "fake" }
+func (m *concurrencyProbeModel) Model() string    { return "fake-model" }
+
+func (m *concurrencyProbeModel) Generate(context.Context, fantasy.Call) (*fantasy.Response, error) {
+	return &fantasy.Response{
+		Content:      fantasy.ResponseContent{fantasy.TextContent{Text: "done"}},
+		FinishReason: fantasy.FinishReasonStop,
+	}, nil
+}
+
+func (m *concurrencyProbeModel) Stream(context.Context, fantasy.Call) (fantasy.StreamResponse, error) {
+	return func(yield func(fantasy.StreamPart) bool) {
+		cur := m.inFlight.Add(1)
+		for {
+			mx := m.maxSeen.Load()
+			if cur <= mx || m.maxSeen.CompareAndSwap(mx, cur) {
+				break
+			}
+		}
+		// Signal that a stream is in flight (non-blocking), then hold here
+		// so a racing second dispatch would be caught by maxSeen.
+		select {
+		case m.entered <- struct{}{}:
+		default:
+		}
+		<-m.release
+		m.inFlight.Add(-1)
+
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextStart, ID: "1"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextDelta, ID: "1", Delta: "done"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextEnd, ID: "1"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeFinish, FinishReason: fantasy.FinishReasonStop})
+	}, nil
+}
+
+func (m *concurrencyProbeModel) GenerateObject(context.Context, fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (m *concurrencyProbeModel) StreamObject(context.Context, fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+// fastModel is a non-blocking model used as the small model in concurrency
+// tests. GenerateTitle runs on the small model; if it shares the probe model,
+// its Stream call races into inFlight/maxSeen and produces spurious failures.
+type fastModel struct{}
+
+func (fastModel) Provider() string { return "fake" }
+func (fastModel) Model() string    { return "fake-model" }
+
+func (fastModel) Generate(context.Context, fantasy.Call) (*fantasy.Response, error) {
+	return &fantasy.Response{
+		Content:      fantasy.ResponseContent{fantasy.TextContent{Text: "title"}},
+		FinishReason: fantasy.FinishReasonStop,
+	}, nil
+}
+
+func (fastModel) Stream(context.Context, fantasy.Call) (fantasy.StreamResponse, error) {
+	return func(yield func(fantasy.StreamPart) bool) {
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextStart, ID: "1"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextDelta, ID: "1", Delta: "title"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextEnd, ID: "1"})
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeFinish, FinishReason: fantasy.FinishReasonStop})
+	}, nil
+}
+
+func (fastModel) GenerateObject(context.Context, fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (fastModel) StreamObject(context.Context, fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+// TestRun_ConcurrentInProcessDispatchStartsOneRun fires a burst of concurrent
+// in-process Run calls (the path channel events use) at an idle session. Only
+// one may become the active run; the rest must queue behind it. Before the
+// dispatch decision was serialized under the per-session mutex, two callers
+// could both pass the busy check and start two runs on the same session — this
+// test catches that regression (maxSeen would exceed one).
+//
+// fastModel is used as the small model so GenerateTitle (which runs on the
+// small model) does not race into the probe's inFlight/maxSeen counters. The
+// queue count is not asserted because PrepareStep drains queued prompts into
+// the active step before the model's Stream is called — by the time "entered"
+// fires the queue is already empty by design.
+func TestRun_ConcurrentInProcessDispatchStartsOneRun(t *testing.T) {
+	t.Parallel()
+	env := testEnv(t)
+	model := &concurrencyProbeModel{
+		entered: make(chan struct{}, 1),
+		release: make(chan struct{}),
+	}
+	sa := testSessionAgent(env, model, fastModel{}, "system").(*sessionAgent)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	const n = 8
+	var wg sync.WaitGroup
+	for range n {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = sa.Run(t.Context(), SessionAgentCall{
+				SessionID: sess.ID,
+				Prompt:    "event",
+			})
+		}()
+	}
+
+	// Wait until the active run's Stream is in flight (blocked on release).
+	select {
+	case <-model.entered:
+	case <-time.After(5 * time.Second):
+		close(model.release)
+		wg.Wait()
+		t.Fatal("no run became active")
+	}
+
+	// Every other dispatch must have either queued (and been folded into the
+	// active step by PrepareStep) or never started its own Stream. Either way,
+	// at most one Stream may be in flight and the high-water mark must be one.
+	require.Equal(t, int32(1), model.inFlight.Load(), "exactly one run may be active")
+	require.Equal(t, int32(1), model.maxSeen.Load(), "no two runs may stream concurrently for one session")
+
+	close(model.release)
+	wg.Wait()
+}

internal/agent/errors.go

@@ -0,0 +1,10 @@
+package agent
+
+import "errors"
+
+var (
+	ErrRequestCancelled = errors.New("request canceled by user")
+	ErrSessionBusy      = errors.New("session is currently processing another request")
+	ErrEmptyPrompt      = errors.New("prompt is empty")
+	ErrSessionMissing   = errors.New("session id is missing")
+)

internal/agent/event.go

@@ -0,0 +1,51 @@
+package agent
+
+import (
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/event"
+)
+
+func (a *sessionAgent) eventPromptSent(sessionID string) {
+	event.PromptSent(
+		a.eventCommon(sessionID, a.largeModel.Get())...,
+	)
+}
+
+func (a *sessionAgent) eventPromptResponded(sessionID string, duration time.Duration) {
+	event.PromptResponded(
+		append(
+			a.eventCommon(sessionID, a.largeModel.Get()),
+			"prompt duration pretty", duration.String(),
+			"prompt duration in seconds", int64(duration.Seconds()),
+		)...,
+	)
+}
+
+func (a *sessionAgent) eventTokensUsed(sessionID string, model Model, usage fantasy.Usage, cost float64) {
+	event.TokensUsed(
+		append(
+			a.eventCommon(sessionID, model),
+			"input tokens", usage.InputTokens,
+			"output tokens", usage.OutputTokens,
+			"cache read tokens", usage.CacheReadTokens,
+			"cache creation tokens", usage.CacheCreationTokens,
+			"total tokens", usage.InputTokens+usage.OutputTokens+usage.CacheReadTokens+usage.CacheCreationTokens,
+			"cost", cost,
+		)...,
+	)
+}
+
+func (a *sessionAgent) eventCommon(sessionID string, model Model) []any {
+	m := model.ModelCfg
+
+	return []any{
+		"session id", sessionID,
+		"provider", m.Provider,
+		"model", m.Model,
+		"reasoning effort", m.ReasoningEffort,
+		"thinking mode", m.Think,
+		"yolo mode", a.isYolo,
+	}
+}

internal/agent/hooked_tool.go

@@ -0,0 +1,142 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent/tools"
+	"github.com/charmbracelet/crush/internal/hooks"
+	"github.com/charmbracelet/crush/internal/permission"
+	"github.com/tidwall/sjson"
+)
+
+// hookedTool wraps a fantasy.AgentTool to run PreToolUse hooks before
+// delegating to the inner tool.
+type hookedTool struct {
+	inner  fantasy.AgentTool
+	runner *hooks.Runner
+}
+
+func newHookedTool(inner fantasy.AgentTool, runner *hooks.Runner) *hookedTool {
+	return &hookedTool{inner: inner, runner: runner}
+}
+
+// wrapToolsWithHooks returns a tool slice with each entry wrapped in a
+// hookedTool. Returns the original slice unchanged when runner is nil or
+// when isSubAgent is true — sub-agents never fire hooks, the top-level
+// invocation of the sub-agent tool itself is wrapped on the caller's side.
+func wrapToolsWithHooks(tools []fantasy.AgentTool, runner *hooks.Runner, isSubAgent bool) []fantasy.AgentTool {
+	if runner == nil || isSubAgent {
+		return tools
+	}
+	out := make([]fantasy.AgentTool, len(tools))
+	for i, tool := range tools {
+		out[i] = newHookedTool(tool, runner)
+	}
+	return out
+}
+
+func (h *hookedTool) Info() fantasy.ToolInfo {
+	return h.inner.Info()
+}
+
+func (h *hookedTool) ProviderOptions() fantasy.ProviderOptions {
+	return h.inner.ProviderOptions()
+}
+
+func (h *hookedTool) SetProviderOptions(opts fantasy.ProviderOptions) {
+	h.inner.SetProviderOptions(opts)
+}
+
+func (h *hookedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+	sessionID := tools.GetSessionFromContext(ctx)
+	result, err := h.runner.Run(ctx, hooks.EventPreToolUse, sessionID, call.Name, call.Input)
+	if err != nil {
+		slog.Warn("Hook execution error, proceeding with tool call",
+			"tool", call.Name, "error", err)
+	}
+
+	if result.Decision == hooks.DecisionDeny || result.Halt {
+		reason := fmt.Sprintf("Tool call blocked by hook. Reason: %s", result.Reason)
+		if result.Halt {
+			reason = fmt.Sprintf("Turn halted by hook. Reason: %s", result.Reason)
+		}
+		resp := fantasy.NewTextErrorResponse(reason)
+		// Halt ends the whole turn; a plain deny only blocks this tool
+		// call so the model can see the error and try something else.
+		resp.StopTurn = result.Halt
+		resp.Metadata = hookMetadataJSON(result)
+		return resp, nil
+	}
+
+	if result.UpdatedInput != "" {
+		call.Input = result.UpdatedInput
+	}
+
+	// An explicit allow from a hook pre-approves the permission prompt for
+	// this tool call. Deny is already handled above; silence falls through
+	// to the normal permission flow.
+	if result.Decision == hooks.DecisionAllow {
+		ctx = permission.WithHookApproval(ctx, call.ID)
+	}
+
+	resp, err := h.inner.Run(ctx, call)
+	if err != nil {
+		return resp, err
+	}
+
+	if result.Context != "" {
+		if resp.Content != "" {
+			resp.Content += "\n"
+		}
+		resp.Content += result.Context
+	}
+
+	resp.Metadata = mergeHookMetadata(resp.Metadata, result)
+	return resp, nil
+}
+
+// buildHookMetadata creates a HookMetadata from an AggregateResult.
+func buildHookMetadata(result hooks.AggregateResult) hooks.HookMetadata {
+	return hooks.HookMetadata{
+		HookCount:    result.HookCount,
+		Decision:     result.Decision.String(),
+		Halt:         result.Halt,
+		Reason:       result.Reason,
+		InputRewrite: result.UpdatedInput != "",
+		Hooks:        result.Hooks,
+	}
+}
+
+// hookMetadataJSON builds a JSON string containing only the hook metadata.
+func hookMetadataJSON(result hooks.AggregateResult) string {
+	meta := buildHookMetadata(result)
+	data, err := json.Marshal(meta)
+	if err != nil {
+		return ""
+	}
+	return `{"hook":` + string(data) + `}`
+}
+
+// mergeHookMetadata injects hook metadata into existing tool metadata.
+func mergeHookMetadata(existing string, result hooks.AggregateResult) string {
+	if result.HookCount == 0 {
+		return existing
+	}
+	meta := buildHookMetadata(result)
+	data, err := json.Marshal(meta)
+	if err != nil {
+		return existing
+	}
+	if existing == "" {
+		existing = "{}"
+	}
+	merged, err := sjson.SetRaw(existing, "hook", string(data))
+	if err != nil {
+		return existing
+	}
+	return merged
+}

internal/agent/hooked_tool_test.go

@@ -0,0 +1,147 @@
+package agent
+
+import (
+	"context"
+	"testing"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/hooks"
+	"github.com/charmbracelet/crush/internal/permission"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeTool records the context it was invoked with so tests can assert on
+// values stamped onto it by the hookedTool decorator.
+type fakeTool struct {
+	name   string
+	called bool
+	gotCtx context.Context
+	resp   fantasy.ToolResponse
+}
+
+func (f *fakeTool) Info() fantasy.ToolInfo {
+	return fantasy.ToolInfo{Name: f.name}
+}
+
+func (f *fakeTool) Run(ctx context.Context, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+	f.called = true
+	f.gotCtx = ctx
+	return f.resp, nil
+}
+
+func (f *fakeTool) ProviderOptions() fantasy.ProviderOptions     { return nil }
+func (f *fakeTool) SetProviderOptions(_ fantasy.ProviderOptions) {}
+
+// newRunner builds a hooks.Runner from a single HookConfig, running the
+// config-loader path that compiles the matcher regex.
+func newRunner(t *testing.T, cmd string) *hooks.Runner {
+	t.Helper()
+	cfg := &config.Config{
+		Hooks: map[string][]config.HookConfig{
+			hooks.EventPreToolUse: {{Command: cmd}},
+		},
+	}
+	require.NoError(t, cfg.ValidateHooks())
+	return hooks.NewRunner(cfg.Hooks[hooks.EventPreToolUse], t.TempDir(), t.TempDir())
+}
+
+func TestHookedTool_AllowStampsHookApproval(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeTool{name: "view", resp: fantasy.NewTextResponse("ok")}
+	runner := newRunner(t, `echo '{"decision":"allow"}'`)
+	tool := newHookedTool(inner, runner)
+
+	_, err := tool.Run(t.Context(), fantasy.ToolCall{ID: "call-1", Name: "view"})
+	require.NoError(t, err)
+	require.True(t, inner.called, "inner tool should have run")
+
+	// The inner tool's permission service can now treat call-1 as pre-approved.
+	svc := permission.NewPermissionService(t.TempDir(), false, nil)
+	granted, err := svc.Request(inner.gotCtx, permission.CreatePermissionRequest{
+		SessionID:  "s1",
+		ToolCallID: "call-1",
+		ToolName:   "view",
+		Action:     "read",
+		Path:       t.TempDir(),
+	})
+	require.NoError(t, err)
+	require.True(t, granted, "hook allow should bypass the permission prompt")
+}
+
+func TestHookedTool_SilentDoesNotStampApproval(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeTool{name: "view", resp: fantasy.NewTextResponse("ok")}
+	runner := newRunner(t, `exit 0`) // no stdout, no decision
+	tool := newHookedTool(inner, runner)
+
+	_, err := tool.Run(t.Context(), fantasy.ToolCall{ID: "call-2", Name: "view"})
+	require.NoError(t, err)
+	require.True(t, inner.called)
+
+	// With no hook opinion, a fresh permission request has nothing stamped
+	// and must fall through to the normal flow. We verify by checking that
+	// the context does not look pre-approved for this call ID: sending a
+	// request that no subscriber resolves will block until cancelled.
+	svc := permission.NewPermissionService(t.TempDir(), false, nil)
+	ctx, cancel := context.WithCancel(inner.gotCtx)
+	cancel()
+	granted, err := svc.Request(ctx, permission.CreatePermissionRequest{
+		SessionID:  "s1",
+		ToolCallID: "call-2",
+		ToolName:   "view",
+		Action:     "read",
+		Path:       t.TempDir(),
+	})
+	require.Error(t, err, "no approval stamped => request should reach the prompt path")
+	require.False(t, granted)
+}
+
+func TestHookedTool_DenySkipsInnerTool(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeTool{name: "bash"}
+	runner := newRunner(t, `echo "blocked" >&2; exit 2`)
+	tool := newHookedTool(inner, runner)
+
+	resp, err := tool.Run(t.Context(), fantasy.ToolCall{ID: "call-3", Name: "bash"})
+	require.NoError(t, err)
+	require.False(t, inner.called, "denied call must not reach the inner tool")
+	require.True(t, resp.IsError)
+	require.Contains(t, resp.Content, "blocked")
+}
+
+func TestWrapToolsWithHooks(t *testing.T) {
+	t.Parallel()
+
+	runner := newRunner(t, `exit 0`)
+	inputs := []fantasy.AgentTool{&fakeTool{name: "a"}, &fakeTool{name: "b"}}
+
+	t.Run("top-level agent wraps every tool", func(t *testing.T) {
+		t.Parallel()
+		out := wrapToolsWithHooks(inputs, runner, false)
+		require.Len(t, out, len(inputs))
+		for i, tool := range out {
+			_, ok := tool.(*hookedTool)
+			require.Truef(t, ok, "tool %d should be a *hookedTool", i)
+		}
+	})
+
+	t.Run("sub-agent skips the wrap", func(t *testing.T) {
+		t.Parallel()
+		out := wrapToolsWithHooks(inputs, runner, true)
+		require.Equal(t, inputs, out, "sub-agent tools should be returned unwrapped")
+		for _, tool := range out {
+			_, isHooked := tool.(*hookedTool)
+			require.False(t, isHooked, "sub-agent tool should not be wrapped")
+		}
+	})
+
+	t.Run("nil runner skips the wrap for both agent kinds", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, inputs, wrapToolsWithHooks(inputs, nil, false))
+		require.Equal(t, inputs, wrapToolsWithHooks(inputs, nil, true))
+	})
+}

internal/agent/loop_detection.go

@@ -0,0 +1,92 @@
+package agent
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+
+	"charm.land/fantasy"
+)
+
+const (
+	loopDetectionWindowSize = 10
+	loopDetectionMaxRepeats = 5
+)
+
+// hasRepeatedToolCalls checks whether the agent is stuck in a loop by looking
+// at recent steps. It examines the last windowSize steps and returns true if
+// any tool-call signature appears more than maxRepeats times.
+func hasRepeatedToolCalls(steps []fantasy.StepResult, windowSize, maxRepeats int) bool {
+	if len(steps) < windowSize {
+		return false
+	}
+
+	window := steps[len(steps)-windowSize:]
+	counts := make(map[string]int)
+
+	for _, step := range window {
+		sig := getToolInteractionSignature(step.Content)
+		if sig == "" {
+			continue
+		}
+		counts[sig]++
+		if counts[sig] > maxRepeats {
+			return true
+		}
+	}
+
+	return false
+}
+
+// getToolInteractionSignature computes a hash signature for the tool
+// interactions in a single step's content. It pairs tool calls with their
+// results (matched by ToolCallID) and returns a hex-encoded SHA-256 hash.
+// If the step contains no tool calls, it returns "".
+func getToolInteractionSignature(content fantasy.ResponseContent) string {
+	toolCalls := content.ToolCalls()
+	if len(toolCalls) == 0 {
+		return ""
+	}
+
+	// Index tool results by their ToolCallID for fast lookup.
+	resultsByID := make(map[string]fantasy.ToolResultContent)
+	for _, tr := range content.ToolResults() {
+		resultsByID[tr.ToolCallID] = tr
+	}
+
+	h := sha256.New()
+	for _, tc := range toolCalls {
+		output := ""
+		if tr, ok := resultsByID[tc.ToolCallID]; ok {
+			output = toolResultOutputString(tr.Result)
+		}
+		io.WriteString(h, tc.ToolName)
+		io.WriteString(h, "\x00")
+		io.WriteString(h, tc.Input)
+		io.WriteString(h, "\x00")
+		io.WriteString(h, output)
+		io.WriteString(h, "\x00")
+	}
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+// toolResultOutputString converts a ToolResultOutputContent to a stable string
+// representation for signature comparison.
+func toolResultOutputString(result fantasy.ToolResultOutputContent) string {
+	if result == nil {
+		return ""
+	}
+	if text, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentText](result); ok {
+		return text.Text
+	}
+	if errResult, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentError](result); ok {
+		if errResult.Error != nil {
+			return errResult.Error.Error()
+		}
+		return ""
+	}
+	if media, ok := fantasy.AsToolResultOutputType[fantasy.ToolResultOutputContentMedia](result); ok {
+		return media.Data
+	}
+	return ""
+}

internal/agent/loop_detection_test.go

@@ -0,0 +1,205 @@
+package agent
+
+import (
+	"fmt"
+	"testing"
+
+	"charm.land/fantasy"
+)
+
+// makeStep creates a StepResult with the given tool calls and results in its Content.
+func makeStep(calls []fantasy.ToolCallContent, results []fantasy.ToolResultContent) fantasy.StepResult {
+	var content fantasy.ResponseContent
+	for _, c := range calls {
+		content = append(content, c)
+	}
+	for _, r := range results {
+		content = append(content, r)
+	}
+	return fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: content,
+		},
+	}
+}
+
+// makeToolStep creates a step with a single tool call and matching text result.
+func makeToolStep(name, input, output string) fantasy.StepResult {
+	callID := fmt.Sprintf("call_%s_%s", name, input)
+	return makeStep(
+		[]fantasy.ToolCallContent{
+			{ToolCallID: callID, ToolName: name, Input: input},
+		},
+		[]fantasy.ToolResultContent{
+			{ToolCallID: callID, ToolName: name, Result: fantasy.ToolResultOutputContentText{Text: output}},
+		},
+	)
+}
+
+// makeEmptyStep creates a step with no tool calls (e.g. a text-only response).
+func makeEmptyStep() fantasy.StepResult {
+	return fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.TextContent{Text: "thinking..."},
+			},
+		},
+	}
+}
+
+func TestHasRepeatedToolCalls(t *testing.T) {
+	t.Run("no steps", func(t *testing.T) {
+		result := hasRepeatedToolCalls(nil, 10, 5)
+		if result {
+			t.Error("expected false for empty steps")
+		}
+	})
+
+	t.Run("fewer steps than window", func(t *testing.T) {
+		steps := make([]fantasy.StepResult, 5)
+		for i := range steps {
+			steps[i] = makeToolStep("read", `{"file":"a.go"}`, "content")
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if result {
+			t.Error("expected false when fewer steps than window size")
+		}
+	})
+
+	t.Run("all different signatures", func(t *testing.T) {
+		steps := make([]fantasy.StepResult, 10)
+		for i := range steps {
+			steps[i] = makeToolStep("tool", fmt.Sprintf(`{"i":%d}`, i), fmt.Sprintf("result-%d", i))
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if result {
+			t.Error("expected false when all signatures are different")
+		}
+	})
+
+	t.Run("exact repeat at threshold not detected", func(t *testing.T) {
+		// maxRepeats=5 means > 5 is needed, so exactly 5 should return false
+		steps := make([]fantasy.StepResult, 10)
+		for i := range 5 {
+			steps[i] = makeToolStep("read", `{"file":"a.go"}`, "content")
+		}
+		for i := 5; i < 10; i++ {
+			steps[i] = makeToolStep("tool", fmt.Sprintf(`{"i":%d}`, i), fmt.Sprintf("result-%d", i))
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if result {
+			t.Error("expected false when count equals maxRepeats (threshold is >)")
+		}
+	})
+
+	t.Run("loop detected", func(t *testing.T) {
+		// 6 identical steps in a window of 10 with maxRepeats=5 → detected
+		steps := make([]fantasy.StepResult, 10)
+		for i := range 6 {
+			steps[i] = makeToolStep("read", `{"file":"a.go"}`, "content")
+		}
+		for i := 6; i < 10; i++ {
+			steps[i] = makeToolStep("tool", fmt.Sprintf(`{"i":%d}`, i), fmt.Sprintf("result-%d", i))
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if !result {
+			t.Error("expected true when same signature appears more than maxRepeats times")
+		}
+	})
+
+	t.Run("steps without tool calls are skipped", func(t *testing.T) {
+		// Mix of tool steps and empty steps — empty ones should not affect counts
+		steps := make([]fantasy.StepResult, 10)
+		for i := range 4 {
+			steps[i] = makeToolStep("read", `{"file":"a.go"}`, "content")
+		}
+		for i := 4; i < 8; i++ {
+			steps[i] = makeEmptyStep()
+		}
+		for i := 8; i < 10; i++ {
+			steps[i] = makeToolStep("write", `{"file":"b.go"}`, "ok")
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if result {
+			t.Error("expected false: only 4 repeated tool calls, empty steps should be skipped")
+		}
+	})
+
+	t.Run("multiple different patterns alternating", func(t *testing.T) {
+		// Two patterns alternating: each appears 5 times — not above threshold
+		steps := make([]fantasy.StepResult, 10)
+		for i := range steps {
+			if i%2 == 0 {
+				steps[i] = makeToolStep("read", `{"file":"a.go"}`, "content-a")
+			} else {
+				steps[i] = makeToolStep("write", `{"file":"b.go"}`, "content-b")
+			}
+		}
+		result := hasRepeatedToolCalls(steps, 10, 5)
+		if result {
+			t.Error("expected false: two patterns each appearing 5 times (not > 5)")
+		}
+	})
+}
+
+func TestGetToolInteractionSignature(t *testing.T) {
+	t.Run("empty content returns empty string", func(t *testing.T) {
+		sig := getToolInteractionSignature(fantasy.ResponseContent{})
+		if sig != "" {
+			t.Errorf("expected empty string, got %q", sig)
+		}
+	})
+
+	t.Run("text only content returns empty string", func(t *testing.T) {
+		content := fantasy.ResponseContent{
+			fantasy.TextContent{Text: "hello"},
+		}
+		sig := getToolInteractionSignature(content)
+		if sig != "" {
+			t.Errorf("expected empty string, got %q", sig)
+		}
+	})
+
+	t.Run("tool call with result produces signature", func(t *testing.T) {
+		content := fantasy.ResponseContent{
+			fantasy.ToolCallContent{ToolCallID: "1", ToolName: "read", Input: `{"file":"a.go"}`},
+			fantasy.ToolResultContent{ToolCallID: "1", ToolName: "read", Result: fantasy.ToolResultOutputContentText{Text: "content"}},
+		}
+		sig := getToolInteractionSignature(content)
+		if sig == "" {
+			t.Error("expected non-empty signature")
+		}
+	})
+
+	t.Run("same interactions produce same signature", func(t *testing.T) {
+		content1 := fantasy.ResponseContent{
+			fantasy.ToolCallContent{ToolCallID: "1", ToolName: "read", Input: `{"file":"a.go"}`},
+			fantasy.ToolResultContent{ToolCallID: "1", ToolName: "read", Result: fantasy.ToolResultOutputContentText{Text: "content"}},
+		}
+		content2 := fantasy.ResponseContent{
+			fantasy.ToolCallContent{ToolCallID: "2", ToolName: "read", Input: `{"file":"a.go"}`},
+			fantasy.ToolResultContent{ToolCallID: "2", ToolName: "read", Result: fantasy.ToolResultOutputContentText{Text: "content"}},
+		}
+		sig1 := getToolInteractionSignature(content1)
+		sig2 := getToolInteractionSignature(content2)
+		if sig1 != sig2 {
+			t.Errorf("expected same signature for same interactions, got %q and %q", sig1, sig2)
+		}
+	})
+
+	t.Run("different inputs produce different signatures", func(t *testing.T) {
+		content1 := fantasy.ResponseContent{
+			fantasy.ToolCallContent{ToolCallID: "1", ToolName: "read", Input: `{"file":"a.go"}`},
+			fantasy.ToolResultContent{ToolCallID: "1", ToolName: "read", Result: fantasy.ToolResultOutputContentText{Text: "content"}},
+		}
+		content2 := fantasy.ResponseContent{
+			fantasy.ToolCallContent{ToolCallID: "1", ToolName: "read", Input: `{"file":"b.go"}`},
+			fantasy.ToolResultContent{ToolCallID: "1", ToolName: "read", Result: fantasy.ToolResultOutputContentText{Text: "content"}},
+		}
+		sig1 := getToolInteractionSignature(content1)
+		sig2 := getToolInteractionSignature(content2)
+		if sig1 == sig2 {
+			t.Error("expected different signatures for different inputs")
+		}
+	})
+}

internal/agent/opencode_routing_test.go

@@ -0,0 +1,110 @@
+package agent
+
+import (
+	"testing"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIsOpenCodeMessagesModel(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		provider string
+		model    string
+		expected bool
+	}{
+		{"opencode-zen", "qwen3.7-max", true},
+		{"opencode-zen", "qwen3.5-plus", true},
+		{"opencode-zen", "qwen3.6-plus", true},
+		{"opencode-zen", "qwen3.7-plus", true},
+		{"opencode-zen", "claude-opus-4-5", true},
+		{"opencode-zen", "claude-sonnet-5", true},
+		{"opencode-zen", "muse-spark-1.3-contributor-free", false},
+		{"opencode-zen", "gpt-5.6-luna", false},
+		{"opencode-zen", "grok-4.5", false},
+		{"opencode-zen", "minimax-m3", false},
+		{"opencode-zen", "kimi-k3", false},
+		{"opencode-zen", "big-pickle", false},
+		{"opencode-go", "minimax-m2.7", true},
+		{"opencode-go", "minimax-m3", true},
+		{"opencode-go", "qwen3.7-max", true},
+		{"opencode-go", "qwen3.7-plus", true},
+		{"opencode-go", "qwen3.6-plus", true},
+		{"opencode-go", "qwen3.8-flash", true},
+		{"opencode-go", "qwen3.8-max", true},
+		{"opencode-go", "muse-spark-1.3-contributor", false},
+		{"opencode-go", "gpt-5.6-luna", false},
+		{"opencode-go", "glm-5.3", false},
+		{"opencode-go", "kimi-k3", false},
+		{"opencode-go", "longcat-2.0", false},
+		{"opencode-go", "ox-alpha-free", false},
+		{"opencode-go", "minimax", false},
+		{"other", "claude-opus-4-5", false},
+		{"other", "qwen3.7-max", false},
+	}
+	for _, tt := range tests {
+		require.Equal(t, tt.expected, isOpenCodeMessagesModel(tt.provider, tt.model), "%s/%s", tt.provider, tt.model)
+	}
+}
+
+func TestIsOpenCodeResponsesModel(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		model    string
+		expected bool
+	}{
+		{"muse-spark-1.3-contributor-free", true},
+		{"muse-spark-1.2", true},
+		{"grok-4.5", true},
+		{"grok-4.6", true},
+		{"grok-build-0.1", true},
+		{"gpt-5.6-luna", true},
+		{"gpt-5.5", true},
+		{"gpt-5.3-codex", true},
+		{"minimax-m3", false},
+		{"qwen3.7-max", false},
+		{"kimi-k3", false},
+		{"glm-5.3", false},
+		{"big-pickle", false},
+		{"ox-alpha-free", false},
+		{"hy3", false},
+		{"longcat-2.0", false},
+	}
+	for _, tt := range tests {
+		require.Equal(t, tt.expected, isOpenCodeResponsesModel(tt.model), tt.model)
+	}
+}
+
+func TestBuildProviderOpenCodeRouting(t *testing.T) {
+	t.Parallel()
+
+	for _, providerID := range []string{
+		string(catwalk.InferenceProviderOpenCodeZen),
+		string(catwalk.InferenceProviderOpenCodeGo),
+	} {
+		t.Run(providerID, func(t *testing.T) {
+			t.Parallel()
+			env := testEnv(t)
+			providerCfg := config.ProviderConfig{
+				ID:      providerID,
+				BaseURL: "https://opencode.ai/zen/v1",
+				Type:    catwalk.TypeOpenAICompat,
+				APIKey:  "$OPENCODE_API_KEY",
+			}
+			coord := newTestCoordinator(t, env, providerID, providerCfg)
+
+			for _, modelID := range []string{"kimi-k3", "muse-spark-1.3-contributor-free", "grok-4.6", "gpt-5.6-luna"} {
+				provider, err := coord.buildProvider(providerCfg, config.SelectedModel{
+					Model:    modelID,
+					Provider: providerID,
+				}, false)
+				require.NoError(t, err, modelID)
+				require.NotNil(t, provider, modelID)
+			}
+		})
+	}
+}

internal/agent/prism_model_test.go

@@ -0,0 +1,101 @@
+package agent
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent/hyper"
+	"github.com/charmbracelet/crush/internal/message"
+
+	"charm.land/fantasy/providers/openai"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExtractPrismModel(t *testing.T) {
+	t.Parallel()
+
+	prismMetadata := func(header http.Header) fantasy.ProviderMetadata {
+		metadata := &openai.ProviderMetadata{}
+		hyper.HeaderFunc(header, metadata)
+		return fantasy.ProviderMetadata{openai.Name: metadata}
+	}
+
+	t.Run("returns the routed model ID and name", func(t *testing.T) {
+		t.Parallel()
+		header := http.Header{}
+		header.Set(hyper.PrismModelIDHeader, "prism-42")
+		header.Set(hyper.PrismModelNameHeader, "GPT-5.2 Codex Max")
+		modelID, modelName := extractPrismModel(prismMetadata(header))
+		require.Equal(t, "prism-42", modelID)
+		require.Equal(t, "GPT-5.2 Codex Max", modelName)
+	})
+
+	t.Run("returns empty when not routed through Prism", func(t *testing.T) {
+		t.Parallel()
+		modelID, modelName := extractPrismModel(fantasy.ProviderMetadata{})
+		require.Empty(t, modelID)
+		require.Empty(t, modelName)
+
+		metadata := &openai.ProviderMetadata{
+			ExtraFields: map[string]json.RawMessage{"remaining": json.RawMessage(`{"hypercredits": 10}`)},
+		}
+		modelID, modelName = extractPrismModel(fantasy.ProviderMetadata{openai.Name: metadata})
+		require.Empty(t, modelID)
+		require.Empty(t, modelName)
+	})
+
+	t.Run("persisted on the assistant message", func(t *testing.T) {
+		t.Parallel()
+		header := http.Header{}
+		header.Set(hyper.PrismModelIDHeader, "prism-42")
+		header.Set(hyper.PrismModelNameHeader, "GPT-5.2 Codex Max")
+
+		msg := message.Message{}
+		msg.PrismModelID, msg.PrismModelName = extractPrismModel(prismMetadata(header))
+		require.Equal(t, "prism-42", msg.PrismModelID)
+		require.Equal(t, "GPT-5.2 Codex Max", msg.PrismModelName)
+	})
+}
+
+func TestExtractPrismSavings(t *testing.T) {
+	t.Parallel()
+
+	prismMetadata := func(header http.Header) fantasy.ProviderMetadata {
+		metadata := &openai.ProviderMetadata{}
+		hyper.HeaderFunc(header, metadata)
+		return fantasy.ProviderMetadata{openai.Name: metadata}
+	}
+
+	t.Run("returns both savings figures when reported", func(t *testing.T) {
+		t.Parallel()
+		header := http.Header{}
+		header.Set(hyper.PrismHypercreditSavingsHeader, "1.5")
+		header.Set(hyper.PrismDollarSavingsHeader, "0.002")
+		hypercredits, dollars := extractPrismSavings(prismMetadata(header))
+		require.NotNil(t, hypercredits)
+		require.Equal(t, 1.5, *hypercredits)
+		require.NotNil(t, dollars)
+		require.Equal(t, 0.002, *dollars)
+	})
+
+	t.Run("returns nil when not reported", func(t *testing.T) {
+		t.Parallel()
+		hypercredits, dollars := extractPrismSavings(fantasy.ProviderMetadata{})
+		require.Nil(t, hypercredits)
+		require.Nil(t, dollars)
+	})
+
+	t.Run("returns nil when malformed", func(t *testing.T) {
+		t.Parallel()
+		metadata := &openai.ProviderMetadata{
+			ExtraFields: map[string]json.RawMessage{
+				hyper.PrismHypercreditSavingsField: json.RawMessage(`"not-a-number"`),
+			},
+		}
+		hypercredits, dollars := extractPrismSavings(fantasy.ProviderMetadata{openai.Name: metadata})
+		require.Nil(t, hypercredits)
+		require.Nil(t, dollars)
+	})
+}

internal/agent/prompts.go

@@ -0,0 +1,42 @@
+package agent
+
+import (
+	"context"
+	_ "embed"
+
+	"github.com/charmbracelet/crush/internal/agent/prompt"
+	"github.com/charmbracelet/crush/internal/config"
+)
+
+//go:embed templates/coder.md.tpl
+var coderPromptTmpl []byte
+
+//go:embed templates/task.md.tpl
+var taskPromptTmpl []byte
+
+//go:embed templates/initialize.md.tpl
+var initializePromptTmpl []byte
+
+func coderPrompt(opts ...prompt.Option) (*prompt.Prompt, error) {
+	systemPrompt, err := prompt.NewPrompt("coder", string(coderPromptTmpl), opts...)
+	if err != nil {
+		return nil, err
+	}
+	return systemPrompt, nil
+}
+
+func taskPrompt(opts ...prompt.Option) (*prompt.Prompt, error) {
+	systemPrompt, err := prompt.NewPrompt("task", string(taskPromptTmpl), opts...)
+	if err != nil {
+		return nil, err
+	}
+	return systemPrompt, nil
+}
+
+func InitializePrompt(cfg *config.ConfigStore) (string, error) {
+	systemPrompt, err := prompt.NewPrompt("initialize", string(initializePromptTmpl))
+	if err != nil {
+		return "", err
+	}
+	return systemPrompt.Build(context.Background(), "", "", cfg)
+}

internal/agent/queued_runid_test.go

@@ -0,0 +1,181 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/stretchr/testify/require"
+)
+
+// gatedStreamModel streams a single text part followed by a clean finish,
+// but blocks the very first Stream call until its gate is released. That
+// lets a test hold a run "active" (past PrepareStep, inside Stream) just
+// long enough to enqueue a follow-up prompt behind the busy session.
+// Subsequent Stream calls (e.g. the recursive run draining the queue)
+// proceed immediately.
+type gatedStreamModel struct {
+	text    string
+	gate    chan struct{}
+	entered chan struct{}
+	calls   atomic.Int64
+}
+
+func (m *gatedStreamModel) Provider() string { return "fake" }
+func (m *gatedStreamModel) Model() string    { return "fake-model" }
+
+func (m *gatedStreamModel) Generate(ctx context.Context, call fantasy.Call) (*fantasy.Response, error) {
+	return &fantasy.Response{
+		Content:      fantasy.ResponseContent{fantasy.TextContent{Text: m.text}},
+		FinishReason: fantasy.FinishReasonStop,
+	}, nil
+}
+
+func (m *gatedStreamModel) Stream(ctx context.Context, call fantasy.Call) (fantasy.StreamResponse, error) {
+	if m.calls.Add(1) == 1 {
+		close(m.entered)
+		select {
+		case <-m.gate:
+		case <-ctx.Done():
+		}
+	}
+	text := m.text
+	return func(yield func(fantasy.StreamPart) bool) {
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextStart, ID: "1"}) {
+			return
+		}
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextDelta, ID: "1", Delta: text}) {
+			return
+		}
+		if !yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeTextEnd, ID: "1"}) {
+			return
+		}
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeFinish, FinishReason: fantasy.FinishReasonStop})
+	}, nil
+}
+
+func (m *gatedStreamModel) GenerateObject(ctx context.Context, call fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (m *gatedStreamModel) StreamObject(ctx context.Context, call fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, errors.New("not implemented")
+}
+
+// TestRun_QueuedRunIDPromptRunsRecursivelyAndPublishesRunComplete is the
+// end-to-end proof of fix 2: a prompt carrying a RunID that is queued
+// behind a busy session must NOT be silently folded into the active turn.
+// It runs as its own turn via the recursive run path and publishes its
+// own terminal RunComplete, so a `crush run` caller blocking on that
+// RunID does not hang. The active turn keeps its own RunComplete too.
+func TestRun_QueuedRunIDPromptRunsRecursivelyAndPublishesRunComplete(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	broker := pubsub.NewBroker[notify.RunComplete]()
+	t.Cleanup(broker.Shutdown)
+
+	large := &gatedStreamModel{
+		text:    "done",
+		gate:    make(chan struct{}),
+		entered: make(chan struct{}),
+	}
+	small := &finishStreamModel{text: "title"}
+
+	sa := NewSessionAgent(SessionAgentOptions{
+		LargeModel:  Model{Model: large, CatwalkCfg: catwalk.Model{ContextWindow: 200000, DefaultMaxTokens: 10000}},
+		SmallModel:  Model{Model: small, CatwalkCfg: catwalk.Model{ContextWindow: 200000, DefaultMaxTokens: 10000}},
+		IsYolo:      true,
+		Sessions:    env.sessions,
+		Messages:    env.messages,
+		RunComplete: broker,
+	}).(*sessionAgent)
+
+	sess, err := env.sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	subCtx, subCancel := context.WithCancel(t.Context())
+	defer subCancel()
+	ch := broker.Subscribe(subCtx)
+
+	// Start the main turn; it blocks inside Stream once active.
+	mainDone := make(chan error, 1)
+	go func() {
+		_, runErr := sa.Run(t.Context(), SessionAgentCall{
+			SessionID: sess.ID,
+			RunID:     "run-main",
+			Prompt:    "main",
+		})
+		mainDone <- runErr
+	}()
+
+	// Wait until the main turn is active (inside Stream).
+	select {
+	case <-large.entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("main run never entered Stream")
+	}
+	require.True(t, sa.IsSessionBusy(sess.ID), "main run must be active before enqueueing the follow-up")
+
+	// Enqueue a RunID-bearing follow-up behind the busy session.
+	res, err := sa.Run(t.Context(), SessionAgentCall{
+		SessionID: sess.ID,
+		RunID:     "run-follow",
+		Prompt:    "follow",
+	})
+	require.NoError(t, err)
+	require.Nil(t, res, "a busy-session follow-up must enqueue and return (nil, nil)")
+	require.Equal(t, 1, sa.QueuedPrompts(sess.ID), "the follow-up must be queued, not folded")
+
+	// Release the main turn so it completes and hands off to the queue.
+	close(large.gate)
+	require.NoError(t, <-mainDone)
+
+	// Both turns must publish their own terminal RunComplete.
+	got := map[string]notify.RunComplete{}
+	deadline := time.After(5 * time.Second)
+	for len(got) < 2 {
+		select {
+		case ev := <-ch:
+			got[ev.Payload.RunID] = ev.Payload
+		case <-deadline:
+			t.Fatalf("timed out waiting for both RunCompletes; got %v", got)
+		}
+	}
+
+	main, ok := got["run-main"]
+	require.True(t, ok, "the active turn must publish its own RunComplete")
+	require.Empty(t, main.Error)
+	require.False(t, main.Cancelled)
+
+	follow, ok := got["run-follow"]
+	require.True(t, ok,
+		"the queued RunID prompt must publish its own RunComplete instead of being folded silently")
+	require.Empty(t, follow.Error)
+	require.False(t, follow.Cancelled)
+	require.Equal(t, "done", follow.Text, "the queued prompt ran as its own turn")
+
+	// Two distinct assistant turns prove the follow-up was not folded.
+	msgs, err := env.messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	var assistants, follows int
+	for _, m := range msgs {
+		switch m.Role {
+		case message.Assistant:
+			assistants++
+		case message.User:
+			if m.Content().String() == "follow" {
+				follows++
+			}
+		}
+	}
+	require.Equal(t, 2, assistants, "the active turn and the recursive turn each produce one assistant message")
+	require.Equal(t, 1, follows, "the follow-up prompt is its own user turn")
+}

internal/agent/request_timeout.go

@@ -0,0 +1,123 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"charm.land/fantasy"
+)
+
+// requestTimeoutError reports that an LLM request exhausted its configured
+// request_timeout budget. For streaming requests this is an idle timeout:
+// it only fires when the provider sends nothing for the whole window, so a
+// slow but actively streaming response is never killed. It wraps the
+// underlying error so callers can still match [context.DeadlineExceeded]
+// through the chain.
+type requestTimeoutError struct {
+	timeout time.Duration
+	idle    bool
+	cause   error
+}
+
+func (e *requestTimeoutError) Error() string {
+	msg := fmt.Sprintf("LLM request timed out after %s", e.timeout)
+	if e.idle {
+		msg = fmt.Sprintf("LLM stream received no data for %s", e.timeout)
+	}
+	if e.cause != nil {
+		return fmt.Sprintf("%s: %v", msg, e.cause)
+	}
+	return msg
+}
+
+func (e *requestTimeoutError) Unwrap() error { return e.cause }
+
+// userMessage explains the timeout in the UI, including how long the request
+// ran before giving up and how to change the limit.
+func (e *requestTimeoutError) userMessage() string {
+	hint := "Increase the limit with \"option request-timeout SECONDS\" or set it to 0 to disable the timeout."
+	if e.idle {
+		return fmt.Sprintf("The model stopped sending data for %s. %s", e.timeout, hint)
+	}
+	return fmt.Sprintf("The model did not respond within %s. %s", e.timeout, hint)
+}
+
+// requestTimeoutModel wraps a [fantasy.LanguageModel] so requests are
+// bounded by the configured request_timeout. Non-streaming calls get a hard
+// per-request deadline, applied per call so fantasy's retry loop gives every
+// attempt a fresh budget — the same per-request semantics the provider SDKs
+// expose. Streams instead get an idle timeout: the budget resets whenever a
+// part arrives and only fires when the provider goes silent, so a slow but
+// actively streaming response is never aborted.
+type requestTimeoutModel struct {
+	fantasy.LanguageModel
+	timeout time.Duration
+}
+
+// newRequestTimeoutModel bounds each request to m with the given timeout. A
+// timeout of zero or less, or a nil model, returns m unchanged.
+func newRequestTimeoutModel(m fantasy.LanguageModel, timeout time.Duration) fantasy.LanguageModel {
+	if m == nil || timeout <= 0 {
+		return m
+	}
+	return requestTimeoutModel{LanguageModel: m, timeout: timeout}
+}
+
+// wrapTimedOut replaces err with the requestTimeoutError when this model's
+// own deadline fired. Other errors — user cancellation, outer deadlines,
+// provider failures — pass through unchanged. Cancellation errors caused by
+// our own timer report as [context.DeadlineExceeded] so callers never
+// mistake a timeout for a user cancellation.
+func wrapTimedOut(ctx context.Context, timeoutErr *requestTimeoutError, err error) error {
+	if err == nil || context.Cause(ctx) != timeoutErr {
+		return err
+	}
+	if errors.Is(err, context.Canceled) {
+		timeoutErr.cause = context.DeadlineExceeded
+	} else {
+		timeoutErr.cause = err
+	}
+	return timeoutErr
+}
+
+// Generate implements [fantasy.LanguageModel]. The request gets a hard
+// deadline: there is no incremental progress signal, so the whole call must
+// finish within the budget.
+func (m requestTimeoutModel) Generate(ctx context.Context, call fantasy.Call) (*fantasy.Response, error) {
+	timeoutErr := &requestTimeoutError{timeout: m.timeout}
+	ctx, cancel := context.WithTimeoutCause(ctx, m.timeout, timeoutErr)
+	defer cancel()
+	resp, err := m.LanguageModel.Generate(ctx, call)
+	return resp, wrapTimedOut(ctx, timeoutErr, err)
+}
+
+// Stream implements [fantasy.LanguageModel].
+//
+// The stream is consumed after Stream returns, so the timer must outlive
+// this call: it fires only after timeout seconds without any part arriving,
+// and is released when iteration ends, whether the stream finishes, breaks,
+// or the idle timeout aborts it. Both the initial connection and gaps
+// between parts share the same budget.
+func (m requestTimeoutModel) Stream(ctx context.Context, call fantasy.Call) (fantasy.StreamResponse, error) {
+	timeoutErr := &requestTimeoutError{timeout: m.timeout, idle: true}
+	ctx, cancel := context.WithCancelCause(ctx)
+	timer := time.AfterFunc(m.timeout, func() { cancel(timeoutErr) })
+
+	inner, err := m.LanguageModel.Stream(ctx, call)
+	if err != nil {
+		timer.Stop()
+		cancel(nil)
+		return nil, wrapTimedOut(ctx, timeoutErr, err)
+	}
+	return func(yield func(fantasy.StreamPart) bool) {
+		defer timer.Stop()
+		defer cancel(nil)
+		inner(func(part fantasy.StreamPart) bool {
+			timer.Reset(m.timeout)
+			part.Error = wrapTimedOut(ctx, timeoutErr, part.Error)
+			return yield(part)
+		})
+	}, nil
+}

internal/agent/request_timeout_test.go

@@ -0,0 +1,286 @@
+package agent
+
+import (
+	"context"
+	"runtime"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"charm.land/x/vcr"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeLanguageModel is a [fantasy.LanguageModel] stub that records the
+// context its methods were called with and can be configured with a custom
+// stream body.
+type fakeLanguageModel struct {
+	generateCtx context.Context
+	streamCtx   context.Context
+	stream      func(yield func(fantasy.StreamPart) bool)
+}
+
+func (f *fakeLanguageModel) Generate(ctx context.Context, _ fantasy.Call) (*fantasy.Response, error) {
+	f.generateCtx = ctx
+	return &fantasy.Response{}, nil
+}
+
+func (f *fakeLanguageModel) Stream(ctx context.Context, _ fantasy.Call) (fantasy.StreamResponse, error) {
+	f.streamCtx = ctx
+	if f.stream == nil {
+		return func(yield func(fantasy.StreamPart) bool) {
+			yield(fantasy.StreamPart{})
+		}, nil
+	}
+	return f.stream, nil
+}
+
+func (f *fakeLanguageModel) GenerateObject(context.Context, fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return &fantasy.ObjectResponse{}, nil
+}
+
+func (f *fakeLanguageModel) StreamObject(context.Context, fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, nil
+}
+
+func (f *fakeLanguageModel) Provider() string { return "fake" }
+func (f *fakeLanguageModel) Model() string    { return "fake-model" }
+
+func TestNewRequestTimeoutModel_Disabled(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	require.Same(t, inner, newRequestTimeoutModel(inner, 0))
+	require.Same(t, inner, newRequestTimeoutModel(inner, -time.Second))
+}
+
+func TestRequestTimeoutModel_GenerateDeadline(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	m := newRequestTimeoutModel(inner, 5*time.Minute)
+
+	_, err := m.Generate(t.Context(), fantasy.Call{})
+	require.NoError(t, err)
+
+	_, ok := inner.generateCtx.Deadline()
+	require.True(t, ok, "Generate should run under a deadline")
+}
+
+func TestRequestTimeoutModel_StreamDeadlineOutlivesCall(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	m := newRequestTimeoutModel(inner, 5*time.Minute)
+
+	stream, err := m.Stream(t.Context(), fantasy.Call{})
+	require.NoError(t, err)
+
+	require.NoError(t, inner.streamCtx.Err(), "the idle timer must not fire while the stream is being consumed")
+
+	for range stream {
+	}
+
+	require.ErrorIs(t, inner.streamCtx.Err(), context.Canceled, "the stream context should be released after the stream ends")
+}
+
+func TestRequestTimeoutModel_StreamAbortsWhenIdle(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	// A stream that outlives the idle window: it waits for the context to
+	// be done and reports what it observed.
+	streamObserved := make(chan error, 1)
+	inner.stream = func(yield func(fantasy.StreamPart) bool) {
+		<-inner.streamCtx.Done()
+		streamObserved <- inner.streamCtx.Err()
+	}
+	m := newRequestTimeoutModel(inner, 10*time.Millisecond)
+	stream, err := m.Stream(t.Context(), fantasy.Call{})
+	require.NoError(t, err)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for range stream {
+		}
+	}()
+
+	select {
+	case err := <-streamObserved:
+		require.ErrorIs(t, err, context.Canceled)
+	case <-time.After(5 * time.Second):
+		t.Fatal("stream was not aborted by the idle timeout")
+	}
+	<-done
+}
+
+func TestRequestTimeoutModel_ActiveStreamSurvives(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	// A stream that keeps sending data: total runtime exceeds the timeout,
+	// but every gap is shorter than the idle window, so it must finish.
+	inner.stream = func(yield func(fantasy.StreamPart) bool) {
+		for range 6 {
+			time.Sleep(10 * time.Millisecond)
+			if !yield(fantasy.StreamPart{}) {
+				return
+			}
+		}
+	}
+	m := newRequestTimeoutModel(inner, 25*time.Millisecond)
+	stream, err := m.Stream(t.Context(), fantasy.Call{})
+	require.NoError(t, err)
+
+	parts := 0
+	for part := range stream {
+		require.NoError(t, part.Error)
+		parts++
+	}
+	require.Equal(t, 6, parts)
+}
+
+// blockingModel blocks until the context is done and then returns the
+// context error, the way a hung provider request would.
+type blockingModel struct {
+	fakeLanguageModel
+}
+
+func (b *blockingModel) Generate(ctx context.Context, _ fantasy.Call) (*fantasy.Response, error) {
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+
+func TestRequestTimeoutModel_GenerateReportsTimeout(t *testing.T) {
+	t.Parallel()
+
+	m := newRequestTimeoutModel(&blockingModel{}, 10*time.Millisecond)
+
+	_, err := m.Generate(t.Context(), fantasy.Call{})
+	require.Error(t, err)
+
+	var timeoutErr *requestTimeoutError
+	require.ErrorAs(t, err, &timeoutErr)
+	require.Equal(t, 10*time.Millisecond, timeoutErr.timeout)
+	require.ErrorIs(t, err, context.DeadlineExceeded, "the deadline must stay detectable through the chain")
+	require.Contains(t, err.Error(), "timed out after 10ms")
+}
+
+func TestRequestTimeoutModel_StreamReportsTimeout(t *testing.T) {
+	t.Parallel()
+
+	inner := &fakeLanguageModel{}
+	// A provider stream that fails with the context error once the deadline
+	// fires, mirroring how SDKs surface mid-stream aborts.
+	inner.stream = func(yield func(fantasy.StreamPart) bool) {
+		<-inner.streamCtx.Done()
+		yield(fantasy.StreamPart{Error: inner.streamCtx.Err()})
+	}
+	m := newRequestTimeoutModel(inner, 10*time.Millisecond)
+	stream, err := m.Stream(t.Context(), fantasy.Call{})
+	require.NoError(t, err)
+
+	var got error
+	for part := range stream {
+		if part.Error != nil {
+			got = part.Error
+		}
+	}
+
+	var timeoutErr *requestTimeoutError
+	require.ErrorAs(t, got, &timeoutErr)
+	require.ErrorIs(t, got, context.DeadlineExceeded)
+}
+
+func TestRequestTimeoutModel_ParentCancelPassesThrough(t *testing.T) {
+	t.Parallel()
+
+	m := newRequestTimeoutModel(&blockingModel{}, 5*time.Minute)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		cancel()
+	}()
+
+	_, err := m.Generate(ctx, fantasy.Call{})
+	require.ErrorIs(t, err, context.Canceled)
+
+	var timeoutErr *requestTimeoutError
+	require.NotErrorAs(t, err, &timeoutErr, "user cancellation must not be reported as a timeout")
+}
+
+func TestRequestTimeoutErrorMessages(t *testing.T) {
+	t.Parallel()
+
+	err := &requestTimeoutError{timeout: time.Second}
+	require.Equal(t, "LLM request timed out after 1s", err.Error())
+	require.Contains(t, err.userMessage(), "1s")
+	require.Contains(t, err.userMessage(), "request-timeout")
+
+	err.cause = context.DeadlineExceeded
+	require.Equal(t, "LLM request timed out after 1s: context deadline exceeded", err.Error())
+
+	idle := &requestTimeoutError{timeout: 2 * time.Second, idle: true}
+	require.Equal(t, "LLM stream received no data for 2s", idle.Error())
+	require.Contains(t, idle.userMessage(), "stopped sending data for 2s")
+	require.Contains(t, idle.userMessage(), "request-timeout")
+}
+
+// timeoutOnlyModel streams a single error part shaped exactly like the one
+// requestTimeoutModel produces when its deadline fires.
+type timeoutOnlyModel struct {
+	fakeLanguageModel
+}
+
+func (m *timeoutOnlyModel) Stream(context.Context, fantasy.Call) (fantasy.StreamResponse, error) {
+	timeoutErr := &requestTimeoutError{timeout: time.Second, idle: true, cause: context.DeadlineExceeded}
+	return func(yield func(fantasy.StreamPart) bool) {
+		yield(fantasy.StreamPart{Type: fantasy.StreamPartTypeError, Error: timeoutErr})
+	}, nil
+}
+
+// TestRequestTimeoutRunFinishMessage pins what the user sees when a request
+// exhausts its timeout: a "Request timed out" finish that names the elapsed
+// budget and how to change it, instead of a bare provider error.
+func TestRequestTimeoutRunFinishMessage(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping on windows for now")
+	}
+
+	env := testEnv(t)
+	model := &timeoutOnlyModel{}
+	agent, err := coderAgent(vcr.NewRecorder(t), env, model, model)
+	require.NoError(t, err)
+
+	session, err := env.sessions.Create(t.Context(), "timeout session")
+	require.NoError(t, err)
+
+	_, err = agent.Run(t.Context(), SessionAgentCall{
+		Prompt:          "Hello",
+		SessionID:       session.ID,
+		MaxOutputTokens: 10000,
+	})
+	require.Error(t, err)
+
+	msgs, err := env.messages.List(t.Context(), session.ID)
+	require.NoError(t, err)
+
+	var finish *message.Finish
+	for _, msg := range msgs {
+		if msg.Role != message.Assistant {
+			continue
+		}
+		if part := msg.FinishPart(); part != nil {
+			finish = part
+		}
+	}
+	require.NotNil(t, finish, "the assistant message should carry a finish part")
+	require.Equal(t, message.FinishReasonError, finish.Reason)
+	require.Equal(t, "Request timed out", finish.Message)
+	require.Contains(t, finish.Details, "stopped sending data for 1s")
+	require.Contains(t, finish.Details, "request-timeout")
+}

internal/agent/run_complete_test.go

@@ -0,0 +1,322 @@
+package agent
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSessionAgentRun_QueueStripsOnComplete verifies that when a Run
+// call is enqueued (because the session is already busy), the
+// OnComplete hook is NOT propagated onto the queued copy. The hook
+// belongs to the caller's retry/coalesce scope (typically
+// coordinator.Run) which has already returned by the time the queue
+// drains; carrying it forward would silently funnel the terminal
+// event into a closure nobody reads, and subscribers (`crush run`)
+// would hang waiting for a RunComplete that never publishes.
+func TestSessionAgentRun_QueueStripsOnComplete(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+
+	const sessionID = "queued-session"
+	// Mark the session as busy so Run takes the queue branch
+	// without needing a real model.
+	a.activeRequests.Set(sessionID, &activeCancel{cancel: func() {}})
+
+	var called bool
+	hook := func(notify.RunComplete) { called = true }
+
+	res, err := a.Run(t.Context(), SessionAgentCall{
+		SessionID:  sessionID,
+		RunID:      "run-xyz",
+		Prompt:     "queued prompt",
+		OnComplete: hook,
+	})
+	require.NoError(t, err)
+	require.Nil(t, res, "queued Run must return (nil, nil)")
+	require.False(t, called,
+		"OnComplete must not fire on the enqueue path; the caller's scope is still live")
+
+	queued, ok := a.messageQueue.Get(sessionID)
+	require.True(t, ok)
+	require.Len(t, queued, 1)
+	require.Nil(t, queued[0].OnComplete,
+		"queued SessionAgentCall must have OnComplete stripped so the drain falls back to the default broker publish")
+	require.Equal(t, "queued prompt", queued[0].Prompt,
+		"all other fields must be preserved on the queued copy")
+	require.Equal(t, "run-xyz", queued[0].RunID,
+		"RunID must be preserved on the queued copy so the drained turn's "+
+			"RunComplete still correlates with the originating SendMessage")
+}
+
+// TestDrainQueueForStep_FiltersUnderDispatchLock verifies that the queue
+// drain evaluates the per-session cancel mark while holding the dispatch
+// mutex (canceledBySeq's documented precondition). Queued calls at or
+// below the cancel high-water mark are dropped, calls queued after the
+// cancel (higher seq) are folded, untracked enqueues (seq == 0) are
+// dropped whenever any mark is present, and the queue is cleared. These
+// calls carry no RunID, so all foldable survivors are returned for
+// folding (the existing follow-up behavior).
+func TestDrainQueueForStep_FiltersUnderDispatchLock(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+
+	const sessionID = "drain-session"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, Prompt: "below", acceptSeq: 1},
+		{SessionID: sessionID, Prompt: "at-mark", acceptSeq: 2},
+		{SessionID: sessionID, Prompt: "after", acceptSeq: 3},
+		{SessionID: sessionID, Prompt: "untracked", acceptSeq: 0},
+	})
+	// Cancel high-water mark at seq 2: seq <= 2 and seq == 0 are covered.
+	a.cancelMark.Set(sessionID, 2)
+
+	fold, canceledWithRunID := a.drainQueueForStep(sessionID)
+
+	require.Len(t, fold, 1,
+		"only the follow-up queued after the cancel (seq > mark) must be folded")
+	require.Equal(t, "after", fold[0].Prompt)
+	require.Empty(t, canceledWithRunID,
+		"no dropped call carried a RunID, so none need a terminal RunComplete")
+
+	_, ok := a.messageQueue.Get(sessionID)
+	require.False(t, ok, "drain must clear the session message queue when nothing is kept")
+}
+
+// TestDrainQueueForStep_NoMarkFoldsAllNonRunID verifies that with no
+// cancel mark recorded, every queued call without a RunID is folded.
+func TestDrainQueueForStep_NoMarkFoldsAllNonRunID(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+
+	const sessionID = "drain-nomark"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, Prompt: "a", acceptSeq: 0},
+		{SessionID: sessionID, Prompt: "b", acceptSeq: 5},
+	})
+
+	fold, canceledWithRunID := a.drainQueueForStep(sessionID)
+	require.Len(t, fold, 2, "no cancel mark means all non-RunID queued calls are folded")
+	require.Empty(t, canceledWithRunID)
+}
+
+// TestDrainQueueForStep_KeepsRunIDPromptsQueued is the core of fix 2: a
+// queued prompt that carries a RunID must NOT be folded into the active
+// turn. Folding it would silently absorb it into another turn and never
+// publish a RunComplete for its RunID, hanging a `crush run` caller that
+// blocks on that event. Such prompts are left in the queue so the
+// recursive run path gives each its own turn and its own RunComplete.
+// Non-RunID prompts are still folded.
+func TestDrainQueueForStep_KeepsRunIDPromptsQueued(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+
+	const sessionID = "drain-runid"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, Prompt: "fold-me", acceptSeq: 1},
+		{SessionID: sessionID, RunID: "run-a", Prompt: "keep-me", acceptSeq: 2},
+		{SessionID: sessionID, RunID: "run-b", Prompt: "keep-me-too", acceptSeq: 3},
+	})
+
+	fold, canceledWithRunID := a.drainQueueForStep(sessionID)
+
+	require.Len(t, fold, 1, "only the non-RunID prompt is folded into the active turn")
+	require.Equal(t, "fold-me", fold[0].Prompt)
+	require.Empty(t, canceledWithRunID)
+
+	kept, ok := a.messageQueue.Get(sessionID)
+	require.True(t, ok, "RunID-bearing prompts must remain queued for the recursive run path")
+	require.Len(t, kept, 2)
+	require.Equal(t, "run-a", kept[0].RunID)
+	require.Equal(t, "run-b", kept[1].RunID)
+}
+
+// TestDrainQueueForStep_ReportsCanceledRunIDDrops verifies that a queued
+// prompt carrying a RunID that is dropped because a cancel covers it is
+// reported in canceledWithRunID so the caller can publish its terminal
+// cancelled RunComplete. A canceled prompt without a RunID is dropped
+// silently as before.
+func TestDrainQueueForStep_ReportsCanceledRunIDDrops(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions: env.sessions,
+		Messages: env.messages,
+	}).(*sessionAgent)
+
+	const sessionID = "drain-cancel-runid"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, RunID: "run-canceled", Prompt: "canceled", acceptSeq: 1},
+		{SessionID: sessionID, Prompt: "canceled-no-runid", acceptSeq: 1},
+		{SessionID: sessionID, RunID: "run-survives", Prompt: "survives", acceptSeq: 5},
+	})
+	a.cancelMark.Set(sessionID, 2)
+
+	fold, canceledWithRunID := a.drainQueueForStep(sessionID)
+
+	require.Empty(t, fold, "no uncanceled non-RunID prompts to fold")
+	require.Len(t, canceledWithRunID, 1,
+		"only the dropped RunID-bearing prompt needs a terminal RunComplete")
+	require.Equal(t, "run-canceled", canceledWithRunID[0].RunID)
+
+	kept, ok := a.messageQueue.Get(sessionID)
+	require.True(t, ok)
+	require.Len(t, kept, 1, "the uncanceled RunID prompt stays queued")
+	require.Equal(t, "run-survives", kept[0].RunID)
+}
+
+// TestRunCompletePublisher_MustDeliverOverTakesPublish exercises the
+// pubsub.Publisher interface change end-to-end: a Broker is the only
+// concrete Publisher implementation and must satisfy both Publish and
+// PublishMustDeliver. The coordinator's final RunComplete emit relies
+// on PublishMustDeliver to apply bounded-blocking semantics so a
+// momentarily-full subscriber buffer can't silently drop the
+// authoritative end-of-run event.
+func TestRunCompletePublisher_MustDeliverOverTakesPublish(t *testing.T) {
+	t.Parallel()
+
+	broker := pubsub.NewBroker[notify.RunComplete]()
+	t.Cleanup(broker.Shutdown)
+
+	// Subscribe before publishing so the event is delivered.
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	ch := broker.Subscribe(ctx)
+
+	rc := notify.RunComplete{SessionID: "S", MessageID: "m", Text: "ok"}
+	var pub pubsub.Publisher[notify.RunComplete] = broker
+	pub.PublishMustDeliver(t.Context(), pubsub.UpdatedEvent, rc)
+
+	select {
+	case got := <-ch:
+		require.Equal(t, rc, got.Payload)
+	case <-time.After(time.Second):
+		t.Fatal("PublishMustDeliver did not deliver event")
+	}
+}
+
+// requireSingleCancelledRunComplete reads exactly one RunComplete from ch,
+// asserts it is the cancelled terminal event for runID, and verifies no
+// second event arrives. This observes the published pubsub event rather
+// than internal bookkeeping, which is the contract a `crush run` caller
+// blocking on the broker actually relies on.
+func requireSingleCancelledRunComplete(t *testing.T, ch <-chan pubsub.Event[notify.RunComplete], sessionID, runID string) {
+	t.Helper()
+	select {
+	case ev := <-ch:
+		require.Equal(t, runID, ev.Payload.RunID,
+			"the published RunComplete must carry the dropped queued prompt's RunID")
+		require.Equal(t, sessionID, ev.Payload.SessionID)
+		require.True(t, ev.Payload.Cancelled,
+			"a dropped queued prompt must publish a cancelled RunComplete")
+	case <-time.After(5 * time.Second):
+		t.Fatal("timed out waiting for the cancelled RunComplete")
+	}
+	select {
+	case extra := <-ch:
+		t.Fatalf("expected exactly one RunComplete, got a second: %+v", extra.Payload)
+	case <-time.After(100 * time.Millisecond):
+	}
+}
+
+// TestCancel_QueuedRunIDPromptPublishesCancelledRunComplete proves the
+// terminal-event behavior end-to-end: a RunID-bearing prompt sitting in
+// the queue that is canceled while queued (via the public Cancel path,
+// which routes through clearQueueAndNotify -> publishCanceledQueueDrops)
+// must emit exactly one cancelled RunComplete on the broker for its
+// RunID. A queued prompt without a RunID is dropped silently. This is the
+// coverage the earlier drain test lacked: it asserted the returned
+// bookkeeping slice, not the published event a `crush run` caller awaits.
+func TestCancel_QueuedRunIDPromptPublishesCancelledRunComplete(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	broker := pubsub.NewBroker[notify.RunComplete]()
+	t.Cleanup(broker.Shutdown)
+
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions:    env.sessions,
+		Messages:    env.messages,
+		RunComplete: broker,
+	}).(*sessionAgent)
+
+	subCtx, subCancel := context.WithCancel(t.Context())
+	defer subCancel()
+	ch := broker.Subscribe(subCtx)
+
+	const sessionID = "cancel-queued-runid"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, Prompt: "no-runid", acceptSeq: 1},
+		{SessionID: sessionID, RunID: "run-queued", Prompt: "queued", acceptSeq: 2},
+	})
+
+	a.Cancel(sessionID)
+
+	requireSingleCancelledRunComplete(t, ch, sessionID, "run-queued")
+
+	_, ok := a.messageQueue.Get(sessionID)
+	require.False(t, ok, "Cancel must clear the queue")
+}
+
+// TestDrainQueueForStep_DroppedRunIDPublishesCancelledRunComplete drives
+// the production drain sequence (drainQueueForStep then
+// publishCanceledQueueDrops, mirroring the PrepareStep handoff) and
+// asserts the dropped RunID-bearing prompt actually publishes exactly one
+// cancelled RunComplete on the broker. The companion bookkeeping test
+// covers the returned slice; this one covers the observable terminal
+// event.
+func TestDrainQueueForStep_DroppedRunIDPublishesCancelledRunComplete(t *testing.T) {
+	t.Parallel()
+
+	env := testEnv(t)
+	broker := pubsub.NewBroker[notify.RunComplete]()
+	t.Cleanup(broker.Shutdown)
+
+	a := NewSessionAgent(SessionAgentOptions{
+		Sessions:    env.sessions,
+		Messages:    env.messages,
+		RunComplete: broker,
+	}).(*sessionAgent)
+
+	subCtx, subCancel := context.WithCancel(t.Context())
+	defer subCancel()
+	ch := broker.Subscribe(subCtx)
+
+	const sessionID = "drain-drop-runid"
+	a.messageQueue.Set(sessionID, []SessionAgentCall{
+		{SessionID: sessionID, RunID: "run-dropped", Prompt: "dropped", acceptSeq: 1},
+		{SessionID: sessionID, Prompt: "dropped-no-runid", acceptSeq: 1},
+	})
+	a.cancelMark.Set(sessionID, 2)
+
+	_, canceledWithRunID := a.drainQueueForStep(sessionID)
+	require.Len(t, canceledWithRunID, 1)
+	a.publishCanceledQueueDrops(canceledWithRunID)
+
+	requireSingleCancelledRunComplete(t, ch, sessionID, "run-dropped")
+}

internal/agent/run_marker.go

@@ -0,0 +1,52 @@
+package agent
+
+import (
+	"context"
+	"sync/atomic"
+)
+
+// runCompleteMarkerKey is the unexported context key carrying a
+// [runCompleteMarker] from the dispatch boundary (backend.runAgent)
+// down into the coordinator. It lets the dispatcher learn whether the
+// coordinator already published the authoritative terminal
+// notify.RunComplete for the run, so a fallback terminal event is only
+// emitted when one is actually missing (e.g. an error returned before
+// sessionAgent.Run ever executed). It avoids a breaking change to the
+// Coordinator interface.
+type runCompleteMarkerKey struct{}
+
+// runCompleteMarker records whether a terminal RunComplete has been
+// published for a run. It is shared by pointer through the context so
+// a publish deep in the call stack is observable by the dispatcher
+// after the call returns.
+type runCompleteMarker struct {
+	published atomic.Bool
+}
+
+// WithRunCompleteMarker returns ctx carrying a fresh marker the
+// coordinator can flag via [MarkRunCompletePublished] once it emits the
+// run's terminal RunComplete. Callers read the result with
+// [RunCompletePublished]. Attaching the marker is optional: code paths
+// without one simply skip the dedup signal.
+func WithRunCompleteMarker(ctx context.Context) context.Context {
+	return context.WithValue(ctx, runCompleteMarkerKey{}, &runCompleteMarker{})
+}
+
+// MarkRunCompletePublished records that the authoritative terminal
+// RunComplete has been published for the run carried by ctx. It is a
+// no-op when no marker is present (e.g. the in-process/local Run path,
+// which is not dispatched through backend.runAgent).
+func MarkRunCompletePublished(ctx context.Context) {
+	if m, ok := ctx.Value(runCompleteMarkerKey{}).(*runCompleteMarker); ok {
+		m.published.Store(true)
+	}
+}
+
+// RunCompletePublished reports whether [MarkRunCompletePublished] was
+// called on ctx's marker. It returns false when no marker is present.
+func RunCompletePublished(ctx context.Context) bool {
+	if m, ok := ctx.Value(runCompleteMarkerKey{}).(*runCompleteMarker); ok {
+		return m.published.Load()
+	}
+	return false
+}

internal/agent/runid.go

@@ -0,0 +1,33 @@
+package agent
+
+import "context"
+
+// runIDContextKey is the unexported context key used to carry a
+// caller-supplied RunID from the workspace HTTP boundary
+// (backend.SendMessage) down into coordinator.Run without forcing a
+// breaking change to the Coordinator.Run signature. The value is
+// then copied onto SessionAgentCall.RunID by the coordinator so the
+// agent's terminal RunComplete event can echo it back to the
+// originating caller.
+type runIDContextKey struct{}
+
+// WithRunID returns ctx tagged with a per-request RunID. It is the
+// boundary helper for callers that need their SendMessage→Run
+// terminal event to be uniquely correlatable (e.g. `crush run`
+// against a session that may be busy). Empty runIDs are stored
+// as-is; downstream code treats an empty RunID as "caller did not
+// supply one" and falls back to SessionID-only correlation.
+func WithRunID(ctx context.Context, runID string) context.Context {
+	return context.WithValue(ctx, runIDContextKey{}, runID)
+}
+
+// RunIDFromContext returns the RunID set by [WithRunID], or "" if
+// none was set or the value is not a string. Exported because the
+// coordinator and tests in other packages need to read it; safe to
+// call on any context.
+func RunIDFromContext(ctx context.Context) string {
+	if v, ok := ctx.Value(runIDContextKey{}).(string); ok {
+		return v
+	}
+	return ""
+}

internal/agent/usage_fallback.go

@@ -0,0 +1,176 @@
+package agent
+
+import (
+	"fmt"
+
+	"charm.land/fantasy"
+)
+
+func usageIsZero(usage fantasy.Usage) bool {
+	return usage.InputTokens == 0 &&
+		usage.OutputTokens == 0 &&
+		usage.TotalTokens == 0 &&
+		usage.ReasoningTokens == 0 &&
+		usage.CacheCreationTokens == 0 &&
+		usage.CacheReadTokens == 0
+}
+
+func fallbackStepUsage(messages []fantasy.Message, step fantasy.StepResult) (fantasy.Usage, bool) {
+	if !usageIsZero(step.Usage) {
+		return step.Usage, false
+	}
+
+	inputTokens := estimateMessageTokens(messages)
+	outputTokens := estimateStepCompletionTokens(step)
+	if inputTokens == 0 && outputTokens == 0 {
+		return fantasy.Usage{}, false
+	}
+
+	return fantasy.Usage{
+		InputTokens:  inputTokens,
+		OutputTokens: outputTokens,
+		TotalTokens:  inputTokens + outputTokens,
+	}, true
+}
+
+func cloneFantasyMessages(messages []fantasy.Message) []fantasy.Message {
+	cloned := make([]fantasy.Message, len(messages))
+	for i, msg := range messages {
+		cloned[i] = msg
+		cloned[i].Content = append([]fantasy.MessagePart(nil), msg.Content...)
+	}
+	return cloned
+}
+
+func estimateMessageTokens(messages []fantasy.Message) int64 {
+	var tokens int64
+	for _, msg := range messages {
+		tokens += approxTokenCount(string(msg.Role))
+		for _, part := range msg.Content {
+			tokens += estimateMessagePartTokens(part)
+		}
+	}
+	return tokens
+}
+
+func estimateStepCompletionTokens(step fantasy.StepResult) int64 {
+	var tokens int64
+	for _, content := range step.Content {
+		switch c := content.(type) {
+		case fantasy.TextContent:
+			tokens += approxTokenCount(c.Text)
+		case *fantasy.TextContent:
+			tokens += approxTokenCount(c.Text)
+		case fantasy.ReasoningContent:
+			tokens += approxTokenCount(c.Text)
+		case *fantasy.ReasoningContent:
+			tokens += approxTokenCount(c.Text)
+		case fantasy.FileContent:
+			tokens += estimateGeneratedFileTokens(c)
+		case *fantasy.FileContent:
+			tokens += estimateGeneratedFileTokens(*c)
+		case fantasy.SourceContent:
+			tokens += estimateSourceTokens(c)
+		case *fantasy.SourceContent:
+			tokens += estimateSourceTokens(*c)
+		case fantasy.ToolCallContent:
+			tokens += estimateToolCallTokens(c.ToolName, c.Input)
+		case *fantasy.ToolCallContent:
+			tokens += estimateToolCallTokens(c.ToolName, c.Input)
+		case fantasy.ToolResultContent:
+			if c.ProviderExecuted {
+				tokens += estimateToolResultContentTokens(c.ToolCallID, c.ToolName, c.ClientMetadata, c.Result)
+			}
+		case *fantasy.ToolResultContent:
+			if c.ProviderExecuted {
+				tokens += estimateToolResultContentTokens(c.ToolCallID, c.ToolName, c.ClientMetadata, c.Result)
+			}
+		}
+	}
+	return tokens
+}
+
+func estimateMessagePartTokens(part fantasy.MessagePart) int64 {
+	switch p := part.(type) {
+	case fantasy.TextPart:
+		return approxTokenCount(p.Text)
+	case *fantasy.TextPart:
+		return approxTokenCount(p.Text)
+	case fantasy.ReasoningPart:
+		return approxTokenCount(p.Text)
+	case *fantasy.ReasoningPart:
+		return approxTokenCount(p.Text)
+	case fantasy.FilePart:
+		return estimateFilePartTokens(p)
+	case *fantasy.FilePart:
+		return estimateFilePartTokens(*p)
+	case fantasy.ToolCallPart:
+		return estimateToolCallTokens(p.ToolName, p.Input)
+	case *fantasy.ToolCallPart:
+		return estimateToolCallTokens(p.ToolName, p.Input)
+	case fantasy.ToolResultPart:
+		return estimateToolResultContentTokens(p.ToolCallID, "", "", p.Output)
+	case *fantasy.ToolResultPart:
+		return estimateToolResultContentTokens(p.ToolCallID, "", "", p.Output)
+	default:
+		return 0
+	}
+}
+
+func estimateToolCallTokens(toolName, input string) int64 {
+	return approxTokenCount(toolName) + approxTokenCount(input)
+}
+
+func estimateToolResultContentTokens(toolCallID, toolName, metadata string, output fantasy.ToolResultOutputContent) int64 {
+	tokens := approxTokenCount(toolCallID) + approxTokenCount(toolName) + approxTokenCount(metadata)
+	switch result := output.(type) {
+	case fantasy.ToolResultOutputContentText:
+		tokens += approxTokenCount(result.Text)
+	case *fantasy.ToolResultOutputContentText:
+		tokens += approxTokenCount(result.Text)
+	case fantasy.ToolResultOutputContentError:
+		if result.Error != nil {
+			tokens += approxTokenCount(result.Error.Error())
+		}
+	case *fantasy.ToolResultOutputContentError:
+		if result.Error != nil {
+			tokens += approxTokenCount(result.Error.Error())
+		}
+	case fantasy.ToolResultOutputContentMedia:
+		tokens += estimateMediaTokens(result.MediaType, result.Text, len(result.Data))
+	case *fantasy.ToolResultOutputContentMedia:
+		tokens += estimateMediaTokens(result.MediaType, result.Text, len(result.Data))
+	}
+	return tokens
+}
+
+func estimateFilePartTokens(file fantasy.FilePart) int64 {
+	return estimateMediaTokens(file.MediaType, file.Filename, len(file.Data))
+}
+
+func estimateGeneratedFileTokens(file fantasy.FileContent) int64 {
+	return estimateMediaTokens(file.MediaType, "", len(file.Data))
+}
+
+func estimateMediaTokens(mediaType, text string, dataBytes int) int64 {
+	if dataBytes == 0 {
+		return approxTokenCount(mediaType) + approxTokenCount(text)
+	}
+	return approxTokenCount(fmt.Sprintf("%s %s %d bytes", mediaType, text, dataBytes))
+}
+
+func estimateSourceTokens(source fantasy.SourceContent) int64 {
+	return approxTokenCount(string(source.SourceType)) +
+		approxTokenCount(source.ID) +
+		approxTokenCount(source.URL) +
+		approxTokenCount(source.Title) +
+		approxTokenCount(source.MediaType) +
+		approxTokenCount(source.Filename)
+}
+
+func approxTokenCount(s string) int64 {
+	if s == "" {
+		return 0
+	}
+	return int64((len(s) + 3) / 4)
+}

internal/agent/usage_fallback_test.go

@@ -0,0 +1,339 @@
+package agent
+
+import (
+	"errors"
+	"testing"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUsageIsZero(t *testing.T) {
+	t.Parallel()
+
+	require.True(t, usageIsZero(fantasy.Usage{}))
+	require.False(t, usageIsZero(fantasy.Usage{InputTokens: 1}))
+	require.False(t, usageIsZero(fantasy.Usage{OutputTokens: 1}))
+	require.False(t, usageIsZero(fantasy.Usage{TotalTokens: 1}))
+	require.False(t, usageIsZero(fantasy.Usage{ReasoningTokens: 1}))
+	require.False(t, usageIsZero(fantasy.Usage{CacheCreationTokens: 1}))
+	require.False(t, usageIsZero(fantasy.Usage{CacheReadTokens: 1}))
+}
+
+func TestFallbackStepUsageKeepsProviderUsage(t *testing.T) {
+	t.Parallel()
+
+	usage := fantasy.Usage{
+		InputTokens:  10,
+		OutputTokens: 5,
+		TotalTokens:  15,
+	}
+	step := fantasy.StepResult{
+		Response: fantasy.Response{Usage: usage},
+	}
+
+	fallbackUsage, estimated := fallbackStepUsage(nil, step)
+	require.False(t, estimated)
+	require.Equal(t, usage, fallbackUsage)
+}
+
+func TestFallbackStepUsageEstimatesPromptAndAssistantText(t *testing.T) {
+	t.Parallel()
+
+	messages := []fantasy.Message{
+		fantasy.NewUserMessage("please explain the implementation details"),
+	}
+	step := fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.TextContent{Text: "the implementation stores state safely"},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(messages, step)
+	require.True(t, estimated)
+	require.Positive(t, usage.InputTokens)
+	require.Positive(t, usage.OutputTokens)
+	require.Equal(t, usage.InputTokens+usage.OutputTokens, usage.TotalTokens)
+}
+
+func TestFallbackStepUsageEstimatesReasoning(t *testing.T) {
+	t.Parallel()
+
+	messages := []fantasy.Message{
+		{
+			Role: fantasy.MessageRoleAssistant,
+			Content: []fantasy.MessagePart{
+				fantasy.ReasoningPart{Text: "first reason about the request"},
+			},
+		},
+	}
+	step := fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.ReasoningContent{Text: "second reason about the answer"},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(messages, step)
+	require.True(t, estimated)
+	require.Positive(t, usage.InputTokens)
+	require.Positive(t, usage.OutputTokens)
+}
+
+func TestFallbackStepUsageEstimatesToolCalls(t *testing.T) {
+	t.Parallel()
+
+	step := fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.ToolCallContent{
+					ToolCallID: "tool-call-1",
+					ToolName:   "view",
+					Input:      `{"file_path":"/tmp/example.go"}`,
+				},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(nil, step)
+	require.True(t, estimated)
+	require.Zero(t, usage.InputTokens)
+	require.Positive(t, usage.OutputTokens)
+	require.Equal(t, usage.OutputTokens, usage.TotalTokens)
+}
+
+func TestFallbackStepUsageEstimatesToolResults(t *testing.T) {
+	t.Parallel()
+
+	messages := []fantasy.Message{
+		{
+			Role: fantasy.MessageRoleTool,
+			Content: []fantasy.MessagePart{
+				fantasy.ToolResultPart{
+					ToolCallID: "tool-call-1",
+					Output: fantasy.ToolResultOutputContentText{
+						Text: "file contents returned by the tool",
+					},
+				},
+				fantasy.ToolResultPart{
+					ToolCallID: "tool-call-2",
+					Output: fantasy.ToolResultOutputContentError{
+						Error: errors.New("permission denied"),
+					},
+				},
+				fantasy.ToolResultPart{
+					ToolCallID: "tool-call-3",
+					Output: fantasy.ToolResultOutputContentMedia{
+						MediaType: "image/png",
+						Text:      "screenshot",
+						Data:      "abc123",
+					},
+				},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(messages, fantasy.StepResult{})
+	require.True(t, estimated)
+	require.Positive(t, usage.InputTokens)
+	require.Zero(t, usage.OutputTokens)
+	require.Equal(t, usage.InputTokens, usage.TotalTokens)
+}
+
+func TestFallbackStepUsageSkipsClientToolResultsAsOutput(t *testing.T) {
+	t.Parallel()
+
+	step := fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.ToolResultContent{
+					ToolCallID: "tool-call-1",
+					ToolName:   "bash",
+					Result: fantasy.ToolResultOutputContentText{
+						Text: "large client-executed payload that should not count as model output tokens",
+					},
+				},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(nil, step)
+	require.False(t, estimated)
+	require.Zero(t, usage.OutputTokens)
+}
+
+func TestFallbackStepUsageCountsProviderToolResultsAsOutput(t *testing.T) {
+	t.Parallel()
+
+	step := fantasy.StepResult{
+		Response: fantasy.Response{
+			Content: fantasy.ResponseContent{
+				fantasy.ToolResultContent{
+					ToolCallID:       "tool-call-1",
+					ToolName:         "web_search",
+					ProviderExecuted: true,
+					ClientMetadata:   "provider metadata",
+					Result:           fantasy.ToolResultOutputContentText{Text: "provider-executed result"},
+				},
+			},
+		},
+	}
+
+	usage, estimated := fallbackStepUsage(nil, step)
+	require.True(t, estimated)
+	require.Positive(t, usage.OutputTokens)
+	require.Equal(t, usage.OutputTokens, usage.TotalTokens)
+}
+
+func TestFallbackStepUsageReturnsZeroWithoutContent(t *testing.T) {
+	t.Parallel()
+
+	usage, estimated := fallbackStepUsage(nil, fantasy.StepResult{})
+	require.False(t, estimated)
+	require.True(t, usageIsZero(usage))
+}
+
+func TestUpdateSessionUsageSkipsEstimatedCost(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{ID: "session-id", Cost: 1.25}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+	usage := fantasy.Usage{InputTokens: 1000, OutputTokens: 2000}
+
+	agent.updateSessionUsage(model, currentSession, usage, nil, true)
+
+	require.Equal(t, 1.25, currentSession.Cost)
+	require.Equal(t, int64(1000), currentSession.PromptTokens)
+	require.Equal(t, int64(2000), currentSession.CompletionTokens)
+	require.True(t, currentSession.EstimatedUsage)
+}
+
+func TestUpdateSessionUsageKeepsCountersForZeroUsage(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{
+		ID:               "session-id",
+		PromptTokens:     123,
+		CompletionTokens: 456,
+		Cost:             1.25,
+	}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+
+	agent.updateSessionUsage(model, currentSession, fantasy.Usage{}, nil, false)
+
+	require.Equal(t, 1.25, currentSession.Cost)
+	require.Equal(t, int64(123), currentSession.PromptTokens)
+	require.Equal(t, int64(456), currentSession.CompletionTokens)
+}
+
+func TestUpdateSessionUsagePreservesOmittedCountersForPartialUsage(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{
+		ID:               "session-id",
+		PromptTokens:     123,
+		CompletionTokens: 456,
+	}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+	usage := fantasy.Usage{InputTokens: 789}
+
+	agent.updateSessionUsage(model, currentSession, usage, nil, false)
+
+	require.Equal(t, int64(789), currentSession.PromptTokens)
+	require.Equal(t, int64(456), currentSession.CompletionTokens)
+}
+
+func TestUpdateSessionUsagePreservesCountersForTotalOnlyUsage(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{
+		ID:               "session-id",
+		PromptTokens:     123,
+		CompletionTokens: 456,
+	}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+	usage := fantasy.Usage{TotalTokens: 100}
+
+	agent.updateSessionUsage(model, currentSession, usage, nil, false)
+
+	require.Equal(t, int64(123), currentSession.PromptTokens)
+	require.Equal(t, int64(456), currentSession.CompletionTokens)
+}
+
+func TestUpdateSessionUsagePreservesPromptForOutputOnlyUsage(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{
+		ID:               "session-id",
+		PromptTokens:     123,
+		CompletionTokens: 456,
+	}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+	usage := fantasy.Usage{OutputTokens: 50}
+
+	agent.updateSessionUsage(model, currentSession, usage, nil, false)
+
+	require.Equal(t, int64(123), currentSession.PromptTokens)
+	require.Equal(t, int64(50), currentSession.CompletionTokens)
+}
+
+func TestUpdateSessionUsageKeepsCountersForEstimatedZeroUsage(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{
+		ID:               "session-id",
+		PromptTokens:     123,
+		CompletionTokens: 456,
+		Cost:             1.25,
+	}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+
+	agent.updateSessionUsage(model, currentSession, fantasy.Usage{}, nil, true)
+
+	require.Equal(t, 1.25, currentSession.Cost)
+	require.Equal(t, int64(123), currentSession.PromptTokens)
+	require.Equal(t, int64(456), currentSession.CompletionTokens)
+}
+
+func TestSummaryCompletionTokens(t *testing.T) {
+	t.Parallel()
+
+	summaryMessage := message.Message{
+		Parts: []message.ContentPart{
+			message.TextContent{Text: "summary text"},
+			message.ReasoningContent{Thinking: "reasoning text"},
+		},
+	}
+
+	require.Equal(t, int64(42), summaryCompletionTokens(fantasy.Usage{OutputTokens: 42}, summaryMessage))
+	require.Equal(t, approxTokenCount("summary text")+approxTokenCount("reasoning text"), summaryCompletionTokens(fantasy.Usage{}, summaryMessage))
+	require.Zero(t, summaryCompletionTokens(fantasy.Usage{}, message.Message{}))
+}
+
+func TestUpdateSessionUsageAddsProviderCost(t *testing.T) {
+	t.Parallel()
+
+	agent := &sessionAgent{}
+	currentSession := &session.Session{ID: "session-id", Cost: 1.25}
+	model := Model{CatwalkCfg: catwalk.Model{CostPer1MIn: 10, CostPer1MOut: 20}}
+	usage := fantasy.Usage{InputTokens: 1000, OutputTokens: 2000}
+
+	agent.updateSessionUsage(model, currentSession, usage, nil, false)
+
+	require.Equal(t, 1.3, currentSession.Cost)
+	require.Equal(t, int64(1000), currentSession.PromptTokens)
+	require.Equal(t, int64(2000), currentSession.CompletionTokens)
+	require.False(t, currentSession.EstimatedUsage)
+}

internal/apigen/docs.html.tmpl

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{{.Info.Title}}</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 60em; margin: 2em auto; padding: 0 1em; color: #222; }
+h1 { margin-bottom: 0; }
+h2 { margin-top: 2em; border-bottom: 1px solid #ccc; padding-bottom: .2em; }
+.endpoint { margin: 1.5em 0; }
+.route { font-family: ui-monospace, monospace; font-size: 1.05em; }
+.method { display: inline-block; min-width: 4.5em; font-weight: bold; }
+table { border-collapse: collapse; margin: .5em 0; }
+th, td { text-align: left; padding: .2em 1em .2em 0; vertical-align: top; }
+pre { background: #f5f5f5; padding: .8em; overflow-x: auto; font-size: .85em; }
+.desc { color: #555; }
+h4 { margin: .8em 0 .2em; font-weight: 600; }
+</style>
+</head>
+<body>
+<h1>{{.Info.Title}}</h1>
+{{if .Info.Description}}<p class="desc">{{.Info.Description}}</p>{{end}}
+<p class="desc">Version {{.Info.Version}} &middot; Base path <code>{{.Base}}</code> &middot; <a href="openapi.json">openapi.json</a></p>
+{{range .Tags}}
+<h2>{{.Name}}</h2>
+{{range .Endpoints}}
+<div class="endpoint">
+<div class="route"><span class="method">{{.Method}}</span> {{.Path}}</div>
+<div>{{.Summary}}</div>
+{{if .Description}}<div class="desc">{{.Description}}</div>{{end}}
+<div class="desc">Success: {{.Status}}</div>
+{{if .Params}}
+<h4>Parameters</h4>
+<table>
+<tr><th>Name</th><th>In</th><th>Required</th><th>Description</th></tr>
+{{range .Params}}<tr><td><code>{{.Name}}</code></td><td>{{.In}}</td><td>{{if .Required}}yes{{else}}no{{end}}</td><td>{{.Description}}</td></tr>
+{{end}}</table>
+{{end}}
+{{if .Request}}<h4>Request body</h4><pre>{{.Request}}</pre>{{end}}
+{{if .SSE}}<h4>Response</h4><p>Streams <code>text/event-stream</code>.</p>{{end}}
+{{if .Response}}<h4>Response body</h4><pre>{{.Response}}</pre>{{end}}
+{{if .Errors}}<h4>Errors</h4><p>{{range $i, $c := .Errors}}{{if $i}}, {{end}}{{$c}}{{end}} &mdash; JSON error object</p>{{end}}
+</div>
+{{end}}
+{{end}}
+</body>
+</html>

internal/apigen/endpoint.go

@@ -0,0 +1,168 @@
+// Package apigen provides a fluent API for documenting HTTP endpoints.
+//
+// An [Endpoint] is the single source of truth for one route: the same
+// value drives mux registration and documentation generation, so the
+// two cannot drift. Endpoints are constructed with the method builders
+// ([Get], [Post], [Put], [Delete]) and finalized with
+// [endpointBuilder.Handle], the only way to produce an Endpoint. A
+// chain without Handle does not compile into a []Endpoint, so
+// incomplete definitions fail at build time.
+package apigen
+
+import "net/http"
+
+// Param documents a single path or query parameter.
+type Param struct {
+	// Name is the parameter name as it appears in the path or query.
+	Name string
+	// In is "path" or "query".
+	In string
+	// Type is the JSON schema type, e.g. "string", "integer".
+	Type string
+	// Description is a short human-readable description.
+	Description string
+	// Required reports whether the parameter must be provided. Path
+	// parameters are always required.
+	Required bool
+}
+
+// Endpoint is the documentation and routing record for a single HTTP
+// endpoint. Construct it with the fluent builders ([Get], [Post], ...);
+// only [endpointBuilder.Handle] produces a complete Endpoint.
+type Endpoint struct {
+	method      string
+	path        string
+	summary     string
+	description string
+	tags        []string
+	params      []Param
+	request     any
+	response    any
+	status      int
+	errors      []int
+	sse         bool
+	handler     http.HandlerFunc
+}
+
+// Method returns the HTTP method, e.g. "GET".
+func (e Endpoint) Method() string { return e.method }
+
+// Path returns the route pattern, e.g. "/v1/workspaces/{id}".
+func (e Endpoint) Path() string { return e.path }
+
+// Summary returns the one-line summary.
+func (e Endpoint) Summary() string { return e.summary }
+
+// Description returns the optional longer prose description.
+func (e Endpoint) Description() string { return e.description }
+
+// Tags returns the grouping tags.
+func (e Endpoint) Tags() []string { return e.tags }
+
+// Params returns the documented path and query parameters.
+func (e Endpoint) Params() []Param { return e.params }
+
+// Request returns the request body example value, or nil for none.
+func (e Endpoint) Request() any { return e.request }
+
+// Response returns the success response example value, or nil for an
+// empty success response.
+func (e Endpoint) Response() any { return e.response }
+
+// Status returns the success status code, defaulting to 200.
+func (e Endpoint) Status() int {
+	if e.status == 0 {
+		return http.StatusOK
+	}
+	return e.status
+}
+
+// Errors returns the status codes that return an error object.
+func (e Endpoint) Errors() []int { return e.errors }
+
+// SSE reports whether the endpoint streams text/event-stream instead
+// of producing a JSON response.
+func (e Endpoint) SSE() bool { return e.sse }
+
+// Handler returns the endpoint's HTTP handler.
+func (e Endpoint) Handler() http.HandlerFunc { return e.handler }
+
+// endpointBuilder accumulates endpoint documentation fluently. It is
+// deliberately a distinct type from [Endpoint]: a []Endpoint literal
+// cannot contain a builder, so a chain missing Handle fails to
+// compile.
+type endpointBuilder struct{ e Endpoint }
+
+// Get begins a GET endpoint for path, e.g. Get("/v1/workspaces/{id}").
+func Get(path string) endpointBuilder {
+	return endpointBuilder{Endpoint{method: http.MethodGet, path: path}}
+}
+
+// Post begins a POST endpoint for path.
+func Post(path string) endpointBuilder {
+	return endpointBuilder{Endpoint{method: http.MethodPost, path: path}}
+}
+
+// Put begins a PUT endpoint for path.
+func Put(path string) endpointBuilder {
+	return endpointBuilder{Endpoint{method: http.MethodPut, path: path}}
+}
+
+// Delete begins a DELETE endpoint for path.
+func Delete(path string) endpointBuilder {
+	return endpointBuilder{Endpoint{method: http.MethodDelete, path: path}}
+}
+
+// Summary sets the one-line summary.
+func (b endpointBuilder) Summary(s string) endpointBuilder { b.e.summary = s; return b }
+
+// Description sets an optional longer prose description.
+func (b endpointBuilder) Description(s string) endpointBuilder { b.e.description = s; return b }
+
+// Tags sets the grouping tags used on the docs page.
+func (b endpointBuilder) Tags(t ...string) endpointBuilder { b.e.tags = t; return b }
+
+// Accepts documents the request body with an example value, e.g.
+// Accepts(proto.Workspace{}). The value's type is used to derive the
+// JSON schema; the reference is compile-checked.
+func (b endpointBuilder) Accepts(v any) endpointBuilder { b.e.request = v; return b }
+
+// Responds documents the success response body with an example value.
+func (b endpointBuilder) Responds(v any) endpointBuilder { b.e.response = v; return b }
+
+// Status sets the success status code when it differs from 200, e.g.
+// 202 for an accepted-but-async operation.
+func (b endpointBuilder) Status(code int) endpointBuilder { b.e.status = code; return b }
+
+// Fails documents status codes that return an error object.
+func (b endpointBuilder) Fails(codes ...int) endpointBuilder { b.e.errors = codes; return b }
+
+// SSE marks the endpoint as streaming text/event-stream.
+func (b endpointBuilder) SSE() endpointBuilder { b.e.sse = true; return b }
+
+// PathParam documents a path parameter. Path parameters are always
+// required.
+func (b endpointBuilder) PathParam(name, desc string) endpointBuilder {
+	return b.param(Param{Name: name, In: "path", Type: "string", Description: desc, Required: true})
+}
+
+// QueryParam documents an optional query parameter.
+func (b endpointBuilder) QueryParam(name, desc string) endpointBuilder {
+	return b.param(Param{Name: name, In: "query", Type: "string", Description: desc})
+}
+
+// RequiredQueryParam documents a required query parameter.
+func (b endpointBuilder) RequiredQueryParam(name, desc string) endpointBuilder {
+	return b.param(Param{Name: name, In: "query", Type: "string", Description: desc, Required: true})
+}
+
+func (b endpointBuilder) param(p Param) endpointBuilder {
+	b.e.params = append(b.e.params, p)
+	return b
+}
+
+// Handle finalizes the endpoint with its HTTP handler.
+func (b endpointBuilder) Handle(h http.HandlerFunc) Endpoint {
+	b.e.handler = h
+	return b.e
+}

internal/apigen/endpoint_test.go

@@ -0,0 +1,207 @@
+package apigen
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+type nested struct {
+	Value string `json:"value"`
+}
+
+type sample struct {
+	ID         string            `json:"id"`
+	Count      int               `json:"count"`
+	Ratio      float64           `json:"ratio,omitempty"`
+	Active     bool              `json:"active,omitempty"`
+	Labels     []string          `json:"labels"`
+	Meta       map[string]string `json:"meta,omitempty"`
+	Nested     nested            `json:"nested"`
+	Ptr        *nested           `json:"ptr,omitempty"`
+	When       time.Time         `json:"when"`
+	Err        error             `json:"error,omitempty"`
+	Anything   any               `json:"anything,omitempty"`
+	Skipped    string            `json:"-"`
+	unexported string
+}
+
+func TestSchemaOfStruct(t *testing.T) {
+	t.Parallel()
+	s := SchemaOf(sample{})
+
+	require.Equal(t, "object", s.Type)
+	require.ElementsMatch(t, []string{"id", "count", "labels", "nested", "when"}, s.Required)
+
+	require.Equal(t, "string", s.Properties["id"].Type)
+	require.Equal(t, "integer", s.Properties["count"].Type)
+	require.Equal(t, "number", s.Properties["ratio"].Type)
+	require.Equal(t, "boolean", s.Properties["active"].Type)
+	require.Equal(t, "array", s.Properties["labels"].Type)
+	require.Equal(t, "string", s.Properties["labels"].Items.Type)
+	require.Equal(t, "object", s.Properties["meta"].Type)
+	require.Equal(t, "string", s.Properties["meta"].AdditionalProperties.Type)
+	require.Equal(t, "object", s.Properties["nested"].Type)
+	require.Equal(t, "string", s.Properties["nested"].Properties["value"].Type)
+	require.Equal(t, "object", s.Properties["ptr"].Type)
+	require.Equal(t, "string", s.Properties["when"].Type)
+	require.Equal(t, "date-time", s.Properties["when"].Format)
+	require.Equal(t, "string", s.Properties["error"].Type)
+	require.Equal(t, &Schema{}, s.Properties["anything"])
+
+	require.NotContains(t, s.Properties, "Skipped")
+	require.NotContains(t, s.Properties, "unexported")
+}
+
+type cyc struct {
+	Name  string `json:"name"`
+	Child *cyc   `json:"child,omitempty"`
+}
+
+func TestSchemaOfCycle(t *testing.T) {
+	t.Parallel()
+	s := SchemaOf(cyc{})
+	require.Equal(t, "object", s.Type)
+	require.Equal(t, "apigen.cyc", s.Properties["child"].Description)
+}
+
+type withTime struct {
+	At time.Time `json:"at"`
+}
+
+func TestSchemaOfSamePackageExpansion(t *testing.T) {
+	t.Parallel()
+	// Types from this package expand even when reached through another.
+	s := SchemaOf(withTime{})
+	require.Equal(t, "string", s.Properties["at"].Type)
+}
+
+type embeds struct {
+	nested
+	Extra string `json:"extra"`
+}
+
+func TestSchemaOfEmbedded(t *testing.T) {
+	t.Parallel()
+	s := SchemaOf(embeds{})
+	require.Contains(t, s.Properties, "value")
+	require.Contains(t, s.Properties, "extra")
+}
+
+func TestBuilderCompileContract(t *testing.T) {
+	t.Parallel()
+	called := false
+	h := func(http.ResponseWriter, *http.Request) { called = true }
+
+	e := Get("/v1/things/{id}").
+		Summary("Get thing").
+		Description("Longer prose.").
+		Tags("things").
+		PathParam("id", "Thing ID").
+		QueryParam("verbose", "Verbose output").
+		RequiredQueryParam("mode", "Mode").
+		Responds(sample{}).
+		Fails(404, 500).
+		Handle(h)
+
+	require.Equal(t, http.MethodGet, e.Method())
+	require.Equal(t, "/v1/things/{id}", e.Path())
+	require.Equal(t, "Get thing", e.Summary())
+	require.Equal(t, "Longer prose.", e.Description())
+	require.Equal(t, []string{"things"}, e.Tags())
+	require.Equal(t, []Param{
+		{Name: "id", In: "path", Type: "string", Description: "Thing ID", Required: true},
+		{Name: "verbose", In: "query", Type: "string", Description: "Verbose output"},
+		{Name: "mode", In: "query", Type: "string", Description: "Mode", Required: true},
+	}, e.Params())
+	require.Equal(t, sample{}, e.Response())
+	require.Nil(t, e.Request())
+	require.Equal(t, []int{404, 500}, e.Errors())
+	require.False(t, e.SSE())
+
+	e.Handler()(nil, nil)
+	require.True(t, called)
+}
+
+func TestBuilderVerbsAndSSE(t *testing.T) {
+	t.Parallel()
+	for method, build := range map[string]func(string) endpointBuilder{
+		http.MethodGet:    Get,
+		http.MethodPost:   Post,
+		http.MethodPut:    Put,
+		http.MethodDelete: Delete,
+	} {
+		e := build("/x").Handle(func(http.ResponseWriter, *http.Request) {})
+		require.Equal(t, method, e.Method())
+	}
+
+	e := Get("/events").SSE().Handle(func(http.ResponseWriter, *http.Request) {})
+	require.True(t, e.SSE())
+}
+
+func TestSpecJSON(t *testing.T) {
+	t.Parallel()
+	info := Info{Title: "Test API", Version: "1.0", Description: "Desc."}
+	endpoints := []Endpoint{
+		Post("/v1/things").
+			Summary("Create thing").
+			Accepts(sample{}).
+			Responds(sample{}).
+			Fails(400).
+			Handle(func(http.ResponseWriter, *http.Request) {}),
+		Get("/v1/things/{id}/events").
+			Summary("Stream").
+			PathParam("id", "Thing ID").
+			SSE().
+			Handle(func(http.ResponseWriter, *http.Request) {}),
+	}
+
+	data, err := SpecJSON(info, "/v1", endpoints)
+	require.NoError(t, err)
+	text := string(data)
+
+	require.Contains(t, text, `"openapi": "3.2.1"`)
+	require.Contains(t, text, `"/things"`)
+	require.Contains(t, text, `"/things/{id}/events"`)
+	require.Contains(t, text, `"text/event-stream"`)
+	require.Contains(t, text, `"application/json"`)
+	require.NotContains(t, text, "/v1/things\"") // base prefix stripped
+}
+
+func TestRenderDocs(t *testing.T) {
+	t.Parallel()
+	info := Info{Title: "Test API", Version: "1.0", Description: "Desc."}
+	endpoints := []Endpoint{
+		Get("/v1/things/{id}").
+			Summary("Get thing").
+			Tags("things").
+			PathParam("id", "Thing ID").
+			Responds(sample{}).
+			Fails(404).
+			Handle(func(http.ResponseWriter, *http.Request) {}),
+	}
+
+	var sb strings.Builder
+	require.NoError(t, RenderDocs(&sb, info, "/v1", endpoints))
+	html := sb.String()
+
+	require.Contains(t, html, "Test API")
+	require.Contains(t, html, "/v1/things/{id}")
+	require.Contains(t, html, "Get thing")
+	require.Contains(t, html, "Thing ID")
+	require.Contains(t, html, "count")
+	require.Contains(t, html, "openapi.json")
+}
+
+func TestErrorSchemaShape(t *testing.T) {
+	t.Parallel()
+	// The shared error schema must stay aligned with the error JSON
+	// handlers actually write: {"error": "..."}.
+	data, err := json.Marshal(errorSchema)
+	require.NoError(t, err)
+	require.Contains(t, string(data), `"error"`)
+}

internal/apigen/openapi.go

@@ -0,0 +1,147 @@
+package apigen
+
+import (
+	"encoding/json"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Info carries the top-level API metadata for the OpenAPI document.
+type Info struct {
+	Title       string
+	Version     string
+	Description string
+}
+
+// document is an OpenAPI 3.1 document rooted at the API's base path.
+type document struct {
+	OpenAPI string              `json:"openapi"`
+	Info    Info                `json:"info"`
+	Paths   map[string]pathItem `json:"paths"`
+}
+
+type pathItem map[string]operation
+
+type operation struct {
+	Summary     string                  `json:"summary"`
+	Description string                  `json:"description,omitempty"`
+	Tags        []string                `json:"tags,omitempty"`
+	Parameters  []parameter             `json:"parameters,omitempty"`
+	RequestBody *requestBody            `json:"requestBody,omitempty"`
+	Responses   map[string]specResponse `json:"responses"`
+}
+
+type parameter struct {
+	Name        string  `json:"name"`
+	In          string  `json:"in"`
+	Description string  `json:"description,omitempty"`
+	Required    bool    `json:"required"`
+	Schema      *Schema `json:"schema"`
+}
+
+type requestBody struct {
+	Required bool                 `json:"required"`
+	Content  map[string]mediaType `json:"content"`
+}
+
+type mediaType struct {
+	Schema *Schema `json:"schema"`
+}
+
+type specResponse struct {
+	Description string               `json:"description"`
+	Content     map[string]mediaType `json:"content,omitempty"`
+}
+
+var errorSchema = &Schema{
+	Type: "object",
+	Properties: map[string]*Schema{
+		"error": {Type: "string"},
+	},
+	Required: []string{"error"},
+}
+
+// SpecJSON renders the endpoints as an OpenAPI 3.1 JSON document. Base
+// is the API's base path (e.g. "/v1"); endpoint paths are relative to
+// it. The output is deterministic: map keys are sorted by
+// encoding/json.
+func SpecJSON(info Info, base string, endpoints []Endpoint) ([]byte, error) {
+	doc := document{
+		OpenAPI: "3.2.1",
+		Info:    info,
+		Paths:   map[string]pathItem{},
+	}
+	for _, e := range endpoints {
+		path := strings.TrimPrefix(e.path, base)
+		op := operation{
+			Summary:     e.summary,
+			Description: e.description,
+			Tags:        e.tags,
+			Responses:   map[string]specResponse{},
+		}
+		for _, p := range e.params {
+			op.Parameters = append(op.Parameters, parameter{
+				Name:        p.Name,
+				In:          p.In,
+				Description: p.Description,
+				Required:    p.Required,
+				Schema:      &Schema{Type: p.Type},
+			})
+		}
+		if e.request != nil {
+			op.RequestBody = &requestBody{
+				Required: true,
+				Content: map[string]mediaType{
+					"application/json": {Schema: SchemaOf(e.request)},
+				},
+			}
+		}
+		status := e.Status()
+		ok := specResponse{Description: http.StatusText(status)}
+		switch {
+		case e.sse:
+			ok.Content = map[string]mediaType{
+				"text/event-stream": {Schema: &Schema{Type: "string"}},
+			}
+		case e.response != nil:
+			ok.Content = map[string]mediaType{
+				"application/json": {Schema: SchemaOf(e.response)},
+			}
+		}
+		op.Responses[strconv.Itoa(status)] = ok
+		for _, code := range e.errors {
+			op.Responses[strconv.Itoa(code)] = specResponse{
+				Description: http.StatusText(code),
+				Content: map[string]mediaType{
+					"application/json": {Schema: errorSchema},
+				},
+			}
+		}
+
+		item := doc.Paths[path]
+		if item == nil {
+			item = pathItem{}
+			doc.Paths[path] = item
+		}
+		item[strings.ToLower(e.method)] = op
+	}
+	return json.MarshalIndent(doc, "", "  ")
+}
+
+// Tags returns the sorted set of tags across endpoints.
+func Tags(endpoints []Endpoint) []string {
+	seen := map[string]bool{}
+	var tags []string
+	for _, e := range endpoints {
+		for _, t := range e.tags {
+			if !seen[t] {
+				seen[t] = true
+				tags = append(tags, t)
+			}
+		}
+	}
+	sort.Strings(tags)
+	return tags
+}

internal/apigen/render.go

@@ -0,0 +1,94 @@
+package apigen
+
+import (
+	_ "embed"
+	"encoding/json"
+	"html/template"
+	"io"
+	"sort"
+)
+
+// RenderDocs writes a plain, self-contained HTML documentation page for
+// the endpoints, grouped by tag.
+func RenderDocs(w io.Writer, info Info, base string, endpoints []Endpoint) error {
+	return docsTemplate.Execute(w, newDocsModel(info, base, endpoints))
+}
+
+type docsModel struct {
+	Info Info
+	Base string
+	Tags []tagGroup
+}
+
+type tagGroup struct {
+	Name      string
+	Endpoints []endpointView
+}
+
+type endpointView struct {
+	Method      string
+	Path        string
+	Summary     string
+	Description string
+	Params      []Param
+	Request     string
+	Response    string
+	Status      int
+	Errors      []int
+	SSE         bool
+}
+
+func newDocsModel(info Info, base string, endpoints []Endpoint) docsModel {
+	byTag := map[string][]endpointView{}
+	for _, e := range endpoints {
+		view := endpointView{
+			Method:      e.method,
+			Path:        e.path,
+			Summary:     e.summary,
+			Description: e.description,
+			Params:      e.params,
+			Status:      e.Status(),
+			Errors:      e.errors,
+			SSE:         e.sse,
+		}
+		if e.request != nil {
+			view.Request = schemaJSON(SchemaOf(e.request))
+		}
+		if e.response != nil {
+			view.Response = schemaJSON(SchemaOf(e.response))
+		}
+		tags := e.tags
+		if len(tags) == 0 {
+			tags = []string{"other"}
+		}
+		for _, t := range tags {
+			byTag[t] = append(byTag[t], view)
+		}
+	}
+
+	model := docsModel{Info: info, Base: base}
+	for _, name := range Tags(endpoints) {
+		group := tagGroup{Name: name, Endpoints: byTag[name]}
+		sort.Slice(group.Endpoints, func(i, j int) bool {
+			return group.Endpoints[i].Path < group.Endpoints[j].Path
+		})
+		model.Tags = append(model.Tags, group)
+	}
+	if other, ok := byTag["other"]; ok {
+		model.Tags = append(model.Tags, tagGroup{Name: "other", Endpoints: other})
+	}
+	return model
+}
+
+func schemaJSON(s *Schema) string {
+	data, err := json.MarshalIndent(s, "", "  ")
+	if err != nil {
+		return ""
+	}
+	return string(data)
+}
+
+//go:embed docs.html.tmpl
+var docsTemplateSource string
+
+var docsTemplate = template.Must(template.New("docs").Parse(docsTemplateSource))

internal/apigen/schema.go

@@ -0,0 +1,134 @@
+package apigen
+
+import (
+	"reflect"
+	"strings"
+	"time"
+)
+
+// Schema is a JSON-Schema-shaped description of a Go value, derived by
+// reflection. It supports the subset of JSON Schema used by the docs
+// page and the OpenAPI document.
+type Schema struct {
+	Type                 string             `json:"type,omitempty"`
+	Format               string             `json:"format,omitempty"`
+	Description          string             `json:"description,omitempty"`
+	Properties           map[string]*Schema `json:"properties,omitempty"`
+	Required             []string           `json:"required,omitempty"`
+	Items                *Schema            `json:"items,omitempty"`
+	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
+}
+
+var (
+	timeType  = reflect.TypeOf(time.Time{})
+	errorType = reflect.TypeOf((*error)(nil)).Elem()
+)
+
+// SchemaOf derives a [Schema] from the type of v, honoring encoding/json
+// tags: field names come from json tags, and fields marked omitempty are
+// not required.
+//
+// Structs from the same package as v's type are expanded recursively;
+// structs from other packages (and true type cycles) are rendered as
+// free-form objects described by their type name, which keeps schemas
+// for wide external types honest without inventing shape.
+func SchemaOf(v any) *Schema {
+	t := reflect.TypeOf(v)
+	if t == nil {
+		return &Schema{}
+	}
+	return schemaOf(t, rootPkg(t), map[reflect.Type]bool{})
+}
+
+// rootPkg returns the package path of the (possibly pointer) type v's
+// named root, used to bound struct expansion to one package.
+func rootPkg(t reflect.Type) string {
+	for t.Kind() == reflect.Pointer {
+		t = t.Elem()
+	}
+	return t.PkgPath()
+}
+
+func schemaOf(t reflect.Type, pkg string, expanding map[reflect.Type]bool) *Schema {
+	switch t {
+	case timeType:
+		return &Schema{Type: "string", Format: "date-time"}
+	case errorType:
+		return &Schema{Type: "string"}
+	}
+
+	switch t.Kind() {
+	case reflect.Pointer:
+		return schemaOf(t.Elem(), pkg, expanding)
+	case reflect.Bool:
+		return &Schema{Type: "boolean"}
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
+		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return &Schema{Type: "integer"}
+	case reflect.Float32, reflect.Float64:
+		return &Schema{Type: "number"}
+	case reflect.String:
+		return &Schema{Type: "string"}
+	case reflect.Slice, reflect.Array:
+		return &Schema{Type: "array", Items: schemaOf(t.Elem(), pkg, expanding)}
+	case reflect.Map:
+		if t.Key().Kind() != reflect.String {
+			return &Schema{Type: "object"}
+		}
+		return &Schema{Type: "object", AdditionalProperties: schemaOf(t.Elem(), pkg, expanding)}
+	case reflect.Struct:
+		return structSchema(t, pkg, expanding)
+	default:
+		// Interfaces (including any) and anything else: free-form.
+		return &Schema{}
+	}
+}
+
+func structSchema(t reflect.Type, pkg string, expanding map[reflect.Type]bool) *Schema {
+	if t.PkgPath() != pkg {
+		return &Schema{Type: "object", Description: t.String()}
+	}
+	if expanding[t] {
+		return &Schema{Type: "object", Description: t.String()}
+	}
+	expanding[t] = true
+	defer delete(expanding, t)
+
+	s := &Schema{Type: "object"}
+	for i := range t.NumField() {
+		f := t.Field(i)
+		tag := f.Tag.Get("json")
+		if tag == "-" {
+			continue
+		}
+		name, opts, _ := strings.Cut(tag, ",")
+		if f.Anonymous && name == "" {
+			// Embedded structs contribute their fields, per
+			// encoding/json semantics, even when the embedded
+			// type itself is unexported.
+			emb := schemaOf(f.Type, pkg, expanding)
+			for k, v := range emb.Properties {
+				if s.Properties == nil {
+					s.Properties = map[string]*Schema{}
+				}
+				s.Properties[k] = v
+			}
+			s.Required = append(s.Required, emb.Required...)
+			continue
+		}
+		if !f.IsExported() {
+			continue
+		}
+		if name == "" {
+			name = f.Name
+		}
+		if s.Properties == nil {
+			s.Properties = map[string]*Schema{}
+		}
+		s.Properties[name] = schemaOf(f.Type, pkg, expanding)
+		if !strings.Contains(opts, "omitempty") {
+			s.Required = append(s.Required, name)
+		}
+	}
+	return s
+}

internal/backend/accepted_run_integration_test.go

@@ -0,0 +1,131 @@
+package backend
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent"
+	"github.com/charmbracelet/crush/internal/agent/agenttest"
+	"github.com/charmbracelet/crush/internal/db"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/session"
+	"github.com/stretchr/testify/require"
+)
+
+// gatedCoordinator wraps a real agent.Coordinator and parks RunAccepted
+// before delegating to it. Every method other than RunAccepted is
+// inherited from the embedded coordinator, so BeginAccepted (called by
+// Backend.SendMessage) and RunAccepted (called by the dispatched run)
+// are the production agent.Coordinator implementations under test, not
+// stubs. The gate only delays entry into the real RunAccepted so a
+// cancel can be made to land in the accepted-but-not-yet-active window
+// deterministically: the accept handle is not consumed by
+// sessionAgent.Run until the real RunAccepted runs after the gate opens.
+type gatedCoordinator struct {
+	agent.Coordinator
+	entered chan struct{}
+	gate    chan struct{}
+}
+
+func (c *gatedCoordinator) RunAccepted(ctx context.Context, accept *agent.AcceptedRun, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	close(c.entered)
+	<-c.gate
+	return c.Coordinator.RunAccepted(ctx, accept, sessionID, prompt, attachments...)
+}
+
+// newRealCoordinator builds a production agent.Coordinator over a
+// DB-backed session/message store, wrapped in a gate. It is constructed
+// through the real agent.NewCoordinator path (via the test-only
+// agenttest helper) with an offline-resolvable model: the
+// cancel-on-entry path under test persists a canceled turn and returns
+// before any model call, so no network I/O happens.
+func newRealCoordinator(t *testing.T) (*gatedCoordinator, session.Service, message.Service) {
+	t.Helper()
+	conn, err := db.Connect(t.Context(), t.TempDir())
+	require.NoError(t, err)
+	t.Cleanup(func() { conn.Close() })
+
+	q := db.New(conn)
+	sessions := session.NewService(q, conn)
+	messages := message.NewService(q)
+
+	coord, err := agenttest.NewCoordinator(t.Context(), t.TempDir(), sessions, messages)
+	require.NoError(t, err)
+
+	return &gatedCoordinator{
+		Coordinator: coord,
+		entered:     make(chan struct{}),
+		gate:        make(chan struct{}),
+	}, sessions, messages
+}
+
+// TestSendMessage_AcceptedCancelRace_RealMachinery exercises the
+// 202/cancel race end-to-end through Backend.SendMessage against the
+// production agent.Coordinator (BeginAccepted + RunAccepted), not a
+// stub. It asserts that a cancel arriving after the prompt is accepted
+// but before the run becomes active is not lost: the accepted handle
+// reaches sessionAgent.Run and drives cancel-on-entry, which persists a
+// canceled turn instead of streaming.
+//
+// This test would fail if Coordinator.BeginAccepted returned nil (Cancel
+// would find no accepted run and record no mark, and the run would
+// receive a nil Accepted handle and skip cancel-on-entry) or if
+// Coordinator.RunAccepted dropped the handle on its way into
+// sessionAgent.Run (the run would likewise skip cancel-on-entry and try
+// to stream the model). In either case no FinishReasonCanceled turn
+// would be persisted.
+func TestSendMessage_AcceptedCancelRace_RealMachinery(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+
+	coord, sessions, messages := newRealCoordinator(t)
+	sess, err := sessions.Create(t.Context(), "session")
+	require.NoError(t, err)
+
+	ws := insertAgentWorkspace(t, b, coord)
+
+	require.NoError(t, b.SendMessage(ws.ID, proto.AgentMessage{SessionID: sess.ID, Prompt: "hi"}))
+
+	// Coordinator.BeginAccepted ran synchronously inside SendMessage
+	// before dispatch; the dispatched run has now entered the gate but
+	// has not yet called the real RunAccepted, so the accept handle is
+	// not yet consumed: the prompt is accepted but not active.
+	select {
+	case <-coord.entered:
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatched run never entered RunAccepted")
+	}
+
+	// A cancel arriving now lands in the accepted-but-not-yet-active
+	// window and is only recorded because BeginAccepted incremented the
+	// accept counter.
+	require.NoError(t, b.CancelSession(ws.ID, sess.ID))
+
+	// Release the gate so the real RunAccepted threads the handle into
+	// sessionAgent.Run, which drives cancel-on-entry.
+	close(coord.gate)
+
+	// The dispatched run returns nil (cancel-on-entry), so runWG drains.
+	waited := make(chan struct{})
+	go func() {
+		ws.runWG.Wait()
+		close(waited)
+	}()
+	select {
+	case <-waited:
+	case <-time.After(5 * time.Second):
+		t.Fatal("runWG.Wait did not complete after the canceled run returned")
+	}
+
+	// The accepted-but-not-yet-active cancel persisted a canceled turn
+	// rather than streaming a real response.
+	msgs, err := messages.List(t.Context(), sess.ID)
+	require.NoError(t, err)
+	require.Len(t, msgs, 2)
+	require.Equal(t, message.User, msgs[0].Role)
+	require.Equal(t, message.Assistant, msgs[1].Role)
+	require.Equal(t, message.FinishReasonCanceled, msgs[1].FinishReason())
+}

internal/backend/agent.go

@@ -0,0 +1,276 @@
+package backend
+
+import (
+	"context"
+	"errors"
+	"os"
+
+	"github.com/charmbracelet/crush/internal/agent"
+	"github.com/charmbracelet/crush/internal/agent/notify"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/charmbracelet/crush/internal/shell"
+)
+
+// SendMessage validates and accepts a prompt for the workspace's agent,
+// then dispatches the run on a goroutine bound to the workspace context
+// and returns immediately. It does not wait for the LLM turn to
+// complete: the run's lifetime is owned by the workspace, not by the
+// caller. Errors from the dispatched run reach observers through the
+// agent event channels (a notify.TypeAgentError notification), not
+// through this return value.
+//
+// SendMessage returns synchronously when the request cannot be accepted:
+// ErrWorkspaceNotFound if the workspace is missing, ErrAgentNotInitialized
+// if its coordinator is nil, the structural validation errors from
+// agent.ValidateCall (ErrEmptyPrompt, ErrSessionMissing) when the prompt
+// or session is missing, and ErrWorkspaceClosing if the workspace is
+// being torn down.
+func (b *Backend) SendMessage(workspaceID string, msg proto.AgentMessage) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if ws.AgentCoordinator == nil {
+		return ErrAgentNotInitialized
+	}
+
+	if err := agent.ValidateCall(agent.SessionAgentCall{
+		SessionID:   msg.SessionID,
+		Prompt:      msg.Prompt,
+		Attachments: proto.AttachmentsToMessage(msg.Attachments),
+	}); err != nil {
+		return err
+	}
+
+	accept := ws.AgentCoordinator.BeginAccepted(msg.SessionID)
+
+	ws.runMu.Lock()
+	if ws.closing {
+		ws.runMu.Unlock()
+		accept.Close()
+		return ErrWorkspaceClosing
+	}
+	ws.runWG.Add(1)
+	ws.runMu.Unlock()
+
+	go b.runAgent(ws, msg, accept)
+	return nil
+}
+
+// runAgent executes an accepted agent run for the workspace. It owns the
+// accept reservation (releasing it on return) and the runWG ticket added
+// by SendMessage. The run is bound to the workspace context so its
+// lifetime is independent of any client's HTTP request.
+//
+// On a non-cancel error it surfaces the failure to observers via a
+// notify.TypeAgentError notification (lossy, best-effort). That alone is
+// not a reliable terminal signal: the agent-event fan-in uses lossy
+// subscribers, so a `crush run` caller blocking on its RunID could hang
+// if the event is dropped. To guarantee termination, when msg.RunID is
+// non-empty and the coordinator did not already publish the run's
+// authoritative terminal RunComplete (e.g. the error was returned before
+// sessionAgent.Run executed, such as a readyWg or UpdateModels failure),
+// runAgent emits an errored RunComplete on the must-deliver
+// runCompletions broker so the waiter observes a deterministic terminal
+// event. context.Canceled is expected (sessionAgent.Run already
+// publishes the cancelled terminal marker) and produces no error
+// terminal event.
+//
+// When msg.RunID is non-empty it is attached to the context via
+// agent.WithRunID so the coordinator can stamp the terminal
+// notify.RunComplete event with that correlator. A run-complete marker
+// is also attached so the coordinator can report whether it published
+// the terminal event, letting runAgent avoid a duplicate fallback.
+func (b *Backend) runAgent(ws *Workspace, msg proto.AgentMessage, accept *agent.AcceptedRun) {
+	defer ws.runWG.Done()
+	defer accept.Close()
+
+	ctx := ws.ctx
+	if msg.RunID != "" {
+		ctx = agent.WithRunID(ctx, msg.RunID)
+	}
+	ctx = agent.WithRunCompleteMarker(ctx)
+
+	_, err := ws.AgentCoordinator.RunAccepted(ctx, accept, msg.SessionID, msg.Prompt, proto.AttachmentsToMessage(msg.Attachments)...)
+	if err == nil || errors.Is(err, context.Canceled) {
+		return
+	}
+
+	ws.AgentNotifications().Publish(pubsub.CreatedEvent, notify.Notification{
+		SessionID: msg.SessionID,
+		RunID:     msg.RunID,
+		Type:      notify.TypeAgentError,
+		Message:   err.Error(),
+	})
+
+	// Reliable terminal fallback. Only needed when a RunID waiter
+	// exists and the coordinator has not already emitted the run's
+	// terminal RunComplete; otherwise this would be a duplicate.
+	if msg.RunID == "" || agent.RunCompletePublished(ctx) {
+		return
+	}
+	if rc := ws.RunCompletions(); rc != nil {
+		rc.PublishMustDeliver(ctx, pubsub.UpdatedEvent, notify.RunComplete{
+			SessionID: msg.SessionID,
+			RunID:     msg.RunID,
+			Error:     err.Error(),
+		})
+	}
+}
+
+// GetAgentInfo returns the agent's model and busy status.
+func (b *Backend) GetAgentInfo(workspaceID string) (proto.AgentInfo, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return proto.AgentInfo{}, err
+	}
+
+	var agentInfo proto.AgentInfo
+	if ws.AgentCoordinator != nil {
+		m := ws.AgentCoordinator.Model()
+		agentInfo = proto.AgentInfo{
+			Model:    m.CatwalkCfg,
+			ModelCfg: m.ModelCfg,
+			IsBusy:   ws.AgentCoordinator.IsBusy(),
+			IsReady:  true,
+		}
+	}
+	return agentInfo, nil
+}
+
+// InitAgent initializes the coder agent for the workspace.
+func (b *Backend) InitAgent(ctx context.Context, workspaceID string, interactive bool) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if interactive {
+		return ws.InitCoderAgent(ctx)
+	}
+	return ws.InitCoderAgentNonInteractive(ctx)
+}
+
+// UpdateAgent reloads the agent model configuration.
+func (b *Backend) UpdateAgent(ctx context.Context, workspaceID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	return ws.UpdateAgentModel(ctx)
+}
+
+// CancelSession cancels an ongoing agent operation for the given
+// session.
+func (b *Backend) CancelSession(workspaceID, sessionID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if ws.AgentCoordinator != nil {
+		ws.AgentCoordinator.Cancel(sessionID)
+	}
+	return nil
+}
+
+// SummarizeSession triggers a session summarization.
+func (b *Backend) SummarizeSession(ctx context.Context, workspaceID, sessionID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if ws.AgentCoordinator == nil {
+		return ErrAgentNotInitialized
+	}
+
+	return ws.AgentCoordinator.Summarize(ctx, sessionID)
+}
+
+// QueuedPrompts returns the number of queued prompts for the session.
+func (b *Backend) QueuedPrompts(workspaceID, sessionID string) (int, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return 0, err
+	}
+
+	if ws.AgentCoordinator == nil {
+		return 0, nil
+	}
+
+	return ws.AgentCoordinator.QueuedPrompts(sessionID), nil
+}
+
+// ClearQueue clears the prompt queue for the session.
+func (b *Backend) ClearQueue(workspaceID, sessionID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if ws.AgentCoordinator != nil {
+		ws.AgentCoordinator.ClearQueue(sessionID)
+	}
+	return nil
+}
+
+// QueuedPromptsList returns the list of queued prompt strings for a
+// session.
+func (b *Backend) QueuedPromptsList(workspaceID, sessionID string) ([]string, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	if ws.AgentCoordinator == nil {
+		return nil, nil
+	}
+
+	return ws.AgentCoordinator.QueuedPromptsList(sessionID), nil
+}
+
+// GetDefaultSmallModel returns the default small model for a provider.
+func (b *Backend) GetDefaultSmallModel(workspaceID, providerID string) (config.SelectedModel, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return config.SelectedModel{}, err
+	}
+
+	return ws.GetDefaultSmallModel(providerID), nil
+}
+
+// RunShellCommand runs a shell command in the workspace directory and
+// persists the command + output as a user message in the session.
+func (b *Backend) RunShellCommand(ctx context.Context, workspaceID string, req proto.ShellCommandRequest) (proto.ShellCommandResponse, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return proto.ShellCommandResponse{}, err
+	}
+
+	var persist shell.PersistFunc
+	if req.SessionID != "" {
+		persist = func(cmd, output string, exitCode int) error {
+			return shell.PersistOutput(ctx, ws.Messages, req.SessionID, cmd, output, exitCode)
+		}
+	}
+
+	result, err := shell.RunAndPersist(ctx, shell.RunOptions{
+		Command:   req.Command,
+		Cwd:       ws.Path,
+		Env:       append(os.Environ(), ws.Env...),
+		TermWidth: req.TermWidth,
+	}, persist)
+	if err != nil {
+		return proto.ShellCommandResponse{}, err
+	}
+
+	return proto.ShellCommandResponse{
+		Output:   result.Output,
+		ExitCode: result.ExitCode,
+	}, nil
+}

internal/backend/agent_runcomplete_test.go

@@ -0,0 +1,163 @@
+package backend
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent"
+	"github.com/charmbracelet/crush/internal/app"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+// errorCoordinator is a minimal agent.Coordinator whose RunAccepted
+// returns a configurable error. When markPublished is true it stamps
+// the run-complete marker on the context before returning, simulating a
+// real coordinator that already published the run's authoritative
+// terminal RunComplete (so runAgent must not emit a duplicate fallback).
+type errorCoordinator struct {
+	err           error
+	markPublished bool
+}
+
+func (c *errorCoordinator) Run(ctx context.Context, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	return nil, c.err
+}
+
+func (c *errorCoordinator) RunAccepted(ctx context.Context, accept *agent.AcceptedRun, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	if c.markPublished {
+		agent.MarkRunCompletePublished(ctx)
+	}
+	return nil, c.err
+}
+
+func (c *errorCoordinator) BeginAccepted(sessionID string) *agent.AcceptedRun { return nil }
+func (c *errorCoordinator) Cancel(string)                                     {}
+func (c *errorCoordinator) CancelAll()                                        {}
+func (c *errorCoordinator) IsBusy() bool                                      { return false }
+func (c *errorCoordinator) IsSessionBusy(string) bool                         { return false }
+func (c *errorCoordinator) QueuedPrompts(string) int                          { return 0 }
+func (c *errorCoordinator) QueuedPromptsList(string) []string                 { return nil }
+func (c *errorCoordinator) ClearQueue(string)                                 {}
+func (c *errorCoordinator) Summarize(context.Context, string) error           { return nil }
+func (c *errorCoordinator) Model() agent.Model                                { return agent.Model{} }
+func (c *errorCoordinator) UpdateModels(context.Context) error                { return nil }
+func (c *errorCoordinator) GenerateTitle(context.Context, string, string)     {}
+
+// insertRunCompleteWorkspace installs a workspace backed by a real
+// app.App (so the runCompletions broker exists) with the given
+// coordinator and a workspace run context derived from base.
+func insertRunCompleteWorkspace(t *testing.T, b *Backend, base context.Context, coord agent.Coordinator) *Workspace {
+	t.Helper()
+	a := app.NewForTest(base)
+	a.AgentCoordinator = coord
+	t.Cleanup(a.ShutdownForTest)
+	ws := &Workspace{
+		ID:           uuid.New().String(),
+		Path:         t.TempDir(),
+		resolvedPath: t.TempDir(),
+		clients:      make(map[string]*clientState),
+		shutdownFn:   func() {},
+	}
+	ws.App = a
+	ws.ctx, ws.cancel = context.WithCancel(base)
+	b.mu.Lock()
+	b.workspaces.Set(ws.ID, ws)
+	b.pathIndex[ws.resolvedPath] = ws.ID
+	b.mu.Unlock()
+	return ws
+}
+
+// TestRunAgent_PreRunErrorPublishesTerminalRunComplete proves that an
+// error returned from RunAccepted before the coordinator could publish
+// its own terminal event (e.g. a readyWg or UpdateModels failure,
+// modeled here by a stub coordinator) still yields a reliable terminal
+// RunComplete for the run's RunID. Without it, a `crush run` caller
+// blocking on that RunID would hang because the lossy TypeAgentError
+// event is not a guaranteed terminal signal.
+func TestRunAgent_PreRunErrorPublishesTerminalRunComplete(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	runErr := errors.New("update models failed")
+	ws := insertRunCompleteWorkspace(t, b, context.Background(), &errorCoordinator{err: runErr})
+
+	subCtx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ch := ws.RunCompletions().Subscribe(subCtx)
+
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", RunID: "run-1", Prompt: "hi"})
+	require.NoError(t, err)
+
+	select {
+	case ev := <-ch:
+		require.Equal(t, "run-1", ev.Payload.RunID,
+			"the terminal RunComplete must carry the dispatched RunID")
+		require.Equal(t, "S1", ev.Payload.SessionID)
+		require.Equal(t, runErr.Error(), ev.Payload.Error,
+			"the fallback terminal event must be marked errored")
+		require.False(t, ev.Payload.Cancelled)
+	case <-time.After(2 * time.Second):
+		t.Fatal("no terminal RunComplete published for a pre-run error; a run waiter would hang")
+	}
+}
+
+// TestRunAgent_NoFallbackWhenCoordinatorPublished ensures the fallback
+// is suppressed when the coordinator already emitted the run's
+// authoritative terminal RunComplete, so callers never observe a
+// duplicate terminal event for the same RunID.
+func TestRunAgent_NoFallbackWhenCoordinatorPublished(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	runErr := errors.New("stream failed after publishing terminal event")
+	ws := insertRunCompleteWorkspace(t, b, context.Background(),
+		&errorCoordinator{err: runErr, markPublished: true})
+
+	subCtx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ch := ws.RunCompletions().Subscribe(subCtx)
+
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", RunID: "run-1", Prompt: "hi"})
+	require.NoError(t, err)
+
+	// Wait for the dispatched run goroutine to return so any publish
+	// has already happened.
+	ws.runWG.Wait()
+
+	select {
+	case ev := <-ch:
+		t.Fatalf("runAgent published a duplicate terminal RunComplete: %+v", ev.Payload)
+	case <-time.After(200 * time.Millisecond):
+	}
+}
+
+// TestRunAgent_CancellationPublishesNoErrorTerminal verifies that a
+// context.Canceled result from RunAccepted produces no errored terminal
+// RunComplete from runAgent: cancellation is sessionAgent.Run's
+// responsibility (it publishes the cancelled marker) and the dispatcher
+// must not synthesize an error terminal for it.
+func TestRunAgent_CancellationPublishesNoErrorTerminal(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	ws := insertRunCompleteWorkspace(t, b, context.Background(),
+		&errorCoordinator{err: context.Canceled})
+
+	subCtx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ch := ws.RunCompletions().Subscribe(subCtx)
+
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", RunID: "run-1", Prompt: "hi"})
+	require.NoError(t, err)
+
+	ws.runWG.Wait()
+
+	select {
+	case ev := <-ch:
+		t.Fatalf("cancellation must not publish a terminal RunComplete: %+v", ev.Payload)
+	case <-time.After(200 * time.Millisecond):
+	}
+}

internal/backend/agent_test.go

@@ -0,0 +1,164 @@
+package backend
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/charmbracelet/crush/internal/agent"
+	"github.com/charmbracelet/crush/internal/app"
+	"github.com/charmbracelet/crush/internal/message"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+// blockingCoordinator is a minimal agent.Coordinator whose RunAccepted
+// blocks until release is closed. It records that RunAccepted was
+// entered so tests can observe the dispatched goroutine. Every other
+// method returns a zero value.
+type blockingCoordinator struct {
+	entered  chan struct{}
+	release  chan struct{}
+	runCount atomic.Int32
+}
+
+func newBlockingCoordinator() *blockingCoordinator {
+	return &blockingCoordinator{
+		entered: make(chan struct{}, 1),
+		release: make(chan struct{}),
+	}
+}
+
+func (c *blockingCoordinator) Run(ctx context.Context, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	return nil, nil
+}
+
+func (c *blockingCoordinator) RunAccepted(ctx context.Context, accept *agent.AcceptedRun, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error) {
+	c.runCount.Add(1)
+	select {
+	case c.entered <- struct{}{}:
+	default:
+	}
+	<-c.release
+	return nil, nil
+}
+
+func (c *blockingCoordinator) BeginAccepted(sessionID string) *agent.AcceptedRun { return nil }
+func (c *blockingCoordinator) Cancel(string)                                     {}
+func (c *blockingCoordinator) CancelAll()                                        {}
+func (c *blockingCoordinator) IsBusy() bool                                      { return false }
+func (c *blockingCoordinator) IsSessionBusy(string) bool                         { return false }
+func (c *blockingCoordinator) QueuedPrompts(string) int                          { return 0 }
+func (c *blockingCoordinator) QueuedPromptsList(string) []string                 { return nil }
+func (c *blockingCoordinator) ClearQueue(string)                                 {}
+func (c *blockingCoordinator) Summarize(context.Context, string) error           { return nil }
+func (c *blockingCoordinator) Model() agent.Model                                { return agent.Model{} }
+func (c *blockingCoordinator) UpdateModels(context.Context) error                { return nil }
+func (c *blockingCoordinator) GenerateTitle(context.Context, string, string)     {}
+
+// insertAgentWorkspace installs a synthetic workspace with the given
+// coordinator (or none) and a workspace run context, mirroring the
+// fields CreateWorkspace initializes.
+func insertAgentWorkspace(t *testing.T, b *Backend, coord agent.Coordinator) *Workspace {
+	t.Helper()
+	ws := &Workspace{
+		ID:           uuid.New().String(),
+		Path:         t.TempDir(),
+		resolvedPath: t.TempDir(),
+		clients:      make(map[string]*clientState),
+		shutdownFn:   func() {},
+	}
+	ws.App = &app.App{AgentCoordinator: coord}
+	ws.ctx, ws.cancel = context.WithCancel(b.ctx)
+	b.mu.Lock()
+	b.workspaces.Set(ws.ID, ws)
+	b.pathIndex[ws.resolvedPath] = ws.ID
+	b.mu.Unlock()
+	return ws
+}
+
+func TestSendMessage_WorkspaceNotFound(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	err := b.SendMessage("nope", proto.AgentMessage{SessionID: "S1", Prompt: "hi"})
+	require.ErrorIs(t, err, ErrWorkspaceNotFound)
+}
+
+func TestSendMessage_AgentNotInitialized(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	ws := insertAgentWorkspace(t, b, nil)
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", Prompt: "hi"})
+	require.ErrorIs(t, err, ErrAgentNotInitialized)
+}
+
+func TestSendMessage_EmptyPrompt(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	ws := insertAgentWorkspace(t, b, newBlockingCoordinator())
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", Prompt: ""})
+	require.ErrorIs(t, err, agent.ErrEmptyPrompt)
+}
+
+func TestSendMessage_SessionMissing(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	ws := insertAgentWorkspace(t, b, newBlockingCoordinator())
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "", Prompt: "hi"})
+	require.ErrorIs(t, err, agent.ErrSessionMissing)
+}
+
+func TestSendMessage_WorkspaceClosing(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	ws := insertAgentWorkspace(t, b, newBlockingCoordinator())
+	ws.runMu.Lock()
+	ws.closing = true
+	ws.runMu.Unlock()
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", Prompt: "hi"})
+	require.ErrorIs(t, err, ErrWorkspaceClosing)
+}
+
+// TestSendMessage_SuccessIncrementsRunWG asserts the happy path returns
+// nil synchronously and dispatches a tracked goroutine: while
+// RunAccepted blocks, runWG.Wait must not complete (the ticket is
+// outstanding); after release it drains.
+func TestSendMessage_SuccessIncrementsRunWG(t *testing.T) {
+	t.Parallel()
+	b, _ := newTestBackend(t)
+	coord := newBlockingCoordinator()
+	ws := insertAgentWorkspace(t, b, coord)
+
+	err := b.SendMessage(ws.ID, proto.AgentMessage{SessionID: "S1", Prompt: "hi"})
+	require.NoError(t, err)
+
+	select {
+	case <-coord.entered:
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatched goroutine never entered RunAccepted")
+	}
+	require.Equal(t, int32(1), coord.runCount.Load())
+
+	waited := make(chan struct{})
+	go func() {
+		ws.runWG.Wait()
+		close(waited)
+	}()
+
+	select {
+	case <-waited:
+		t.Fatal("runWG.Wait completed while the run was still in flight; ticket was not added")
+	case <-time.After(100 * time.Millisecond):
+	}
+
+	close(coord.release)
+
+	select {
+	case <-waited:
+	case <-time.After(2 * time.Second):
+		t.Fatal("runWG.Wait did not complete after the run returned")
+	}
+}

internal/backend/backend.go

@@ -0,0 +1,1137 @@
+// Package backend provides transport-agnostic operations for managing
+// workspaces, sessions, agents, permissions, and events. It is consumed
+// by protocol-specific layers such as HTTP (server) and ACP.
+package backend
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/app"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/db"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/skills"
+	"github.com/charmbracelet/crush/internal/ui/util"
+	"github.com/charmbracelet/crush/internal/version"
+	"github.com/google/uuid"
+)
+
+// Common errors returned by backend operations.
+var (
+	ErrWorkspaceNotFound       = errors.New("workspace not found")
+	ErrLSPClientNotFound       = errors.New("LSP client not found")
+	ErrAgentNotInitialized     = errors.New("agent coordinator not initialized")
+	ErrPathRequired            = errors.New("path is required")
+	ErrInvalidPermissionAction = errors.New("invalid permission action")
+	ErrUnknownCommand          = errors.New("unknown command")
+	ErrInvalidClientID         = errors.New("invalid client_id")
+	ErrClientNotAttached       = errors.New("client not attached")
+	ErrWorkspaceClosing        = errors.New("workspace closing")
+	ErrServerShuttingDown      = errors.New("server is shutting down")
+	ErrServerNotIdle           = errors.New("server is hosting live workspaces")
+	ErrClientRetired           = errors.New("client has been retired")
+	ErrChannelOptInMismatch    = errors.New("requested channels differ from the existing workspace; channels are an explicit opt-in and are not shared across duplicate creates")
+)
+
+// DefaultCreateGrace is the window in which a client must open an SSE
+// stream after creating a workspace before its creation hold is
+// released. Exposed as a package variable so tests can shorten it.
+var DefaultCreateGrace = 30 * time.Second
+
+// DefaultIdleShutdownDelay is how long the server stays alive after its
+// last workspace is released before it shuts itself down. The delay
+// exists so a client that closes one session and opens another moments
+// later (the same directory or a different one) reuses the still-running
+// server instead of racing its shutdown: with an immediate shutdown the
+// new client can attach to — or create a workspace on — a server that is
+// already tearing down, and then observe its coder agent as "offline".
+// Any workspace create within the window cancels the pending shutdown.
+// Overridable via CRUSH_SERVER_IDLE_TIMEOUT (seconds; 0 restores the
+// old shut-down-immediately behavior).
+var DefaultIdleShutdownDelay = 60 * time.Second
+
+// DefaultDetachGrace is how long a client's claim on a workspace survives
+// after its last SSE stream drops without an explicit release. The stream
+// is the client's refcount claim, so tearing the workspace down the instant
+// it closes turns any momentary drop (a hiccup, a suspended laptop, a proxy
+// timeout) into a permanently lost workspace: the client's reconnect comes
+// back milliseconds later to an ID the server no longer knows. A client
+// that released its claim first (a clean exit) skips the grace. Overridable
+// via CRUSH_SERVER_DETACH_GRACE (seconds; 0 restores immediate teardown).
+var DefaultDetachGrace = 10 * time.Second
+
+// ShutdownFunc is called when the backend needs to trigger a server
+// shutdown (e.g. when the last workspace is removed).
+type ShutdownFunc func()
+
+// Backend provides transport-agnostic business logic for the Crush
+// server. It manages workspaces and delegates to [app.App] services.
+//
+// Locking order: when both [Backend.mu] and [Workspace.clientsMu] are
+// held at once, [Backend.mu] is acquired first. Detach paths
+// ([detachStream], [releaseHoldLocked], [expireHold]) only hold
+// [Workspace.clientsMu] briefly, drop it, then call [teardown] which
+// takes [Backend.mu] (and then re-takes [Workspace.clientsMu] to
+// re-check that the workspace has not been re-claimed). This avoids
+// the AB/BA hazard with [CreateWorkspace], which holds [Backend.mu]
+// while calling [registerClient] so that a workspace cannot be torn
+// down beneath it.
+type Backend struct {
+	workspaces *csync.Map[string, *Workspace]
+	// pathIndex maps a resolved absolute workspace path to its
+	// workspace ID. Reads and writes are serialised via mu so
+	// concurrent CreateWorkspace calls at the same path deduplicate
+	// deterministically.
+	pathIndex map[string]string
+	// pending counts CreateWorkspace calls that have committed to the
+	// slow initialization path (config/db/app setup) but have not yet
+	// registered their workspace in the map. It is guarded by mu.
+	// teardown must observe pending == 0 in addition to an empty
+	// workspace map before triggering server shutdown: otherwise a
+	// teardown of the last live workspace could race ahead of a
+	// concurrent create — which releases mu during its slow init — and
+	// shut the whole server down out from under the workspace being
+	// born.
+	pending int
+	// shutdownTimer, when non-nil, is an armed idle-shutdown timer
+	// waiting out lingerDelay before it shuts the server down. It is
+	// guarded by mu and cancelled the moment a new create arrives.
+	shutdownTimer *time.Timer
+	// closing latches the decision to exit. Every site that commits to
+	// a shutdown sets it while still holding mu, because shutdownFn has
+	// to run unlocked; CreateWorkspace refuses once it is set. That
+	// makes the shutdown-vs-create decision atomic: a create can never
+	// be handed a workspace on a process that is already leaving.
+	closing bool
+	// retired holds the IDs of clients that announced their exit via
+	// RetireClient. Creates from a retired client are refused, which is what
+	// lets a client release a workspace whose ID it never learned.
+	//
+	// Entries are never pruned, and deliberately so: an entry is exactly
+	// what refuses a create that was already on the wire when the client
+	// said goodbye, and HTTP gives no ordering between two requests, so
+	// there is no moment at which the server can prove none is still coming.
+	// Dropping an entry to save memory would reintroduce the orphaned
+	// workspace this mechanism exists to prevent. The cost is one UUID per
+	// client process, and the server only outlives its clients for as long
+	// as sessions keep arriving inside the idle-shutdown window.
+	retired map[string]struct{}
+	mu      sync.Mutex
+
+	cfg         *config.ConfigStore
+	ctx         context.Context
+	shutdownFn  ShutdownFunc
+	createGrace time.Duration
+	lingerDelay time.Duration
+	detachGrace time.Duration
+}
+
+// clientState tracks one client's claim on a workspace.
+//
+//   - streams counts the number of live SSE event streams the client
+//     currently has open against the workspace.
+//   - holdTimer is non-nil in the two timer-held states: the client
+//     created the workspace but has not yet attached an SSE stream
+//     (fires after createGrace), or the client's last SSE stream dropped
+//     without an explicit release (fires after detachGrace, giving the
+//     client's reconnect loop a window to re-attach). Either way the
+//     timer releases the claim when it expires.
+//   - currentSessionID records which session this client is currently
+//     viewing. Empty string means the client has no session selected
+//     (e.g. the landing screen). Cleared automatically when the
+//     clientState entry is removed.
+//   - released marks that the client gave up its claim explicitly while
+//     streams were still open, which a clean exit does. The final stream
+//     detach then tears down immediately instead of waiting out the
+//     detach grace for a client that is not coming back.
+//
+// streams and holdTimer are mutually exclusive in practice (the hold
+// timer is stopped the moment an SSE stream attaches), but both being
+// zero/nil means the entry has been released and should be removed.
+type clientState struct {
+	streams          int
+	holdTimer        *time.Timer
+	currentSessionID string
+	released         bool
+}
+
+// Workspace represents a running [app.App] workspace with its
+// associated resources and state.
+type Workspace struct {
+	*app.App
+	ID     string
+	Path   string
+	Cfg    *config.ConfigStore
+	Env    []string
+	Skills *skills.Manager
+
+	// resolvedPath is the path used as the dedup key in
+	// Backend.pathIndex. It is filepath.EvalSymlinks(filepath.Abs(Path))
+	// with fallback to the cleaned absolute path.
+	resolvedPath string
+
+	// ctx is the workspace-scoped run context. It is derived from
+	// the backend context in CreateWorkspace and lives for the
+	// lifetime of the workspace; cancel tears it down. Agent runs
+	// dispatched on behalf of this workspace are bound to ctx so
+	// their lifetime is owned by the workspace, not by any single
+	// client's HTTP request.
+	ctx    context.Context
+	cancel context.CancelFunc
+
+	// runMu guards closing and gates dispatch of new agent runs.
+	// closing is set by Shutdown so no new runs are accepted once
+	// teardown has begun. runWG tracks dispatched agent goroutines
+	// so Shutdown can wait for them to return before app cleanup.
+	runMu   sync.Mutex
+	closing bool
+	runWG   sync.WaitGroup
+
+	// clientsMu guards clients. It is held only briefly (no IO).
+	clientsMu sync.Mutex
+	// clients tracks each client's claim on this workspace. Refcount
+	// is a derived value: len(clients).
+	clients map[string]*clientState
+
+	// shutdownFn is the function invoked by [Backend.teardown] to
+	// release the workspace's underlying resources. It defaults to the
+	// embedded [app.App.Shutdown]; tests may override it to avoid
+	// driving a full [app.App] through shutdown.
+	shutdownFn func()
+}
+
+// invokeShutdown calls the workspace shutdown hook if set, falling
+// back to the workspace [Workspace.Shutdown] wrapper when not.
+func (w *Workspace) invokeShutdown() {
+	if w.shutdownFn != nil {
+		w.shutdownFn()
+		return
+	}
+	if w.App != nil {
+		w.Shutdown()
+	}
+}
+
+// Shutdown tears the workspace down in an order that is safe for
+// agent runs whose lifetime is bound to the workspace context. It
+// shadows the promoted [app.App.Shutdown] so callers reaching
+// ws.Shutdown() always observe this ordering:
+//
+//  1. Mark the workspace closing so no new agent runs are accepted.
+//  2. Cancel the workspace run context so any dispatched goroutine
+//     that has not yet registered its per-session cancel still
+//     observes cancellation.
+//  3. Cancel active coordinator work for runs that already
+//     registered their per-session cancel function.
+//  4. Wait for dispatched agent goroutines to return.
+//  5. Run the embedded [app.App.Shutdown] cleanup (DB, LSP, etc).
+//
+// CancelAll is idempotent, so the second call inside app.App.Shutdown
+// is harmless; the important guarantee is that cancel -> CancelAll ->
+// runWG.Wait completes before the embedded cleanup touches the DB.
+func (w *Workspace) Shutdown() {
+	w.runMu.Lock()
+	w.closing = true
+	w.runMu.Unlock()
+
+	if w.cancel != nil {
+		w.cancel()
+	}
+	if w.App != nil && w.AgentCoordinator != nil {
+		w.AgentCoordinator.CancelAll()
+	}
+	w.runWG.Wait()
+	if w.App != nil {
+		w.App.Shutdown()
+	}
+}
+
+// New creates a new [Backend].
+func New(ctx context.Context, cfg *config.ConfigStore, shutdownFn ShutdownFunc) *Backend {
+	return &Backend{
+		workspaces:  csync.NewMap[string, *Workspace](),
+		pathIndex:   make(map[string]string),
+		retired:     make(map[string]struct{}),
+		cfg:         cfg,
+		ctx:         ctx,
+		shutdownFn:  shutdownFn,
+		createGrace: DefaultCreateGrace,
+		lingerDelay: idleShutdownDelayFromEnv(),
+		detachGrace: durationFromEnv("CRUSH_SERVER_DETACH_GRACE", DefaultDetachGrace),
+	}
+}
+
+// idleShutdownDelayFromEnv returns the idle-shutdown delay, honoring a
+// CRUSH_SERVER_IDLE_TIMEOUT override (in seconds; 0 disables lingering).
+func idleShutdownDelayFromEnv() time.Duration {
+	return durationFromEnv("CRUSH_SERVER_IDLE_TIMEOUT", DefaultIdleShutdownDelay)
+}
+
+// durationFromEnv reads a whole number of seconds from the named
+// environment variable, falling back to def when it is unset or
+// unparseable. Zero is a meaningful value for both lifecycle windows it
+// configures, so it is accepted.
+func durationFromEnv(name string, def time.Duration) time.Duration {
+	if v := os.Getenv(name); v != "" {
+		if secs, err := strconv.Atoi(v); err == nil && secs >= 0 {
+			return time.Duration(secs) * time.Second
+		}
+	}
+	return def
+}
+
+// SetCreateGrace overrides the create-grace window. Intended for tests
+// that need short timeouts.
+func (b *Backend) SetCreateGrace(d time.Duration) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.createGrace = d
+}
+
+// SetDetachGrace overrides how long a client's claim survives after its
+// last SSE stream drops. A value <= 0 restores the tear-down-immediately
+// behavior. Intended for tests.
+func (b *Backend) SetDetachGrace(d time.Duration) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.detachGrace = d
+}
+
+// SetIdleShutdownDelay overrides how long the server lingers after its
+// last workspace is released before shutting down. A value <= 0 restores
+// the shut-down-immediately behavior. Intended for tests.
+func (b *Backend) SetIdleShutdownDelay(d time.Duration) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.lingerDelay = d
+}
+
+// GetWorkspace retrieves a workspace by ID.
+func (b *Backend) GetWorkspace(id string) (*Workspace, error) {
+	ws, ok := b.workspaces.Get(id)
+	if !ok {
+		return nil, ErrWorkspaceNotFound
+	}
+	return ws, nil
+}
+
+// ListWorkspaces returns all running workspaces.
+func (b *Backend) ListWorkspaces() []proto.Workspace {
+	workspaces := []proto.Workspace{}
+	for _, ws := range b.workspaces.Seq2() {
+		workspaces = append(workspaces, workspaceToProto(ws))
+	}
+	return workspaces
+}
+
+// CreateWorkspace initializes a new workspace from the given
+// parameters, or returns an existing workspace if one already exists at
+// the same resolved path (first-wins semantics).
+//
+// args.ClientID must be a valid UUID identifying the calling client;
+// the resulting workspace registers a creation hold on behalf of that
+// client which is released either by the first SSE attach (which
+// converts it into a stream claim) or by the grace window expiring.
+func (b *Backend) CreateWorkspace(args proto.Workspace) (*Workspace, proto.Workspace, error) {
+	if args.Path == "" {
+		return nil, proto.Workspace{}, ErrPathRequired
+	}
+	clientID, err := validateClientID(args.ClientID)
+	if err != nil {
+		return nil, proto.Workspace{}, err
+	}
+
+	key, err := resolveWorkspaceKey(args.Path)
+	if err != nil {
+		return nil, proto.Workspace{}, fmt.Errorf("failed to resolve workspace path: %w", err)
+	}
+
+	b.mu.Lock()
+	if err := b.admitLocked(clientID); err != nil {
+		b.mu.Unlock()
+		return nil, proto.Workspace{}, err
+	}
+	// A client is arriving: cancel any pending idle shutdown so we never
+	// hand back a workspace on a server that is about to tear itself down.
+	b.cancelShutdownLocked()
+	if existingID, ok := b.pathIndex[key]; ok {
+		if ws, found := b.workspaces.Get(existingID); found {
+			// Hold b.mu while registering: teardown also
+			// acquires b.mu before tearing the workspace
+			// down, so this guarantees the workspace we
+			// return cannot be torn out from under us
+			// between lookup and registerClient. Lock order
+			// here is b.mu -> ws.clientsMu.
+			if !stringSlicesEqual(ws.Cfg.Overrides().EnabledChannels, args.Channels) {
+				b.mu.Unlock()
+				return nil, proto.Workspace{}, ErrChannelOptInMismatch
+			}
+			logFirstWinsMismatch(ws, args)
+			b.registerClient(ws, clientID)
+			b.mu.Unlock()
+			return ws, workspaceToProto(ws), nil
+		}
+		// pathIndex referenced a workspace that has since been
+		// removed; clean the stale entry and fall through.
+		delete(b.pathIndex, key)
+	}
+	// Commit to the slow creation path. Mark this create as pending
+	// while mu is still held so a teardown that runs during the
+	// unlocked init below cannot observe an empty backend and shut the
+	// server down. The deferred decrement runs after the workspace has
+	// been registered (or the create has failed), keeping the invariant
+	// that pending only drops once the workspace is visible in the map.
+	b.pending++
+	b.mu.Unlock()
+	defer func() {
+		b.mu.Lock()
+		b.pending--
+		// If this create ended up registering nothing (it failed, or
+		// deduped onto an existing workspace that has since gone) and
+		// it was holding the last teardown back, the server may now be
+		// idle with no pending work. Arm the idle-shutdown timer here so
+		// a failed create racing the last teardown does not leak an
+		// empty server that a plain teardown already declined to reap.
+		shutdownNow := b.scheduleShutdownIfIdleLocked()
+		b.mu.Unlock()
+		if shutdownNow {
+			slog.Info("No workspaces remain after create settled, shutting down server...")
+			b.shutdownFn()
+		}
+	}()
+
+	id := uuid.New().String()
+	cfg, err := config.Init(args.Path, args.DataDir, args.Debug)
+	if err != nil {
+		return nil, proto.Workspace{}, fmt.Errorf("failed to initialize config: %w", err)
+	}
+
+	cfg.Overrides().SkipPermissionRequests = args.YOLO
+	cfg.Overrides().EnabledChannels = args.Channels
+
+	if err := createDotCrushDir(cfg.Config().Options.DataDirectory); err != nil {
+		return nil, proto.Workspace{}, fmt.Errorf("failed to create data directory: %w", err)
+	}
+
+	conn, err := db.Connect(b.ctx, cfg.Config().Options.DataDirectory, db.WithDataDirLock(true))
+	if err != nil {
+		return nil, proto.Workspace{}, fmt.Errorf("failed to connect to database: %w", err)
+	}
+
+	// Discover skills once per workspace, before app.New. The backend
+	// hosts multiple workspaces concurrently, so the manager is
+	// constructed WITHOUT WithGlobalMirror to prevent last-writer-wins
+	// cross-talk between workspaces.
+	discoveryCfg := skillsDiscoveryConfig(cfg)
+	allSkills, activeSkills, skillStates := skills.DiscoverFromConfig(discoveryCfg)
+	skillsMgr := skills.NewManager(
+		allSkills, activeSkills, skillStates,
+		skills.WithResolvedPaths(discoveryCfg.ResolvePaths()),
+		skills.WithWorkingDir(discoveryCfg.WorkingDir),
+	)
+
+	appWorkspace, err := app.New(b.ctx, conn, cfg, skillsMgr)
+	if err != nil {
+		return nil, proto.Workspace{}, fmt.Errorf("failed to create app workspace: %w", err)
+	}
+
+	wsCtx, wsCancel := context.WithCancel(b.ctx)
+	ws := &Workspace{
+		App:          appWorkspace,
+		ID:           id,
+		Path:         args.Path,
+		Cfg:          cfg,
+		Env:          args.Env,
+		Skills:       skillsMgr,
+		resolvedPath: key,
+		ctx:          wsCtx,
+		cancel:       wsCancel,
+		clients:      make(map[string]*clientState),
+	}
+
+	b.mu.Lock()
+	// Re-check admission: the client may have retired while the slow
+	// init above ran with b.mu released, and registering a claim for a
+	// client that has already announced its exit would strand the
+	// workspace. (b.closing cannot have flipped: every shutdown decision
+	// requires pending == 0, and this create has held pending since
+	// before it released b.mu.)
+	if err := b.admitLocked(clientID); err != nil {
+		b.mu.Unlock()
+		ws.invokeShutdown()
+		return nil, proto.Workspace{}, err
+	}
+	// Re-check the index under the lock: a concurrent caller may have
+	// won the race between the initial unlock and here.
+	if existingID, ok := b.pathIndex[key]; ok {
+		if existing, found := b.workspaces.Get(existingID); found {
+			// Register under b.mu so teardown cannot run
+			// between lookup and registerClient. Lock order
+			// is b.mu -> ws.clientsMu.
+			if !stringSlicesEqual(existing.Cfg.Overrides().EnabledChannels, args.Channels) {
+				b.mu.Unlock()
+				ws.invokeShutdown()
+				return nil, proto.Workspace{}, ErrChannelOptInMismatch
+			}
+			logFirstWinsMismatch(existing, args)
+			b.registerClient(existing, clientID)
+			b.mu.Unlock()
+			ws.invokeShutdown()
+			return existing, workspaceToProto(existing), nil
+		}
+		delete(b.pathIndex, key)
+	}
+	b.workspaces.Set(id, ws)
+	b.pathIndex[key] = id
+	// Register the originating client's hold while still holding
+	// b.mu so the workspace is observable with its claim from the
+	// moment it appears in the index.
+	b.registerClient(ws, clientID)
+	b.mu.Unlock()
+
+	if args.Version != "" && args.Version != version.Version {
+		slog.Warn(
+			"Client/server version mismatch",
+			"client", args.Version,
+			"server", version.Version,
+		)
+		appWorkspace.SendEvent(util.NewWarnMsg(fmt.Sprintf(
+			"Server version %q differs from client version %q. Consider restarting the server.",
+			version.Version, args.Version,
+		)))
+	}
+
+	return ws, workspaceToProto(ws), nil
+}
+
+// skillsDiscoveryConfig adapts a *config.ConfigStore to the
+// skills.DiscoveryConfig that DiscoverFromConfig consumes.
+func skillsDiscoveryConfig(cfg *config.ConfigStore) skills.DiscoveryConfig {
+	opts := cfg.Config().Options
+	var paths, disabled []string
+	if opts != nil {
+		paths = opts.SkillsPaths
+		disabled = opts.DisabledSkills
+	}
+	var resolver func(string) (string, error)
+	if r := cfg.Resolver(); r != nil {
+		resolver = r.ResolveValue
+	}
+	return skills.DiscoveryConfig{
+		SkillsPaths:    paths,
+		DisabledSkills: disabled,
+		WorkingDir:     cfg.WorkingDir(),
+		Resolver:       resolver,
+	}
+}
+
+// skillStatesToProto converts internal skill discovery states into the
+// wire format.
+func skillStatesToProto(states []*skills.SkillState) []proto.SkillState {
+	if len(states) == 0 {
+		return nil
+	}
+	out := make([]proto.SkillState, len(states))
+	for i, s := range states {
+		entry := proto.SkillState{
+			Name:  s.Name,
+			Path:  s.Path,
+			State: proto.SkillDiscoveryState(s.State),
+		}
+		if s.Err != nil {
+			entry.Error = s.Err.Error()
+		}
+		out[i] = entry
+	}
+	return out
+}
+
+// AttachClient registers a new SSE stream for the given client on the
+// workspace. The stream's deferred cleanup must call DetachClient with
+// the same arguments to release the claim.
+//
+// The lookup and the clients-map mutation are performed under
+// [Backend.mu] so that AttachClient cannot race with [Backend.teardown]:
+// teardown also holds [Backend.mu] while removing the workspace from
+// b.workspaces, so once AttachClient observes the workspace and takes
+// ws.clientsMu (under b.mu), no concurrent teardown can succeed without
+// re-checking the (now non-empty) clients map. Lock order is the
+// canonical b.mu -> ws.clientsMu.
+func (b *Backend) AttachClient(workspaceID, clientID string) error {
+	if _, err := validateClientID(clientID); err != nil {
+		return err
+	}
+
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	ws, ok := b.workspaces.Get(workspaceID)
+	if !ok {
+		return ErrWorkspaceNotFound
+	}
+
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	cs, ok := ws.clients[clientID]
+	if !ok {
+		// Defensive: SSE attach without a prior CreateWorkspace by
+		// this client still installs a stream claim so the stream
+		// stays alive for its duration.
+		ws.clients[clientID] = &clientState{streams: 1}
+		return nil
+	}
+	if cs.holdTimer != nil {
+		cs.holdTimer.Stop()
+		cs.holdTimer = nil
+	}
+	cs.streams++
+	return nil
+}
+
+// DetachClient releases one SSE stream's hold on the workspace. When the
+// client has no streams left and no pending creation hold, its claim
+// either enters the detach grace — giving a reconnecting client time to
+// re-attach — or, if the grace is disabled or the client already released
+// its claim, is removed, tearing the workspace down once the refcount
+// hits zero.
+func (b *Backend) DetachClient(workspaceID, clientID string) {
+	ws, ok := b.workspaces.Get(workspaceID)
+	if !ok {
+		return
+	}
+	b.detachStream(ws, clientID)
+}
+
+// admitLocked reports whether clientID may still take a claim on this
+// server. It must be called with b.mu held, which is what makes the
+// answer atomic with respect to the shutdown latch and to RetireClient.
+func (b *Backend) admitLocked(clientID string) error {
+	if b.closing {
+		return ErrServerShuttingDown
+	}
+	if _, ok := b.retired[clientID]; ok {
+		return ErrClientRetired
+	}
+	return nil
+}
+
+// RetireClient records that a client has exited and releases every claim it
+// holds, across every workspace. It is the authoritative "this client is
+// gone" signal, and the reason a client never has to guess whether a create
+// whose response it lost left a workspace behind: either the create landed
+// first and this call releases its claim, or it arrives later and is
+// refused, registering nothing.
+//
+// Idempotent. Lock order is the canonical b.mu -> ws.clientsMu; teardowns
+// for workspaces the client was last on run after b.mu is released and
+// re-check under both locks.
+func (b *Backend) RetireClient(clientID string) error {
+	if _, err := validateClientID(clientID); err != nil {
+		return err
+	}
+
+	b.mu.Lock()
+	if b.retired == nil {
+		b.retired = make(map[string]struct{})
+	}
+	b.retired[clientID] = struct{}{}
+	var orphaned []*Workspace
+	for _, ws := range b.workspaces.Seq2() {
+		ws.clientsMu.Lock()
+		if cs, ok := ws.clients[clientID]; ok {
+			if cs.holdTimer != nil {
+				cs.holdTimer.Stop()
+			}
+			delete(ws.clients, clientID)
+			if len(ws.clients) == 0 {
+				orphaned = append(orphaned, ws)
+			}
+		}
+		ws.clientsMu.Unlock()
+	}
+	b.mu.Unlock()
+
+	for _, ws := range orphaned {
+		b.teardown(ws)
+	}
+	return nil
+}
+
+// releaseHold releases the creation hold for a client, if any. Active
+// stream claims are unaffected. Idempotent: returns nil if the
+// workspace or the client's hold no longer exist.
+func (b *Backend) releaseHold(workspaceID, clientID string) error {
+	if _, err := validateClientID(clientID); err != nil {
+		return err
+	}
+	ws, ok := b.workspaces.Get(workspaceID)
+	if !ok {
+		return nil
+	}
+	b.releaseHoldLocked(ws, clientID)
+	return nil
+}
+
+// registerClient installs (idempotently) the given client's claim on
+// the workspace and starts a grace timer if the entry is fresh.
+//
+// A duplicate create from a client whose claim is timer-held (waiting to
+// attach, or waiting out the detach grace) re-arms it for a full create
+// grace and supersedes any earlier explicit release: the client is coming
+// back. The re-arm installs a fresh clientState rather than resetting the
+// old timer, so an already-fired timer racing this call fails expireHold's
+// identity check instead of killing the new claim.
+func (b *Backend) registerClient(ws *Workspace, clientID string) {
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	if old, ok := ws.clients[clientID]; ok {
+		old.released = false
+		if old.holdTimer == nil {
+			// Live streams hold the claim; nothing to re-arm.
+			return
+		}
+		old.holdTimer.Stop()
+		ws.clients[clientID] = b.newHeldClient(ws, clientID, old.currentSessionID, b.createGrace)
+		return
+	}
+	ws.clients[clientID] = b.newHeldClient(ws, clientID, "", b.createGrace)
+}
+
+// newHeldClient builds a clientState whose claim is held only by a timer
+// that releases it after grace. Callers must hold ws.clientsMu.
+func (b *Backend) newHeldClient(ws *Workspace, clientID, sessionID string, grace time.Duration) *clientState {
+	cs := &clientState{currentSessionID: sessionID}
+	cs.holdTimer = time.AfterFunc(grace, func() {
+		b.expireHold(ws, clientID, cs)
+	})
+	return cs
+}
+
+// expireHold is the body of the grace timer. It runs in its own
+// goroutine and races against AttachClient/releaseHold; the timer
+// stays valid only while the entry's holdTimer still points at it.
+func (b *Backend) expireHold(ws *Workspace, clientID string, timer *clientState) {
+	ws.clientsMu.Lock()
+	cs, ok := ws.clients[clientID]
+	if !ok || cs != timer || cs.holdTimer == nil || cs.streams > 0 {
+		ws.clientsMu.Unlock()
+		return
+	}
+	cs.holdTimer = nil
+	delete(ws.clients, clientID)
+	teardown := len(ws.clients) == 0
+	ws.clientsMu.Unlock()
+	if teardown {
+		b.teardown(ws)
+	}
+}
+
+func (b *Backend) releaseHoldLocked(ws *Workspace, clientID string) {
+	ws.clientsMu.Lock()
+	cs, ok := ws.clients[clientID]
+	if !ok {
+		ws.clientsMu.Unlock()
+		return
+	}
+	if cs.holdTimer != nil {
+		cs.holdTimer.Stop()
+		cs.holdTimer = nil
+	}
+	teardown := false
+	if cs.streams == 0 {
+		delete(ws.clients, clientID)
+		teardown = len(ws.clients) == 0
+	} else {
+		// The client gave up its claim while streams are still open, which
+		// is what a clean exit looks like. Remember it so the final detach
+		// skips the reconnect grace.
+		cs.released = true
+	}
+	ws.clientsMu.Unlock()
+	if teardown {
+		b.teardown(ws)
+	}
+}
+
+func (b *Backend) detachStream(ws *Workspace, clientID string) {
+	b.mu.Lock()
+	grace := b.detachGrace
+	b.mu.Unlock()
+
+	ws.clientsMu.Lock()
+	cs, ok := ws.clients[clientID]
+	if !ok {
+		ws.clientsMu.Unlock()
+		return
+	}
+	if cs.streams > 0 {
+		cs.streams--
+	}
+	teardown := false
+	if cs.streams == 0 && cs.holdTimer == nil {
+		if grace > 0 && !cs.released {
+			// The stream dropped without the client releasing its claim, so
+			// treat it as an interruption rather than an exit: hold the
+			// workspace under a timer long enough for the client's
+			// reconnect to re-attach (AttachClient stops the timer).
+			cs.holdTimer = time.AfterFunc(grace, func() {
+				b.expireHold(ws, clientID, cs)
+			})
+		} else {
+			delete(ws.clients, clientID)
+			teardown = len(ws.clients) == 0
+		}
+	}
+	ws.clientsMu.Unlock()
+	if teardown {
+		b.teardown(ws)
+	}
+}
+
+// teardown removes the workspace from the index, shuts down its
+// underlying [app.App], and triggers a server shutdown if it was the
+// last workspace alive.
+//
+// Callers reach teardown after observing len(ws.clients) == 0 while
+// holding ws.clientsMu and then releasing it. Between that release
+// and the b.mu.Lock below, a concurrent CreateWorkspace may have
+// re-registered a client (CreateWorkspace holds b.mu while doing so,
+// so it is mutually exclusive with this critical section). teardown
+// re-checks under both locks (in the canonical b.mu -> ws.clientsMu
+// order) and aborts if the workspace has been re-claimed.
+func (b *Backend) teardown(ws *Workspace) {
+	b.mu.Lock()
+	ws.clientsMu.Lock()
+	if len(ws.clients) > 0 {
+		// Race: a CreateWorkspace re-registered a client
+		// between the detach path dropping ws.clientsMu and us
+		// taking b.mu. Abort: the workspace is still alive.
+		ws.clientsMu.Unlock()
+		b.mu.Unlock()
+		return
+	}
+	ws.clientsMu.Unlock()
+	if existing, ok := b.pathIndex[ws.resolvedPath]; ok && existing == ws.ID {
+		delete(b.pathIndex, ws.resolvedPath)
+	}
+	b.workspaces.Del(ws.ID)
+	// Arm (or, with lingering disabled, request) the idle shutdown. It
+	// only proceeds once there is genuinely nothing left: no live
+	// workspaces AND no create in flight. Deferring via the linger lets a
+	// client returning moments later reuse this server instead of racing
+	// its shutdown.
+	shutdownNow := b.scheduleShutdownIfIdleLocked()
+	b.mu.Unlock()
+
+	ws.invokeShutdown()
+
+	if shutdownNow {
+		slog.Info("Last workspace removed, shutting down server...")
+		b.shutdownFn()
+	}
+}
+
+// scheduleShutdownIfIdleLocked decides what to do about server shutdown
+// after a workspace count or pending-create change. It must be called
+// with b.mu held.
+//
+// It returns true only when the caller should shut the server down
+// synchronously (after releasing b.mu) — that is, when the server is idle
+// and lingering is disabled (lingerDelay <= 0). When lingering is enabled
+// it instead arms a one-shot timer that re-checks idleness after
+// lingerDelay and shuts down then, and returns false. When the server is
+// not idle (a workspace is live or a create is in flight) it does
+// nothing and returns false.
+//
+// Returning true also latches [Backend.closing], since the caller has to
+// release b.mu before it can run shutdownFn.
+func (b *Backend) scheduleShutdownIfIdleLocked() (shutdownNow bool) {
+	if b.shutdownFn == nil {
+		return false
+	}
+	if b.workspaces.Len() != 0 || b.pending != 0 {
+		return false
+	}
+	if b.lingerDelay <= 0 {
+		b.closing = true
+		return true
+	}
+	if b.shutdownTimer == nil {
+		b.shutdownTimer = time.AfterFunc(b.lingerDelay, b.maybeShutdown)
+	}
+	return false
+}
+
+// cancelShutdownLocked stops any armed idle-shutdown timer. It must be
+// called with b.mu held.
+func (b *Backend) cancelShutdownLocked() {
+	if b.shutdownTimer != nil {
+		b.shutdownTimer.Stop()
+		b.shutdownTimer = nil
+	}
+}
+
+// maybeShutdown is the idle-shutdown timer callback. It shuts the server
+// down only if it is still idle when the linger window elapses; any
+// create that arrived in the meantime cancelled the timer (or bumped
+// pending / the workspace count), so this re-check makes the linger
+// race-free. Deciding to exit latches [Backend.closing] under the same
+// lock, so a create arriving in the gap before shutdownFn runs is
+// refused instead of being initialized on a departing process.
+func (b *Backend) maybeShutdown() {
+	b.mu.Lock()
+	b.shutdownTimer = nil
+	idle := b.workspaces.Len() == 0 && b.pending == 0
+	if idle {
+		b.closing = true
+	}
+	fn := b.shutdownFn
+	b.mu.Unlock()
+	if idle && fn != nil {
+		slog.Info("Server idle, shutting down...")
+		fn()
+	}
+}
+
+// DeleteWorkspace is the public entry point used by the HTTP DELETE
+// handler. It releases the named client's creation hold; live streams
+// from the same client remain attached and continue holding the
+// workspace open until their own deferred DetachClient runs.
+func (b *Backend) DeleteWorkspace(id, clientID string) error {
+	return b.releaseHold(id, clientID)
+}
+
+// SetCurrentSession records which session the given client is
+// currently viewing within the workspace. Passing an empty sessionID
+// clears the client's current-session entry (e.g. the client has
+// returned to the landing screen).
+//
+// The client must be actually attached — i.e. its [clientState] entry
+// must exist and have at least one live stream. A bare creation hold
+// (streams == 0) is rejected with [ErrClientNotAttached]. This
+// guards against zombie writes from a client that has detached and
+// against ghost presence from a hold-only client that never opened an
+// SSE stream.
+func (b *Backend) SetCurrentSession(workspaceID, clientID, sessionID string) error {
+	if _, err := validateClientID(clientID); err != nil {
+		return err
+	}
+	ws, ok := b.workspaces.Get(workspaceID)
+	if !ok {
+		return ErrWorkspaceNotFound
+	}
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	cs, ok := ws.clients[clientID]
+	if !ok || cs.streams == 0 {
+		// No entry, or hold-only (no live stream): refuse the
+		// write. The presence record this is meant to feed
+		// should only reflect clients that can actually observe
+		// session events.
+		return ErrClientNotAttached
+	}
+	cs.currentSessionID = sessionID
+	return nil
+}
+
+// AttachedClients returns the number of clients currently viewing
+// sessionID in the given workspace. Only clients with at least one live
+// SSE stream (streams > 0) AND a matching currentSessionID are counted;
+// pure creation holds do not contribute. Returns [ErrWorkspaceNotFound]
+// if the workspace is unknown.
+func (b *Backend) AttachedClients(workspaceID, sessionID string) (int, error) {
+	ws, ok := b.workspaces.Get(workspaceID)
+	if !ok {
+		return 0, ErrWorkspaceNotFound
+	}
+	return ws.AttachedClientsForSession(sessionID), nil
+}
+
+// AttachedClientsForSession returns the number of clients in this
+// workspace whose currentSessionID equals sessionID and which have at
+// least one live SSE stream. Hold-only clients (streams == 0) do not
+// contribute. Acquires the workspace's [clientsMu] briefly; the
+// returned count is a point-in-time snapshot.
+func (w *Workspace) AttachedClientsForSession(sessionID string) int {
+	w.clientsMu.Lock()
+	defer w.clientsMu.Unlock()
+	n := 0
+	for _, cs := range w.clients {
+		if cs.streams > 0 && cs.currentSessionID == sessionID {
+			n++
+		}
+	}
+	return n
+}
+
+// GetWorkspaceProto returns the proto representation of a workspace.
+func (b *Backend) GetWorkspaceProto(id string) (proto.Workspace, error) {
+	ws, err := b.GetWorkspace(id)
+	if err != nil {
+		return proto.Workspace{}, err
+	}
+	return workspaceToProto(ws), nil
+}
+
+// VersionInfo returns server version information.
+func (b *Backend) VersionInfo() proto.VersionInfo {
+	return proto.VersionInfo{
+		Version:   version.Version,
+		Commit:    version.Commit,
+		BuildID:   version.BuildID,
+		GoVersion: runtime.Version(),
+		Platform:  fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH),
+	}
+}
+
+// Config returns the server-level configuration.
+func (b *Backend) Config() *config.ConfigStore {
+	return b.cfg
+}
+
+// Shutdown initiates a graceful server shutdown.
+func (b *Backend) Shutdown() {
+	b.mu.Lock()
+	b.closing = true
+	fn := b.shutdownFn
+	b.mu.Unlock()
+	if fn != nil {
+		fn()
+	}
+}
+
+// ShutdownIfIdle shuts the server down only when it is hosting no
+// workspaces and has no creates in flight, reporting false when it declined
+// because work is live.
+//
+// This is the only shutdown a client may request. A client asks in order to
+// replace a version-mismatched server, and it cannot check idleness itself
+// without a second round trip a new session can slip into. Deciding here,
+// under the lock creates and teardowns take, closes that window: the answer
+// is atomic, and granting it latches the decision so creates arriving
+// afterwards are refused.
+func (b *Backend) ShutdownIfIdle() bool {
+	b.mu.Lock()
+	live, pending := b.workspaces.Len(), b.pending
+	idle := live == 0 && pending == 0
+	if idle {
+		b.closing = true
+	}
+	fn := b.shutdownFn
+	b.mu.Unlock()
+	if !idle {
+		slog.Warn("Refusing shutdown request: server is not idle",
+			"workspaces", live, "pending_creates", pending)
+		return false
+	}
+	if fn != nil {
+		fn()
+	}
+	return true
+}
+
+// resolveWorkspaceKey returns a stable canonical form of path suitable
+// for use as a dedup key. It applies filepath.Abs, then attempts
+// filepath.EvalSymlinks; because EvalSymlinks errors on non-existent
+// paths, it falls back to the cleaned absolute path in that case.
+func resolveWorkspaceKey(path string) (string, error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", err
+	}
+	if resolved, err := filepath.EvalSymlinks(abs); err == nil {
+		return resolved, nil
+	}
+	return abs, nil
+}
+
+// validateClientID returns the trimmed UUID string or an error if the
+// input is empty or not a valid UUID.
+func validateClientID(id string) (string, error) {
+	if id == "" {
+		return "", ErrInvalidClientID
+	}
+	if _, err := uuid.Parse(id); err != nil {
+		return "", fmt.Errorf("%w: %v", ErrInvalidClientID, err)
+	}
+	return id, nil
+}
+
+func workspaceToProto(ws *Workspace) proto.Workspace {
+	cfg := ws.Cfg.Config()
+	out := proto.Workspace{
+		ID:       ws.ID,
+		Path:     ws.Path,
+		YOLO:     ws.Cfg.Overrides().SkipPermissionRequests,
+		Channels: ws.Cfg.Overrides().EnabledChannels,
+		DataDir:  cfg.Options.DataDirectory,
+		Debug:    cfg.Options.Debug,
+		Config:   cfg,
+		Env:      ws.Env,
+		Version:  version.Version,
+	}
+	if ws.Skills != nil {
+		out.Skills = skillStatesToProto(ws.Skills.States())
+	}
+	return out
+}
+
+// logFirstWinsMismatch emits a debug line whenever a second
+// CreateWorkspace at the same resolved path arrives with flags that
+// differ from the originating workspace. The existing workspace wins;
+// the incoming flags are silently ignored.
+//
+// The comparison is done against the incoming args as the caller sent
+// them — including empty/zero values — rather than after defaulting.
+// This means that, for example, a second caller who omits DataDir
+// while the first set one will still log the mismatch.
+func logFirstWinsMismatch(existing *Workspace, args proto.Workspace) {
+	existingCfg := existing.Cfg.Config()
+	existingYOLO := existing.Cfg.Overrides().SkipPermissionRequests
+	existingChannels := existing.Cfg.Overrides().EnabledChannels
+	if existingYOLO == args.YOLO &&
+		existingCfg.Options.Debug == args.Debug &&
+		existingCfg.Options.DataDirectory == args.DataDir &&
+		stringSlicesEqual(existing.Env, args.Env) &&
+		stringSlicesEqual(existingChannels, args.Channels) {
+		return
+	}
+	slog.Debug(
+		"Workspace flag mismatch on duplicate create; first wins",
+		"workspace_id", existing.ID,
+		"path", existing.Path,
+		"existing_yolo", existingYOLO,
+		"requested_yolo", args.YOLO,
+		"existing_debug", existingCfg.Options.Debug,
+		"requested_debug", args.Debug,
+		"existing_data_dir", existingCfg.Options.DataDirectory,
+		"requested_data_dir", args.DataDir,
+		"existing_env", existing.Env,
+		"requested_env", args.Env,
+		"existing_channels", existingChannels,
+		"requested_channels", args.Channels,
+	)
+}
+
+// stringSlicesEqual reports whether a and b contain the same strings
+// in the same order. nil and empty are treated as equal.
+func stringSlicesEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

internal/backend/backend_skills_test.go

@@ -0,0 +1,167 @@
+package backend_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+	"github.com/charmbracelet/crush/internal/backend"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/charmbracelet/crush/internal/skills"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackend_WorkspaceSkillsIsolation verifies that skill discovery
+// state and SSE events are per-workspace, not process-global. Two
+// workspaces in the same backend process must not see each other's
+// discoveries (either in their initial snapshot or in subsequent
+// PublishStates events).
+func TestBackend_WorkspaceSkillsIsolation(t *testing.T) {
+	// Isolate all of config.Init's filesystem reads from the host. The
+	// project-local .agents/skills/<name>/SKILL.md per working dir is
+	// what we actually want each workspace to see; everything else
+	// (global skills, XDG dirs, etc.) must be empty/deterministic.
+	hostHome := t.TempDir()
+	t.Setenv("HOME", hostHome)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(hostHome, ".config"))
+	t.Setenv("XDG_DATA_HOME", filepath.Join(hostHome, ".local", "share"))
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(hostHome, ".cache"))
+	t.Setenv("CRUSH_SKILLS_DIR", t.TempDir())
+
+	// Each workspace gets its own working directory containing a
+	// distinct project-local skill so the discovery output differs.
+	wdA := t.TempDir()
+	wdB := t.TempDir()
+	writeSkill(t, wdA, "wsa-only-skill", "Workspace A only skill.")
+	writeSkill(t, wdB, "wsb-only-skill", "Workspace B only skill.")
+
+	srvCfg, err := config.Init(wdA, "", false)
+	require.NoError(t, err)
+	b := backend.New(t.Context(), srvCfg, nil)
+
+	cidA := uuid.New().String()
+	cidB := uuid.New().String()
+
+	wsA, _, err := b.CreateWorkspace(proto.Workspace{
+		ClientID: cidA,
+		Path:     wdA,
+		DataDir:  filepath.Join(wdA, ".crush"),
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = b.DeleteWorkspace(wsA.ID, cidA) })
+
+	wsB, _, err := b.CreateWorkspace(proto.Workspace{
+		ClientID: cidB,
+		Path:     wdB,
+		DataDir:  filepath.Join(wdB, ".crush"),
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = b.DeleteWorkspace(wsB.ID, cidB) })
+
+	require.NotNil(t, wsA.Skills, "workspace A must have its own skills.Manager")
+	require.NotNil(t, wsB.Skills, "workspace B must have its own skills.Manager")
+	require.NotSame(t, wsA.Skills, wsB.Skills, "managers must be distinct instances per workspace")
+
+	// Initial snapshots see each workspace's own filesystem skill, and
+	// neither sees the other's.
+	statesA := wsA.Skills.States()
+	statesB := wsB.Skills.States()
+	require.True(t, containsSkillName(statesA, "wsa-only-skill"),
+		"workspace A snapshot missing its own skill")
+	require.False(t, containsSkillName(statesA, "wsb-only-skill"),
+		"workspace A snapshot leaked workspace B's skill")
+	require.True(t, containsSkillName(statesB, "wsb-only-skill"),
+		"workspace B snapshot missing its own skill")
+	require.False(t, containsSkillName(statesB, "wsa-only-skill"),
+		"workspace B snapshot leaked workspace A's skill")
+
+	// Subscribe to each workspace's SSE event stream.
+	ctxA, cancelA := context.WithCancel(t.Context())
+	t.Cleanup(cancelA)
+	chA, err := b.SubscribeEvents(ctxA, wsA.ID)
+	require.NoError(t, err)
+
+	ctxB, cancelB := context.WithCancel(t.Context())
+	t.Cleanup(cancelB)
+	chB, err := b.SubscribeEvents(ctxB, wsB.ID)
+	require.NoError(t, err)
+
+	// Trigger a republish on workspace A only. The marker name lets us
+	// distinguish this event from any incidental backend activity.
+	const marker = "wsa-republish-marker"
+	wsA.Skills.PublishStates([]*skills.SkillState{
+		{Name: marker, State: skills.StateNormal},
+	})
+
+	// Workspace A must receive its own event.
+	require.True(t,
+		waitForSkillsEvent(t, chA, marker, 2*time.Second),
+		"workspace A never received its own skills event")
+
+	// Workspace B must NOT receive workspace A's event.
+	require.False(t,
+		waitForSkillsEvent(t, chB, marker, 250*time.Millisecond),
+		"workspace B leaked workspace A's skills event")
+
+	// And A's published states are now visible on its manager's
+	// snapshot (verifies PublishStates updates the cache, not just the
+	// broker).
+	updatedA := wsA.Skills.States()
+	require.True(t, containsSkillName(updatedA, marker),
+		"PublishStates must update Manager.States()")
+
+	// B's manager snapshot is untouched.
+	require.False(t, containsSkillName(wsB.Skills.States(), marker),
+		"workspace B's Manager.States() leaked workspace A's republish")
+}
+
+func writeSkill(t *testing.T, workingDir, name, desc string) {
+	t.Helper()
+	skillDir := filepath.Join(workingDir, ".agents", "skills", name)
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+	content := fmt.Sprintf("---\nname: %s\ndescription: %s\n---\n%s\n", name, desc, desc)
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+}
+
+func containsSkillName(states []*skills.SkillState, name string) bool {
+	for _, s := range states {
+		if s.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// waitForSkillsEvent drains the given event channel until either a
+// pubsub.Event[skills.Event] containing a state named marker arrives or
+// the timeout elapses. Non-skills events on the channel are silently
+// skipped — the backend fans in many event types and we only care
+// about skills here.
+func waitForSkillsEvent(t *testing.T, ch <-chan pubsub.Event[tea.Msg], marker string, timeout time.Duration) bool {
+	t.Helper()
+	deadline := time.After(timeout)
+	for {
+		select {
+		case ev, ok := <-ch:
+			if !ok {
+				return false
+			}
+			se, ok := ev.Payload.(pubsub.Event[skills.Event])
+			if !ok {
+				continue
+			}
+			if containsSkillName(se.Payload.States, marker) {
+				return true
+			}
+		case <-deadline:
+			return false
+		}
+	}
+}

internal/backend/backend_test.go

@@ -0,0 +1,1784 @@
+package backend
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+// newTestBackend returns a Backend whose teardown path skips any
+// real [app.App] shutdown work. Useful for state-machine tests that
+// install synthetic workspaces directly via insertTestWorkspace.
+func newTestBackend(t *testing.T) (*Backend, *atomic.Int32) {
+	t.Helper()
+	var shutdownCount atomic.Int32
+	b := &Backend{
+		workspaces:  csync.NewMap[string, *Workspace](),
+		pathIndex:   make(map[string]string),
+		ctx:         context.Background(),
+		createGrace: 50 * time.Millisecond,
+		shutdownFn:  func() { shutdownCount.Add(1) },
+	}
+	return b, &shutdownCount
+}
+
+// insertTestWorkspace installs a synthetic workspace into b at the
+// given resolved path. Its shutdownFn is recorded in the returned
+// counter so tests can assert it ran exactly once.
+func insertTestWorkspace(t *testing.T, b *Backend, key string) (*Workspace, *atomic.Int32) {
+	t.Helper()
+	var shutdowns atomic.Int32
+	ws := &Workspace{
+		ID:           uuid.New().String(),
+		Path:         key,
+		resolvedPath: key,
+		clients:      make(map[string]*clientState),
+		shutdownFn:   func() { shutdowns.Add(1) },
+	}
+	b.mu.Lock()
+	b.workspaces.Set(ws.ID, ws)
+	b.pathIndex[key] = ws.ID
+	b.mu.Unlock()
+	return ws, &shutdowns
+}
+
+func newClientID(t *testing.T) string {
+	t.Helper()
+	return uuid.New().String()
+}
+
+func TestResolveWorkspaceKey_AbsoluteAndSymlink(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	real, err := filepath.EvalSymlinks(tmp)
+	require.NoError(t, err)
+
+	got, err := resolveWorkspaceKey(tmp)
+	require.NoError(t, err)
+	require.Equal(t, real, got)
+}
+
+func TestResolveWorkspaceKey_NonExistentFallback(t *testing.T) {
+	t.Parallel()
+
+	missing := filepath.Join(t.TempDir(), "does", "not", "exist")
+	got, err := resolveWorkspaceKey(missing)
+	require.NoError(t, err)
+	abs, err := filepath.Abs(missing)
+	require.NoError(t, err)
+	require.Equal(t, abs, got)
+}
+
+func TestValidateClientID(t *testing.T) {
+	t.Parallel()
+
+	_, err := validateClientID("")
+	require.ErrorIs(t, err, ErrInvalidClientID)
+	_, err = validateClientID("not-a-uuid")
+	require.ErrorIs(t, err, ErrInvalidClientID)
+
+	id := uuid.New().String()
+	got, err := validateClientID(id)
+	require.NoError(t, err)
+	require.Equal(t, id, got)
+}
+
+func TestRegisterClient_Idempotent(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	b.registerClient(ws, cid)
+
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	require.Len(t, ws.clients, 1)
+	require.NotNil(t, ws.clients[cid].holdTimer)
+	require.Equal(t, 0, ws.clients[cid].streams)
+}
+
+func TestAttachClient_ConsumesHold(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+
+	ws.clientsMu.Lock()
+	require.Len(t, ws.clients, 1)
+	require.Nil(t, ws.clients[cid].holdTimer, "attach must stop the grace timer")
+	require.Equal(t, 1, ws.clients[cid].streams)
+	ws.clientsMu.Unlock()
+
+	// Wait past the grace window: a stopped timer must not fire.
+	time.Sleep(150 * time.Millisecond)
+	require.Equal(t, int32(0), shutdowns.Load(), "workspace must not be torn down while attached")
+}
+
+func TestAttachClient_WithoutPriorCreate(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	require.Len(t, ws.clients, 1)
+	require.Equal(t, 1, ws.clients[cid].streams)
+	require.Nil(t, ws.clients[cid].holdTimer)
+}
+
+func TestAttachClient_DuplicateStreams(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+
+	ws.clientsMu.Lock()
+	require.Equal(t, 2, ws.clients[cid].streams)
+	ws.clientsMu.Unlock()
+
+	b.DetachClient(ws.ID, cid)
+	ws.clientsMu.Lock()
+	require.Equal(t, 1, ws.clients[cid].streams)
+	ws.clientsMu.Unlock()
+	require.Equal(t, int32(0), shutdowns.Load())
+
+	b.DetachClient(ws.ID, cid)
+	require.Equal(t, int32(1), shutdowns.Load(), "second detach tears down the workspace")
+}
+
+func TestDetachClient_LastStreamTearsDown(t *testing.T) {
+	t.Parallel()
+
+	b, srvShutdowns := newTestBackend(t)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	b.DetachClient(ws.ID, cid)
+
+	require.Equal(t, int32(1), wsShutdowns.Load())
+	require.Equal(t, int32(1), srvShutdowns.Load(), "last workspace shut down must trigger server shutdown")
+	_, err := b.GetWorkspace(ws.ID)
+	require.ErrorIs(t, err, ErrWorkspaceNotFound)
+}
+
+func TestHoldExpiry_TearsDown(t *testing.T) {
+	t.Parallel()
+
+	b, srvShutdowns := newTestBackend(t)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+
+	require.Eventually(t, func() bool {
+		return wsShutdowns.Load() == 1 && srvShutdowns.Load() == 1
+	}, 1*time.Second, 5*time.Millisecond)
+}
+
+func TestReleaseHold_NoStreams(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+
+	require.Equal(t, int32(1), shutdowns.Load())
+	// Idempotent.
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+func TestReleaseHold_WithActiveStream(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+
+	ws.clientsMu.Lock()
+	require.Equal(t, 1, ws.clients[cid].streams)
+	require.Nil(t, ws.clients[cid].holdTimer)
+	ws.clientsMu.Unlock()
+	require.Equal(t, int32(0), shutdowns.Load())
+
+	b.DetachClient(ws.ID, cid)
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+func TestReleaseHoldThenAttach(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	require.NoError(t, b.releaseHold(ws.ID, cid)) // no entry yet — no-op.
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	ws.clientsMu.Lock()
+	require.Equal(t, 1, ws.clients[cid].streams)
+	ws.clientsMu.Unlock()
+	require.NoError(t, b.releaseHold(ws.ID, cid)) // hold-only no-op (no hold timer).
+	require.Equal(t, int32(0), shutdowns.Load())
+	b.DetachClient(ws.ID, cid)
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+func TestRefcountWithSecondClient(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/a")
+
+	cidA := newClientID(t)
+	cidB := newClientID(t)
+	b.registerClient(ws, cidA)
+	require.NoError(t, b.AttachClient(ws.ID, cidA))
+	b.registerClient(ws, cidB)
+	require.NoError(t, b.AttachClient(ws.ID, cidB))
+
+	b.DetachClient(ws.ID, cidA)
+	ws.clientsMu.Lock()
+	require.Contains(t, ws.clients, cidB)
+	require.NotContains(t, ws.clients, cidA)
+	ws.clientsMu.Unlock()
+	require.Equal(t, int32(0), shutdowns.Load(), "workspace survives while second client attached")
+
+	b.DetachClient(ws.ID, cidB)
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+func TestAttachClient_InvalidID(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/a")
+
+	require.ErrorIs(t, b.AttachClient(ws.ID, ""), ErrInvalidClientID)
+	require.ErrorIs(t, b.AttachClient(ws.ID, "not-a-uuid"), ErrInvalidClientID)
+}
+
+func TestDeleteWorkspace_RejectsBadClientID(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/a")
+
+	require.ErrorIs(t, b.DeleteWorkspace(ws.ID, ""), ErrInvalidClientID)
+	require.ErrorIs(t, b.DeleteWorkspace(ws.ID, "not-a-uuid"), ErrInvalidClientID)
+}
+
+// TestHoldExpiry_RaceWithAttach checks that, when the grace timer fires
+// while a concurrent AttachClient call is in flight, the workspace ends
+// up either fully attached or fully torn down — never in a half-state.
+func TestHoldExpiry_RaceWithAttach(t *testing.T) {
+	t.Parallel()
+
+	for i := range 50 {
+		b, _ := newTestBackend(t)
+		// Tighten the grace window further to force the race.
+		b.createGrace = 1 * time.Millisecond
+		ws, shutdowns := insertTestWorkspace(t, b, "/tmp/race")
+
+		cid := newClientID(t)
+		b.registerClient(ws, cid)
+		// Attach concurrently with the very short grace timer.
+		errCh := make(chan error, 1)
+		go func() { errCh <- b.AttachClient(ws.ID, cid) }()
+		<-errCh
+
+		// Wait for any pending timer to settle.
+		time.Sleep(10 * time.Millisecond)
+
+		ws.clientsMu.Lock()
+		gotShutdown := shutdowns.Load() == 1
+		cs, present := ws.clients[cid]
+		var (
+			gotStreams   int
+			gotHoldTimer *time.Timer
+		)
+		if present {
+			gotStreams = cs.streams
+			gotHoldTimer = cs.holdTimer
+		}
+		ws.clientsMu.Unlock()
+		// Either the workspace was torn down OR the client is
+		// attached with streams==1 and the hold timer cleared.
+		// The state must be consistent: if shutdown, client is
+		// gone; if attached, no teardown and streams==1.
+		if gotShutdown {
+			require.False(t, present, "iter %d: shutdown but client still present", i)
+		} else {
+			require.True(t, present, "iter %d: not shutdown but client missing", i)
+			require.Equal(t, 1, gotStreams, "iter %d: attach winner must leave streams=1", i)
+			require.Nil(t, gotHoldTimer, "iter %d: attach winner must clear holdTimer", i)
+		}
+	}
+}
+
+// TestConcurrentAttachDetach exercises the state machine under
+// parallel attach/detach pressure with the race detector.
+func TestConcurrentAttachDetach(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/a")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid)) // ensure refcount stays > 0.
+
+	const n = 50
+	var wg sync.WaitGroup
+	wg.Add(n)
+	for range n {
+		go func() {
+			defer wg.Done()
+			cid2 := newClientID(t)
+			_ = b.AttachClient(ws.ID, cid2)
+			b.DetachClient(ws.ID, cid2)
+		}()
+	}
+	wg.Wait()
+
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	require.Len(t, ws.clients, 1)
+	require.Contains(t, ws.clients, cid)
+}
+
+// TestPathDedupe_FullCreate exercises CreateWorkspace end-to-end
+// (config init, real app.App). Two CreateWorkspace calls at the same
+// path return the same workspace ID and share the clients map.
+func TestPathDedupe_FullCreate(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cidA := uuid.New().String()
+	cidB := uuid.New().String()
+
+	wsA, protoA, err := b.CreateWorkspace(protoWS(cwd, dataDir, cidA))
+	require.NoError(t, err)
+	require.NotEmpty(t, protoA.ID)
+	require.Equal(t, protoA.DataDir, wsA.Cfg.Config().Options.DataDirectory)
+
+	wsB, protoB, err := b.CreateWorkspace(protoWS(cwd, dataDir, cidB))
+	require.NoError(t, err)
+	require.Equal(t, wsA.ID, wsB.ID, "second create at same path must return existing workspace")
+	require.Equal(t, protoA.ID, protoB.ID)
+
+	wsA.clientsMu.Lock()
+	require.Contains(t, wsA.clients, cidA)
+	require.Contains(t, wsA.clients, cidB)
+	wsA.clientsMu.Unlock()
+}
+
+// TestPathDedupe_DifferentPaths_DifferentWorkspaces confirms that two
+// CreateWorkspace calls at distinct paths produce distinct workspaces.
+func TestPathDedupe_DifferentPaths_DifferentWorkspaces(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	cwdA := t.TempDir()
+	cwdB := t.TempDir()
+	dataA := t.TempDir()
+	dataB := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	wsA, _, err := b.CreateWorkspace(protoWS(cwdA, dataA, uuid.New().String()))
+	require.NoError(t, err)
+	wsB, _, err := b.CreateWorkspace(protoWS(cwdB, dataB, uuid.New().String()))
+	require.NoError(t, err)
+	require.NotEqual(t, wsA.ID, wsB.ID)
+}
+
+// TestPathDedupe_FirstWinsKeepsOriginalEnv verifies that the second
+// create at the same path returns the *originating* client's Env in
+// its proto and does not mutate the existing workspace's YOLO/Debug
+// flags.
+func TestPathDedupe_FirstWinsKeepsOriginalEnv(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	originalEnv := []string{"FOO=bar"}
+	argsA := protoWS(cwd, dataDir, uuid.New().String())
+	argsA.YOLO = true
+	argsA.Env = originalEnv
+	wsA, protoA, err := b.CreateWorkspace(argsA)
+	require.NoError(t, err)
+	require.True(t, protoA.YOLO)
+	require.Equal(t, originalEnv, protoA.Env)
+
+	argsB := protoWS(cwd, dataDir, uuid.New().String())
+	argsB.YOLO = false
+	argsB.Debug = true
+	argsB.Env = []string{"BAZ=qux"}
+	_, protoB, err := b.CreateWorkspace(argsB)
+	require.NoError(t, err)
+	require.Equal(t, protoA.ID, protoB.ID)
+	require.True(t, protoB.YOLO, "first wins: YOLO must remain true")
+	require.Equal(t, originalEnv, protoB.Env, "proto must carry the originating client's Env")
+	require.Equal(t, wsA.Cfg.Overrides().SkipPermissionRequests, true)
+}
+
+// TestPathDedupe_Symlink confirms two paths that resolve to the same
+// target share a workspace.
+func TestPathDedupe_Symlink(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink semantics differ on windows")
+	}
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	real := t.TempDir()
+	link := filepath.Join(t.TempDir(), "link")
+	require.NoError(t, os.Symlink(real, link))
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	wsA, _, err := b.CreateWorkspace(protoWS(real, dataDir, uuid.New().String()))
+	require.NoError(t, err)
+	wsB, _, err := b.CreateWorkspace(protoWS(link, dataDir, uuid.New().String()))
+	require.NoError(t, err)
+	require.Equal(t, wsA.ID, wsB.ID)
+}
+
+// TestPathDedupe_NonExistentPath ensures CreateWorkspace tolerates a
+// path that does not yet exist (EvalSymlinks falls back to Abs).
+func TestPathDedupe_NonExistentPath(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	parent := t.TempDir()
+	missing := filepath.Join(parent, "does-not-exist")
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	_, p, err := b.CreateWorkspace(protoWS(missing, dataDir, uuid.New().String()))
+	require.NoError(t, err)
+	require.NotEmpty(t, p.ID)
+}
+
+// TestCreateWorkspace_IdempotentSameClient checks that a duplicate
+// create from the same client at the same path does not produce a
+// second claim.
+func TestCreateWorkspace_IdempotentSameClient(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cid := uuid.New().String()
+	ws1, _, err := b.CreateWorkspace(protoWS(cwd, dataDir, cid))
+	require.NoError(t, err)
+	ws2, _, err := b.CreateWorkspace(protoWS(cwd, dataDir, cid))
+	require.NoError(t, err)
+	require.Equal(t, ws1.ID, ws2.ID)
+
+	ws1.clientsMu.Lock()
+	require.Len(t, ws1.clients, 1, "duplicate create from same client must not double the claim")
+	ws1.clientsMu.Unlock()
+}
+
+// TestPathDedupe_ParallelCreates ensures two simultaneous CreateWorkspace
+// calls at the same path produce the same workspace and the clients map
+// contains both client IDs.
+func TestPathDedupe_ParallelCreates(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cidA := uuid.New().String()
+	cidB := uuid.New().String()
+
+	type result struct {
+		ws    *Workspace
+		proto proto.Workspace
+		err   error
+	}
+	ch := make(chan result, 2)
+	start := make(chan struct{})
+	go func() {
+		<-start
+		ws, p, err := b.CreateWorkspace(protoWS(cwd, dataDir, cidA))
+		ch <- result{ws, p, err}
+	}()
+	go func() {
+		<-start
+		ws, p, err := b.CreateWorkspace(protoWS(cwd, dataDir, cidB))
+		ch <- result{ws, p, err}
+	}()
+	close(start)
+	r1 := <-ch
+	r2 := <-ch
+	require.NoError(t, r1.err)
+	require.NoError(t, r2.err)
+	require.Equal(t, r1.ws.ID, r2.ws.ID, "both creates must converge on one workspace ID")
+
+	ws := r1.ws
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	require.Contains(t, ws.clients, cidA)
+	require.Contains(t, ws.clients, cidB)
+}
+
+// TestCreateWorkspace_RejectsBadClientID covers the 400 path from the
+// backend side.
+func TestCreateWorkspace_RejectsBadClientID(t *testing.T) {
+	t.Parallel()
+
+	b := New(context.Background(), nil, func() {})
+
+	_, _, err := b.CreateWorkspace(protoWS("/tmp/x", t.TempDir(), ""))
+	require.ErrorIs(t, err, ErrInvalidClientID)
+	_, _, err = b.CreateWorkspace(protoWS("/tmp/x", t.TempDir(), "not-a-uuid"))
+	require.ErrorIs(t, err, ErrInvalidClientID)
+}
+
+// drainBackend tears the backend down at the end of a test by deleting
+// every remaining workspace. Necessary so the test process doesn't
+// leak goroutines or DB handles from the embedded [app.App] instances.
+func drainBackend(t *testing.T, b *Backend) {
+	t.Helper()
+	for _, ws := range b.workspaces.Seq2() {
+		ws.clientsMu.Lock()
+		ids := make([]string, 0, len(ws.clients))
+		for id := range ws.clients {
+			ids = append(ids, id)
+		}
+		ws.clientsMu.Unlock()
+		for _, cid := range ids {
+			_ = b.releaseHold(ws.ID, cid)
+		}
+	}
+}
+
+func protoWS(path, dataDir, clientID string) proto.Workspace {
+	return proto.Workspace{Path: path, DataDir: dataDir, ClientID: clientID}
+}
+
+// syncBuffer is a thread-safe buffer that can be safely read and written
+// from multiple goroutines.
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (sb *syncBuffer) Write(p []byte) (n int, err error) {
+	sb.mu.Lock()
+	defer sb.mu.Unlock()
+	return sb.buf.Write(p)
+}
+
+func (sb *syncBuffer) String() string {
+	sb.mu.Lock()
+	defer sb.mu.Unlock()
+	return sb.buf.String()
+}
+
+// captureDebugLogs installs a buffer-backed slog handler at Debug
+// level for the duration of the test, returning the buffer. The
+// previous default handler is restored via t.Cleanup.
+func captureDebugLogs(t *testing.T) *syncBuffer {
+	t.Helper()
+	var sb syncBuffer
+	prev := slog.Default()
+	handler := slog.NewTextHandler(&sb, &slog.HandlerOptions{Level: slog.LevelDebug})
+	slog.SetDefault(slog.New(handler))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+	return &sb
+}
+
+// xdgIsolated points HOME and XDG_* variables at fresh tempdirs so
+// CreateWorkspace's config loading does not interfere with the host
+// machine's real config.
+func xdgIsolated(t *testing.T) {
+	t.Helper()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+}
+
+// TestFirstWinsMismatch_LogsOnFlagDifferences verifies that the
+// debug mismatch line is emitted when any of YOLO, Debug, DataDir,
+// or Env differs between the first and second CreateWorkspace at
+// the same path, and that the existing workspace's Debug flag is
+// not overwritten.
+func TestFirstWinsMismatch_LogsOnFlagDifferences(t *testing.T) {
+	tests := []struct {
+		name   string
+		mutate func(*proto.Workspace)
+	}{
+		{
+			name:   "yolo",
+			mutate: func(p *proto.Workspace) { p.YOLO = true },
+		},
+		{
+			name:   "debug",
+			mutate: func(p *proto.Workspace) { p.Debug = true },
+		},
+		{
+			name:   "datadir",
+			mutate: func(p *proto.Workspace) { p.DataDir = "" },
+		},
+		{
+			name:   "env",
+			mutate: func(p *proto.Workspace) { p.Env = []string{"NEW=val"} },
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			xdgIsolated(t)
+			cwd := t.TempDir()
+			dataDir := t.TempDir()
+
+			buf := captureDebugLogs(t)
+			b := New(context.Background(), nil, func() {})
+			b.SetCreateGrace(2 * time.Second)
+			t.Cleanup(func() { drainBackend(t, b) })
+
+			argsA := protoWS(cwd, dataDir, uuid.New().String())
+			argsA.Env = []string{"FOO=bar"}
+			wsA, _, err := b.CreateWorkspace(argsA)
+			require.NoError(t, err)
+			originalDebug := wsA.Cfg.Config().Options.Debug
+			originalYOLO := wsA.Cfg.Overrides().SkipPermissionRequests
+
+			argsB := protoWS(cwd, dataDir, uuid.New().String())
+			argsB.Env = []string{"FOO=bar"} // identical by default
+			tc.mutate(&argsB)
+			_, _, err = b.CreateWorkspace(argsB)
+			require.NoError(t, err)
+
+			require.Contains(
+				t, buf.String(),
+				"Workspace flag mismatch on duplicate create",
+				"expected debug log for mismatching %s", tc.name,
+			)
+			// Existing workspace's YOLO and Debug must not change.
+			require.Equal(t, originalYOLO, wsA.Cfg.Overrides().SkipPermissionRequests, "YOLO must be immutable on first-wins")
+			require.Equal(t, originalDebug, wsA.Cfg.Config().Options.Debug, "Debug must be immutable on first-wins")
+		})
+	}
+}
+
+// TestFirstWinsMismatch_NoLogWhenIdentical confirms identical args
+// do not emit the mismatch log line.
+func TestFirstWinsMismatch_NoLogWhenIdentical(t *testing.T) {
+	xdgIsolated(t)
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+
+	buf := captureDebugLogs(t)
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	argsA := protoWS(cwd, dataDir, uuid.New().String())
+	argsA.Env = []string{"FOO=bar"}
+	_, _, err := b.CreateWorkspace(argsA)
+	require.NoError(t, err)
+
+	argsB := protoWS(cwd, dataDir, uuid.New().String())
+	argsB.Env = []string{"FOO=bar"}
+	_, _, err = b.CreateWorkspace(argsB)
+	require.NoError(t, err)
+
+	require.False(t,
+		strings.Contains(buf.String(), "Workspace flag mismatch on duplicate create"),
+		"identical args must not log a mismatch: %s", buf.String())
+}
+
+// TestChannelOptInBoundary_DuplicateCreate verifies that channels are
+// an explicit opt-in that is never shared across a duplicate create at
+// the same path. A second client whose requested channels differ from
+// the existing workspace (including a client that did not opt in at
+// all) is rejected rather than silently inheriting the existing
+// workspace's channels.
+func TestChannelOptInBoundary_DuplicateCreate(t *testing.T) {
+	tests := []struct {
+		name            string
+		firstChannels   []string
+		secondChannels  []string
+		wantMismatchErr bool
+	}{
+		{
+			name:            "second omits opt-in",
+			firstChannels:   []string{"server:webhook"},
+			secondChannels:  nil,
+			wantMismatchErr: true,
+		},
+		{
+			name:            "second opts into extra channel",
+			firstChannels:   nil,
+			secondChannels:  []string{"server:webhook"},
+			wantMismatchErr: true,
+		},
+		{
+			name:            "different channels",
+			firstChannels:   []string{"server:webhook"},
+			secondChannels:  []string{"server:events"},
+			wantMismatchErr: true,
+		},
+		{
+			name:            "identical channels shared",
+			firstChannels:   []string{"server:webhook"},
+			secondChannels:  []string{"server:webhook"},
+			wantMismatchErr: false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			xdgIsolated(t)
+			cwd := t.TempDir()
+			dataDir := t.TempDir()
+
+			b := New(context.Background(), nil, func() {})
+			b.SetCreateGrace(2 * time.Second)
+			t.Cleanup(func() { drainBackend(t, b) })
+
+			argsA := protoWS(cwd, dataDir, uuid.New().String())
+			argsA.Channels = tc.firstChannels
+			wsA, _, err := b.CreateWorkspace(argsA)
+			require.NoError(t, err)
+
+			argsB := protoWS(cwd, dataDir, uuid.New().String())
+			argsB.Channels = tc.secondChannels
+			wsB, protoB, err := b.CreateWorkspace(argsB)
+
+			if tc.wantMismatchErr {
+				require.ErrorIs(t, err, ErrChannelOptInMismatch)
+				require.Nil(t, wsB)
+				// The existing workspace must not be mutated
+				// and must not register the rejected client.
+				require.Equal(t, tc.firstChannels, wsA.Cfg.Overrides().EnabledChannels,
+					"existing channels must be immutable on rejection")
+				wsA.clientsMu.Lock()
+				require.Len(t, wsA.clients, 1, "rejected client must not be registered")
+				wsA.clientsMu.Unlock()
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wsA.ID, protoB.ID)
+			require.Equal(t, tc.firstChannels, protoB.Channels)
+		})
+	}
+}
+
+// TestRaceTwoClientsAttachOneDetaches exercises the PLAN-required
+// race scenario: two clients attach concurrently, then one detaches.
+// The workspace must remain alive with refcount==1 and the clients
+// map must reflect the remaining client only.
+func TestRaceTwoClientsAttachOneDetaches(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/race-two")
+
+	cidA := newClientID(t)
+	cidB := newClientID(t)
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		require.NoError(t, b.AttachClient(ws.ID, cidA))
+	}()
+	go func() {
+		defer wg.Done()
+		require.NoError(t, b.AttachClient(ws.ID, cidB))
+	}()
+	wg.Wait()
+
+	ws.clientsMu.Lock()
+	require.Len(t, ws.clients, 2, "both clients must be attached")
+	ws.clientsMu.Unlock()
+
+	b.DetachClient(ws.ID, cidA)
+
+	ws.clientsMu.Lock()
+	require.Len(t, ws.clients, 1, "refcount must be 1 after one detach")
+	require.Contains(t, ws.clients, cidB, "remaining client must be cidB")
+	require.NotContains(t, ws.clients, cidA, "detached client must be removed")
+	ws.clientsMu.Unlock()
+	require.Equal(t, int32(0), shutdowns.Load(), "workspace must remain alive")
+
+	// Drain.
+	b.DetachClient(ws.ID, cidB)
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+// TestExplicitDeleteThenAttach reproduces the PLAN scenario: start
+// with a real hold, releaseHold consumes it, AttachClient from the
+// same clientID creates a fresh entry with streams==1, and calling
+// releaseHold again is a no-op. A second client keeps the workspace
+// alive so AttachClient can still resolve the workspace ID after the
+// first client's hold is released.
+func TestExplicitDeleteThenAttach(t *testing.T) {
+	t.Parallel()
+
+	// Large grace window so timers cannot fire during the test
+	// — we want to exercise the explicit releaseHold path.
+	b, _ := newTestBackend(t)
+	b.createGrace = time.Hour
+	ws, shutdowns := insertTestWorkspace(t, b, "/tmp/delete-then-attach")
+
+	// Anchor client keeps the workspace registered in
+	// b.workspaces across the cid's releaseHold below.
+	anchor := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, anchor))
+
+	cid := newClientID(t)
+	// Real hold via registerClient (mirrors CreateWorkspace).
+	b.registerClient(ws, cid)
+	ws.clientsMu.Lock()
+	require.Contains(t, ws.clients, cid)
+	require.NotNil(t, ws.clients[cid].holdTimer, "hold must be live")
+	require.Equal(t, 0, ws.clients[cid].streams)
+	ws.clientsMu.Unlock()
+
+	// releaseHold: consumes the hold and removes the entry
+	// (streams == 0). The anchor client keeps the workspace
+	// alive.
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+	require.Equal(t, int32(0), shutdowns.Load(), "anchor must keep workspace alive")
+	ws.clientsMu.Lock()
+	require.NotContains(t, ws.clients, cid, "entry must be removed by releaseHold")
+	ws.clientsMu.Unlock()
+
+	// AttachClient creates a fresh entry with streams==1 and no
+	// hold timer.
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	ws.clientsMu.Lock()
+	require.Contains(t, ws.clients, cid, "fresh entry must be created")
+	require.Equal(t, 1, ws.clients[cid].streams, "fresh attach must start at streams=1")
+	require.Nil(t, ws.clients[cid].holdTimer, "fresh attach must have no hold timer")
+	ws.clientsMu.Unlock()
+
+	// Calling releaseHold again is a no-op (no hold timer to
+	// stop, streams > 0 so the entry stays).
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+	ws.clientsMu.Lock()
+	require.Contains(t, ws.clients, cid, "releaseHold must not touch a stream-only entry")
+	require.Equal(t, 1, ws.clients[cid].streams)
+	require.Nil(t, ws.clients[cid].holdTimer)
+	ws.clientsMu.Unlock()
+
+	// Drain.
+	b.DetachClient(ws.ID, cid)
+	b.DetachClient(ws.ID, anchor)
+	require.Equal(t, int32(1), shutdowns.Load())
+}
+
+// TestAttachClient_RacesWithTeardown forces AttachClient to compete
+// with the teardown path triggered by DetachClient. Before the fix,
+// AttachClient could observe a workspace after teardown had already
+// decided to remove it (because AttachClient did not synchronize with
+// Backend.mu), leaving a live stream claim attached to a workspace
+// that was then removed and shut down. With the fix, the outcome must
+// be deterministic: either AttachClient won and the workspace is
+// alive with the client registered, or teardown won and AttachClient
+// returns ErrWorkspaceNotFound — never a half-state where the
+// workspace is gone but ws.clients still contains the new client.
+func TestAttachClient_RacesWithTeardown(t *testing.T) {
+	t.Parallel()
+
+	for i := range 200 {
+		b, _ := newTestBackend(t)
+		// Keep the grace window long so it can't fire during the
+		// test and confuse the bookkeeping.
+		b.createGrace = time.Hour
+		ws, shutdowns := insertTestWorkspace(t, b, "/tmp/race-teardown")
+
+		// Seed: cidA holds the workspace open via a stream. The
+		// imminent DetachClient(cidA) will be the *only* claim
+		// drop, so teardown will run.
+		cidA := newClientID(t)
+		require.NoError(t, b.AttachClient(ws.ID, cidA))
+
+		// cidB attempts to attach concurrently with the detach
+		// that will tear the workspace down.
+		cidB := newClientID(t)
+		start := make(chan struct{})
+		errCh := make(chan error, 1)
+		detachDone := make(chan struct{})
+		go func() {
+			<-start
+			errCh <- b.AttachClient(ws.ID, cidB)
+		}()
+		go func() {
+			<-start
+			b.DetachClient(ws.ID, cidA)
+			close(detachDone)
+		}()
+		close(start)
+
+		// Wait for both goroutines so teardown (including
+		// shutdownFn) has fully run before we read state.
+		attachErr := <-errCh
+		<-detachDone
+
+		_, wsStillRegistered := b.workspaces.Get(ws.ID)
+		ws.clientsMu.Lock()
+		_, hasA := ws.clients[cidA]
+		_, hasB := ws.clients[cidB]
+		clientCount := len(ws.clients)
+		ws.clientsMu.Unlock()
+		shutdownCount := shutdowns.Load()
+
+		switch {
+		case attachErr == nil:
+			// AttachClient won. The workspace must be alive
+			// (registered) with cidB in its clients map. cidA
+			// may or may not still be there depending on who
+			// took clientsMu first, but the workspace must
+			// not have been torn down.
+			require.True(t, wsStillRegistered,
+				"iter %d: attach succeeded but workspace was removed", i)
+			require.True(t, hasB,
+				"iter %d: attach succeeded but cidB missing from clients", i)
+			require.Equal(t, int32(0), shutdownCount,
+				"iter %d: attach succeeded but workspace was shut down", i)
+		case errors.Is(attachErr, ErrWorkspaceNotFound):
+			// Teardown won. The workspace must be removed,
+			// shut down exactly once, and ws.clients must be
+			// empty (no half-state with cidB inserted into a
+			// dead workspace's clients map).
+			require.False(t, wsStillRegistered,
+				"iter %d: ErrWorkspaceNotFound but workspace still registered", i)
+			require.Equal(t, int32(1), shutdownCount,
+				"iter %d: ErrWorkspaceNotFound but shutdown count = %d", i, shutdownCount)
+			require.False(t, hasA,
+				"iter %d: teardown won but cidA still in clients", i)
+			require.False(t, hasB,
+				"iter %d: teardown won but cidB still in clients (would be the leaked attach)", i)
+			require.Zero(t, clientCount,
+				"iter %d: teardown won but clients map is non-empty", i)
+		default:
+			t.Fatalf("iter %d: unexpected AttachClient error: %v", i, attachErr)
+		}
+	}
+}
+
+// TestSetCurrentSession_BasicAttachAndSwitch verifies the happy path:
+// an attached client can set its current session, a second attached
+// client can target the same session, and one of them can switch to a
+// different session without disturbing the other's record.
+func TestSetCurrentSession_BasicAttachAndSwitch(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-basic")
+
+	cidA := newClientID(t)
+	cidB := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cidA))
+	require.NoError(t, b.AttachClient(ws.ID, cidB))
+
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidA, "S1"))
+	ws.clientsMu.Lock()
+	require.Equal(t, "S1", ws.clients[cidA].currentSessionID)
+	ws.clientsMu.Unlock()
+
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidB, "S1"))
+	ws.clientsMu.Lock()
+	require.Equal(t, "S1", ws.clients[cidA].currentSessionID)
+	require.Equal(t, "S1", ws.clients[cidB].currentSessionID)
+	ws.clientsMu.Unlock()
+
+	// B switches to S2; counts redistribute.
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidB, "S2"))
+	ws.clientsMu.Lock()
+	require.Equal(t, "S1", ws.clients[cidA].currentSessionID)
+	require.Equal(t, "S2", ws.clients[cidB].currentSessionID)
+	ws.clientsMu.Unlock()
+
+	// A clears its selection.
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidA, ""))
+	ws.clientsMu.Lock()
+	require.Empty(t, ws.clients[cidA].currentSessionID)
+	require.Equal(t, "S2", ws.clients[cidB].currentSessionID)
+	ws.clientsMu.Unlock()
+
+	// Drain to release the workspace.
+	b.DetachClient(ws.ID, cidA)
+	b.DetachClient(ws.ID, cidB)
+}
+
+// TestSetCurrentSession_DetachClearsEntry verifies the implicit
+// cleanup: once a client's [clientState] entry is removed (last
+// stream closed), its currentSessionID is gone with it.
+func TestSetCurrentSession_DetachClearsEntry(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-detach")
+
+	// Anchor client so the workspace is not torn down when cid
+	// detaches.
+	anchor := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, anchor))
+
+	cid := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	require.NoError(t, b.SetCurrentSession(ws.ID, cid, "S2"))
+
+	b.DetachClient(ws.ID, cid)
+
+	ws.clientsMu.Lock()
+	_, present := ws.clients[cid]
+	ws.clientsMu.Unlock()
+	require.False(t, present, "detach must remove the clientState entry along with its currentSessionID")
+
+	// A follow-up SetCurrentSession on the gone client must be
+	// rejected with ErrClientNotAttached.
+	require.ErrorIs(t, b.SetCurrentSession(ws.ID, cid, "S3"), ErrClientNotAttached)
+
+	b.DetachClient(ws.ID, anchor)
+}
+
+// TestSetCurrentSession_RejectsHoldOnly verifies that a registered
+// client whose only claim is a creation hold (streams == 0) cannot
+// influence presence: SetCurrentSession returns ErrClientNotAttached
+// and the entry's currentSessionID stays empty.
+func TestSetCurrentSession_RejectsHoldOnly(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	// Keep the grace window large so the hold survives the test.
+	b.createGrace = time.Hour
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-hold")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+
+	require.ErrorIs(t, b.SetCurrentSession(ws.ID, cid, "S1"), ErrClientNotAttached)
+
+	ws.clientsMu.Lock()
+	require.Empty(t, ws.clients[cid].currentSessionID, "hold-only client must not write a session id")
+	ws.clientsMu.Unlock()
+
+	// Drain.
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+}
+
+// TestSetCurrentSession_UnknownClient verifies that a client with no
+// entry at all is rejected with ErrClientNotAttached.
+func TestSetCurrentSession_UnknownClient(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-unknown")
+
+	require.ErrorIs(t, b.SetCurrentSession(ws.ID, newClientID(t), "S1"), ErrClientNotAttached)
+}
+
+// TestSetCurrentSession_RejectsBadInputs covers the validation
+// branches: empty/malformed client_id and unknown workspace.
+func TestSetCurrentSession_RejectsBadInputs(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-bad")
+
+	require.ErrorIs(t, b.SetCurrentSession(ws.ID, "", "S1"), ErrInvalidClientID)
+	require.ErrorIs(t, b.SetCurrentSession(ws.ID, "not-a-uuid", "S1"), ErrInvalidClientID)
+
+	require.ErrorIs(
+		t,
+		b.SetCurrentSession("00000000-0000-0000-0000-000000000000", newClientID(t), "S1"),
+		ErrWorkspaceNotFound,
+	)
+}
+
+// TestSetCurrentSession_RaceWithDetach exercises concurrent
+// SetCurrentSession updates from one client racing against detach
+// on a second client. The final state must be self-consistent: any
+// remaining clientState entries reflect a coherent
+// (streams, currentSessionID) pair.
+func TestSetCurrentSession_RaceWithDetach(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/current-session-race")
+
+	cidA := newClientID(t)
+	cidB := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cidA))
+	require.NoError(t, b.AttachClient(ws.ID, cidB))
+
+	var wg sync.WaitGroup
+	const updates = 200
+	wg.Add(3)
+	go func() {
+		defer wg.Done()
+		for i := range updates {
+			// Errors are tolerated: once cidA detaches,
+			// further updates against cidA must return
+			// ErrClientNotAttached but never panic.
+			_ = b.SetCurrentSession(ws.ID, cidA, "SA")
+			_ = i
+		}
+	}()
+	go func() {
+		defer wg.Done()
+		for i := range updates {
+			_ = b.SetCurrentSession(ws.ID, cidB, "SB")
+			_ = i
+		}
+	}()
+	go func() {
+		defer wg.Done()
+		// Single concurrent detach of cidA partway through.
+		b.DetachClient(ws.ID, cidA)
+	}()
+	wg.Wait()
+
+	ws.clientsMu.Lock()
+	defer ws.clientsMu.Unlock()
+	require.NotContains(t, ws.clients, cidA, "detached client must be gone")
+	require.Contains(t, ws.clients, cidB, "remaining client must still be present")
+	require.Equal(t, "SB", ws.clients[cidB].currentSessionID, "remaining client must keep its last set session")
+}
+
+// TestAttachedClients_BasicLifecycle walks one session's count through
+// attach -> set -> second client joins -> switch -> detach. It also
+// confirms hold-only and unselected clients do not contribute.
+func TestAttachedClients_BasicLifecycle(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	// Keep the grace window long so the hold-only client survives.
+	b.createGrace = time.Hour
+	ws, _ := insertTestWorkspace(t, b, "/tmp/attached-clients-basic")
+
+	// No clients yet.
+	n, err := b.AttachedClients(ws.ID, "S1")
+	require.NoError(t, err)
+	require.Zero(t, n)
+
+	// Attach A, set to S1. Count for S1 is 1; count for S2 is 0.
+	cidA := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cidA))
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidA, "S1"))
+
+	n, err = b.AttachedClients(ws.ID, "S1")
+	require.NoError(t, err)
+	require.Equal(t, 1, n)
+	n, err = b.AttachedClients(ws.ID, "S2")
+	require.NoError(t, err)
+	require.Zero(t, n)
+
+	// Attach B, set to S1. Count for S1 is 2.
+	cidB := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cidB))
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidB, "S1"))
+
+	n, _ = b.AttachedClients(ws.ID, "S1")
+	require.Equal(t, 2, n)
+
+	// B switches to S2; counts redistribute.
+	require.NoError(t, b.SetCurrentSession(ws.ID, cidB, "S2"))
+	n, _ = b.AttachedClients(ws.ID, "S1")
+	require.Equal(t, 1, n)
+	n, _ = b.AttachedClients(ws.ID, "S2")
+	require.Equal(t, 1, n)
+
+	// A hold-only client must NOT be counted, even if we were able to
+	// imagine a currentSessionID on it. registerClient leaves
+	// currentSessionID empty by construction, and SetCurrentSession
+	// rejects hold-only writers — so the contract holds two ways.
+	cidHold := newClientID(t)
+	b.registerClient(ws, cidHold)
+	t.Cleanup(func() { _ = b.releaseHold(ws.ID, cidHold) })
+	n, _ = b.AttachedClients(ws.ID, "S1")
+	require.Equal(t, 1, n, "hold-only client must not contribute")
+	n, _ = b.AttachedClients(ws.ID, "")
+	require.Equal(t, 0, n,
+		"empty sessionID must not match the hold-only entry (streams==0)")
+
+	// A client with streams > 0 but currentSessionID == "" is NOT
+	// counted toward any non-empty session, and is matched only
+	// against the empty session id (which represents the landing
+	// screen).
+	cidC := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cidC))
+	n, _ = b.AttachedClients(ws.ID, "S1")
+	require.Equal(t, 1, n, "stream-only client with empty currentSessionID must not be counted toward S1")
+	n, _ = b.AttachedClients(ws.ID, "")
+	require.Equal(t, 1, n, "stream-only client with empty currentSessionID matches the empty session id")
+
+	// B detaches: count for S2 drops to 0.
+	b.DetachClient(ws.ID, cidB)
+	n, _ = b.AttachedClients(ws.ID, "S2")
+	require.Zero(t, n)
+	n, _ = b.AttachedClients(ws.ID, "S1")
+	require.Equal(t, 1, n, "A still on S1")
+
+	// Final cleanup.
+	b.DetachClient(ws.ID, cidA)
+	b.DetachClient(ws.ID, cidC)
+}
+
+// TestAttachedClients_UnknownWorkspace verifies the error surface.
+func TestAttachedClients_UnknownWorkspace(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	_, err := b.AttachedClients("00000000-0000-0000-0000-000000000000", "S1")
+	require.ErrorIs(t, err, ErrWorkspaceNotFound)
+}
+
+// TestTeardown_DefersShutdownWhileCreatePending verifies the core of the
+// "coder agent offline after more than one session" fix: tearing down the
+// last live workspace must NOT shut the server down while another
+// CreateWorkspace is mid-flight (it has committed to the slow init path
+// but not yet registered its workspace). Without the pending guard, the
+// teardown observed an empty workspace map and killed the whole server
+// out from under the workspace being born.
+func TestTeardown_DefersShutdownWhileCreatePending(t *testing.T) {
+	t.Parallel()
+
+	b, serverShutdowns := newTestBackend(t)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/pending-guard")
+
+	// Simulate a concurrent create that has passed the pending++ point
+	// but has not yet registered its workspace.
+	b.mu.Lock()
+	b.pending = 1
+	b.mu.Unlock()
+
+	b.teardown(ws)
+
+	require.Equal(t, int32(1), wsShutdowns.Load(),
+		"the torn-down workspace's own resources must still be released")
+	require.Equal(t, int32(0), serverShutdowns.Load(),
+		"server must not shut down while a create is in flight")
+}
+
+// TestTeardown_ShutsDownWhenIdleAndNoPending is the control for the guard
+// above: with no create in flight, tearing down the last workspace still
+// triggers the server shutdown, preserving the "shut down when empty"
+// behavior.
+func TestTeardown_ShutsDownWhenIdleAndNoPending(t *testing.T) {
+	t.Parallel()
+
+	b, serverShutdowns := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/idle-shutdown")
+
+	b.teardown(ws)
+
+	require.Equal(t, int32(1), serverShutdowns.Load(),
+		"server must shut down once the last workspace is gone and nothing is pending")
+}
+
+// TestCreateWorkspace_PendingBalancedOnSuccess drives the real
+// CreateWorkspace path and asserts the in-flight `pending` counter it
+// uses to hold off server shutdown is balanced back to zero once the
+// workspace is registered. This guards the bookkeeping the unit-level
+// teardown tests stub out: a refactor that drops the increment or
+// misplaces the deferred decrement would reintroduce the shutdown race.
+func TestCreateWorkspace_PendingBalancedOnSuccess(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	b, shutdownCount := newTestBackend(t)
+	// Keep the create hold alive so its grace timer can't fire and tear
+	// the workspace down mid-assertion.
+	b.SetCreateGrace(time.Hour)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	_, _, err := b.CreateWorkspace(protoWS(t.TempDir(), t.TempDir(), uuid.New().String()))
+	require.NoError(t, err)
+
+	b.mu.Lock()
+	pending := b.pending
+	b.mu.Unlock()
+	require.Equal(t, 0, pending, "pending must return to zero after a successful create")
+	require.Equal(t, int32(0), shutdownCount.Load(), "a live workspace must not trigger shutdown")
+}
+
+// TestCreateWorkspace_PendingBalancedAndReapsOnFailure asserts that a
+// create which fails during its slow init still decrements `pending`, and
+// that the deferred reap shuts an otherwise-idle server down (the safety
+// net that keeps a failed create racing the last teardown from leaking an
+// empty server the plain teardown declined to close).
+func TestCreateWorkspace_PendingBalancedAndReapsOnFailure(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	b, shutdownCount := newTestBackend(t)
+
+	// A data dir whose parent is a regular file makes the workspace's
+	// data-directory creation fail deterministically, after the pending
+	// counter has been incremented.
+	tmp := t.TempDir()
+	fileAsParent := filepath.Join(tmp, "notadir")
+	require.NoError(t, os.WriteFile(fileAsParent, []byte("x"), 0o600))
+	badDataDir := filepath.Join(fileAsParent, "data")
+
+	_, _, err := b.CreateWorkspace(protoWS(tmp, badDataDir, uuid.New().String()))
+	require.Error(t, err, "create must fail when the data dir cannot be created")
+
+	b.mu.Lock()
+	pending := b.pending
+	remaining := b.workspaces.Len()
+	b.mu.Unlock()
+	require.Equal(t, 0, pending, "pending must return to zero after a failed create")
+	require.Zero(t, remaining, "no workspace should be registered after a failed create")
+	require.Equal(t, int32(1), shutdownCount.Load(),
+		"a failed create that leaves the server idle must reap it")
+}
+
+// TestServer_CreateCancelsPendingIdleShutdown is the regression test for
+// the coder-agent-offline handoff: when the last client of a session
+// leaves, the server must linger (not shut down immediately), and a
+// client returning within the linger window — the same directory or a
+// different one — must cancel that pending shutdown so it is never handed
+// a workspace on a server that is about to die.
+func TestServer_CreateCancelsPendingIdleShutdown(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+	t.Setenv("CRUSH_DISABLE_PROVIDER_AUTO_UPDATE", "1")
+
+	b, shutdownCount := newTestBackend(t)
+	b.SetIdleShutdownDelay(10 * time.Second) // long enough not to fire mid-test
+	b.SetCreateGrace(time.Hour)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	// Session 1: a workspace that is attached then leaves, arming the
+	// idle-shutdown timer.
+	wsA, _ := insertTestWorkspace(t, b, "/tmp/linger-A")
+	cidA := newClientID(t)
+	require.NoError(t, b.AttachClient(wsA.ID, cidA))
+	b.DetachClient(wsA.ID, cidA)
+
+	b.mu.Lock()
+	armed := b.shutdownTimer != nil
+	b.mu.Unlock()
+	require.True(t, armed, "idle-shutdown timer must be armed after the last client leaves")
+	require.Equal(t, int32(0), shutdownCount.Load(), "server must linger, not shut down immediately")
+
+	// Session 2 arrives within the linger window: creating a workspace
+	// must cancel the pending shutdown.
+	_, _, err := b.CreateWorkspace(protoWS(t.TempDir(), t.TempDir(), uuid.New().String()))
+	require.NoError(t, err)
+
+	b.mu.Lock()
+	stillArmed := b.shutdownTimer != nil
+	b.mu.Unlock()
+	require.False(t, stillArmed, "a create within the linger window must cancel the pending shutdown")
+	require.Equal(t, int32(0), shutdownCount.Load(), "server must not shut down after a client returns")
+}
+
+// TestServer_ShutsDownAfterLingerWhenIdle confirms the linger still ends
+// in a shutdown when no client returns: the server is not leaked.
+func TestServer_ShutsDownAfterLingerWhenIdle(t *testing.T) {
+	t.Parallel()
+
+	b, shutdownCount := newTestBackend(t)
+	b.SetIdleShutdownDelay(100 * time.Millisecond)
+
+	wsA, _ := insertTestWorkspace(t, b, "/tmp/linger-idle")
+	cidA := newClientID(t)
+	require.NoError(t, b.AttachClient(wsA.ID, cidA))
+	b.DetachClient(wsA.ID, cidA)
+
+	// Nobody returns: after the linger elapses the server shuts down.
+	require.Eventually(t, func() bool { return shutdownCount.Load() == 1 },
+		2*time.Second, 10*time.Millisecond,
+		"idle server must shut down after the linger window")
+}
+
+// -- Detach grace --
+//
+// The SSE stream is a client's refcount claim, so a stream that drops
+// without an explicit release must not destroy the workspace before the
+// client's reconnect loop can come back. These cover both outcomes of
+// that window plus the fast path a clean exit still gets.
+
+// TestDetachStream_GraceSurvivesReattach is the core regression: a
+// momentary stream drop followed by a reconnect must leave the workspace
+// exactly where it was. Before the grace, the reconnect came back to a
+// workspace ID the server no longer knew, and every later request 404'd
+// forever because a sibling session kept the server itself alive.
+func TestDetachStream_GraceSurvivesReattach(t *testing.T) {
+	t.Parallel()
+
+	b, srvShutdowns := newTestBackend(t)
+	b.SetDetachGrace(time.Hour)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/blip")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+
+	b.DetachClient(ws.ID, cid)
+	require.Equal(t, int32(0), wsShutdowns.Load(),
+		"a dropped stream must not tear the workspace down within the grace")
+	live, err := b.GetWorkspace(ws.ID)
+	require.NoError(t, err, "the workspace must still be addressable by its original ID")
+	require.Same(t, ws, live)
+
+	// The reconnect lands and converts the grace back into a stream claim.
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	ws.clientsMu.Lock()
+	cs := ws.clients[cid]
+	require.Equal(t, 1, cs.streams)
+	require.Nil(t, cs.holdTimer, "re-attaching must cancel the grace timer")
+	ws.clientsMu.Unlock()
+	require.Equal(t, int32(0), srvShutdowns.Load())
+}
+
+// TestDetachStream_GraceExpiryTearsDown checks the grace is bounded: a
+// client that never comes back must not pin the workspace (and with it
+// the server) indefinitely.
+func TestDetachStream_GraceExpiryTearsDown(t *testing.T) {
+	t.Parallel()
+
+	b, srvShutdowns := newTestBackend(t)
+	b.SetDetachGrace(50 * time.Millisecond)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/gone-for-good")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	b.DetachClient(ws.ID, cid)
+
+	require.Eventually(t, func() bool { return srvShutdowns.Load() == 1 },
+		2*time.Second, 10*time.Millisecond,
+		"an unclaimed grace must expire and tear the workspace down")
+	require.Equal(t, int32(1), wsShutdowns.Load())
+	_, err := b.GetWorkspace(ws.ID)
+	require.ErrorIs(t, err, ErrWorkspaceNotFound)
+}
+
+// TestDetachStream_ExplicitReleaseSkipsGrace keeps clean exits fast: a
+// client that says goodbye before its stream closes is not coming back,
+// so the grace must not delay the teardown.
+func TestDetachStream_ExplicitReleaseSkipsGrace(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	b.SetDetachGrace(time.Hour)
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/clean-exit")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+
+	// The order a quitting client produces: release, then the stream ends.
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+	require.Equal(t, int32(0), wsShutdowns.Load(), "the live stream still holds it")
+	b.DetachClient(ws.ID, cid)
+
+	require.Equal(t, int32(1), wsShutdowns.Load(),
+		"an explicitly released client must tear down without waiting out the grace")
+}
+
+// TestRegisterClient_RearmsGraceAndCancelsRelease covers a client that
+// recovers by re-creating the workspace rather than re-attaching: the
+// duplicate create must buy it a fresh attach window and undo an earlier
+// release, and the superseded timer must not be able to kill the new claim.
+func TestRegisterClient_RearmsGraceAndCancelsRelease(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	b.SetDetachGrace(50 * time.Millisecond)
+	b.createGrace = time.Hour
+	ws, wsShutdowns := insertTestWorkspace(t, b, "/tmp/rearm")
+
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	require.NoError(t, b.releaseHold(ws.ID, cid))
+	b.DetachClient(ws.ID, cid)
+	require.Equal(t, int32(1), wsShutdowns.Load())
+
+	// A second workspace, this time reclaimed by a duplicate create while
+	// its short detach grace is running.
+	ws2, ws2Shutdowns := insertTestWorkspace(t, b, "/tmp/rearm-2")
+	b.registerClient(ws2, cid)
+	require.NoError(t, b.AttachClient(ws2.ID, cid))
+	b.DetachClient(ws2.ID, cid)
+	b.registerClient(ws2, cid)
+
+	ws2.clientsMu.Lock()
+	require.False(t, ws2.clients[cid].released)
+	ws2.clientsMu.Unlock()
+
+	//nolint:forbidigo // The superseded 50ms timer has to be given its chance to fire.
+	time.Sleep(200 * time.Millisecond)
+	require.Equal(t, int32(0), ws2Shutdowns.Load(),
+		"the re-armed claim must outlive the timer it replaced")
+}
+
+// -- Client retirement --
+
+// TestRetireClient_ReleasesEveryClaim checks the primitive a quitting
+// client relies on: one call drops its claims everywhere, whether they
+// are held by a stream, a create hold, or a detach grace.
+func TestRetireClient_ReleasesEveryClaim(t *testing.T) {
+	t.Parallel()
+
+	b, _ := newTestBackend(t)
+	b.SetDetachGrace(time.Hour)
+	b.createGrace = time.Hour
+
+	streamed, streamedShutdowns := insertTestWorkspace(t, b, "/tmp/retire-stream")
+	held, heldShutdowns := insertTestWorkspace(t, b, "/tmp/retire-hold")
+	shared, sharedShutdowns := insertTestWorkspace(t, b, "/tmp/retire-shared")
+
+	cid, other := newClientID(t), newClientID(t)
+	b.registerClient(streamed, cid)
+	require.NoError(t, b.AttachClient(streamed.ID, cid))
+	b.registerClient(held, cid)
+	b.registerClient(shared, cid)
+	b.registerClient(shared, other)
+
+	require.NoError(t, b.RetireClient(cid))
+
+	require.Equal(t, int32(1), streamedShutdowns.Load())
+	require.Equal(t, int32(1), heldShutdowns.Load())
+	require.Equal(t, int32(0), sharedShutdowns.Load(),
+		"a workspace another client is still using must be left alone")
+	shared.clientsMu.Lock()
+	require.NotContains(t, shared.clients, cid)
+	require.Contains(t, shared.clients, other)
+	shared.clientsMu.Unlock()
+
+	// Idempotent: retiring twice is not an error and changes nothing.
+	require.NoError(t, b.RetireClient(cid))
+	require.Equal(t, int32(1), streamedShutdowns.Load())
+}
+
+// TestRetireClient_RefusesLaterCreates is what makes teardown exact
+// without timing guesses. A recovery create whose response the client
+// never saw can still land on the server afterwards; refusing it is the
+// only way to guarantee it cannot leave a workspace nobody can name.
+func TestRetireClient_RefusesLaterCreates(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	b := New(context.Background(), nil, func() {})
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cid := newClientID(t)
+	require.NoError(t, b.RetireClient(cid))
+
+	_, _, err := b.CreateWorkspace(protoWS(t.TempDir(), t.TempDir(), cid))
+	require.ErrorIs(t, err, ErrClientRetired)
+	require.Zero(t, b.workspaces.Len(), "a refused create must register nothing")
+}
+
+// TestRetireClient_DuringPendingCreate drives the actual ordering the
+// design has to survive: retirement lands while a create is already
+// inside its slow initialization, holding b.mu released. The create must
+// notice at its commit point and discard the workspace it built rather
+// than registering a claim for a client that has already gone.
+func TestRetireClient_DuringPendingCreate(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	b := New(context.Background(), nil, func() {})
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cid := newClientID(t)
+	cwd, dataDir := t.TempDir(), t.TempDir()
+
+	createErr := make(chan error, 1)
+	go func() {
+		_, _, err := b.CreateWorkspace(protoWS(cwd, dataDir, cid))
+		createErr <- err
+	}()
+
+	// pending is bumped under b.mu before the create releases the lock for
+	// its slow init (config, db, app), and dropped only after the workspace
+	// is registered. Observing pending == 1 therefore means the create is
+	// genuinely mid-flight with b.mu free — the exact window retirement has
+	// to cover. Nothing here fakes the race; the create really is running.
+	require.Eventually(t, func() bool {
+		b.mu.Lock()
+		defer b.mu.Unlock()
+		return b.pending == 1
+	}, 30*time.Second, time.Millisecond, "create must reach its slow path")
+
+	require.NoError(t, b.RetireClient(cid))
+
+	require.ErrorIs(t, <-createErr, ErrClientRetired,
+		"a create that commits after retirement must be refused")
+	require.Zero(t, b.workspaces.Len(), "no workspace may be left behind")
+}
+
+// -- Shutdown as an atomic decision --
+
+// TestShutdownIfIdle_RefusesWhileWorkspaceLive is the guard that keeps a
+// second session alive: an upgrading client asks a mismatched server to
+// stand down, and only the server can answer without racing a session
+// that arrives between the question and the answer.
+func TestShutdownIfIdle_RefusesWhileWorkspaceLive(t *testing.T) {
+	t.Parallel()
+
+	b, shutdowns := newTestBackend(t)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/in-use")
+	cid := newClientID(t)
+	b.registerClient(ws, cid)
+
+	require.False(t, b.ShutdownIfIdle(), "a server hosting a workspace must refuse")
+	require.Equal(t, int32(0), shutdowns.Load())
+
+	// Refusing must not latch anything: the server keeps serving.
+	b.mu.Lock()
+	require.False(t, b.closing)
+	b.mu.Unlock()
+}
+
+// TestShutdownIfIdle_RefusesWhileCreatePending closes the subtler half of
+// the same window: a workspace still working through its slow startup is
+// not yet in the workspace map, so a count-based check would call the
+// server idle and kill a session that is being born.
+func TestShutdownIfIdle_RefusesWhileCreatePending(t *testing.T) {
+	t.Parallel()
+
+	b, shutdowns := newTestBackend(t)
+	b.mu.Lock()
+	b.pending = 1
+	b.mu.Unlock()
+
+	require.False(t, b.ShutdownIfIdle())
+	require.Equal(t, int32(0), shutdowns.Load())
+}
+
+// TestShutdownIfIdle_GrantedAndFinal preserves upgrades: an idle server
+// does stand down, and the decision is final so a create arriving
+// afterwards is refused instead of being initialized on a dying process.
+func TestShutdownIfIdle_GrantedAndFinal(t *testing.T) {
+	t.Parallel()
+
+	b, shutdowns := newTestBackend(t)
+	require.True(t, b.ShutdownIfIdle())
+	require.Equal(t, int32(1), shutdowns.Load())
+
+	_, _, err := b.CreateWorkspace(protoWS(t.TempDir(), t.TempDir(), newClientID(t)))
+	require.ErrorIs(t, err, ErrServerShuttingDown)
+}
+
+// TestIdleShutdown_RefusesLaterCreates covers the same finality for the
+// unprompted path: a server that decided to exit because it went idle
+// must not accept the create of a client that arrives a moment later.
+func TestIdleShutdown_RefusesLaterCreates(t *testing.T) {
+	t.Parallel()
+
+	b, shutdowns := newTestBackend(t)
+	b.SetIdleShutdownDelay(10 * time.Millisecond)
+	ws, _ := insertTestWorkspace(t, b, "/tmp/going-idle")
+	cid := newClientID(t)
+	require.NoError(t, b.AttachClient(ws.ID, cid))
+	b.DetachClient(ws.ID, cid)
+
+	require.Eventually(t, func() bool { return shutdowns.Load() == 1 },
+		2*time.Second, 10*time.Millisecond)
+
+	_, _, err := b.CreateWorkspace(protoWS(t.TempDir(), t.TempDir(), cid))
+	require.ErrorIs(t, err, ErrServerShuttingDown,
+		"the client must be told to retry against a replacement server")
+}

internal/backend/config.go

@@ -0,0 +1,347 @@
+package backend
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/charmbracelet/crush/internal/agent"
+	mcptools "github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/commands"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/charmbracelet/crush/internal/skills"
+)
+
+// publishConfigChanged publishes a ConfigChanged event on the workspace's
+// event broker so all subscribers (e.g. remote clients) refresh their
+// cached config snapshot. It also re-initializes any MCP servers whose
+// configuration changed as a result of the write.
+func publishConfigChanged(ws *Workspace) {
+	if ws == nil || ws.App == nil {
+		return
+	}
+
+	// Re-init MCP servers whose config changed. MCP state is process-global,
+	// so this only needs to happen once regardless of which workspace
+	// triggered the write. Run async so unrelated config writes (model
+	// switches, API keys) don't block on MCP reconciliation. Bound to the
+	// workspace ctx so teardown cancels any in-flight init.
+	go mcptools.Reinitialize(ws.ctx, ws.Cfg)
+
+	ws.SendEvent(pubsub.Event[proto.ConfigChanged]{
+		Type:    pubsub.UpdatedEvent,
+		Payload: proto.ConfigChanged{WorkspaceID: ws.ID},
+	})
+}
+
+// MCPResourceContents holds the contents of an MCP resource returned
+// by the backend.
+type MCPResourceContents struct {
+	URI      string `json:"uri"`
+	MIMEType string `json:"mime_type,omitempty"`
+	Text     string `json:"text,omitempty"`
+	Blob     []byte `json:"blob,omitempty"`
+}
+
+// SetConfigField sets a key/value pair in the config file for the
+// given scope.
+func (b *Backend) SetConfigField(workspaceID string, scope config.Scope, key string, value any) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.SetConfigField(scope, key, value); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// RemoveConfigField removes a key from the config file for the given
+// scope.
+func (b *Backend) RemoveConfigField(workspaceID string, scope config.Scope, key string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.RemoveConfigField(scope, key); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// UpdatePreferredModel updates the preferred model for the given type
+// and persists it to the config file at the given scope.
+func (b *Backend) UpdatePreferredModel(workspaceID string, scope config.Scope, modelType config.SelectedModelType, model config.SelectedModel) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.UpdatePreferredModel(scope, modelType, model); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// SetCompactMode sets the compact mode setting and persists it.
+func (b *Backend) SetCompactMode(workspaceID string, scope config.Scope, enabled bool) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.SetCompactMode(scope, enabled); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// SetProviderAPIKey sets the API key for a provider and persists it.
+func (b *Backend) SetProviderAPIKey(workspaceID string, scope config.Scope, providerID string, apiKey any) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.SetProviderAPIKey(scope, providerID, apiKey); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// ImportCopilot attempts to import a GitHub Copilot token from disk.
+func (b *Backend) ImportCopilot(workspaceID string) (*oauth.Token, bool, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, false, err
+	}
+	token, ok := ws.Cfg.ImportCopilot()
+	if ok {
+		publishConfigChanged(ws)
+	}
+	return token, ok, nil
+}
+
+// RefreshOAuthToken refreshes the OAuth token for a provider.
+func (b *Backend) RefreshOAuthToken(ctx context.Context, workspaceID string, scope config.Scope, providerID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := ws.Cfg.RefreshOAuthToken(ctx, scope, providerID); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// ProjectNeedsInitialization checks whether the project in this
+// workspace needs initialization.
+func (b *Backend) ProjectNeedsInitialization(workspaceID string) (bool, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return false, err
+	}
+	return config.ProjectNeedsInitialization(ws.Cfg)
+}
+
+// MarkProjectInitialized marks the project as initialized.
+func (b *Backend) MarkProjectInitialized(workspaceID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	if err := config.MarkProjectInitialized(ws.Cfg); err != nil {
+		return err
+	}
+	publishConfigChanged(ws)
+	return nil
+}
+
+// InitializePrompt builds the initialization prompt for the workspace.
+func (b *Backend) InitializePrompt(workspaceID string) (string, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return "", err
+	}
+	return agent.InitializePrompt(ws.Cfg)
+}
+
+// ReadSkill reads a skill's content by ID.
+func (b *Backend) ReadSkill(ctx context.Context, workspaceID, skillID string) ([]byte, proto.SkillReadResult, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, proto.SkillReadResult{}, err
+	}
+
+	mgr := ws.Skills
+	content, result, err := skills.ReadContent(
+		mgr.ActiveSkills(), mgr.ResolvedPaths(), mgr.WorkingDir(), skillID,
+	)
+	if err != nil {
+		return nil, proto.SkillReadResult{}, err
+	}
+	return content, proto.SkillReadResult{
+		Name:        result.Name,
+		Description: result.Description,
+		Source:      string(result.Source),
+		Builtin:     result.Builtin,
+	}, nil
+}
+
+// ListSkills returns the effective visible skills for a workspace.
+func (b *Backend) ListSkills(workspaceID string) ([]proto.SkillInfo, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+	mgr := ws.Skills
+	entries := skills.Catalog(mgr.ActiveSkills(), mgr.ResolvedPaths(), mgr.WorkingDir())
+	result := make([]proto.SkillInfo, len(entries))
+	for i, entry := range entries {
+		result[i] = proto.SkillInfo{
+			ID:            entry.ID,
+			Name:          entry.Name,
+			Description:   entry.Description,
+			Label:         entry.Label,
+			Source:        string(entry.Source),
+			UserInvocable: entry.UserInvocable,
+		}
+	}
+	return result, nil
+}
+
+// EnableDockerMCP validates Docker MCP availability, stages the
+// configuration, starts the MCP client, and persists the config.
+func (b *Backend) EnableDockerMCP(ctx context.Context, workspaceID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	mcpConfig, err := ws.Cfg.PrepareDockerMCPConfig()
+	if err != nil {
+		return err
+	}
+
+	if err := mcptools.InitializeSingle(ctx, config.DockerMCPName, ws.Cfg); err != nil {
+		disableErr := mcptools.DisableSingle(ws.Cfg, config.DockerMCPName)
+		ws.Cfg.RemoveDockerMCPInMemory()
+		return fmt.Errorf("failed to start docker MCP: %w", errors.Join(err, disableErr))
+	}
+
+	if err := ws.Cfg.PersistDockerMCPConfig(mcpConfig); err != nil {
+		disableErr := mcptools.DisableSingle(ws.Cfg, config.DockerMCPName)
+		ws.Cfg.RemoveDockerMCPInMemory()
+		return fmt.Errorf("docker MCP started but failed to persist configuration: %w", errors.Join(err, disableErr))
+	}
+
+	publishConfigChanged(ws)
+	return nil
+}
+
+// DisableDockerMCP closes the Docker MCP client, removes the
+// configuration, and persists the change.
+func (b *Backend) DisableDockerMCP(workspaceID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	if err := mcptools.DisableSingle(ws.Cfg, config.DockerMCPName); err != nil {
+		return fmt.Errorf("failed to disable docker MCP: %w", err)
+	}
+
+	if err := ws.Cfg.DisableDockerMCP(); err != nil {
+		return err
+	}
+
+	publishConfigChanged(ws)
+	return nil
+}
+
+// RefreshMCPTools refreshes the tools for a named MCP server.
+func (b *Backend) RefreshMCPTools(ctx context.Context, workspaceID, name string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	mcptools.RefreshTools(ctx, ws.Cfg, name)
+	return nil
+}
+
+// ReadMCPResource reads a resource from a named MCP server.
+func (b *Backend) ReadMCPResource(ctx context.Context, workspaceID, name, uri string) ([]MCPResourceContents, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+	contents, err := mcptools.ReadResource(ctx, ws.Cfg, name, uri)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]MCPResourceContents, len(contents))
+	for i, c := range contents {
+		result[i] = MCPResourceContents{
+			URI:      c.URI,
+			MIMEType: c.MIMEType,
+			Text:     c.Text,
+			Blob:     c.Blob,
+		}
+	}
+	return result, nil
+}
+
+// GetMCPPrompt retrieves a prompt from a named MCP server.
+func (b *Backend) GetMCPPrompt(workspaceID, clientID, promptID string, args map[string]string) (string, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return "", err
+	}
+	return commands.GetMCPPrompt(ws.Cfg, clientID, promptID, args)
+}
+
+func (b *Backend) ListMCPPrompts(workspaceID string) ([]proto.MCPPrompt, error) {
+	if _, err := b.GetWorkspace(workspaceID); err != nil {
+		return nil, err
+	}
+	prompts, err := commands.LoadMCPPrompts()
+	if err != nil {
+		return nil, err
+	}
+	result := make([]proto.MCPPrompt, len(prompts))
+	for i, prompt := range prompts {
+		arguments := make([]proto.MCPPromptArgument, len(prompt.Arguments))
+		for j, argument := range prompt.Arguments {
+			arguments[j] = proto.MCPPromptArgument{
+				ID:          argument.ID,
+				Title:       argument.Title,
+				Description: argument.Description,
+				Required:    argument.Required,
+			}
+		}
+		result[i] = proto.MCPPrompt{
+			ID:          prompt.ID,
+			Title:       prompt.Title,
+			Description: prompt.Description,
+			PromptID:    prompt.PromptID,
+			ClientID:    prompt.ClientID,
+			Arguments:   arguments,
+		}
+	}
+	return result, nil
+}
+
+// GetWorkingDir returns the working directory for a workspace.
+func (b *Backend) GetWorkingDir(workspaceID string) (string, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return "", err
+	}
+	return ws.Cfg.WorkingDir(), nil
+}

internal/backend/config_test.go

@@ -0,0 +1,207 @@
+package backend
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/proto"
+	"github.com/charmbracelet/crush/internal/pubsub"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+// awaitConfigChanged drains events until a ConfigChanged is received
+// for the given workspace ID, or fails the test on timeout. Other
+// event types are ignored.
+func awaitConfigChanged(t *testing.T, evc <-chan pubsub.Event[tea.Msg], workspaceID string) {
+	t.Helper()
+	deadline := time.After(2 * time.Second)
+	for {
+		select {
+		case ev, ok := <-evc:
+			if !ok {
+				t.Fatal("event channel closed before ConfigChanged arrived")
+			}
+			cc, ok := ev.Payload.(pubsub.Event[proto.ConfigChanged])
+			if !ok {
+				continue
+			}
+			require.Equal(t, workspaceID, cc.Payload.WorkspaceID)
+			return
+		case <-deadline:
+			t.Fatal("timed out waiting for ConfigChanged event")
+		}
+	}
+}
+
+// newPublishingWorkspace creates a real workspace through the backend
+// so its embedded *app.App is wired up and SendEvent works. It returns
+// the backend, the workspace, and a fresh event subscription.
+func newPublishingWorkspace(t *testing.T) (*Backend, *Workspace, <-chan pubsub.Event[tea.Msg]) {
+	t.Helper()
+	xdgIsolated(t)
+
+	cwd := t.TempDir()
+	dataDir := t.TempDir()
+
+	b := New(context.Background(), nil, func() {})
+	b.SetCreateGrace(2 * time.Second)
+	t.Cleanup(func() { drainBackend(t, b) })
+
+	cid := uuid.New().String()
+	ws, _, err := b.CreateWorkspace(protoWS(cwd, dataDir, cid))
+	require.NoError(t, err)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	return b, ws, ws.Events(ctx)
+}
+
+func TestSetConfigField_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	require.NoError(t, b.SetConfigField(ws.ID, config.ScopeGlobal, "options.debug", true))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+func TestRemoveConfigField_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	// Seed a field we can then remove. Setting also publishes, so
+	// drain the resulting event before testing remove.
+	require.NoError(t, b.SetConfigField(ws.ID, config.ScopeGlobal, "options.debug", true))
+	awaitConfigChanged(t, evc, ws.ID)
+
+	require.NoError(t, b.RemoveConfigField(ws.ID, config.ScopeGlobal, "options.debug"))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+func TestUpdatePreferredModel_PublishesConfigChanged(t *testing.T) {
+	if raceEnabled {
+		// UpdatePreferredModel writes config.Models concurrently
+		// with the agent coordinator's async sub-agent builder
+		// that reads it via buildAgentModels. That race is
+		// pre-existing in the codebase and unrelated to this
+		// item; ConfigStore mutations are not currently
+		// synchronized against background readers in [app.App].
+		// The mutator → publish wiring is unit-tested via
+		// publishConfigChanged regardless.
+		t.Skip("skipped under -race: pre-existing race between ConfigStore writes and agent coordinator startup")
+	}
+	b, ws, evc := newPublishingWorkspace(t)
+
+	model := config.SelectedModel{Provider: "openai", Model: "gpt-4"}
+	require.NoError(t, b.UpdatePreferredModel(ws.ID, config.ScopeGlobal, config.SelectedModelTypeLarge, model))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+func TestSetCompactMode_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	require.NoError(t, b.SetCompactMode(ws.ID, config.ScopeGlobal, true))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+func TestSetProviderAPIKey_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	require.NoError(t, b.SetProviderAPIKey(ws.ID, config.ScopeGlobal, "openai", "test-key"))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+func TestMarkProjectInitialized_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	require.NoError(t, b.MarkProjectInitialized(ws.ID))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+// TestImportCopilot_PublishesConfigChanged exercises the success path
+// by seeding a token file in the location ImportCopilot scans, then
+// asserting the event fires only when ok==true.
+func TestImportCopilot_PublishesConfigChanged(t *testing.T) {
+	// ImportCopilot reads from external user-state directories that
+	// vary by OS. Rather than recreate that setup, drive the
+	// publishing helper directly and assert ImportCopilot's
+	// no-event-on-not-found semantics are preserved.
+	b, ws, evc := newPublishingWorkspace(t)
+
+	// Not-found path: no token exists, so no event must fire.
+	_, ok, err := b.ImportCopilot(ws.ID)
+	require.NoError(t, err)
+	require.False(t, ok, "ImportCopilot should return ok=false when no token is present")
+
+	select {
+	case ev := <-evc:
+		if _, isCC := ev.Payload.(pubsub.Event[proto.ConfigChanged]); isCC {
+			t.Fatal("ImportCopilot must not publish ConfigChanged when nothing was imported")
+		}
+	case <-time.After(100 * time.Millisecond):
+		// Expected: no ConfigChanged.
+	}
+
+	// Helper sanity: publishing manually does fire the event.
+	publishConfigChanged(ws)
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+// TestRefreshOAuthToken_PublishesConfigChangedOnError verifies that
+// the unhappy path does not publish (mutator returned an error). The
+// happy path requires a real OAuth-capable provider configured with a
+// refreshable token, which is beyond an isolated unit test's scope.
+func TestRefreshOAuthToken_NoEventOnError(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	// Provider does not exist → store returns an error → no event.
+	err := b.RefreshOAuthToken(context.Background(), ws.ID, config.ScopeGlobal, "no-such-provider")
+	require.Error(t, err)
+
+	select {
+	case ev := <-evc:
+		if _, isCC := ev.Payload.(pubsub.Event[proto.ConfigChanged]); isCC {
+			t.Fatal("RefreshOAuthToken must not publish ConfigChanged when it errors")
+		}
+	case <-time.After(100 * time.Millisecond):
+	}
+}
+
+// TestDisableDockerMCP_PublishesConfigChanged seeds a Docker MCP entry
+// directly so DisableDockerMCP has something to remove without needing
+// a running Docker daemon for PrepareDockerMCPConfig's availability
+// probe.
+func TestDisableDockerMCP_PublishesConfigChanged(t *testing.T) {
+	b, ws, evc := newPublishingWorkspace(t)
+
+	// Persist a Docker MCP entry directly via the store so the
+	// downstream DisableDockerMCP path has something to remove.
+	require.NoError(t, ws.Cfg.PersistDockerMCPConfig(config.DockerMCPConfig()))
+	drainEvents(evc, 100*time.Millisecond)
+
+	require.NoError(t, b.DisableDockerMCP(ws.ID))
+	awaitConfigChanged(t, evc, ws.ID)
+}
+
+// drainEvents reads from evc until quiet for the given window. Used
+// to flush events emitted by setup steps so the assertion can target
+// the event from the action under test.
+func drainEvents(evc <-chan pubsub.Event[tea.Msg], quiet time.Duration) {
+	for {
+		select {
+		case <-evc:
+		case <-time.After(quiet):
+			return
+		}
+	}
+}
+
+// TestPublishConfigChanged_NilWorkspaceSafe documents that the helper
+// is safe to call on workspaces without an *app.App (e.g. synthetic
+// test workspaces).
+func TestPublishConfigChanged_NilWorkspaceSafe(t *testing.T) {
+	t.Parallel()
+	require.NotPanics(t, func() { publishConfigChanged(nil) })
+	require.NotPanics(t, func() { publishConfigChanged(&Workspace{}) })
+}

internal/backend/events.go

@@ -0,0 +1,145 @@
+package backend
+
+import (
+	"context"
+
+	tea "charm.land/bubbletea/v2"
+
+	mcptools "github.com/charmbracelet/crush/internal/agent/tools/mcp"
+	"github.com/charmbracelet/crush/internal/app"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/pubsub"
+)
+
+// SubscribeEvents returns a per-caller event channel for a workspace.
+// Each caller receives all events; multiple callers do not compete.
+func (b *Backend) SubscribeEvents(ctx context.Context, workspaceID string) (<-chan pubsub.Event[tea.Msg], error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	return ws.Events(ctx), nil
+}
+
+// GetLSPStates returns the state of all LSP clients.
+func (b *Backend) GetLSPStates(workspaceID string) (map[string]app.LSPClientInfo, error) {
+	_, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	return app.GetLSPStates(), nil
+}
+
+// GetLSPDiagnostics returns diagnostics for a specific LSP client in
+// the workspace.
+func (b *Backend) GetLSPDiagnostics(workspaceID, lspName string) (any, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	for name, client := range ws.LSPManager.Clients().Seq2() {
+		if name == lspName {
+			return client.GetDiagnostics(), nil
+		}
+	}
+
+	return nil, ErrLSPClientNotFound
+}
+
+// GetWorkspaceConfig returns the workspace-level configuration.
+func (b *Backend) GetWorkspaceConfig(workspaceID string) (*config.Config, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	return ws.Cfg.Config(), nil
+}
+
+// GetWorkspaceProviders returns the configured providers for a
+// workspace.
+func (b *Backend) GetWorkspaceProviders(workspaceID string) (any, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	providers, _ := config.Providers(ws.Cfg.Config())
+	return providers, nil
+}
+
+// LSPStart starts an LSP server for the given path.
+func (b *Backend) LSPStart(ctx context.Context, workspaceID, path string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	ws.LSPManager.Start(ctx, path)
+	return nil
+}
+
+// LSPStopAll stops all LSP servers for a workspace.
+func (b *Backend) LSPStopAll(ctx context.Context, workspaceID string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	ws.LSPManager.StopAll(ctx)
+	return nil
+}
+
+// MCPGetStates returns the current state of all MCP clients.
+func (b *Backend) MCPGetStates(_ string) map[string]mcptools.ClientInfo {
+	return mcptools.GetStates()
+}
+
+// MCPRefreshPrompts refreshes prompts for a named MCP client.
+func (b *Backend) MCPRefreshPrompts(ctx context.Context, _ string, name string) {
+	mcptools.RefreshPrompts(ctx, name)
+}
+
+// MCPRefreshResources refreshes resources for a named MCP client.
+func (b *Backend) MCPRefreshResources(ctx context.Context, _ string, name string) {
+	mcptools.RefreshResources(ctx, name)
+}
+
+// MCPPendingAuth returns the MCP servers awaiting OAuth authentication,
+// for clients that need to prompt the user. workspaceID selects the
+// workspace whose config provides the server URLs.
+func (b *Backend) MCPPendingAuth(workspaceID string) ([]mcptools.PendingAuthServer, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+	return mcptools.PendingAuthMCPs(ws.Cfg), nil
+}
+
+// MCPAuthURL returns the current OAuth authorization URL for a named
+// server, if a flow is in progress.
+func (b *Backend) MCPAuthURL(name string) string {
+	return mcptools.MCPAuthURL(name)
+}
+
+// MCPAuthenticate runs the OAuth flow for a named MCP server with the
+// local browser suppressed: the authorization URL is exposed via
+// MCPAuthURL/MCPPendingAuth for the calling client to open on the user's
+// machine. The call blocks until the flow completes, fails, or ctx is
+// cancelled. workspaceID selects the workspace whose config drives the
+// flow.
+func (b *Backend) MCPAuthenticate(ctx context.Context, workspaceID, name string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+	finish, cancel, err := mcptools.BeginAuth(ws.Cfg, name)
+	if err != nil {
+		return err
+	}
+	defer cancel()
+	return finish(ctx)
+}

internal/backend/filetracker.go

@@ -0,0 +1,37 @@
+package backend
+
+import (
+	"context"
+	"time"
+)
+
+// FileTrackerRecordRead records a file read for a session.
+func (b *Backend) FileTrackerRecordRead(ctx context.Context, workspaceID, sessionID, path string) error {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return err
+	}
+
+	ws.FileTracker.RecordRead(ctx, sessionID, path)
+	return nil
+}
+
+// FileTrackerLastReadTime returns the last read time for a file in a session.
+func (b *Backend) FileTrackerLastReadTime(ctx context.Context, workspaceID, sessionID, path string) (time.Time, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	return ws.FileTracker.LastReadTime(ctx, sessionID, path), nil
+}
+
+// FileTrackerListReadFiles returns the list of read files for a session.
+func (b *Backend) FileTrackerListReadFiles(ctx context.Context, workspaceID, sessionID string) ([]string, error) {
+	ws, err := b.GetWorkspace(workspaceID)
+	if err != nil {
+		return nil, err
+	}
+
+	return ws.FileTracker.ListReadFiles(ctx, sessionID)
+}