cli.go RawHistoryFolder

1package agent
2
3import (
4	"bufio"
5	"context"
6	"encoding/json"
7	"errors"
8	"fmt"
9	"io"
10	"os"
11	"os/signal"
12	"path/filepath"
13	"slices"
14	"strings"
15	"sync"
16	"syscall"
17	"time"
18
19	"github.com/bnema/zut/packages/agent/extensions"
20	"github.com/bnema/zut/packages/agent/extproto"
21	"github.com/bnema/zut/packages/agent/modes"
22	"github.com/bnema/zut/packages/agent/skills"
23	"github.com/bnema/zut/packages/agent/subagents"
24	"github.com/bnema/zut/packages/agent/tools"
25	"github.com/bnema/zut/packages/core"
26	"github.com/bnema/zut/packages/provider"
27	"github.com/bnema/zut/packages/provider/auth"
28	"github.com/bnema/zut/packages/tui"
29)
30
31// interactiveExtHooks is a tiny adapter that lets the extension
32// manager call back into the Interactive instance built later in
33// runInteractive. Alerts are buffered until the instance is attached so
34// an extension that signals attention during startup is not silently lost.
35// Keep the startup buffer bounded because extensions can flood their host.
36const maxBufferedInteractiveAlerts = 64
37
38type interactiveExtHooks struct {
39	mu              sync.Mutex
40	interactive     *modes.Interactive
41	pendingAlerts   []interactiveAlert
42	pendingStatuses map[string]interactiveStatus
43	pendingWidgets  map[string]interactiveWidget
44}
45
46type interactiveAlert struct {
47	extName string
48	alert   extproto.AlertRequest
49}
50
51type interactiveStatus struct {
52	extName string
53	key     string
54	level   string
55	text    string
56}
57
58type interactiveWidget struct {
59	extName  string
60	id       string
61	position string
62	title    string
63	lines    []string
64}
65
66func (h *interactiveExtHooks) iv() *modes.Interactive {
67	if h == nil {
68		return nil
69	}
70	h.mu.Lock()
71	defer h.mu.Unlock()
72	return h.interactive
73}
74
75func (h *interactiveExtHooks) attachInteractive(iv *modes.Interactive) {
76	if h == nil || iv == nil {
77		return
78	}
79	h.mu.Lock()
80	h.interactive = iv
81	pendingAlerts := h.pendingAlerts
82	pendingStatuses := h.pendingStatuses
83	pendingWidgets := h.pendingWidgets
84	h.pendingAlerts = nil
85	h.pendingStatuses = nil
86	h.pendingWidgets = nil
87	h.mu.Unlock()
88	for _, item := range pendingAlerts {
89		iv.Alert(item.extName, item.alert)
90	}
91	for _, item := range pendingStatuses {
92		iv.SetStatus(item.extName, item.key, item.level, item.text)
93	}
94	for _, item := range pendingWidgets {
95		iv.SetWidget(item.extName, item.id, item.position, item.title, item.lines)
96	}
97}
98
99func (h *interactiveExtHooks) Notify(extName, level, message string) {
100	if iv := h.iv(); iv != nil {
101		iv.Notify(extName, level, message)
102	}
103}
104func (h *interactiveExtHooks) Alert(extName string, alert extproto.AlertRequest) {
105	if h == nil {
106		return
107	}
108	h.mu.Lock()
109	if h.interactive == nil {
110		if len(h.pendingAlerts) < maxBufferedInteractiveAlerts {
111			h.pendingAlerts = append(h.pendingAlerts, interactiveAlert{extName: extName, alert: alert})
112		}
113		h.mu.Unlock()
114		return
115	}
116	iv := h.interactive
117	h.mu.Unlock()
118	iv.Alert(extName, alert)
119}
120func (h *interactiveExtHooks) Submit(text string) {
121	if iv := h.iv(); iv != nil {
122		iv.SubmitOrQueue(text, nil)
123	}
124}
125func (h *interactiveExtHooks) SubmitSlash(text string) {
126	if iv := h.iv(); iv != nil {
127		iv.SubmitSlash(text)
128	}
129}
130func (h *interactiveExtHooks) Insert(text string) {
131	if iv := h.iv(); iv != nil {
132		iv.Insert(text)
133	}
134}
135func (h *interactiveExtHooks) Display(extName, text string) {
136	if iv := h.iv(); iv != nil {
137		iv.Display(extName, text)
138	}
139}
140func (h *interactiveExtHooks) ClearNotes(extName string) {
141	if iv := h.iv(); iv != nil {
142		iv.ClearNotes(extName)
143	}
144}
145func (h *interactiveExtHooks) OpenPanel(extName string, spec extproto.PanelSpec) {
146	if iv := h.iv(); iv != nil {
147		iv.OpenPanel(extName, spec)
148	}
149}
150func (h *interactiveExtHooks) UpdatePanel(extName, panelID, title string, lines []string, footer string) {
151	if iv := h.iv(); iv != nil {
152		iv.UpdatePanel(extName, panelID, title, lines, footer)
153	}
154}
155func (h *interactiveExtHooks) ClosePanel(extName, panelID string) {
156	if iv := h.iv(); iv != nil {
157		iv.ClosePanel(extName, panelID)
158	}
159}
160func pendingChromeKey(extName, key string) string { return extName + "\x00" + key }
161
162func (h *interactiveExtHooks) SetStatus(extName, key, level, text string) {
163	if h == nil {
164		return
165	}
166	h.mu.Lock()
167	if h.interactive == nil {
168		if h.pendingStatuses == nil {
169			h.pendingStatuses = map[string]interactiveStatus{}
170		}
171		pendingKey := pendingChromeKey(extName, key)
172		if strings.TrimSpace(text) == "" {
173			delete(h.pendingStatuses, pendingKey)
174		} else {
175			h.pendingStatuses[pendingKey] = interactiveStatus{extName: extName, key: key, level: level, text: text}
176		}
177		h.mu.Unlock()
178		return
179	}
180	iv := h.interactive
181	h.mu.Unlock()
182	iv.SetStatus(extName, key, level, text)
183}
184func (h *interactiveExtHooks) SetWidget(extName, id, position, title string, lines []string) {
185	if h == nil {
186		return
187	}
188	h.mu.Lock()
189	if h.interactive == nil {
190		if h.pendingWidgets == nil {
191			h.pendingWidgets = map[string]interactiveWidget{}
192		}
193		h.pendingWidgets[pendingChromeKey(extName, id)] = interactiveWidget{
194			extName: extName, id: id, position: position, title: title, lines: append([]string(nil), lines...),
195		}
196		h.mu.Unlock()
197		return
198	}
199	iv := h.interactive
200	h.mu.Unlock()
201	iv.SetWidget(extName, id, position, title, lines)
202}
203func (h *interactiveExtHooks) ClearWidget(extName, id string) {
204	if h == nil {
205		return
206	}
207	h.mu.Lock()
208	if h.interactive == nil {
209		if h.pendingWidgets != nil {
210			delete(h.pendingWidgets, pendingChromeKey(extName, id))
211		}
212		h.mu.Unlock()
213		return
214	}
215	iv := h.interactive
216	h.mu.Unlock()
217	iv.ClearWidget(extName, id)
218}
219
220func (h *interactiveExtHooks) ClearExtensionChrome(extName string) {
221	if h == nil {
222		return
223	}
224	h.mu.Lock()
225	if h.interactive == nil {
226		prefix := extName + "\x00"
227		for key := range h.pendingStatuses {
228			if strings.HasPrefix(key, prefix) {
229				delete(h.pendingStatuses, key)
230			}
231		}
232		for key := range h.pendingWidgets {
233			if strings.HasPrefix(key, prefix) {
234				delete(h.pendingWidgets, key)
235			}
236		}
237		h.mu.Unlock()
238		return
239	}
240	iv := h.interactive
241	h.mu.Unlock()
242	iv.ClearExtensionChrome(extName)
243}
244
245// extToolAdapter bridges *extensions.Manager to the
246// ExtensionToolSource interface declared in build.go (kept narrow to
247// avoid a build->extensions import cycle). One adapter instance per
248// run; used at every Resolve point so re-built agents pick up the
249// same set of extension tools.
250type extToolAdapter struct {
251	mgr *extensions.Manager
252}
253
254var _ ExtensionToolSource = (*extToolAdapter)(nil)
255var _ ExtensionSkillSource = (*extToolAdapter)(nil)
256
257func (a *extToolAdapter) Skills() []*skills.Skill {
258	if a == nil || a.mgr == nil {
259		return nil
260	}
261	return a.mgr.Skills()
262}
263
264func (a *extToolAdapter) Tools() []ExtensionToolInfo {
265	infos := a.mgr.Tools()
266	out := make([]ExtensionToolInfo, len(infos))
267	for i, t := range infos {
268		out[i] = ExtensionToolInfo{
269			Extension:   t.Extension,
270			Name:        t.Name,
271			Description: t.Description,
272			Schema:      t.Schema,
273			Deferred:    t.Deferred,
274		}
275	}
276	return out
277}
278
279func (a *extToolAdapter) NewExtensionTool(info ExtensionToolInfo) core.Tool {
280	return extensions.NewTool(a.mgr, extensions.ToolInfo{
281		Extension:   info.Extension,
282		Name:        info.Name,
283		Description: info.Description,
284		Schema:      info.Schema,
285		Deferred:    info.Deferred,
286	})
287}
288
289// liveInteractiveAgent returns the agent currently owned by the TUI. The
290// fallback is only used before the Interactive has been constructed.
291//
292// Agent rebuilds, such as cross-provider model switches, replace the TUI's
293// agent without replacing the startup pointer held by runInteractive. Session
294// operations must therefore resolve the live agent at the time of the action.
295func liveInteractiveAgent(iv *modes.Interactive, fallback *core.Agent) *core.Agent {
296	if iv != nil {
297		return iv.Agent()
298	}
299	return fallback
300}
301
302func newSessionTransition(mu *sync.RWMutex) func(func()) {
303	return func(fn func()) {
304		mu.Lock()
305		defer mu.Unlock()
306		fn()
307	}
308}
309
310// newPersistModelCallback returns the callback used by the TUI while its
311// session transition write lock is held. It must not acquire that lock again
312// because sync.RWMutex is not reentrant.
313func newPersistModelCallback(persistMu *sync.Mutex, sess **core.Session, activeProvider, activeModel *string, notify func(string)) func(string, string) {
314	return func(providerName, model string) {
315		providerName = strings.TrimSpace(providerName)
316		model = strings.TrimSpace(model)
317
318		persistMu.Lock()
319		var sessionErr error
320		if *sess != nil {
321			sessionErr = (*sess).UpdateModel(providerName, model)
322		}
323		*activeProvider = providerName
324		*activeModel = model
325		persistMu.Unlock()
326		if sessionErr != nil {
327			if notify != nil {
328				notify("model change was not persisted: " + sessionErr.Error())
329			}
330			return
331		}
332
333		cfg, err := LoadConfig()
334		if err != nil {
335			if notify != nil {
336				notify("model changed for this run, but config could not be read: " + err.Error())
337			}
338			return
339		}
340		cfg.Provider = providerName
341		cfg.Model = model
342		if err := SaveConfig(cfg); err != nil && notify != nil {
343			notify("model changed for this run, but config could not be saved: " + err.Error())
344		}
345	}
346}
347
348func closeAgentLSP(ag *core.Agent) {
349	if ag != nil {
350		_ = tools.CloseLSPManagers(ag.ToolsSnapshot())
351	}
352}
353
354func closeResolvedLSP(r Resolved) {
355	_ = tools.CloseLSPManagers(r.ToolRegistry)
356}
357
358func trimMessagesForResume(msgs []provider.Message, keepTail int) []provider.Message {
359	if keepTail <= 0 || len(msgs) <= keepTail {
360		return provider.RepairOrphanedToolResults(msgs)
361	}
362	var out []provider.Message
363	start := len(msgs) - keepTail
364	var carriedToolNames []string
365	addToolNames := func(names []string) {
366		for _, name := range names {
367			if name == "" || slices.Contains(carriedToolNames, name) {
368				continue
369			}
370			carriedToolNames = append(carriedToolNames, name)
371		}
372	}
373	// Activation markers in the discarded prefix still affect the retained
374	// provider request. Carry them onto its first message rather than dropping
375	// deferred-tool availability when the resume tail is shortened.
376	for _, msg := range msgs[:start] {
377		addToolNames(msg.AddedToolNames)
378	}
379	// Preserve the synthetic compaction summary when present so an
380	// already-compacted session stays compacted after resume. Count it
381	// within the tail budget instead of dropping it at the exact boundary.
382	if len(msgs) > 0 && msgs[0].Meta["compaction"] == "true" && start > 0 {
383		out = append(out, msgs[0])
384		start++
385	}
386	// Avoid hydrating a tail that starts with orphan tool_result rows;
387	// provider APIs require those to be paired with an earlier tool_use.
388	for start < len(msgs) && msgs[start].Role == provider.RoleTool {
389		start++
390	}
391	out = append(out, msgs[start:]...)
392	if len(carriedToolNames) > 0 && len(out) > 0 {
393		first := out[0]
394		for _, name := range first.AddedToolNames {
395			addToolNames([]string{name})
396		}
397		first.AddedToolNames = append([]string(nil), carriedToolNames...)
398		out[0] = first
399	}
400	return provider.RepairOrphanedToolResults(out)
401}
402
403// sessionResumeCandidate contains all state needed to resume a session.
404// It is deliberately assembled before the caller changes any live state:
405// opening the transcript, reading usage, and rebuilding a provider/model
406// must all succeed before the candidate can replace the current session.
407type sessionResumeCandidate struct {
408	session          *core.Session
409	agent            *core.Agent
410	messages         []provider.Message
411	fullMessageCount int
412	cumulative       provider.Usage
413	lastTurn         provider.Usage
414	provider         string
415	model            string
416	rebuilt          bool
417}
418
419// prepareSessionResume opens and validates a selected session without
420// touching the current agent. Missing provider/model metadata is treated as
421// legacy metadata: the current agent is reused, preserving compatibility
422// with sessions written before those fields were persisted.
423//
424// The returned candidate owns session until its caller commits it. On any
425// error this function closes the candidate session and leaves the current
426// agent untouched.
427func prepareSessionResume(path string, current *core.Agent, currentProvider, currentModel string, buildAgentFor func(string, string) (*core.Agent, string, string, error)) (sessionResumeCandidate, error) {
428	return prepareSessionResumeWithOptions(path, current, currentProvider, currentModel, false, false, buildAgentFor)
429}
430
431// prepareSessionResumeWithOptions is the provider/model-aware implementation.
432// An explicit CLI provider or model keeps that field authoritative; an empty
433// field falls back to the selected session's metadata when it is complete.
434func prepareSessionResumeWithOptions(path string, current *core.Agent, currentProvider, currentModel string, explicitProvider, explicitModel bool, buildAgentFor func(string, string) (*core.Agent, string, string, error)) (candidate sessionResumeCandidate, err error) {
435	if current == nil {
436		return candidate, fmt.Errorf("no agent running; log in first")
437	}
438
439	sess, msgs, err := core.OpenSession(path)
440	if err != nil {
441		return candidate, err
442	}
443	keepSession := false
444	defer func() {
445		if !keepSession {
446			_ = sess.Close()
447		}
448	}()
449
450	cumulative, lastTurn, err := core.SessionUsageDetail(path)
451	if err != nil {
452		return candidate, fmt.Errorf("read session usage: %w", err)
453	}
454
455	fullMessageCount := len(msgs)
456	resumedMessages := trimMessagesForResume(msgs, 100)
457	storedProvider := strings.TrimSpace(sess.Meta.Provider)
458	storedModel := strings.TrimSpace(sess.Meta.Model)
459	currentProvider = strings.TrimSpace(currentProvider)
460	currentModel = strings.TrimSpace(currentModel)
461
462	candidate = sessionResumeCandidate{
463		session:          sess,
464		agent:            current,
465		messages:         resumedMessages,
466		fullMessageCount: fullMessageCount,
467		cumulative:       cumulative,
468		lastTurn:         lastTurn,
469		provider:         currentProvider,
470		model:            currentModel,
471	}
472
473	// Old sessions may have either field absent. Only a complete stored
474	// selection is actionable; otherwise resume exactly as older zut did.
475	if storedProvider == "" || storedModel == "" {
476		keepSession = true
477		return candidate, nil
478	}
479
480	resumeProvider := storedProvider
481	if explicitProvider {
482		resumeProvider = currentProvider
483	}
484	resumeModel := storedModel
485	if explicitModel {
486		resumeModel = currentModel
487	}
488	if resumeProvider == currentProvider && resumeModel == currentModel {
489		keepSession = true
490		return candidate, nil
491	}
492	if buildAgentFor == nil {
493		return sessionResumeCandidate{}, fmt.Errorf("cannot resume session with provider %q and model %q: no agent builder configured", resumeProvider, resumeModel)
494	}
495
496	rebuilt, resolvedProvider, resolvedModel, err := buildAgentFor(resumeProvider, resumeModel)
497	if err != nil {
498		return sessionResumeCandidate{}, fmt.Errorf("rebuild agent for session provider %q/model %q: %w", resumeProvider, resumeModel, err)
499	}
500	if rebuilt == nil {
501		return sessionResumeCandidate{}, fmt.Errorf("rebuild agent for session provider %q/model %q returned no agent", resumeProvider, resumeModel)
502	}
503	resolvedProvider = strings.TrimSpace(resolvedProvider)
504	resolvedModel = strings.TrimSpace(resolvedModel)
505	if resolvedProvider == "" {
506		resolvedProvider = storedProvider
507	}
508	if resolvedModel == "" {
509		resolvedModel = storedModel
510	}
511
512	// Hydrate and seed the replacement while it is still private. The live
513	// agent is not modified until the caller commits the complete candidate.
514	rebuilt.SetMessages(resumedMessages)
515	rebuilt.SeedCost(cumulative)
516	rebuilt.SeedLastTurnUsage(lastTurn)
517	candidate.agent = rebuilt
518	candidate.provider = resolvedProvider
519	candidate.model = resolvedModel
520	candidate.rebuilt = true
521	keepSession = true
522	return candidate, nil
523}
524
525// buildNonInteractiveSessionAgent constructs a provider/model-specific agent
526// for startup resume while preserving the cwd sandbox and extension tools that
527// were attached to the initial resolution.
528func buildNonInteractiveSessionAgent(ctx context.Context, args Args, base Resolved, extMgr *extensions.Manager, providerName, model string) (*core.Agent, string, string, error) {
529	next := args
530	next.Provider = providerName
531	next.Model = model
532	resolved, err := Resolve(next, true)
533	if err != nil {
534		return nil, "", "", err
535	}
536	resolved.UseSandbox(base.Sandbox)
537	if extMgr != nil {
538		resolved.MergeExtensionTools(&extToolAdapter{mgr: extMgr})
539	}
540	ag := resolved.NewAgent()
541	wireNonInteractiveAgentExtHooks(ctx, ag, extMgr)
542	return ag, resolved.Provider, resolved.Model, nil
543}
544
545// applySessionResume shares the startup gate, candidate hydration, and
546// commit order used by interactive and non-interactive session opening. The
547// old append handle is closed only after the candidate has been prepared and
548// seeded successfully.
549func applySessionResume(sess *core.Session, ag *core.Agent, currentProvider, currentModel string, explicitProvider, explicitModel bool, buildAgentFor func(string, string) (*core.Agent, string, string, error)) (sessionResumeCandidate, error) {
550	candidate := sessionResumeCandidate{
551		session:          sess,
552		agent:            ag,
553		fullMessageCount: 0,
554		provider:         currentProvider,
555		model:            currentModel,
556	}
557	if ag != nil {
558		candidate.fullMessageCount = len(ag.Messages())
559	}
560	if sess == nil || ag == nil {
561		return candidate, nil
562	}
563	// A newly created meta-only session is already on the active pair. Avoid
564	// reopening and closing it through the resume path: Close intentionally
565	// removes fresh empty sessions, and a second append handle would otherwise
566	// keep an unlinked file alive.
567	if len(ag.Messages()) == 0 &&
568		strings.TrimSpace(sess.Meta.Provider) == strings.TrimSpace(currentProvider) &&
569		strings.TrimSpace(sess.Meta.Model) == strings.TrimSpace(currentModel) {
570		return candidate, nil
571	}
572	candidate, err := prepareSessionResumeWithOptions(sess.Path, ag, currentProvider, currentModel, explicitProvider, explicitModel, buildAgentFor)
573	if err != nil {
574		_ = sess.Close()
575		return sessionResumeCandidate{}, err
576	}
577	if !candidate.rebuilt {
578		candidate.agent.SetMessages(candidate.messages)
579		candidate.agent.SeedCost(candidate.cumulative)
580		candidate.agent.SeedLastTurnUsage(candidate.lastTurn)
581	}
582	_ = sess.Close()
583	return candidate, nil
584}
585
586// applyInitialSessionResume applies the same provider/model-aware candidate
587// contract used by interactive session switching to non-interactive startup
588// modes. The returned session owns the replacement append handle.
589func applyInitialSessionResume(ctx context.Context, args Args, base Resolved, extMgr *extensions.Manager, sess *core.Session, ag *core.Agent) (*core.Session, *core.Agent, string, string, error) {
590	candidate, err := applySessionResume(sess, ag, base.Provider, base.Model,
591		strings.TrimSpace(args.Provider) != "", strings.TrimSpace(args.Model) != "", func(providerName, model string) (*core.Agent, string, string, error) {
592			return buildNonInteractiveSessionAgent(ctx, args, base, extMgr, providerName, model)
593		})
594	if err != nil {
595		return nil, ag, "", "", err
596	}
597	return candidate.session, candidate.agent, candidate.provider, candidate.model, nil
598}
599
600// fanoutAgentEvent translates a core.AgentEvent into the wire-format
601// EventFromHost and pushes it through the extension manager. Only
602// the events that have a clear extension-facing meaning are
603// forwarded; internal-only ones (text_delta, tool_progress) are
604// dropped to keep the per-extension stream sane.
605func sessionContext(sess *core.Session) *extproto.SessionContext {
606	if sess == nil {
607		return nil
608	}
609	return &extproto.SessionContext{
610		ID:        sess.Meta.ID,
611		ParentID:  sess.Meta.Parent,
612		Path:      sess.Path,
613		CWD:       sess.Meta.CWD,
614		ForkPoint: sess.Meta.ForkPoint,
615	}
616}
617
618func announceSession(mgr *extensions.Manager, sess *core.Session) {
619	if mgr == nil {
620		return
621	}
622	var states map[string]json.RawMessage
623	if sess != nil {
624		states = copyExtensionStates(sess.ExtensionState)
625	}
626	mgr.EmitSessionEvent("session_start", sessionContext(sess), states)
627	if sess != nil {
628		mgr.EmitSessionEvent("session_opened", sessionContext(sess), states)
629	}
630}
631
632func copyExtensionStates(states map[string]json.RawMessage) map[string]json.RawMessage {
633	if len(states) == 0 {
634		return nil
635	}
636	out := make(map[string]json.RawMessage, len(states))
637	for name, state := range states {
638		out[name] = append(json.RawMessage(nil), state...)
639	}
640	return out
641}
642
643func persistExtensionToolResult(mgr *extensions.Manager, sess *core.Session, result core.ToolResult) {
644	if sess == nil {
645		return
646	}
647	details, ok := result.Details.(extensions.ToolResultDetails)
648	if !ok || details.Extension == "" || len(details.State) == 0 {
649		return
650	}
651	if err := sess.AppendExtensionState(details.Extension, details.State); err != nil {
652		fmt.Fprintf(os.Stderr, "extension state: %v\n", err)
653		return
654	}
655	if mgr != nil {
656		mgr.UpdateSessionState(details.Extension, details.State)
657	}
658}
659
660func fanoutAgentEvent(mgr *extensions.Manager, ev core.AgentEvent) {
661	if mgr == nil {
662		return
663	}
664	switch e := ev.(type) {
665	case core.EvTurnStart:
666		mgr.EmitEvent(extproto.EventFromHost{Event: "turn_start", Step: e.Step})
667	case core.EvToolCall:
668		mgr.EmitEvent(extproto.EventFromHost{
669			Event: "tool_call", ToolID: e.ID, ToolName: e.Name, ToolArgs: e.Args,
670		})
671	case core.EvAssistantMessage:
672		// Concat the visible text portions of the message; binary
673		// blocks (tool_use, etc.) are skipped because subscribers
674		// usually want a string they can grep / display.
675		var text string
676		for _, c := range e.Message.Content {
677			if tb, ok := c.(provider.TextBlock); ok {
678				text += tb.Text
679			}
680		}
681		mgr.EmitEvent(extproto.EventFromHost{Event: "assistant_message", Text: text})
682	case core.EvTurnEnd:
683		ev := extproto.EventFromHost{Event: "turn_end", Stop: string(e.Stop)}
684		if e.Err != nil {
685			ev.Error = e.Err.Error()
686		}
687		mgr.EmitEvent(ev)
688	}
689}
690
691// Run is the top-level entrypoint for the zut binary.
692func Run(rawArgs []string, version string) error {
693	// Extension installs can invoke external build and clone processes.
694	// Give those processes a cancellation context without changing signal
695	// handling for the interactive modes below.
696	extCtx := context.Background()
697	stopExtContext := func() {}
698	if len(rawArgs) > 0 && rawArgs[0] == "ext" {
699		extCtx, stopExtContext = signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
700	}
701	defer stopExtContext()
702
703	// Subcommand router: `zut bot ...` is handled separately so the
704	// generic flag parser doesn't reject "bot" as a positional arg.
705	if handled, err := runBotCommand(rawArgs, version); handled {
706		return err
707	}
708	if handled, err := runExtCommand(extCtx, rawArgs, version); handled {
709		return err
710	}
711	if handled, err := runUpdateCommand(rawArgs, version); handled {
712		return err
713	}
714	if handled, err := runZutfileCommand(rawArgs, version); handled {
715		return err
716	}
717	return runWithArgsRaw(rawArgs, version)
718}
719
720func runWithArgsRaw(rawArgs []string, version string) error {
721	// `zut rpc` is shorthand for `zut --rpc` so third-party apps can
722	// spawn the binary with a clean argv. Strip the leading 'rpc'
723	// token and let the rest flow through the normal arg parser.
724	if len(rawArgs) > 0 && rawArgs[0] == "rpc" {
725		rawArgs = append([]string{"--rpc"}, rawArgs[1:]...)
726	}
727
728	args, err := ParseArgs(rawArgs)
729	if err != nil {
730		PrintHelp(version)
731		return err
732	}
733	if args.Help {
734		PrintHelp(version)
735		return nil
736	}
737	if args.Version {
738		fmt.Println("zut", version)
739		return nil
740	}
741	// Model catalog: load any cached discovery data before we inspect
742	// the model list (list-models, print/json, interactive).
743	prepareRuntimeCatalog()
744
745	if args.ListModels {
746		printModels()
747		return nil
748	}
749
750	return runWithArgs(args, version)
751}
752
753func runWithArgs(args Args, version string) error {
754	ctx := context.Background()
755	switch args.Mode {
756	case ModePrint:
757		return runPrintMode(ctx, args, version)
758	case ModeStream:
759		return runStreamMode(ctx, args, version)
760	case ModeJSON:
761		return runJSONMode(ctx, args, version)
762	case ModeRPC:
763		return runRPCMode(ctx, args, version)
764	case ModeSubagentWorker:
765		return runSubagentWorkerMode(ctx, args, version)
766	default:
767		return runInteractive(ctx, args, version)
768	}
769}
770
771// ---- print / json modes: require credentials, run single-shot ----
772
773// nonInteractiveExtHooks is the HostHooks impl used by print / json
774// modes. They have no TUI, so notify / display go to stderr and
775// submit / insert are no-ops (the extension can't steer a
776// single-shot run once it's in flight anyway).
777type nonInteractiveExtHooks struct{}
778
779func (nonInteractiveExtHooks) Notify(ext, level, message string) {
780	fmt.Fprintf(os.Stderr, "[%s] %s: %s\n", ext, level, message)
781}
782func (nonInteractiveExtHooks) Alert(string, extproto.AlertRequest)                  {}
783func (nonInteractiveExtHooks) Submit(string)                                        {}
784func (nonInteractiveExtHooks) SubmitSlash(string)                                   {}
785func (nonInteractiveExtHooks) Insert(string)                                        {}
786func (nonInteractiveExtHooks) Display(string, string)                               {}
787func (nonInteractiveExtHooks) ClearNotes(string)                                    {}
788func (nonInteractiveExtHooks) OpenPanel(string, extproto.PanelSpec)                 {}
789func (nonInteractiveExtHooks) UpdatePanel(string, string, string, []string, string) {}
790func (nonInteractiveExtHooks) ClosePanel(string, string)                            {}
791func (nonInteractiveExtHooks) SetStatus(string, string, string, string)             {}
792func (nonInteractiveExtHooks) SetWidget(string, string, string, string, []string)   {}
793func (nonInteractiveExtHooks) ClearWidget(string, string)                           {}
794
795// setupNonInteractiveExtensions loads --ext paths and (unless
796// --no-ext) runs discovery. Returns the manager so the caller can
797// wire tools into the resolved registry, and a cleanup closure to
798// defer. Mirrors the interactive-mode setup minus the TUI hooks.
799func setupNonInteractiveExtensions(ctx context.Context, args Args, r *Resolved, version string) (*extensions.Manager, func()) {
800	extMgr := extensions.New(ZutHome(), r.CWD, version, r.Provider, r.Model, nonInteractiveExtHooks{})
801	for _, e := range extMgr.LoadExplicit(ctx, args.Exts) {
802		fmt.Fprintln(os.Stderr, "extension load:", e)
803	}
804	if !args.NoExt {
805		for _, e := range extMgr.Discover(ctx) {
806			fmt.Fprintln(os.Stderr, "extension load:", e)
807		}
808	}
809	extMgr.WaitForReady(3 * time.Second)
810	r.MergeExtensionTools(&extToolAdapter{mgr: extMgr})
811	return extMgr, func() { extMgr.Stop(2 * time.Second) }
812}
813
814// wireNonInteractiveAgentExtHooks installs the same BeforeToolExecute
815// / BeforeTurn / BeforeAssistantMessage / OnEvent hooks the
816// interactive path wires up, so extensions get their normal
817// event-intercept surface in print / json / rpc flows too.
818func wireNonInteractiveAgentExtHooks(ctx context.Context, ag *core.Agent, extMgr *extensions.Manager) {
819	if ag == nil || extMgr == nil {
820		return
821	}
822	ag.BeforeToolExecute = func(call provider.ToolCallBlock) (bool, string, json.RawMessage) {
823		res := extMgr.InterceptToolCall(ctx, call.ID, call.Name, call.Arguments)
824		if res.Block {
825			return false, res.Reason, nil
826		}
827		return true, "", res.ModifiedArgs
828	}
829	ag.BeforeTurnContext = func(turnCtx context.Context, step int) (bool, string, string) {
830		res := extMgr.InterceptTurnStart(turnCtx, step)
831		return !res.Block, res.Reason, res.Context
832	}
833	ag.BeforeAssistantMessage = func(text string) (bool, string, string) {
834		res := extMgr.InterceptAssistantMessage(ctx, text)
835		if res.Block {
836			return false, res.Reason, ""
837		}
838		return true, "", res.ReplaceText
839	}
840	ag.OnEvent = func(ev core.AgentEvent) { fanoutAgentEvent(extMgr, ev) }
841}
842
843type printStats struct {
844	Provider              string `json:"provider"`
845	Model                 string `json:"model"`
846	PromptTokens          int    `json:"prompt_tokens"`
847	ReasoningTokens       *int   `json:"reasoning_tokens"`
848	GeneratedOutputTokens int    `json:"generated_output_tokens"`
849	ElapsedMS             int64  `json:"elapsed_ms"`
850}
851
852func writePrintStats(path, providerID, model string, usage provider.Usage, elapsed time.Duration) error {
853	var reasoning *int
854	generated := usage.OutputTokens
855	if usage.ReasoningTokensKnown {
856		count := usage.ReasoningTokens
857		reasoning = &count
858		generated -= count
859		if generated < 0 {
860			generated = 0
861		}
862	}
863	stats := printStats{
864		Provider:              providerID,
865		Model:                 model,
866		PromptTokens:          usage.InputTokens + usage.CacheReadTokens + usage.CacheWriteTokens,
867		ReasoningTokens:       reasoning,
868		GeneratedOutputTokens: generated,
869		ElapsedMS:             elapsed.Milliseconds(),
870	}
871	data, err := json.MarshalIndent(stats, "", "  ")
872	if err != nil {
873		return fmt.Errorf("encode stats: %w", err)
874	}
875	data = append(data, '\n')
876	if err := os.WriteFile(path, data, 0o644); err != nil {
877		return fmt.Errorf("write stats %q: %w", path, err)
878	}
879	return nil
880}
881
882func runPrintMode(ctx context.Context, args Args, version string) error {
883	if args.NoYolo {
884		fmt.Fprintln(os.Stderr, "warning: --no-yolo has no effect in print mode (no interactive prompt available); tools will run without confirmation")
885	}
886	r, err := Resolve(args, true)
887	if err != nil {
888		return err
889	}
890	extMgr, stopExt := setupNonInteractiveExtensions(ctx, args, &r, version)
891	defer stopExt()
892
893	ag := r.NewAgent()
894	initialAg := ag
895	defer func() {
896		closeAgentLSP(ag)
897		if ag != initialAg {
898			closeAgentLSP(initialAg)
899		}
900	}()
901	wireNonInteractiveAgentExtHooks(ctx, ag, extMgr)
902	sess, err := openOrCreateSession(args, r, ag, version)
903	if err != nil {
904		return err
905	}
906	if sess != nil {
907		var providerName, model string
908		sess, ag, providerName, model, err = applyInitialSessionResume(ctx, args, r, extMgr, sess, ag)
909		if err != nil {
910			return err
911		}
912		r.Provider, r.Model = providerName, model
913		ag.OnToolResult = func(_ string, result core.ToolResult) { persistExtensionToolResult(extMgr, sess, result) }
914		defer sess.Close()
915	}
916	announceSession(extMgr, sess)
917
918	prompt := args.Prompt
919	if prompt == "" {
920		piped, _ := readAllStdin()
921		prompt = strings.TrimSpace(piped)
922	}
923	if prompt == "" {
924		return fmt.Errorf("print mode requires a prompt (arg or stdin)")
925	}
926
927	start := len(ag.Messages())
928	if err := runZutfileStartupPre(ctx, args.StartupPre, r.CWD, r.Sandbox, ag, nil, os.Stderr); err != nil {
929		return err
930	}
931	if err := reloadResourcesAfterStartupPre(ctx, args, extMgr, r.Sandbox, ag); err != nil {
932		return err
933	}
934	started := time.Now()
935	usage, err := modes.RunPrint(ctx, ag, prompt, nil, os.Stdout)
936	elapsed := time.Since(started)
937	WriteNewTranscript(ag, sess, start)
938	if err != nil {
939		return err
940	}
941	if args.StatsPath != "" {
942		return writePrintStats(args.StatsPath, r.Provider, r.Model, usage, elapsed)
943	}
944	return nil
945}
946
947func runStreamMode(ctx context.Context, args Args, version string) error {
948	if args.NoYolo {
949		fmt.Fprintln(os.Stderr, "warning: --no-yolo has no effect in stream mode (no interactive prompt available); tools will run without confirmation")
950	}
951	r, err := Resolve(args, true)
952	if err != nil {
953		return err
954	}
955	extMgr, stopExt := setupNonInteractiveExtensions(ctx, args, &r, version)
956	defer stopExt()
957
958	ag := r.NewAgent()
959	initialAg := ag
960	defer func() {
961		closeAgentLSP(ag)
962		if ag != initialAg {
963			closeAgentLSP(initialAg)
964		}
965	}()
966	wireNonInteractiveAgentExtHooks(ctx, ag, extMgr)
967	sess, err := openOrCreateSession(args, r, ag, version)
968	if err != nil {
969		return err
970	}
971	if sess != nil {
972		var providerName, model string
973		sess, ag, providerName, model, err = applyInitialSessionResume(ctx, args, r, extMgr, sess, ag)
974		if err != nil {
975			return err
976		}
977		r.Provider, r.Model = providerName, model
978		ag.OnToolResult = func(_ string, result core.ToolResult) { persistExtensionToolResult(extMgr, sess, result) }
979		defer sess.Close()
980	}
981	announceSession(extMgr, sess)
982
983	prompt := args.Prompt
984	if prompt == "" {
985		piped, _ := readAllStdin()
986		prompt = strings.TrimSpace(piped)
987	}
988	if prompt == "" {
989		return fmt.Errorf("stream mode requires a prompt (arg or stdin)")
990	}
991
992	start := len(ag.Messages())
993	preSink, finishPre := newStreamTextSink(os.Stdout)
994	if err := runZutfileStartupPre(ctx, args.StartupPre, r.CWD, r.Sandbox, ag, preSink, os.Stderr); err != nil {
995		finishPre()
996		return err
997	}
998	finishPre()
999	if err := reloadResourcesAfterStartupPre(ctx, args, extMgr, r.Sandbox, ag); err != nil {
1000		return err
1001	}
1002	err = modes.RunStream(ctx, ag, prompt, nil, os.Stdout)
1003	WriteNewTranscript(ag, sess, start)
1004	return err
1005}
1006
1007func newStreamTextSink(out io.Writer) (func(core.AgentEvent), func()) {
1008	var streamed, wroteText, lastWasNL bool
1009	writeText := func(text string) {
1010		if text == "" {
1011			return
1012		}
1013		_, _ = fmt.Fprint(out, text)
1014		if syncer, ok := out.(interface{ Sync() error }); ok {
1015			_ = syncer.Sync()
1016		}
1017		wroteText = true
1018		lastWasNL = strings.HasSuffix(text, "\n")
1019	}
1020	sink := func(ev core.AgentEvent) {
1021		switch e := ev.(type) {
1022		case core.EvAssistantStart:
1023			streamed = false
1024		case core.EvTextDelta:
1025			streamed = true
1026			writeText(e.Delta)
1027		case core.EvAssistantMessage:
1028			if streamed {
1029				return
1030			}
1031			var text strings.Builder
1032			for _, content := range e.Message.Content {
1033				if block, ok := content.(provider.TextBlock); ok {
1034					if text.Len() > 0 {
1035						text.WriteString("\n")
1036					}
1037					text.WriteString(block.Text)
1038				}
1039			}
1040			writeText(text.String())
1041		}
1042	}
1043	finish := func() {
1044		if wroteText && !lastWasNL {
1045			writeText("\n")
1046		}
1047	}
1048	return sink, finish
1049}
1050
1051func runJSONMode(ctx context.Context, args Args, version string) error {
1052	if args.NoYolo {
1053		fmt.Fprintln(os.Stderr, "warning: --no-yolo has no effect in json mode (no interactive prompt available); tools will run without confirmation")
1054	}
1055	r, err := Resolve(args, true)
1056	if err != nil {
1057		return err
1058	}
1059	extMgr, stopExt := setupNonInteractiveExtensions(ctx, args, &r, version)
1060	defer stopExt()
1061
1062	ag := r.NewAgent()
1063	initialAg := ag
1064	defer func() {
1065		closeAgentLSP(ag)
1066		if ag != initialAg {
1067			closeAgentLSP(initialAg)
1068		}
1069	}()
1070	wireNonInteractiveAgentExtHooks(ctx, ag, extMgr)
1071	sess, err := openOrCreateSession(args, r, ag, version)
1072	if err != nil {
1073		return err
1074	}
1075	if sess != nil {
1076		var providerName, model string
1077		sess, ag, providerName, model, err = applyInitialSessionResume(ctx, args, r, extMgr, sess, ag)
1078		if err != nil {
1079			return err
1080		}
1081		r.Provider, r.Model = providerName, model
1082		ag.OnToolResult = func(_ string, result core.ToolResult) { persistExtensionToolResult(extMgr, sess, result) }
1083		defer sess.Close()
1084	}
1085	announceSession(extMgr, sess)
1086
1087	prompt := args.Prompt
1088	if prompt == "" {
1089		piped, _ := readAllStdin()
1090		prompt = strings.TrimSpace(piped)
1091	}
1092	if prompt == "" {
1093		return fmt.Errorf("json mode requires a prompt (arg or stdin)")
1094	}
1095
1096	start := len(ag.Messages())
1097	enc := json.NewEncoder(os.Stdout)
1098	preSink := func(ev core.AgentEvent) {
1099		_ = enc.Encode(modes.EventToJSON(ev))
1100	}
1101	if err := runZutfileStartupPre(ctx, args.StartupPre, r.CWD, r.Sandbox, ag, preSink, os.Stderr); err != nil {
1102		_ = enc.Encode(map[string]any{"type": "error", "message": err.Error()})
1103		return err
1104	}
1105	if err := reloadResourcesAfterStartupPre(ctx, args, extMgr, r.Sandbox, ag); err != nil {
1106		_ = enc.Encode(map[string]any{"type": "error", "message": err.Error()})
1107		return err
1108	}
1109	err = modes.RunJSON(ctx, ag, prompt, nil, os.Stdout)
1110	WriteNewTranscript(ag, sess, start)
1111	return err
1112}
1113
1114// runZutfileStartupPre runs entry.pre before the main non-interactive prompt.
1115// "!command" values execute via BashTool; other values are sent as an agent turn.
1116// shellOut receives live shell chunks (typically os.Stderr); sink receives
1117// agent events for plain-text pre (stream mode wires a live text sink).
1118func runZutfileStartupPre(ctx context.Context, pre, cwd string, sandbox *tools.Sandbox, ag *core.Agent, sink func(core.AgentEvent), shellOut io.Writer) error {
1119	pre = strings.TrimSpace(pre)
1120	if pre == "" {
1121		return nil
1122	}
1123	if cmd, ok := modes.ShellEscapeCommand(pre); ok {
1124		raw, err := json.Marshal(map[string]any{"command": cmd})
1125		if err != nil {
1126			return err
1127		}
1128		if shellOut != nil {
1129			fmt.Fprintf(shellOut, "$ %s\n", cmd)
1130			if f, ok := shellOut.(interface{ Sync() error }); ok {
1131				_ = f.Sync()
1132			}
1133		}
1134		progress := func(chunk string) {
1135			if shellOut == nil || chunk == "" {
1136				return
1137			}
1138			fmt.Fprint(shellOut, chunk)
1139			if f, ok := shellOut.(interface{ Sync() error }); ok {
1140				_ = f.Sync()
1141			}
1142		}
1143		bash := &tools.BashTool{CWD: cwd, Sandbox: sandbox}
1144		res, err := bash.Execute(ctx, raw, progress)
1145		if err != nil {
1146			return fmt.Errorf("zutfile entry.pre: %w", err)
1147		}
1148		if res.IsError {
1149			var sb strings.Builder
1150			for _, c := range res.Content {
1151				if tb, ok := c.(provider.TextBlock); ok {
1152					sb.WriteString(tb.Text)
1153				}
1154			}
1155			msg := strings.TrimSpace(sb.String())
1156			if msg == "" {
1157				msg = "command failed"
1158			}
1159			return fmt.Errorf("zutfile entry.pre: %s", msg)
1160		}
1161		return nil
1162	}
1163	if ag == nil {
1164		return fmt.Errorf("zutfile entry.pre requires an agent for non-shell prompts")
1165	}
1166	if sink == nil {
1167		sink = func(core.AgentEvent) {}
1168	}
1169	return ag.Prompt(ctx, pre, nil, sink)
1170}
1171
1172var errInteractiveAgentChanged = errors.New("interactive agent or web-search policy changed during prompt refresh")
1173
1174// refreshAgentToolsAndPrompt re-resolves tools (including rediscovered
1175// skills and currently loaded extension tools) and updates the live
1176// agent's registry and system prompt. Used after /reload-ext and after
1177// zutfile entry.pre installs new skills or extensions.
1178// mutateRegistry, if non-nil, can inject session-specific tools (e.g. subagent_spawn).
1179// interactive, when non-nil, serializes the final commit with agent replacement.
1180func refreshAgentToolsAndPrompt(args Args, sharedSandbox *tools.Sandbox, extToolAdapter ExtensionToolSource, ag *core.Agent, mutateRegistry func(core.Registry) core.Registry, interactive *modes.Interactive) (subagents.WebSearchPolicy, error) {
1181	if ag == nil {
1182		return subagents.WebSearchDeny, nil
1183	}
1184	var webSearchPolicyGeneration uint64
1185	if interactive != nil {
1186		// Capture before Resolve: the final commit must fail if settings,
1187		// Telegram attachment, or a newer registry commit changes policy while
1188		// filesystem/config/extension discovery is in flight.
1189		webSearchPolicyGeneration = interactive.WebSearchPolicyGeneration()
1190	}
1191	resolved, err := Resolve(args, true)
1192	if err != nil {
1193		return subagents.WebSearchDeny, fmt.Errorf("refresh agent prompt and tools: %w", err)
1194	}
1195	if sharedSandbox != nil {
1196		resolved.UseSandbox(sharedSandbox)
1197	}
1198	if extToolAdapter != nil {
1199		resolved.MergeExtensionTools(extToolAdapter)
1200	}
1201	reg := resolved.ToolRegistry
1202	if resolved.WebSearchPolicy != subagents.WebSearchAllow {
1203		delete(reg, "web_search")
1204	}
1205	if mutateRegistry != nil {
1206		reg = mutateRegistry(reg)
1207	}
1208	if interactive != nil {
1209		oldTools, applied := interactive.ApplyAgentPromptConfigAtWebSearchGeneration(ag, resolved.SystemPrompt, reg, webSearchPolicyGeneration)
1210		if !applied {
1211			_ = tools.CloseLSPManagers(reg)
1212			return subagents.WebSearchDeny, errInteractiveAgentChanged
1213		}
1214		interactive.DeferUntilIdle(func() {
1215			_ = tools.CloseLSPManagers(oldTools)
1216		})
1217		return webSearchPolicyForRegistry(resolved.WebSearchPolicy, ag.ToolsSnapshot()), nil
1218	}
1219	oldTools := ag.SetPromptConfig(resolved.SystemPrompt, reg)
1220	_ = tools.CloseLSPManagers(oldTools)
1221	return webSearchPolicyForRegistry(resolved.WebSearchPolicy, reg), nil
1222}
1223
1224func webSearchPolicyForRegistry(policy subagents.WebSearchPolicy, reg core.Registry) subagents.WebSearchPolicy {
1225	if policy == subagents.WebSearchAllow {
1226		if _, ok := reg["web_search"]; ok {
1227			return subagents.WebSearchAllow
1228		}
1229	}
1230	return subagents.WebSearchDeny
1231}
1232
1233func webSearchToolAllowedForSession(args Args) bool {
1234	if args.NoTools || args.PermissionSet != nil {
1235		return false
1236	}
1237	if args.ToolsSet || len(args.Tools) > 0 {
1238		return toolListContains(args.Tools, "web_search")
1239	}
1240	return true
1241}
1242
1243func webSearchExplicitlyEnabledForSession(args Args) bool {
1244	return !args.NoTools && args.PermissionSet == nil && (args.ToolsSet || len(args.Tools) > 0) && toolListContains(args.Tools, "web_search")
1245}
1246
1247// reloadResourcesAfterStartupPre reloads extensions (if any) and
1248// refreshes the agent tool registry + system prompt so skills/extensions
1249// installed by entry.pre are visible to the following turn.
1250func reloadResourcesAfterStartupPre(ctx context.Context, args Args, extMgr *extensions.Manager, sharedSandbox *tools.Sandbox, ag *core.Agent) error {
1251	if strings.TrimSpace(args.StartupPre) == "" || ag == nil {
1252		return nil
1253	}
1254	adapter := &extToolAdapter{mgr: extMgr}
1255	if extMgr != nil {
1256		_ = extMgr.Reload(ctx, 2*time.Second)
1257	}
1258	_, err := refreshAgentToolsAndPrompt(args, sharedSandbox, adapter, ag, nil, nil)
1259	return err
1260}
1261
1262// ---- interactive mode: opens the TUI even without credentials ----
1263
1264func subagentPolicyFromConfig(cfg SubagentsConfig) subagents.SubagentPolicy {
1265	parseDuration := func(value string) time.Duration {
1266		if strings.TrimSpace(value) == "" {
1267			return 0
1268		}
1269		parsed, err := time.ParseDuration(strings.TrimSpace(value))
1270		if err != nil || parsed <= 0 {
1271			return 0
1272		}
1273		return parsed
1274	}
1275	return subagents.SubagentPolicy{
1276		MaxConcurrent:          cfg.MaxConcurrent,
1277		MaxConcurrentPerParent: cfg.MaxConcurrentPerParent,
1278		QueueTimeout:           parseDuration(cfg.QueueTimeout),
1279		DefaultTimeout:         parseDuration(cfg.DefaultTimeout),
1280		MaxTurns:               cfg.MaxTurns,
1281		MaxOutputBytes:         cfg.MaxOutputBytes,
1282		MaxOutputLines:         cfg.MaxOutputLines,
1283		AllowedTools:           append([]string(nil), cfg.AllowedTools...),
1284		AllowedRoots:           append([]string(nil), cfg.AllowedRoots...),
1285		HeartbeatInterval:      parseDuration(cfg.HeartbeatInterval),
1286		IdleTimeout:            parseDuration(cfg.IdleTimeout),
1287		ReconnectTimeout:       parseDuration(cfg.ReconnectTimeout),
1288		CancelGracePeriod:      parseDuration(cfg.CancelGracePeriod),
1289	}
1290}
1291
1292func runInteractive(ctx context.Context, args Args, version string) error {
1293	initialCfg, _ := LoadConfig()
1294	// Resolve WITHOUT requiring credentials.
1295	r, err := Resolve(args, false)
1296	if err != nil {
1297		return err
1298	}
1299
1300	authStore := AuthStoreFor()
1301	mgr := auth.NewManager(authStore)
1302	defer mgr.Close()
1303
1304	// Keep the sandbox pointer stable across agent rebuilds (login / model
1305	// switch). The Interactive UI toggles the lock via this pointer, and
1306	// rebuilt tool instances must share the same one so the lock sticks.
1307	sharedSandbox := r.Sandbox
1308
1309	// persistMu guards the active session and selection across the agent
1310	// loop, TUI callbacks, and session swaps. Declare it before tool
1311	// construction because subagent defaults must read the live selection too.
1312	var persistMu sync.Mutex
1313	// Serialize session transitions with persistence callbacks so a candidate
1314	// is read only after the old agent is flushed and cannot be overwritten by
1315	// an in-flight append before commit.
1316	var sessionTransitionMu sync.RWMutex
1317	activeProvider := r.Provider
1318	activeModel := r.Model
1319
1320	// Build the extension manager BEFORE the agent so we can fold
1321	// extension-defined tools into the registry. Attach the interactive
1322	// host after constructing it below so startup alerts can be buffered.
1323	var iv *modes.Interactive
1324	extHooks := &interactiveExtHooks{}
1325	extMgr := extensions.New(ZutHome(), r.CWD, version, r.Provider, r.Model, extHooks)
1326	var startupExtensionErrors []string
1327	// --ext paths first so they win against installed extensions of
1328	// the same name (loadOne's first-write-wins semantics).
1329	for _, e := range extMgr.LoadExplicit(ctx, args.Exts) {
1330		startupExtensionErrors = append(startupExtensionErrors, e.Error())
1331	}
1332	// --no-ext skips the global + project-local discovery scan;
1333	// explicit --ext paths above are still honoured so you can run
1334	// "only this extension" with --no-ext --ext ./x.
1335	if !args.NoExt {
1336		for _, e := range extMgr.Discover(ctx) {
1337			startupExtensionErrors = append(startupExtensionErrors, e.Error())
1338		}
1339	}
1340	// Wait briefly for extensions to flush their initial register_tool
1341	// frames before we build the agent's tool registry. Half a second
1342	// is plenty for any extension that's actually well-behaved; ones
1343	// that don't send a ready frame eat the full grace and proceed.
1344	// 3s is the per-extension grace period for the ready frame.
1345	// Native binaries are instant; runtimes like `npx tsx` take ~1.5s
1346	// from cold cache. The wait is tight only for extensions that
1347	// haven't sent ready by then; ones that signalled earlier release
1348	// the wait immediately.
1349	extMgr.WaitForReady(3 * time.Second)
1350	defer extMgr.Stop(2 * time.Second)
1351
1352	extToolAdapter := &extToolAdapter{mgr: extMgr}
1353	r.MergeExtensionTools(extToolAdapter)
1354	webSearchGuard := &webSearchSessionGuard{}
1355
1356	// Build the subagent supervisor BEFORE the agent so the auto-subagents
1357	// tool can reference it during tool-registry construction. State
1358	// lives under ZutHome/subagents so per-agent meta/events survive
1359	// restarts; the user can hunt orphaned agents down with
1360	// `git worktree list` if anything misbehaves.
1361	//
1362	// subagentsMgr is also captured by loadSession / changeCWD closures
1363	// further down the function, which is why we keep the variable
1364	// in this outer scope rather than scoping it tighter.
1365	var subagentsMgr *subagents.Supervisor
1366	subagentsMgr = subagents.New(subagents.Config{
1367		Context:         ctx,
1368		Root:            filepath.Join(ZutHome(), "subagents"),
1369		RepoRoot:        r.CWD,
1370		Provider:        r.Provider,
1371		FastMode:        r.FastMode,
1372		WebSearchPolicy: webSearchPolicyForRegistry(r.WebSearchPolicy, r.ToolRegistry),
1373		BaseURL:         r.BaseURL,
1374		InsecureTLS:     r.InsecureTLS,
1375		Policy:          subagentPolicyFromConfig(initialCfg.Subagents),
1376		// Keep an explicit launch key in this callback only. Supervisor persists
1377		// connection settings, but never stores credentials in Agent metadata
1378		// or puts them in the worker's argv/environment.
1379		ResolveCredential: func(ctx context.Context, providerID string) (subagents.Credential, error) {
1380			childProvider := canonicalProvider(providerID)
1381			persistMu.Lock()
1382			hostProvider := canonicalProvider(activeProvider)
1383			persistMu.Unlock()
1384			if childProvider == "" {
1385				childProvider = hostProvider
1386			}
1387			explicit := ""
1388			// A launch-time API key is scoped to the provider selected at
1389			// startup. Never send it to an explicitly different child
1390			// provider; resolve that provider's own credential instead.
1391			if args.APIKey != "" && childProvider == hostProvider {
1392				explicit = args.APIKey
1393			}
1394			if childProvider == "ollama" && explicit == "" {
1395				return subagents.Credential{Value: "ollama", Method: "apikey"}, nil
1396			}
1397			credential, method, accountID, err := ResolveCredentialFullContext(ctx, childProvider, explicit)
1398			if err != nil {
1399				// Providers backed only by a local endpoint do not need a key.
1400				// Leave stdin untouched and let the child resolve that endpoint.
1401				if !CredentialAvailable(childProvider) {
1402					return subagents.Credential{}, nil
1403				}
1404				return subagents.Credential{}, err
1405			}
1406			return subagents.Credential{Value: credential, Method: method, AccountID: accountID}, nil
1407		},
1408	})
1409	if args.PermissionSet != nil {
1410		// Packaged zutfile agents have an explicit capability ceiling. A
1411		// child process would otherwise rebuild a fresh unrestricted sandbox,
1412		// so do not expose either slash or tool-based delegation from this
1413		// restricted host until worker capability propagation exists.
1414		subagentsMgr = nil
1415	} else {
1416		// Replaying every historical event log can take seconds for users with
1417		// many completed subagents. The manager is safe for concurrent snapshots,
1418		// so populate the detached-agent dashboard in the background instead of
1419		// blocking the first interactive paint.
1420		go func() { _, _ = subagentsMgr.Reload() }()
1421	}
1422
1423	// onSpawnedSupervisor is the OnSpawned callback the subagent_spawn tool
1424	// fires after every successful spawn. It hands the agent off to
1425	// the running Interactive so the watcher can flush a summary back
1426	// into chat when all sub-agents finish. Reads `iv` lazily because
1427	// the Interactive is constructed after the agent.
1428	onSpawnedSupervisor := func(a *subagents.Agent, task string) {
1429		if iv != nil {
1430			iv.TrackSubagentWorker(a, task)
1431		}
1432	}
1433	resolveSubagent := func(name string) (*subagents.Profile, error) {
1434		return findSubagentProfile(r.CWD, name)
1435	}
1436
1437	// Inject the auto-subagent tools only when /settings -> auto-subagents
1438	// is currently enabled. Registering them unconditionally leaves the model
1439	// trying to call them (and getting a polite error) even when the user has
1440	// switched the feature off. The /settings toggle live-mutates the running
1441	// agent's registry separately so flipping the flag mid-session takes effect
1442	// on the next turn.
1443	injectSubagentTools := func(reg core.Registry) core.Registry {
1444		if reg == nil || subagentsMgr == nil || !autoSubagentsAnyToolAllowed(args) {
1445			return reg
1446		}
1447		if !AutoSubagentsEnabled() {
1448			return reg
1449		}
1450		if autoSubagentsToolAllowed(args) {
1451			canonical := &tools.SubagentSpawnTool{
1452				Supervisor: subagentsMgr,
1453				Enabled:    AutoSubagentsEnabled,
1454				DefaultModel: func() string {
1455					persistMu.Lock()
1456					defer persistMu.Unlock()
1457					return activeModel
1458				},
1459				DefaultProvider: func() string {
1460					persistMu.Lock()
1461					defer persistMu.Unlock()
1462					return activeProvider
1463				},
1464				DefaultReasoning: func() string { return r.Reasoning },
1465				ResolveSubagent:  resolveSubagent,
1466				OnSpawned:        onSpawnedSupervisor,
1467			}
1468			reg[canonical.Name()] = canonical
1469		}
1470		if autoSubagentsStatusToolAllowed(args) {
1471			statusTool := &tools.SubagentStatusTool{
1472				Supervisor: subagentsMgr,
1473				Enabled:    AutoSubagentsEnabled,
1474			}
1475			reg[statusTool.Name()] = statusTool
1476		}
1477		return reg
1478	}
1479	prepareInteractiveRegistry := func(reg core.Registry) core.Registry {
1480		reg = injectSubagentTools(reg)
1481		return webSearchGuard.wrapRegistry(reg)
1482	}
1483	prepareResolvedInteractiveRegistry := func(reg core.Registry, policy subagents.WebSearchPolicy) core.Registry {
1484		// The resolved policy is a ceiling. In particular, an extension named
1485		// web_search must not reintroduce the capability when --no-tools,
1486		// --tools, a packaged PermissionSet, or persisted settings deny it.
1487		if policy != subagents.WebSearchAllow {
1488			delete(reg, "web_search")
1489		}
1490		return prepareInteractiveRegistry(reg)
1491	}
1492	prepareResolvedInteractiveRegistry(r.ToolRegistry, r.WebSearchPolicy)
1493	initialWebSearchPolicy := webSearchPolicyForRegistry(r.WebSearchPolicy, r.ToolRegistry)
1494	webSearchGuard.setAvailable(initialWebSearchPolicy == subagents.WebSearchAllow)
1495	if subagentsMgr != nil {
1496		subagentsMgr.SetWebSearchPolicy(initialWebSearchPolicy)
1497	}
1498
1499	// Confirmation gate: when --no-yolo is on, the agent must ask
1500	// the user before every tool call. In interactive mode the TUI
1501	// provides the Confirmer; in print/json/rpc modes there's no
1502	// way to prompt, so the gate is constructed with a nil inner
1503	// which auto-refuses every call with a helpful reason.
1504	var confirmGate *core.ConfirmGate
1505	if args.NoYolo {
1506		confirmGate = core.NewConfirmGate(nil) // set below for interactive
1507	}
1508
1509	// Capture current args in a closure so BuildAgent can re-resolve
1510	// after a successful login (picks up the newly stored credential).
1511	wireAgentExt := func(a *core.Agent) *core.Agent {
1512		if a == nil {
1513			return a
1514		}
1515		a.BeforeToolExecute = func(call provider.ToolCallBlock) (bool, string, json.RawMessage) {
1516			// Guards run before confirmation because they may rewrite the
1517			// arguments. The user must approve the effective call that will
1518			// actually execute, not the model's original arguments.
1519			r := extMgr.InterceptToolCall(ctx, call.ID, call.Name, call.Arguments)
1520			if r.Block {
1521				return false, r.Reason, nil
1522			}
1523			effectiveArgs := call.Arguments
1524			if len(r.ModifiedArgs) > 0 && json.Valid(r.ModifiedArgs) {
1525				effectiveArgs = r.ModifiedArgs
1526			}
1527			if confirmGate != nil {
1528				var content strings.Builder
1529				_, currentTools := a.PromptConfig()
1530				if tool, err := currentTools.Get(call.Name); err == nil {
1531					if previewer, ok := tool.(core.ToolPreviewer); ok {
1532						preview, err := previewer.Preview(ctx, effectiveArgs)
1533						if err != nil {
1534							return false, err.Error(), nil
1535						}
1536						for _, block := range preview.Content {
1537							if text, ok := block.(provider.TextBlock); ok {
1538								if content.Len() > 0 {
1539									content.WriteString("\n")
1540								}
1541								content.WriteString(text.Text)
1542							}
1543						}
1544					}
1545				}
1546				ok, reason, _ := confirmGate.CheckToolCall(core.ToolCallConfirmation{
1547					ID:      call.ID,
1548					Name:    call.Name,
1549					Summary: core.BuildPreview(effectiveArgs, 120),
1550					Content: content.String(),
1551					Origin:  call.Origin,
1552				})
1553				if !ok {
1554					return false, reason, nil
1555				}
1556			}
1557			return true, "", r.ModifiedArgs
1558		}
1559		a.BeforeTurnContext = func(turnCtx context.Context, step int) (bool, string, string) {
1560			r := extMgr.InterceptTurnStart(turnCtx, step)
1561			return !r.Block, r.Reason, r.Context
1562		}
1563		a.BeforeAssistantMessage = func(text string) (bool, string, string) {
1564			r := extMgr.InterceptAssistantMessage(ctx, text)
1565			if r.Block {
1566				return false, r.Reason, ""
1567			}
1568			return true, "", r.ReplaceText
1569		}
1570		a.OnEvent = func(ev core.AgentEvent) { fanoutAgentEvent(extMgr, ev) }
1571		return a
1572	}
1573
1574	var ag *core.Agent
1575	buildAgent := func() (*core.Agent, string, string, error) {
1576		resolved, err := Resolve(args, true)
1577		if err != nil {
1578			return nil, "", "", err
1579		}
1580		resolved.UseSandbox(sharedSandbox)
1581		if subagentsMgr != nil {
1582			subagentsMgr.SetProvider(resolved.Provider)
1583			subagentsMgr.SetProviderSettings(resolved.BaseURL, resolved.InsecureTLS)
1584		}
1585		resolved.MergeExtensionTools(extToolAdapter)
1586		prepareResolvedInteractiveRegistry(resolved.ToolRegistry, resolved.WebSearchPolicy)
1587		return wireAgentExt(resolved.NewAgent()), resolved.Provider, resolved.Model, nil
1588	}
1589
1590	// Rebuild agent with an explicit provider/model override.
1591	buildAgentFor := func(providerOverride, modelOverride string) (*core.Agent, string, string, error) {
1592		next := args
1593		if providerOverride != "" {
1594			next.Provider = providerOverride
1595		}
1596		if modelOverride != "" {
1597			next.Model = modelOverride
1598		}
1599		resolved, err := Resolve(next, true)
1600		if err != nil {
1601			return nil, "", "", err
1602		}
1603		resolved.UseSandbox(sharedSandbox)
1604		if subagentsMgr != nil {
1605			subagentsMgr.SetProvider(resolved.Provider)
1606			subagentsMgr.SetProviderSettings(resolved.BaseURL, resolved.InsecureTLS)
1607		}
1608		resolved.MergeExtensionTools(extToolAdapter)
1609		prepareResolvedInteractiveRegistry(resolved.ToolRegistry, resolved.WebSearchPolicy)
1610		return wireAgentExt(resolved.NewAgent()), resolved.Provider, resolved.Model, nil
1611	}
1612
1613	// Rebuild agent for the rescue picker after a recoverable failure.
1614	// Unlike buildAgentFor, this drops launch-time --api-key and
1615	// --base-url overrides because those are typically the cause of the
1616	// rescue (a bad key, a typo'd base URL, or a corporate gateway that
1617	// only the originally-picked provider needed). Re-resolving without
1618	// them lets the rescue retry use env vars / auth.json / provider
1619	// defaults the way zut would have without the overrides.
1620	buildAgentForRescue := func(providerOverride, modelOverride string) (*core.Agent, string, string, error) {
1621		next := args
1622		next.APIKey = ""
1623		next.BaseURL = ""
1624		if providerOverride != "" {
1625			next.Provider = providerOverride
1626		}
1627		if modelOverride != "" {
1628			next.Model = modelOverride
1629		}
1630		resolved, err := Resolve(next, true)
1631		if err != nil {
1632			return nil, "", "", err
1633		}
1634		resolved.UseSandbox(sharedSandbox)
1635		if subagentsMgr != nil {
1636			subagentsMgr.SetProvider(resolved.Provider)
1637			subagentsMgr.SetProviderSettings(resolved.BaseURL, resolved.InsecureTLS)
1638		}
1639		resolved.MergeExtensionTools(extToolAdapter)
1640		prepareResolvedInteractiveRegistry(resolved.ToolRegistry, resolved.WebSearchPolicy)
1641		return wireAgentExt(resolved.NewAgent()), resolved.Provider, resolved.Model, nil
1642	}
1643
1644	if r.HasCredential() {
1645		ag = wireAgentExt(r.NewAgent())
1646	}
1647
1648	// /reload-ext callback: after the manager has respawned every
1649	// extension, re-resolve the tool registry (built-ins + freshly-
1650	// registered extension tools) and swap it onto the current
1651	// agent in-place. The current agent may have been replaced by a
1652	// /model swap since spawn, so re-read the live `ag` on each
1653	// invocation.
1654	extMgr.SetOnReload(func() {
1655		current := liveInteractiveAgent(iv, ag)
1656		if current == nil {
1657			return
1658		}
1659		if _, err := refreshAgentToolsAndPrompt(args, sharedSandbox, extToolAdapter, current, prepareInteractiveRegistry, iv); err != nil && iv != nil {
1660			iv.ReportError(err)
1661		}
1662	})
1663
1664	var sess *core.Session
1665	var sessBaselineMsgs int // messages already on disk when current session opened
1666	var sessionTitlePending bool
1667	if !args.NoSess && ag != nil {
1668		var sessErr error
1669		sess, sessErr = openOrCreateSession(args, r, ag, version)
1670		if sessErr != nil {
1671			return sessErr
1672		}
1673		sessBaselineMsgs = len(ag.Messages())
1674		if sess != nil {
1675			// Startup resume uses the same provider/model-aware preparation as
1676			// the interactive session picker. This matters for --continue,
1677			// --resume, and explicit --session paths whose latest meta row was
1678			// written by another provider/model.
1679			candidate, resumeErr := applySessionResume(sess, ag, r.Provider, r.Model,
1680				strings.TrimSpace(args.Provider) != "", strings.TrimSpace(args.Model) != "", buildAgentFor)
1681			if resumeErr != nil {
1682				return resumeErr
1683			}
1684			sess = candidate.session
1685			ag = candidate.agent
1686			sessBaselineMsgs = candidate.fullMessageCount
1687			activeProvider = candidate.provider
1688			activeModel = candidate.model
1689			r.Provider = candidate.provider
1690			r.Model = candidate.model
1691		}
1692		if sess != nil && ag != nil {
1693			sessionTitlePending = sess.Meta.Parent != "" && sess.Title == "" && len(ag.Messages()) <= sess.Meta.ForkPoint
1694		}
1695	}
1696	announceSession(extMgr, sess)
1697	defer func() {
1698		persistMu.Lock()
1699		defer persistMu.Unlock()
1700		if sess != nil {
1701			sess.Close()
1702		}
1703	}()
1704
1705	// persistMessage is the per-message hook bound to the agent. It
1706	// appends each new transcript message to the live session as soon
1707	// as it lands, so a kill / closed terminal / OS crash costs at
1708	// most the in-flight turn instead of the whole session. The
1709	// baseline counter advances in lock-step so the exit-time flush
1710	// doesn't double-write rows already on disk.
1711	persistMessage := func(m provider.Message) {
1712		sessionTransitionMu.RLock()
1713		defer sessionTransitionMu.RUnlock()
1714		persistMu.Lock()
1715		defer persistMu.Unlock()
1716		if sess == nil {
1717			return
1718		}
1719		if err := sess.AppendMessage(m); err == nil {
1720			sessBaselineMsgs++
1721		}
1722	}
1723	persistUsage := func(cum provider.Usage) {
1724		sessionTransitionMu.RLock()
1725		defer sessionTransitionMu.RUnlock()
1726		persistMu.Lock()
1727		defer persistMu.Unlock()
1728		if sess == nil {
1729			return
1730		}
1731		_ = sess.AppendUsage(cum, cum)
1732	}
1733	persistCompaction := func(messages []provider.Message) {
1734		sessionTransitionMu.RLock()
1735		var session *extproto.SessionContext
1736		var states map[string]json.RawMessage
1737		persistMu.Lock()
1738		if sess != nil {
1739			if err := sess.AppendCompaction(messages); err == nil {
1740				sessBaselineMsgs = len(messages)
1741				session = sessionContext(sess)
1742				states = copyExtensionStates(sess.ExtensionState)
1743			}
1744		}
1745		persistMu.Unlock()
1746		sessionTransitionMu.RUnlock()
1747		if session != nil {
1748			extMgr.EmitSessionEvent("session_compacted", session, states)
1749		}
1750	}
1751	persistCompactHandoff := func(state json.RawMessage) error {
1752		sessionTransitionMu.RLock()
1753		defer sessionTransitionMu.RUnlock()
1754		persistMu.Lock()
1755		defer persistMu.Unlock()
1756		if sess == nil {
1757			return nil
1758		}
1759		return sess.UpdateCompactHandoff(state)
1760	}
1761	currentCompactHandoff := func() json.RawMessage {
1762		persistMu.Lock()
1763		defer persistMu.Unlock()
1764		if sess == nil {
1765			return nil
1766		}
1767		return append(json.RawMessage(nil), sess.Meta.CompactHandoff...)
1768	}
1769	persistToolResult := func(_ string, result core.ToolResult) {
1770		persistMu.Lock()
1771		defer persistMu.Unlock()
1772		persistExtensionToolResult(extMgr, sess, result)
1773	}
1774	wireAgentPersist := func(a *core.Agent) *core.Agent {
1775		if a == nil {
1776			return a
1777		}
1778		a.OnMessageAppended = persistMessage
1779		a.OnUsage = persistUsage
1780		a.OnTranscriptCompacted = persistCompaction
1781		a.OnToolResult = persistToolResult
1782		return a
1783	}
1784	wireAgentPersist(ag)
1785	defer func() {
1786		closeAgentLSP(liveInteractiveAgent(iv, ag))
1787		closeResolvedLSP(r)
1788	}()
1789
1790	// Re-wrap the build closures so any agent constructed by the TUI
1791	// (login, /model swap to a different provider) also gets the
1792	// persistence hooks. Without this, switching provider would
1793	// silently revert to the old in-memory-only behaviour. Selection state
1794	// is published by the successful transition itself, not by preparation.
1795	baseBuildAgent := buildAgent
1796	buildAgent = func() (*core.Agent, string, string, error) {
1797		a, p, m, err := baseBuildAgent()
1798		return wireAgentPersist(a), p, m, err
1799	}
1800	baseBuildAgentFor := buildAgentFor
1801	buildAgentFor = func(providerOverride, modelOverride string) (*core.Agent, string, string, error) {
1802		a, p, m, err := baseBuildAgentFor(providerOverride, modelOverride)
1803		return wireAgentPersist(a), p, m, err
1804	}
1805	baseBuildAgentForRescue := buildAgentForRescue
1806	buildAgentForRescue = func(providerOverride, modelOverride string) (*core.Agent, string, string, error) {
1807		a, p, m, err := baseBuildAgentForRescue(providerOverride, modelOverride)
1808		return wireAgentPersist(a), p, m, err
1809	}
1810
1811	// loadSession replaces the current session with the one at path and
1812	// hands its messages to the agent. Used by the /sessions picker.
1813	loadSession := func(path string) error {
1814		// Hold the transition lock from the pre-flush through the commit.
1815		// Persistence callbacks take the read side, so an active session
1816		// cannot be snapshotted before its lazy writes land or overwritten by
1817		// a callback while the candidate is being installed.
1818		sessionTransitionMu.Lock()
1819		defer sessionTransitionMu.Unlock()
1820
1821		currentAg := liveInteractiveAgent(iv, ag)
1822		if currentAg == nil {
1823			return fmt.Errorf("no agent running; log in first")
1824		}
1825
1826		persistMu.Lock()
1827		currentProvider := activeProvider
1828		currentModel := activeModel
1829		oldSess := sess
1830		// Flush before reading the candidate. Use the locked form rather
1831		// than the public callback, which would acquire the read lock held
1832		// by this transition.
1833		if oldSess != nil {
1834			writeNewTranscriptLocked(currentAg, oldSess, sessBaselineMsgs)
1835		}
1836		currentMessageCount := len(currentAg.Messages())
1837		currentCost := currentAg.Cost()
1838		persistMu.Unlock()
1839
1840		// A candidate build must not publish its provider/model as the live
1841		// selection before the candidate commits.
1842		candidate, err := prepareSessionResume(path, currentAg, currentProvider, currentModel, baseBuildAgentFor)
1843		if err != nil {
1844			// prepareSessionResume closes its append handle on failure;
1845			// no live agent or session has been changed.
1846			return err
1847		}
1848		committed := false
1849		defer func() {
1850			if !committed {
1851				_ = candidate.session.Close()
1852			}
1853		}()
1854
1855		// Wire the private candidate before it can become visible. This is
1856		// also required for legacy same-provider resumes, where the current
1857		// agent is reused and only its transcript/usage are refreshed.
1858		wireAgentPersist(candidate.agent)
1859
1860		persistMu.Lock()
1861		// A provider rebuild ran outside persistMu. Refuse to install it if
1862		// the live agent, session, selection, transcript, or cost changed in
1863		// the meantime; otherwise a slow resume could discard a newer turn or
1864		// model swap.
1865		live := liveInteractiveAgent(iv, ag)
1866		changed := sess != oldSess || activeProvider != currentProvider || activeModel != currentModel || live != currentAg
1867		if !changed && live != nil {
1868			changed = len(live.Messages()) != currentMessageCount || live.Cost() != currentCost
1869		}
1870		if changed {
1871			persistMu.Unlock()
1872			return fmt.Errorf("session changed while loading; please try again")
1873		}
1874		newStates := copyExtensionStates(candidate.session.ExtensionState)
1875		if oldSess != nil {
1876			_ = oldSess.Close()
1877		}
1878		sess = candidate.session
1879		sessionTitlePending = candidate.session != nil && candidate.session.Meta.Parent != "" && candidate.session.Title == "" && candidate.fullMessageCount <= candidate.session.Meta.ForkPoint
1880		// The live agent only receives a compact resume window, but the
1881		// session file remains intact. Keep the persistence baseline at
1882		// the original on-disk message count so future turns append after
1883		// the full session instead of duplicating the hydrated tail.
1884		sessBaselineMsgs = candidate.fullMessageCount
1885
1886		if candidate.rebuilt {
1887			// Commit the TUI agent while persistMu still protects the session
1888			// writer, so no new message can land on the old file between the
1889			// two state changes.
1890			if iv != nil {
1891				iv.ApplySessionAgentWithCompactHandoff(candidate.agent, candidate.provider, candidate.model, candidate.session.Meta.CompactHandoff)
1892			}
1893			ag = candidate.agent
1894		} else {
1895			currentAg.SetMessages(candidate.messages)
1896			currentAg.SeedCost(candidate.cumulative)
1897			currentAg.SeedLastTurnUsage(candidate.lastTurn)
1898			ag = currentAg
1899		}
1900		activeProvider = candidate.provider
1901		activeModel = candidate.model
1902		if subagentsMgr != nil && candidate.session != nil {
1903			// Keep the dashboard scope in the same commit as the session,
1904			// agent, usage, and persistence baseline.
1905			if iv != nil {
1906				iv.SetSubagentSessionScope(candidate.session.ID)
1907			} else {
1908				subagentsMgr.SetActiveSession(candidate.session.ID)
1909			}
1910		}
1911		committed = true
1912		persistMu.Unlock()
1913		if candidate.session.Meta.Parent != "" {
1914			extMgr.EmitSessionEvent("session_forked", sessionContext(candidate.session), newStates)
1915		}
1916		extMgr.EmitSessionEvent("session_switched", sessionContext(candidate.session), newStates)
1917		return nil
1918	}
1919
1920	// changeCWD switches the running session to a new working directory.
1921	// Wired into InteractiveConfig.ChangeCWD and invoked by the hidden
1922	// /cd slash command (which itself is only fired by the workspaces
1923	// extension's panel-key Enter handler today; the user can type /cd
1924	// directly but it's not in autocomplete / help / the README).
1925	//
1926	// Steps, in order:
1927	//   1. resolve + validate the new path (~ expansion, abs/rel)
1928	//   2. stage the candidate cwd, sandbox, and subagent state
1929	//   3. rebuild the agent and allocate its new session
1930	//   4. commit all new state together, closing the old session last
1931	//   5. push the committed state into the running Interactive
1932	//
1933	// The /jail state is preserved verbatim: if the sandbox was locked
1934	// to the old cwd, it stays locked, just re-pointed at the new one.
1935	changeCWD := func(path string) error {
1936		sessionTransitionMu.Lock()
1937		defer sessionTransitionMu.Unlock()
1938		if path == "" {
1939			return fmt.Errorf("empty path")
1940		}
1941		// ~ expansion.
1942		if path == "~" || strings.HasPrefix(path, "~/") {
1943			home, herr := os.UserHomeDir()
1944			if herr != nil || home == "" {
1945				return fmt.Errorf("cannot expand ~: %v", herr)
1946			}
1947			if path == "~" {
1948				path = home
1949			} else {
1950				path = filepath.Join(home, path[2:])
1951			}
1952		}
1953		if !filepath.IsAbs(path) {
1954			path = filepath.Join(args.CWD, path)
1955		}
1956		absPath, err := filepath.Abs(path)
1957		if err != nil {
1958			return err
1959		}
1960		info, err := os.Stat(absPath)
1961		if err != nil {
1962			return err
1963		}
1964		if !info.IsDir() {
1965			return fmt.Errorf("not a directory: %s", absPath)
1966		}
1967
1968		currentAg := liveInteractiveAgent(iv, ag)
1969		if currentAg == nil {
1970			return fmt.Errorf("no agent running; log in first")
1971		}
1972
1973		// Stage the candidate state while retaining a complete rollback
1974		// snapshot. A failed rebuild or session allocation must leave the
1975		// current agent, session, sandbox, and subagent root usable.
1976		oldCWD := args.CWD
1977		oldResolvedCWD := r.CWD
1978		oldPermissionSet := args.PermissionSet
1979		persistMu.Lock()
1980		oldActiveProvider := activeProvider
1981		oldActiveModel := activeModel
1982		persistMu.Unlock()
1983		oldSupervisorRoot := ""
1984		if subagentsMgr != nil {
1985			oldSupervisorRoot = subagentsMgr.RepoRoot()
1986		}
1987		oldSandboxRoot := ""
1988		oldSandboxLocked := false
1989		if sharedSandbox != nil {
1990			oldSandboxRoot = sharedSandbox.Root
1991			oldSandboxLocked = sharedSandbox.Locked()
1992		}
1993		rollback := func() {
1994			args.CWD = oldCWD
1995			r.CWD = oldResolvedCWD
1996			args.PermissionSet = oldPermissionSet
1997			persistMu.Lock()
1998			activeProvider = oldActiveProvider
1999			activeModel = oldActiveModel
2000			persistMu.Unlock()
2001			if subagentsMgr != nil {
2002				subagentsMgr.SetRepoRoot(oldSupervisorRoot)
2003			}
2004			if sharedSandbox != nil {
2005				sharedSandbox.Root = oldSandboxRoot
2006				if oldSandboxLocked {
2007					sharedSandbox.Lock()
2008				} else {
2009					sharedSandbox.Unlock()
2010				}
2011			}
2012		}
2013
2014		args.CWD = absPath
2015		r.CWD = absPath
2016		if subagentsMgr != nil {
2017			subagentsMgr.SetRepoRoot(absPath)
2018		}
2019		if args.PermissionSet != nil {
2020			expanded := args.PermissionSet.Expand(absPath, args.AgentDataDir)
2021			args.PermissionSet = &expanded
2022		}
2023		if sharedSandbox != nil {
2024			sharedSandbox.Root = absPath
2025			if oldSandboxLocked {
2026				sharedSandbox.Lock()
2027			} else {
2028				sharedSandbox.Unlock()
2029			}
2030		}
2031
2032		// Rebuild the agent so tools / AGENTS.md / system prompt
2033		// re-bind to the new cwd. buildAgent() reads from args + r.
2034		newAg, newProvider, newModel, berr := buildAgent()
2035		if berr != nil {
2036			rollback()
2037			return fmt.Errorf("rebuild agent: %w", berr)
2038		}
2039
2040		// Fresh session in the new cwd's bucket. We bypass
2041		// openOrCreateSession's --continue / --resume branches
2042		// because /cd's semantics are "start fresh here", matching
2043		// what relaunching `zut --cwd <path>` would do today.
2044		var newSess *core.Session
2045		if !args.NoSess {
2046			newRoot := agentSessionsRoot(ZutHome(), args)
2047			core.PruneEmptySessions(newRoot, absPath)
2048			var serr error
2049			newSess, serr = core.NewSession(newRoot, absPath, newProvider, newModel, version)
2050			if serr != nil {
2051				rollback()
2052				return fmt.Errorf("open session in %s: %w", absPath, serr)
2053			}
2054		}
2055
2056		// Invalidate any title request before swapping the host-owned session
2057		// pointer. The interactive state reset below happens after the swap,
2058		// so this guard closes the window where a late result could otherwise
2059		// be written to the new session.
2060		if iv != nil {
2061			iv.CancelPendingSessionTitle()
2062		}
2063
2064		// Commit only after every fallible operation has succeeded. Close
2065		// the old session last so rollback never has to resurrect it.
2066		var newStates map[string]json.RawMessage
2067		persistMu.Lock()
2068		if sess != nil {
2069			writeNewTranscriptLocked(currentAg, sess, sessBaselineMsgs)
2070			_ = sess.Close()
2071		}
2072		sess = newSess
2073		if newSess != nil {
2074			newStates = copyExtensionStates(newSess.ExtensionState)
2075		}
2076		sessBaselineMsgs = 0
2077		sessionTitlePending = false
2078		activeProvider = newProvider
2079		activeModel = newModel
2080		persistMu.Unlock()
2081		ag = newAg
2082		closeAgentLSP(currentAg)
2083
2084		// Push the new state into the running Interactive.
2085		if iv != nil {
2086			startupPaths := instructionContextPaths(loadAgentsContext(absPath, ZutHome()))
2087			iv.ApplyChangedCWDWithStartupContext(newAg, newProvider, newModel, absPath, startupPaths)
2088		}
2089
2090		// Re-scope the subagent dashboard to the new session.
2091		if subagentsMgr != nil && newSess != nil {
2092			if iv != nil {
2093				iv.SetSubagentSessionScope(newSess.ID)
2094			} else {
2095				subagentsMgr.SetActiveSession(newSess.ID)
2096			}
2097		}
2098		if newSess != nil {
2099			extMgr.EmitSessionEvent("session_opened", sessionContext(newSess), newStates)
2100		}
2101		return nil
2102	}
2103
2104	devBuild := isDevVersion(version)
2105	if devBuild {
2106		fmt.Fprintln(os.Stderr, "zut:", devVersionNotice)
2107	}
2108	term := tui.NewProcTerm()
2109
2110	var updateCh chan modes.UpdateInfo
2111	var changelogCh chan modes.ChangelogPayload
2112	if !devBuild {
2113		// Kick off the async update check so the banner can appear when the
2114		// http response eventually arrives (usually <1s on cached DNS). Map
2115		// agent.UpdateInfo -> modes.UpdateInfo here to avoid a cyclic import.
2116		updateCh = make(chan modes.UpdateInfo, 1)
2117		go func() {
2118			defer close(updateCh)
2119			src := <-CheckForUpdateAsync(ZutHome(), version)
2120			updateCh <- modes.UpdateInfo{
2121				Current:   src.Current,
2122				Latest:    src.Latest,
2123				Available: src.Available,
2124				URL:       src.URL,
2125			}
2126		}()
2127
2128		// Changelog: when the running version differs from the last
2129		// version whose release notes the user dismissed, fetch the
2130		// release body from GitHub and have the TUI show it once. On
2131		// first-ever launch (no prior LastChangelogShown), seed the
2132		// stored version silently — don't dump release notes at someone
2133		// who just installed.
2134		changelogCh = make(chan modes.ChangelogPayload, 1)
2135		go func() {
2136			defer close(changelogCh)
2137			cfg, _ := LoadConfig()
2138			if cfg.LastChangelogShown == "" {
2139				SeedChangelogVersion(version)
2140				return
2141			}
2142			if !ShouldShowChangelog(version, cfg) {
2143				return
2144			}
2145			info := <-FetchChangelogAsync(version)
2146			if info.Body == "" {
2147				return
2148			}
2149			changelogCh <- modes.ChangelogPayload{
2150				Version: info.Version,
2151				Body:    info.Body,
2152				URL:     info.URL,
2153			}
2154		}()
2155	}
2156
2157	fastMode := r.FastMode
2158	quickModelShortcuts := make([]modes.QuickModelShortcut, len(initialCfg.QuickModelShortcuts))
2159	for idx, s := range initialCfg.QuickModelShortcuts {
2160		quickModelShortcuts[idx] = modes.QuickModelShortcut{Provider: s.Provider, Model: s.Model}
2161	}
2162	theme, _, themeErr := tui.DetectThemeWithCustom(ZutHome(), initialCfg.Theme, 80*time.Millisecond)
2163	if themeErr != nil {
2164		fmt.Fprintln(os.Stderr, "theme load:", themeErr)
2165		if initialCfg.Theme != "" && !tui.ThemeExists(ZutHome(), initialCfg.Theme) {
2166			initialCfg.Theme = ""
2167			_ = SaveConfig(initialCfg)
2168		}
2169	}
2170
2171	// subagentsMgr was constructed and reloaded earlier (before the agent
2172	// build, so the auto-subagents tool could capture it). Here we just
2173	// scope the dashboard to the active host session so /subagents only
2174	// shows agents this session spawned (and any pre-upgrade unscoped
2175	// agents — see SnapshotAll docs). Updated again whenever the
2176	// user swaps sessions via loadSession below.
2177	if sess != nil && subagentsMgr != nil {
2178		subagentsMgr.SetActiveSession(sess.ID)
2179	}
2180	// Best-effort shutdown on interactive exit: stop all running
2181	// agents so they don't outlive their parent zut.
2182	if subagentsMgr != nil {
2183		defer subagentsMgr.StopAll()
2184	}
2185
2186	var startupSkills []*skills.Skill
2187	if r.SkillTool != nil {
2188		startupSkills = r.SkillTool.Skills()
2189	}
2190	homeDir, _ := os.UserHomeDir()
2191	discoveredSubagents, _ := subagents.Discover(r.CWD, homeDir)
2192	subagentsAddendum := subagents.SystemPromptAddendum(discoveredSubagents)
2193	autoSubagentsToolAllowedForSession := autoSubagentsToolAllowed(args)
2194	autoSubagentsStatusToolAllowedForSession := autoSubagentsStatusToolAllowed(args)
2195	webSearchToolAllowedForInvocation := webSearchToolAllowedForSession(args)
2196	webSearchInvocationOverride := webSearchExplicitlyEnabledForSession(args)
2197	setWebSearchAvailable := func(available bool) {
2198		webSearchGuard.setAvailable(available)
2199		if subagentsMgr == nil {
2200			return
2201		}
2202		policy := subagents.WebSearchDeny
2203		if available {
2204			policy = subagents.WebSearchAllow
2205		}
2206		subagentsMgr.SetWebSearchPolicy(policy)
2207	}
2208
2209	iv = modes.NewInteractive(modes.InteractiveConfig{
2210		Terminal:                       term,
2211		Theme:                          theme,
2212		InlineImagesEnabled:            initialCfg.InlineImagesEnabled,
2213		TerminalAlertsEnabled:          initialCfg.TerminalAlertsEnabled,
2214		TerminalTitleEnabled:           initialCfg.TerminalTitleEnabled,
2215		AutoSubagentsEnabled:           initialCfg.AutoSubagentsEnabled,
2216		PonytailEnabled:                initialCfg.PonytailEnabled,
2217		WebSearchEnabled:               initialCfg.WebSearchEnabled,
2218		WebSearchToolAllowed:           &webSearchToolAllowedForInvocation,
2219		WebSearchInvocationOverride:    webSearchInvocationOverride,
2220		AutoSubagentsToolAllowed:       &autoSubagentsToolAllowedForSession,
2221		AutoSubagentsStatusToolAllowed: &autoSubagentsStatusToolAllowedForSession,
2222		FastMode:                       &fastMode,
2223		LSPEnabled:                     initialCfg.LSPEnabled,
2224		SubagentLSPEnabled:             initialCfg.SubagentLSPEnabled,
2225		AutoCompactThreshold:           initialCfg.AutoCompactThreshold,
2226		JailByDefault:                  initialCfg.JailByDefault,
2227		QuickModelShortcuts:            quickModelShortcuts,
2228		RecursiveFileSuggest:           initialCfg.RecursiveFileSuggest,
2229		RespectGitignore:               initialCfg.RespectGitignore,
2230		CompactMode:                    initialCfg.CompactMode,
2231		TUIInputStyle:                  initialCfg.TUIInputStyle,
2232		TUIStatusPosition:              initialCfg.TUIStatusPosition,
2233		TUIWorkingPosition:             initialCfg.TUIWorkingPosition,
2234		TUISubagentPosition:            initialCfg.TUISubagentPosition,
2235		ThemeName:                      initialCfg.Theme,
2236		FlatTools:                      initialCfg.FlatToolRender(),
2237		CompactUser:                    initialCfg.CompactUserInput(),
2238		ExtensionThemes:                extMgr.ThemeOptions,
2239		AutoSubagentsSystemAddendum:    AutoSubagentsSystemAddendum,
2240		SubagentsSystemAddendum:        subagentsAddendum,
2241		SettingsStore:                  configSettingsStore{},
2242		Model:                          r.Model,
2243		Provider:                       r.Provider,
2244		AuthMethod:                     r.AuthMethod,
2245		BaseURL:                        r.BaseURL,
2246		Reasoning:                      r.Reasoning,
2247		SystemPrompt:                   r.SystemPrompt,
2248		Tools:                          r.ToolRegistry,
2249		MaxSteps:                       r.MaxSteps,
2250		CWD:                            r.CWD,
2251		StartupAgentName:               args.AgentName,
2252		StartupContextPaths:            instructionContextPaths(r.ContextFiles),
2253		StartupExtensionNames:          startupExtensionNames(extMgr.All()),
2254		StartupExtensionErrors:         startupExtensionErrors,
2255		StartupSkillNames:              startupSkillNames(startupSkills),
2256		ShowInstructionsAtStartup:      initialCfg.ShowInstructionsAtStartup,
2257		ZutHome:                        ZutHome(),
2258		SessionsRoot:                   agentSessionsRoot(ZutHome(), args),
2259		Version:                        version,
2260		UpdateInfoChan:                 updateCh,
2261		Sandbox:                        sharedSandbox,
2262		Agent:                          ag,
2263		InitialCompactHandoff:          currentCompactHandoff(),
2264		InitialSessionTitle: func() string {
2265			if sess == nil || sessionTitlePending {
2266				return ""
2267			}
2268			return sess.Title
2269		}(),
2270		InitialSessionTitlePending: sessionTitlePending,
2271		InitialInput:               args.Prompt,
2272		StartupPre:                 args.StartupPre,
2273		OnStartupPreDone: func() {
2274			// entry.pre often installs skills/extensions; rediscover them
2275			// before the user starts a model turn.
2276			current := liveInteractiveAgent(iv, ag)
2277			if extMgr != nil {
2278				_ = extMgr.Reload(context.Background(), 2*time.Second)
2279			}
2280			if current != nil {
2281				if _, err := refreshAgentToolsAndPrompt(args, sharedSandbox, extToolAdapter, current, prepareInteractiveRegistry, iv); err != nil {
2282					iv.ReportError(err)
2283				}
2284			}
2285		},
2286		RefreshTools: func() error {
2287			current := liveInteractiveAgent(iv, ag)
2288			webSearchPolicy, err := refreshAgentToolsAndPrompt(args, sharedSandbox, extToolAdapter, current, prepareInteractiveRegistry, iv)
2289			if err != nil {
2290				if !errors.Is(err, errInteractiveAgentChanged) {
2291					setWebSearchAvailable(false)
2292				}
2293				return err
2294			}
2295			setWebSearchAvailable(webSearchPolicy == subagents.WebSearchAllow)
2296			return nil
2297		},
2298		SetWebSearchAvailable: setWebSearchAvailable,
2299		RefreshPrompt: func() error {
2300			current := liveInteractiveAgent(iv, ag)
2301			webSearchPolicy, err := refreshAgentToolsAndPrompt(args, sharedSandbox, extToolAdapter, current, prepareInteractiveRegistry, iv)
2302			if err != nil {
2303				return err
2304			}
2305			setWebSearchAvailable(webSearchPolicy == subagents.WebSearchAllow)
2306			return nil
2307		},
2308		AuthManager:                mgr,
2309		LlamaCPPConfig:             ResolveLlamaCPPConfig,
2310		RefreshLlamaCPPModels:      RefreshLlamaCPPModels,
2311		BuildAgent:                 buildAgent,
2312		SetKimiCLIFallbackDisabled: SetKimiCLIFallbackDisabled,
2313		BuildAgentFor:              buildAgentFor,
2314		BuildAgentForRescue:        buildAgentForRescue,
2315		LoggedInProviders: func() []string {
2316			var out []string
2317			seen := map[string]bool{}
2318			for _, p := range knownProviders {
2319				if CredentialAvailable(p) && !seen[p] {
2320					out = append(out, p)
2321					seen[p] = true
2322				}
2323			}
2324			// Include custom providers that have credentials stored.
2325			for p := range provider.CustomProviders() {
2326				if CredentialAvailable(p) && !seen[p] {
2327					out = append(out, p)
2328					seen[p] = true
2329				}
2330			}
2331			// Ollama models are always available (no auth needed).
2332			if !seen["ollama"] {
2333				out = append(out, "ollama")
2334			}
2335			return out
2336		},
2337		LoadSession:           loadSession,
2338		ChangeCWD:             changeCWD,
2339		PersistCompactHandoff: persistCompactHandoff,
2340		CurrentCompactHandoff: currentCompactHandoff,
2341		CurrentSessionPath: func() string {
2342			persistMu.Lock()
2343			defer persistMu.Unlock()
2344			if sess == nil {
2345				return ""
2346			}
2347			return sess.Path
2348		},
2349		FlushSession: func() {
2350			sessionTransitionMu.RLock()
2351			defer sessionTransitionMu.RUnlock()
2352			// Append any not-yet-persisted agent messages to the
2353			// current session file, then advance the baseline so
2354			// the final WriteNewTranscript at exit doesn't write
2355			// duplicates. Per-message persistence keeps the on-
2356			// disk file current already, so this is mostly a
2357			// defensive flush — still needed for /session export
2358			// to guarantee the exported bytes include the very
2359			// last in-flight turn.
2360			currentAg := iv.Agent()
2361			if currentAg == nil {
2362				return
2363			}
2364			persistMu.Lock()
2365			defer persistMu.Unlock()
2366			if sess == nil {
2367				return
2368			}
2369			writeNewTranscriptLocked(currentAg, sess, sessBaselineMsgs)
2370			sessBaselineMsgs = len(currentAg.Messages())
2371		},
2372		SessionTransition: newSessionTransition(&sessionTransitionMu),
2373		Extensions:        extMgr,
2374		Supervisor:        subagentsMgr,
2375		ResolveSubagent:   resolveSubagent,
2376		ChangelogChan:     changelogCh,
2377		OnChangelogDismiss: func() {
2378			// For development builds, store the actual release version
2379			// so the same changelog doesn't show again next launch.
2380			// For real builds, store the binary version.
2381			v := version
2382			if devBuild {
2383				if iv != nil && iv.ChangelogVersion() != "" {
2384					v = iv.ChangelogVersion()
2385				}
2386			}
2387			_ = MarkChangelogShown(v)
2388		},
2389		SkillSnapshot: func() []*skills.Skill {
2390			if args.NoSkill {
2391				// --no-skill: nothing for the picker to show.
2392				return nil
2393			}
2394			// Re-discover so the picker reflects edits made during
2395			// the session. Cheap; SKILL.md files are small. Filter
2396			// out built-in skills — they're hidden from user-facing
2397			// surfaces because they're implementation detail; the
2398			// model still sees them through the system-prompt
2399			// manifest and the skill tool.
2400			userHome, _ := os.UserHomeDir()
2401			list, _ := skills.Discover(ZutHome(), r.CWD, userHome, args.WithSkills)
2402			list = mergeExtensionSkills(skills.NewTool(list), extMgr.Skills())
2403			return skills.VisibleSkills(list)
2404		},
2405		NoYolo:      args.NoYolo,
2406		ConfirmGate: confirmGate,
2407		PersistModel: newPersistModelCallback(&persistMu, &sess, &activeProvider, &activeModel, func(message string) {
2408			if iv != nil {
2409				iv.Notify("session", "error", message)
2410			}
2411		}),
2412		CurrentSessionTitle: func() string {
2413			sessionTransitionMu.RLock()
2414			defer sessionTransitionMu.RUnlock()
2415			persistMu.Lock()
2416			defer persistMu.Unlock()
2417			if sess == nil || sessionTitlePending {
2418				return ""
2419			}
2420			return sess.Title
2421		},
2422		CurrentSessionTitlePending: func() bool {
2423			sessionTransitionMu.RLock()
2424			defer sessionTransitionMu.RUnlock()
2425			persistMu.Lock()
2426			defer persistMu.Unlock()
2427			return sessionTitlePending
2428		},
2429		PersistTitle: func(title string) error {
2430			persistMu.Lock()
2431			defer persistMu.Unlock()
2432			if sess == nil {
2433				return nil
2434			}
2435			if err := sess.UpdateTitle(title); err != nil {
2436				return err
2437			}
2438			sessionTitlePending = false
2439			return nil
2440		},
2441		OnSessionTitleChanged: func(title string) {
2442			sessionTransitionMu.RLock()
2443			defer sessionTransitionMu.RUnlock()
2444			persistMu.Lock()
2445			defer persistMu.Unlock()
2446			if sess != nil {
2447				sess.Title = title
2448				sessionTitlePending = false
2449			}
2450		},
2451	})
2452	extHooks.attachInteractive(iv)
2453
2454	// Bind the interactive TUI as the Confirmer. We deferred this
2455	// until now because the gate is constructed before the TUI
2456	// (the BeforeToolExecute closure captures it). SetConfirmer
2457	// is mutex-guarded on the gate so this is safe.
2458	if confirmGate != nil {
2459		confirmGate.SetConfirmer(&confirmationEventConfirmer{
2460			inner: iv,
2461			emit:  extMgr.EmitEvent,
2462		})
2463	}
2464
2465	// Signal-driven flush: a SIGTERM / SIGHUP to the zut process
2466	// (closed terminal window, system shutdown, kill) used to lose
2467	// the entire in-memory transcript because the deferred post-Run
2468	// flush below never ran. Per-message persistence above covers
2469	// most of it; this handler writes any in-flight remainder and
2470	// then exits the process so we don't double-paint over a
2471	// broken terminal that the TUI's restore deferreds can no
2472	// longer fix from a signal context.
2473	//
2474	// SIGINT is intentionally NOT handled here — the TUI consumes
2475	// Ctrl+C as a regular key event for cancel/clear semantics, and
2476	// installing a SIGINT notifier here would swallow it.
2477	sigCh := make(chan os.Signal, 1)
2478	signal.Notify(sigCh, syscall.SIGTERM, syscall.SIGHUP)
2479	defer signal.Stop(sigCh)
2480	go func() {
2481		_, ok := <-sigCh
2482		if !ok {
2483			return
2484		}
2485		finalAg := iv.Agent()
2486		if finalAg != nil {
2487			persistMu.Lock()
2488			if sess != nil {
2489				writeNewTranscriptLocked(finalAg, sess, sessBaselineMsgs)
2490				sessBaselineMsgs = len(finalAg.Messages())
2491				_ = sess.Close()
2492				sess = nil
2493			}
2494			persistMu.Unlock()
2495		}
2496		closeAgentLSP(finalAg)
2497		closeResolvedLSP(r)
2498		// Stop supervised workers before exiting. os.Exit skips deferred
2499		// cleanup, so relying only on the normal runInteractive defer would
2500		// leave child daemons (and their descendants) alive after a TERM or
2501		// HUP delivered to the host.
2502		if subagentsMgr != nil {
2503			subagentsMgr.StopAll()
2504		}
2505		// Exit cleanly. Re-raising the signal would skip os.Exit's
2506		// at-exit hooks; explicit exit is fine because we've already
2507		// flushed the only at-risk state (the session file) and stopped
2508		// supervised workers.
2509		os.Exit(0)
2510	}()
2511
2512	runErr := iv.Run(ctx)
2513
2514	// Flush final transcript to session (only if we had / ended up with an agent).
2515	if finalAg := iv.Agent(); finalAg != nil {
2516		persistMu.Lock()
2517		if sess != nil {
2518			writeNewTranscriptLocked(finalAg, sess, sessBaselineMsgs)
2519			sessBaselineMsgs = len(finalAg.Messages())
2520		}
2521		persistMu.Unlock()
2522	}
2523	return runErr
2524}
2525
2526func agentSessionsRoot(root string, args Args) string {
2527	if args.AgentName == "" {
2528		return root
2529	}
2530	return filepath.Join(root, "sessions", "agents", safeAgentName(args.AgentName))
2531}
2532
2533// openOrCreateSession returns a session for the run. sess may be nil
2534// with a nil error if session persistence is disabled.
2535func openOrCreateSession(args Args, r Resolved, ag *core.Agent, version string) (*core.Session, error) {
2536	if args.NoSess {
2537		return nil, nil
2538	}
2539	// Sweep meta-only files left over from older zut versions (and from
2540	// any session that crashed before its first AppendMessage). Cheap;
2541	// reads the first few bytes of each file in the cwd's session dir.
2542	sessionsRoot := agentSessionsRoot(ZutHome(), args)
2543	core.PruneEmptySessions(sessionsRoot, args.CWD)
2544	var (
2545		s    *core.Session
2546		msgs []provider.Message
2547		err  error
2548	)
2549	switch {
2550	case args.Session != "":
2551		s, msgs, err = core.OpenSession(args.Session)
2552		// The subagent-worker child passes a fixed --session path that
2553		// may not exist yet on first Spawn. Treat ENOENT as "create
2554		// a fresh session AT THIS PATH" so the conversation actually
2555		// gets persisted; without this fallback the subagent child runs
2556		// with sess==nil and every Resume re-starts with no memory
2557		// of the prior turns. Other openers (--continue / --resume /
2558		// the picker) never see ENOENT here because they only choose
2559		// paths that already exist on disk.
2560		if err != nil && errors.Is(err, os.ErrNotExist) {
2561			s, err = core.NewSessionAtPath(args.Session, args.CWD, r.Provider, r.Model, version)
2562			msgs = nil
2563		}
2564	case args.Continue:
2565		latest := core.LatestSession(sessionsRoot, args.CWD)
2566		if latest != "" {
2567			s, msgs, err = core.OpenSession(latest)
2568		}
2569	case args.Resume:
2570		picked, perr := pickSession(sessionsRoot, args.CWD)
2571		if perr != nil {
2572			return nil, perr
2573		}
2574		if picked != "" {
2575			s, msgs, err = core.OpenSession(picked)
2576		}
2577	}
2578	if err != nil {
2579		return nil, err
2580	}
2581	if s != nil {
2582		ag.SetMessages(msgs)
2583		if cum, last, uerr := core.SessionUsageDetail(s.Path); uerr == nil {
2584			ag.SeedCost(cum)
2585			ag.SeedLastTurnUsage(last)
2586		}
2587		return s, nil
2588	}
2589	return core.NewSession(sessionsRoot, args.CWD, r.Provider, r.Model, version)
2590}
2591
2592func pickSession(root, cwd string) (string, error) {
2593	files := core.ListSessions(root, cwd)
2594	if len(files) == 0 {
2595		fmt.Fprintln(os.Stderr, "no sessions for", cwd)
2596		return "", nil
2597	}
2598	for i, f := range files {
2599		fmt.Fprintf(os.Stderr, "  %2d) %s\n", i+1, f)
2600	}
2601	fmt.Fprint(os.Stderr, "pick #: ")
2602	rd := bufio.NewReader(os.Stdin)
2603	line, _ := rd.ReadString('\n')
2604	line = strings.TrimSpace(line)
2605	var n int
2606	if _, err := fmt.Sscanf(line, "%d", &n); err != nil || n < 1 || n > len(files) {
2607		return "", fmt.Errorf("invalid selection")
2608	}
2609	return files[n-1], nil
2610}
2611
2612// WriteNewTranscript appends only messages after index `from` from the
2613// agent's transcript to the session. Used by callers that don't hold
2614// the persistMu (non-interactive print/json modes which run a single
2615// turn under their own goroutine).
2616func WriteNewTranscript(ag *core.Agent, sess *core.Session, from int) {
2617	writeNewTranscriptLocked(ag, sess, from)
2618}
2619
2620// writeNewTranscriptLocked is the same as WriteNewTranscript. The
2621// suffix marks that interactive callers must hold persistMu when
2622// invoking it so concurrent appends from the agent loop don't race
2623// with this catch-up flush.
2624func writeNewTranscriptLocked(ag *core.Agent, sess *core.Session, from int) {
2625	if sess == nil || ag == nil {
2626		return
2627	}
2628	msgs := ag.Messages()
2629	for i := from; i < len(msgs); i++ {
2630		_ = sess.AppendMessage(msgs[i])
2631	}
2632	cum := ag.Cost()
2633	_ = sess.AppendUsage(cum, cum)
2634}
2635
2636func readAllStdin() (string, error) {
2637	fi, err := os.Stdin.Stat()
2638	if err != nil {
2639		return "", err
2640	}
2641	if (fi.Mode() & os.ModeCharDevice) != 0 {
2642		return "", nil
2643	}
2644	b, err := io.ReadAll(os.Stdin)
2645	return string(b), err
2646}
2647
2648func printModels() {
2649	models := provider.Active()
2650
2651	// Compute column widths from actual data so wide providers (e.g.
2652	// xiaomi-token-plan-sgp) and long bedrock model ids don't force the
2653	// `name` column off-screen. Floors mirror the historical layout so
2654	// short catalogs look the same as before.
2655	provW, idW, srcW := len("provider"), len("model id"), len("source")
2656	for _, m := range models {
2657		if w := len(m.Provider); w > provW {
2658			provW = w
2659		}
2660		if w := len(m.ID); w > idW {
2661			idW = w
2662		}
2663		source := m.Source
2664		if source == "" {
2665			source = "catalog"
2666		}
2667		if m.Speculative {
2668			source = "speculative"
2669		}
2670		if w := len(source); w > srcW {
2671			srcW = w
2672		}
2673	}
2674
2675	header := fmt.Sprintf("%-*s  %-*s  %8s  %8s  %s  %-*s  %s",
2676		provW, "provider",
2677		idW, "model id",
2678		"context", "max-out", "reasoning",
2679		srcW, "source",
2680		"name")
2681	fmt.Println(header)
2682
2683	for _, m := range models {
2684		reason := " "
2685		if m.Reasoning {
2686			reason = "✓"
2687		}
2688		source := m.Source
2689		if source == "" {
2690			source = "catalog"
2691		}
2692		if m.Speculative {
2693			source = "speculative"
2694		}
2695		fmt.Printf("%-*s  %-*s  %8d  %8d     %s      %-*s  %s\n",
2696			provW, m.Provider,
2697			idW, m.ID,
2698			m.ContextWindow, m.MaxOutput,
2699			reason,
2700			srcW, source,
2701			m.DisplayName)
2702	}
2703}