Trim eager read tool schemas

* docs(agents): codify recurring review blockers in AGENTS.md

Capture the high-frequency classes that drive multi-round maintainer reviews
(stale bases, path canonicalization, secret handling, partial setup, missing
regression tests, scope honesty) so coding agents fix them before first review.

Refs #856

* docs(agents): tighten security and atomic-write review guidance

Require open-time containment binding instead of pre-open EvalSymlinks, and
require temp-file then atomic replace rather than exclusive create alone.

Refs #856

* docs(agents): require traversal-wide containment for no-follow APIs

Final-component-only O_NOFOLLOW is insufficient on Linux and reparse
points need platform protections. Align the Security edges guidance
with the full-path containment requirement from review.

.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.5.0"}
+{".":"0.6.0"}

AGENTS.md

@@ -67,3 +67,39 @@ requirements. If a related check fails, fix it. If a required check cannot run
 because of the environment or fails for an unrelated external reason, report
 the exact failure and obtain maintainer direction rather than silently ignoring
 it.
+
+## 4. Common Review Blockers
+
+These classes drive multi-round reviews. Fix them before requesting review:
+
+- **Fresh base:** Rebase onto the current PR base (`main` or stacked target)
+  before review. A stale head that rolls back mainline commits is a hard
+  blocker, not a merge-time detail. Resolve conflicts by keeping upstream
+  behavior unless the PR intentionally changes it.
+- **Platform truth:** Code and tests must pass on Linux, macOS, and Windows.
+  Compare paths after canonicalization (physical/`EvalSymlinks` form); never
+  assert raw `t.TempDir()` spellings (`/var` vs `/private/var` on macOS, short
+  paths on Windows). Prefer one cross-platform function with small `GOOS`
+  checks over duplicated helpers that drift.
+- **Security edges:** Keep secrets out of argv, env dumps, and logs. Redact
+  success and error paths (including stderr). Fail closed on ownership, lease,
+  and permission checks. Do not rely on pre-open path resolution
+  (`EvalSymlinks` then open) for containment: that is a check-to-use race.
+  Bind containment at open/use time with rooted or handle-relative,
+  traversal-resistant APIs. If a no-follow API is used, apply it to every
+  traversed component and enforce the platform's reparse-point protections;
+  final-component-only no-follow is insufficient. On multi-step setup, roll back
+  only what this run created; never destroy pre-existing resources you did
+  not create; never report success when cleanup or unlock failed.
+- **Atomic shared state:** Write a complete temporary file, then atomically
+  replace the destination so concurrent readers never see a partial write.
+  Exclusive create or a write lock alone is not enough for readers. Serialize
+  the full read-modify-write sequence for lockfiles and shared stores.
+- **Tests match the claim:** Every behavior or security-boundary change needs a
+  regression test, including the failure path. Path-sensitive logic needs at
+  least one non-Linux path case (or a hermetic fake that exercises the same
+  normalization).
+- **Honest scope:** PR description, help text, and comments must match what
+  shipped. Wire advertised entry points or shrink the claim. Do not bundle
+  unrelated fixes. Do not widen security allowlists by name alone; check
+  classification and side effects too.

CHANGELOG.md

@@ -6,6 +6,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once the first release is
 tagged. Until then, source builds report the version `dev`.
 
+## [0.6.0](https://github.com/Gitlawb/zero/compare/v0.5.0...v0.6.0) (2026-07-29)
+
+
+### Features
+
+* add persistent session goals ([#803](https://github.com/Gitlawb/zero/issues/803)) ([5d1869e](https://github.com/Gitlawb/zero/commit/5d1869e7bc193c97e07418b57b823905c1151d5d))
+* **providers:** add Fireworks AI provider preset ([#772](https://github.com/Gitlawb/zero/issues/772)) ([58daea7](https://github.com/Gitlawb/zero/commit/58daea7a482927e5ab35afaf97761c60bb35e113))
+* **skills:** report hash drift in skill info ([#795](https://github.com/Gitlawb/zero/issues/795)) ([9fbdc34](https://github.com/Gitlawb/zero/commit/9fbdc341551601c13434cf7b9b6f5e4ea4c483b1))
+
+
+### Bug Fixes
+
+* **acp:** interrupt idle reads on cancellation ([#782](https://github.com/Gitlawb/zero/issues/782)) ([15b7a54](https://github.com/Gitlawb/zero/commit/15b7a5475cfeefddbc59634551451a8872b996b7))
+* **cli:** include plugins info in shell completions ([#794](https://github.com/Gitlawb/zero/issues/794)) ([fa8734f](https://github.com/Gitlawb/zero/commit/fa8734f17927de8832dfe041e043cfb86f93d12a))
+* **config:** kill provider-command process tree via job object on Windows ([#690](https://github.com/Gitlawb/zero/issues/690)) ([5c58256](https://github.com/Gitlawb/zero/commit/5c58256abc29c185b449f8ce79647eb3fae61882))
+* **config:** make the provider-command timeout an upper bound ([#811](https://github.com/Gitlawb/zero/issues/811)) ([#813](https://github.com/Gitlawb/zero/issues/813)) ([1c38e8c](https://github.com/Gitlawb/zero/commit/1c38e8cba50db255f3cda8b7cf4298712b2933e1))
+* **config:** stop billing provider-command fixtures to the 5s timeout ([#810](https://github.com/Gitlawb/zero/issues/810)) ([f5fa4ff](https://github.com/Gitlawb/zero/commit/f5fa4ffc64537897aa78a56edca36d8f1dacd021))
+* **cron:** reserve job IDs atomically ([#686](https://github.com/Gitlawb/zero/issues/686)) ([d9b882e](https://github.com/Gitlawb/zero/commit/d9b882eb0a94f38de8447cb54b57860ccd8ed053))
+* **lint:** resolve static analysis baseline ([#769](https://github.com/Gitlawb/zero/issues/769)) ([583e653](https://github.com/Gitlawb/zero/commit/583e6530bd849a8efcb2b88bbe8c297e8592e62c))
+* **providers:** retry provably pre-send transport failures ([#447](https://github.com/Gitlawb/zero/issues/447)) ([#750](https://github.com/Gitlawb/zero/issues/750)) ([8acd42a](https://github.com/Gitlawb/zero/commit/8acd42a3bd743a35807d762f23a33fb61c171839))
+* **sandbox:** add platform-specific write lock around grant state file ([#752](https://github.com/Gitlawb/zero/issues/752)) ([#755](https://github.com/Gitlawb/zero/issues/755)) ([88fb7b6](https://github.com/Gitlawb/zero/commit/88fb7b6192c1ac8173089967d5e9119f92d7a101))
+* **sandbox:** clarify scoped permission prompts ([#798](https://github.com/Gitlawb/zero/issues/798)) ([9fe02ae](https://github.com/Gitlawb/zero/commit/9fe02ae52e3234cb9dae76e0c5594a287ccbb52a))
+* **sandbox:** deny reads of git's credential stores ([#815](https://github.com/Gitlawb/zero/issues/815)) ([#816](https://github.com/Gitlawb/zero/issues/816)) ([33c94ec](https://github.com/Gitlawb/zero/commit/33c94ec7a3e7987e6e36b5fd5e037ff4e6e84c26))
+* **sandbox:** preserve user config and retry denied writes ([#801](https://github.com/Gitlawb/zero/issues/801)) ([81a5e6c](https://github.com/Gitlawb/zero/commit/81a5e6cb716ba4b7ecf7ff3ff261dfa51fd01098))
+* **sandbox:** scrub the daemon token file pointer ([#677](https://github.com/Gitlawb/zero/issues/677)) ([#818](https://github.com/Gitlawb/zero/issues/818)) ([3e7692d](https://github.com/Gitlawb/zero/commit/3e7692d8f0885d346809869935c81a9cf055d89e))
+* **swarm:** close lifecycle admission on shutdown ([#776](https://github.com/Gitlawb/zero/issues/776)) ([bdbda89](https://github.com/Gitlawb/zero/commit/bdbda89f3e42d93e8058ab3e1e9ef402659530cd))
+* **tui:** fix rendering corruption over multipass + Windows Terminal ([#709](https://github.com/Gitlawb/zero/issues/709)) ([5bb1bc1](https://github.com/Gitlawb/zero/commit/5bb1bc11c3188dcea7709ff07c8b25dda3541de8))
+* **tui:** paste clipboard images with Ctrl+V ([#534](https://github.com/Gitlawb/zero/issues/534)) ([#807](https://github.com/Gitlawb/zero/issues/807)) ([ec3b822](https://github.com/Gitlawb/zero/commit/ec3b8225050eb62f0f41a9582ed2881d2f9dcc8e))
+* **tui:** reset quiet clock for new runs ([#799](https://github.com/Gitlawb/zero/issues/799)) ([a4a805a](https://github.com/Gitlawb/zero/commit/a4a805a6c82c51cb255e909bd87ca183c8805cf2))
+* **windows:** use PowerShell for command execution ([#804](https://github.com/Gitlawb/zero/issues/804)) ([518d2e5](https://github.com/Gitlawb/zero/commit/518d2e53ba3fa073090a9b41c278face85b59b64))
+
 ## [0.5.0](https://github.com/Gitlawb/zero/compare/v0.4.0...v0.5.0) (2026-07-22)
 
 

README.md

@@ -131,6 +131,7 @@ export ANTHROPIC_API_KEY=...
 export GEMINI_API_KEY=...
 export AIMLAPI_API_KEY=...
 export LONGCAT_API_KEY=...
+export FIREWORKS_API_KEY=...
 export MINIMAX_API_KEY=...
 export MINIMAXI_API_KEY=...
 ```
@@ -147,6 +148,12 @@ To configure Meituan LongCat (LongCat-2.0) directly, run:
 zero providers setup longcat --set-active
 ```
 
+To configure Fireworks AI directly, run:
+
+```bash
+zero providers setup fireworks --set-active
+```
+
 MiniMax presets use the Anthropic-compatible endpoints for the global and China
 regions:
 

internal/acp/jsonrpc.go

@@ -17,6 +17,7 @@ import (
 	"fmt"
 	"io"
 	"sync"
+	"sync/atomic"
 )
 
 // JSON-RPC 2.0 standard error codes.
@@ -80,8 +81,9 @@ type NotifyFunc func(ctx context.Context, params json.RawMessage)
 // requests/notifications — needed because ACP is bidirectional (the agent calls
 // the client for session/request_permission, fs/*, terminal/*).
 type Conn struct {
-	reader *bufio.Reader
-	w      io.Writer
+	rawReader    io.Reader // wrapped lazily in Serve, once ctx is known — see interruptibleReader
+	readerCloser io.Closer
+	w            io.Writer
 
 	writeMu sync.Mutex // serializes all writes to w
 
@@ -96,10 +98,15 @@ type Conn struct {
 	wg sync.WaitGroup // tracks in-flight inbound handlers
 }
 
-// NewConn builds a peer reading ndjson from r and writing ndjson to w.
+// NewConn builds a peer reading ndjson from r and writing ndjson to w. This
+// Conn does not own r: cancelling Serve's context cannot forcibly close it, so
+// a Read on r that's genuinely idle (never returns on its own) leaves Serve
+// blocked until r itself produces something — e.g. a test that closes r's own
+// write side to unblock it. Use NewOwnedConn when this Conn should own r's
+// lifetime.
 func NewConn(r io.Reader, w io.Writer) *Conn {
 	return &Conn{
-		reader:    bufio.NewReader(r),
+		rawReader: r,
 		w:         w,
 		handlers:  make(map[string]HandlerFunc),
 		notifiers: make(map[string]NotifyFunc),
@@ -107,6 +114,18 @@ func NewConn(r io.Reader, w io.Writer) *Conn {
 	}
 }
 
+// NewOwnedConn is like NewConn but declares that this Conn exclusively owns r:
+// if r implements io.Closer, Serve closes it on context cancellation to
+// interrupt an otherwise-idle blocking Read. Only pass a reader whose lifetime
+// this Conn should control — e.g. the process's own stdin — never a reader a
+// caller retains or shares elsewhere, since cancellation tears it down
+// permanently for every consumer, not just this Conn.
+func NewOwnedConn(r io.Reader, w io.Writer) *Conn {
+	c := NewConn(r, w)
+	c.readerCloser, _ = r.(io.Closer)
+	return c
+}
+
 // Handle registers a request handler for method.
 func (c *Conn) Handle(method string, fn HandlerFunc) { c.handlers[method] = fn }
 
@@ -128,17 +147,36 @@ func (c *Conn) Serve(ctx context.Context) error {
 		c.wg.Wait()
 	}()
 
+	interruptible := newInterruptibleReader(ctx, c.rawReader, c.readerCloser)
+	reader := bufio.NewReader(interruptible)
+
 	for {
 		// One ndjson value per line. Framing per line (rather than streaming the
 		// decoder) keeps a single malformed line from making the whole connection
 		// unrecoverable — we report -32700 and continue.
-		line, err := c.reader.ReadBytes('\n')
+		//
+		// generation brackets this SPECIFIC ReadBytes call: bufio may invoke
+		// interruptible.Read zero or more times underneath it (zero when the
+		// answer is already sitting in bufio's own buffer — including a
+		// previously-buffered, not-yet-surfaced error: bufio can return a
+		// complete line with a nil error while quietly caching an error it
+		// received ALONGSIDE that line's bytes, which then surfaces on the VERY
+		// NEXT call with no further contact with interruptible.Read at all). The
+		// generation only advances inside interruptible.Read's own cancellation
+		// branch, so "unchanged across this call" is proof this call's outcome
+		// didn't pass through that branch — whether because it was answered from
+		// the buffer or because it raced ctx.Done() and won. Only that proof
+		// makes it safe to call the outcome genuine.
+		before := interruptible.generation()
+		line, err := reader.ReadBytes('\n')
+		interrupted := interruptible.generation() != before
+
 		if len(bytes.TrimSpace(line)) > 0 {
 			c.handleLine(ctx, line)
 		}
 		if err != nil {
 			c.failAllPending(err)
-			if errors.Is(err, io.EOF) || ctx.Err() != nil {
+			if errors.Is(err, io.EOF) || interrupted {
 				return nil
 			}
 			return err
@@ -146,6 +184,100 @@ func (c *Conn) Serve(ctx context.Context) error {
 	}
 }
 
+// interruptibleReader wraps a reader so a context cancellation can unblock a
+// currently in-flight Read without ever discarding — or misattributing — the
+// real outcome of a call that wasn't actually blocked.
+//
+// Each Read runs the underlying call on its own goroutine and races it against
+// ctx.Done(). If the underlying call finishes first, its result is returned
+// exactly as received; ctx being cancelled a moment later has no bearing on a
+// call that already had its answer. If ctx.Done() fires first, closer (when
+// non-nil) is closed to nudge a genuinely blocked read, the generation counter
+// is bumped, and the call STILL waits for and returns the underlying call's own
+// result — never a synthesized one — since closing a reader's outcome is
+// whatever the reader itself reports for it, not ours to invent.
+//
+// The counter is what lets Serve tell a call that was actually raced against
+// cancellation apart from one merely answered while cancellation happened to be
+// pending — the distinction the read loop's own doc comment explains.
+type interruptibleReader struct {
+	inner  io.Reader
+	closer io.Closer
+	ctx    context.Context
+
+	closeOnce sync.Once
+	gen       atomic.Int64
+}
+
+func newInterruptibleReader(ctx context.Context, inner io.Reader, closer io.Closer) *interruptibleReader {
+	return &interruptibleReader{inner: inner, closer: closer, ctx: ctx}
+}
+
+func (r *interruptibleReader) generation() int64 { return r.gen.Load() }
+
+type interruptibleReadResult struct {
+	n   int
+	err error
+}
+
+// interruptibleReadDecision arbitrates whether an underlying Read completed or
+// cancellation claimed it first. Completion is recorded before the result is
+// published so cancellation cannot misclassify a finished read merely because
+// its goroutine has not sent the result yet.
+type interruptibleReadDecision struct {
+	once sync.Once
+}
+
+func (d *interruptibleReadDecision) complete() { d.once.Do(func() {}) }
+
+func (d *interruptibleReadDecision) interrupt() (claimed bool) {
+	d.once.Do(func() { claimed = true })
+	return claimed
+}
+
+// readInner records completion in the Read call's deferred epilogue. It also
+// converts a reader panic into a terminal error so the helper goroutine always
+// publishes a result for Read to join.
+func (r *interruptibleReader) readInner(p []byte, decision *interruptibleReadDecision) (res interruptibleReadResult) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			res = interruptibleReadResult{err: fmt.Errorf("acp: reader panicked: %v", recovered)}
+		}
+		decision.complete()
+	}()
+	res.n, res.err = r.inner.Read(p)
+	return res
+}
+
+func (r *interruptibleReader) Read(p []byte) (int, error) {
+	resultCh := make(chan interruptibleReadResult, 1)
+	var decision interruptibleReadDecision
+	go func() {
+		resultCh <- r.readInner(p, &decision)
+	}()
+	select {
+	case res := <-resultCh:
+		return res.n, res.err
+	case <-r.ctx.Done():
+		// resultCh may not be readable yet even when inner.Read has returned: its
+		// goroutine can be descheduled between recording completion and publishing
+		// the result. Only interrupt a call that cancellation actually claims.
+		if decision.interrupt() {
+			r.gen.Add(1)
+			if r.closer != nil {
+				r.closeOnce.Do(func() { _ = r.closer.Close() })
+			}
+		}
+		// Wait for the real result rather than returning synthetically: p is
+		// still being written by the goroutine above until it does, so returning
+		// early would race that write, and the actual error (whatever closing
+		// the reader produced, or whatever the reader was already about to
+		// report) is what the caller should see.
+		res := <-resultCh
+		return res.n, res.err
+	}
+}
+
 // handleLine decodes and dispatches one ndjson frame. A parse failure replies
 // with -32700 (id null) and keeps the connection alive.
 func (c *Conn) handleLine(ctx context.Context, line []byte) {

internal/acp/jsonrpc_test.go

@@ -3,11 +3,30 @@ package acp
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
+	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 )
 
+type testReadCloser struct {
+	read  func([]byte) (int, error)
+	close func() error
+}
+
+func (r testReadCloser) Read(p []byte) (int, error) { return r.read(p) }
+func (r testReadCloser) Close() error               { return r.close() }
+
+type testReader func([]byte) (int, error)
+
+func (r testReader) Read(p []byte) (int, error) { return r(p) }
+
+type testWriter func([]byte) (int, error)
+
+func (w testWriter) Write(p []byte) (int, error) { return w(p) }
+
 // connPair wires two Conns together over in-memory pipes and serves both.
 func connPair(t *testing.T) (a, b *Conn, stop func()) {
 	t.Helper()
@@ -25,6 +44,275 @@ func connPair(t *testing.T) (a, b *Conn, stop func()) {
 	}
 }
 
+func TestConnServeCancellationInterruptsIdleRead(t *testing.T) {
+	pipeReader, writer := io.Pipe()
+	t.Cleanup(func() { _ = writer.Close() })
+	// Buffered + non-blocking send, not close: interruptibleReader retries each
+	// underlying Read on its own goroutine, so if bufio ever calls this more than
+	// once, a close() here would panic on the second call.
+	readStarted := make(chan struct{}, 1)
+	closeCalls := make(chan struct{}, 2)
+	reader := testReadCloser{
+		read: func(p []byte) (int, error) {
+			select {
+			case readStarted <- struct{}{}:
+			default:
+			}
+			return pipeReader.Read(p)
+		},
+		close: func() error {
+			closeCalls <- struct{}{}
+			return pipeReader.Close()
+		},
+	}
+	conn := NewOwnedConn(reader, io.Discard)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(ctx) }()
+
+	<-readStarted
+	cancel()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Serve returned %v after cancellation, want nil", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after cancelling an idle connection")
+	}
+	if got := len(closeCalls); got != 1 {
+		t.Fatalf("reader Close calls = %d, want 1", got)
+	}
+}
+
+func TestConnServePreservesTerminalReadErrorDuringCancellation(t *testing.T) {
+	for _, closable := range []bool{false, true} {
+		name := "non-closable"
+		if closable {
+			name = "closable"
+		}
+		t.Run(name, func(t *testing.T) {
+			wantErr := errors.New("read failed")
+			read := testReader(func(p []byte) (int, error) {
+				return copy(p, "not json"), wantErr
+			})
+			closeCalls := make(chan struct{}, 1)
+			var reader io.Reader = read
+			if closable {
+				reader = testReadCloser{
+					read: read,
+					close: func() error {
+						closeCalls <- struct{}{}
+						return nil
+					},
+				}
+			}
+			// Buffered + non-blocking send, not close: a later change adding a
+			// second write (e.g. an additional error frame) must not panic on a
+			// repeated close of an already-closed channel.
+			writeStarted := make(chan struct{}, 1)
+			releaseWrite := make(chan struct{})
+			writer := testWriter(func(p []byte) (int, error) {
+				select {
+				case writeStarted <- struct{}{}:
+				default:
+				}
+				<-releaseWrite
+				return len(p), nil
+			})
+			newConn := NewConn
+			if closable {
+				// Ownership matters here: this case exists to prove that even a
+				// Conn entitled to close its reader on cancellation still
+				// preserves a terminal error that was already decided.
+				newConn = NewOwnedConn
+			}
+			conn := newConn(reader, writer)
+			ctx, cancel := context.WithCancel(context.Background())
+			done := make(chan error, 1)
+			go func() { done <- conn.Serve(ctx) }()
+
+			<-writeStarted
+			cancel()
+			close(releaseWrite)
+			select {
+			case err := <-done:
+				if !errors.Is(err, wantErr) {
+					t.Fatalf("Serve returned %v, want terminal read error %v", err, wantErr)
+				}
+			case <-time.After(time.Second):
+				t.Fatal("Serve did not return after terminal read error")
+			}
+			if got := len(closeCalls); got != 0 {
+				t.Fatalf("reader Close calls = %d, want 0 after terminal read", got)
+			}
+		})
+	}
+}
+
+// TestConnServePreservesReadErrorBufferedAlongsideAPriorLine is the deterministic
+// regression test for jatmn's #782 finding: a real, non-EOF ReadBytes failure can
+// be DECIDED before cancellation ever happens, yet only SURFACE afterward, and
+// must still be reported rather than swallowed as a clean shutdown.
+//
+// bufio.Reader can obtain data AND a terminal error from ONE underlying Read call
+// (io.Reader explicitly permits returning (n>0, err) together). If a delimiter is
+// found within that data, ReadBytes returns the line with a nil error for THIS
+// call, but bufio caches the error internally and returns it — WITHOUT calling the
+// underlying reader again — on the very next ReadBytes call. This test forces that
+// exact sequence: the underlying reader hands back one complete, validly-framed
+// line together with wantErr in a SINGLE call (asserted below to be its ONLY
+// call), the loop dispatches that line through a synchronous path that blocks the
+// read loop, cancellation is asserted to have happened before the loop attempts
+// its next read, and only then is the block released. By the time the read loop
+// asks for more input, cancellation is already in effect and the underlying
+// reader is never touched again — so if Serve attributed the resulting error to
+// cancellation merely because ctx was already done, it would incorrectly return
+// nil. It must instead recognize that this read was answered entirely from
+// bufio's own cache, never raced against ctx.Done(), and report wantErr.
+func TestConnServePreservesReadErrorBufferedAlongsideAPriorLine(t *testing.T) {
+	wantErr := errors.New("read failed")
+	var readCalls atomic.Int32
+	read := testReader(func(p []byte) (int, error) {
+		readCalls.Add(1)
+		// An unsupported jsonrpc version with an id takes the SYNCHRONOUS
+		// writeError path in handleLine (not a dispatched goroutine), giving this
+		// test a reliable blocking point between processing this line and the
+		// loop's next ReadBytes call.
+		return copy(p, `{"jsonrpc":"1.0","id":1}`+"\n"), wantErr
+	})
+	writeStarted := make(chan struct{}, 1)
+	releaseWrite := make(chan struct{})
+	var releaseWriteOnce sync.Once
+	release := func() { releaseWriteOnce.Do(func() { close(releaseWrite) }) }
+	t.Cleanup(release)
+	writer := testWriter(func(p []byte) (int, error) {
+		select {
+		case writeStarted <- struct{}{}:
+		default:
+		}
+		<-releaseWrite
+		return len(p), nil
+	})
+	conn := NewConn(read, writer)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(ctx) }()
+
+	// The synchronous write confirms the first (and, per the panic guard above,
+	// only) read has already returned and is being processed — cancelling now
+	// lands squarely in the gap between that read and the loop's next one, never
+	// racing an in-flight interruptibleReader.Read call.
+	select {
+	case <-writeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not reach the synchronous write")
+	}
+	cancel()
+	release()
+
+	select {
+	case err := <-done:
+		if !errors.Is(err, wantErr) {
+			t.Fatalf("Serve returned %v, want the buffered terminal read error %v", err, wantErr)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after the buffered terminal read error")
+	}
+	if got := readCalls.Load(); got != 1 {
+		t.Fatalf("underlying Read calls = %d, want exactly 1 (bufio must have served the second ReadBytes from its cache)", got)
+	}
+}
+
+// TestInterruptibleReaderPrefersDecidedResultOverCancellation is the regression
+// test for jatmn's second #782 finding: interruptibleReader.Read's select
+// between resultCh and ctx.Done() chooses pseudo-randomly when both are ready,
+// so a real, already-decided outcome (e.g. a terminal transport error) could be
+// misattributed to cancellation purely because ctx also happened to be done by
+// the time the select ran. Each iteration lets the underlying Read return (so
+// resultCh already holds the real outcome) before cancelling, maximizing the
+// odds of landing exactly in that ambiguous window; the generation counter must
+// never advance when the real, already-decided result is what gets returned.
+func TestInterruptibleReaderPrefersDecidedResultOverCancellation(t *testing.T) {
+	wantErr := errors.New("read failed")
+	for i := 0; i < 100; i++ {
+		resultReady := make(chan struct{})
+		read := testReader(func(p []byte) (int, error) {
+			defer close(resultReady)
+			return copy(p, "x"), wantErr
+		})
+		ctx, cancel := context.WithCancel(context.Background())
+		r := newInterruptibleReader(ctx, read, nil)
+
+		readDone := make(chan interruptibleReadResult, 1)
+		go func() {
+			n, err := r.Read(make([]byte, 8))
+			readDone <- interruptibleReadResult{n, err}
+		}()
+
+		<-resultReady
+		time.Sleep(time.Millisecond) // bias resultCh's send ahead of cancel
+		cancel()
+
+		res := <-readDone
+		if !errors.Is(res.err, wantErr) {
+			t.Fatalf("iteration %d: Read returned %v, want %v", i, res.err, wantErr)
+		}
+		if got := r.generation(); got != 0 {
+			t.Fatalf("iteration %d: generation = %d, want 0 (a decided result must never be attributed to cancellation)", i, got)
+		}
+		cancel()
+	}
+}
+
+// TestInterruptibleReadCompletionWinsBeforeResultPublication exercises the
+// actual inner-read wrapper at the handoff between the underlying Read and the
+// helper goroutine's result publication. Cancellation must not reclassify a
+// result returned by this wrapper as interrupted.
+func TestInterruptibleReadCompletionWinsBeforeResultPublication(t *testing.T) {
+	wantErr := errors.New("read failed")
+	read := testReader(func(p []byte) (int, error) {
+		return copy(p, "x"), wantErr
+	})
+	r := newInterruptibleReader(context.Background(), read, nil)
+	var decision interruptibleReadDecision
+	readComplete := make(chan struct{})
+	resultCh := make(chan interruptibleReadResult)
+	go func() {
+		res := r.readInner(make([]byte, 8), &decision)
+		close(readComplete)
+		resultCh <- res
+	}()
+
+	<-readComplete
+	if decision.interrupt() {
+		t.Fatal("cancellation claimed a read that completed before result publication")
+	}
+	res := <-resultCh
+	if res.n != 1 || !errors.Is(res.err, wantErr) {
+		t.Fatalf("inner read result = (%d, %v), want (1, %v)", res.n, res.err, wantErr)
+	}
+}
+
+func TestConnServeReportsReaderPanicAsTerminalError(t *testing.T) {
+	read := testReader(func([]byte) (int, error) {
+		panic("boom")
+	})
+	conn := NewConn(read, io.Discard)
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(context.Background()) }()
+
+	select {
+	case err := <-done:
+		const want = "acp: reader panicked: boom"
+		if err == nil || err.Error() != want {
+			t.Fatalf("Serve returned %v, want %q", err, want)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after reader panic")
+	}
+}
+
 func TestConnRequestResponse(t *testing.T) {
 	a, b, stop := connPair(t)
 	defer stop()

internal/agent/additional_permissions_validation_test.go

@@ -5,9 +5,29 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/Gitlawb/zero/internal/sandbox"
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
+type normalizationRecordingShellTool struct {
+	calls []map[string]any
+}
+
+func (tool *normalizationRecordingShellTool) Name() string { return "bash" }
+func (tool *normalizationRecordingShellTool) Description() string {
+	return "record normalized shell arguments"
+}
+func (tool *normalizationRecordingShellTool) Parameters() tools.Schema {
+	return tools.Schema{Type: "object", AdditionalProperties: true}
+}
+func (tool *normalizationRecordingShellTool) Safety() tools.Safety {
+	return tools.Safety{SideEffect: tools.SideEffectShell, Permission: tools.PermissionAllow}
+}
+func (tool *normalizationRecordingShellTool) Run(_ context.Context, args map[string]any) tools.Result {
+	tool.calls = append(tool.calls, cloneArgs(args))
+	return tools.Result{Status: tools.StatusOK}
+}
+
 // A shell call that sets sandbox_permissions: with_additional_permissions but
 // omits (or malforms) additional_permissions can never succeed: the same
 // validation runs again at grant time regardless of the user's decision. It
@@ -107,9 +127,7 @@ func TestExecuteToolCallMissingAdditionalPermissionsErrorIsActionable(t *testing
 	if !strings.Contains(result.Output, `{"network": {"enabled": true}}`) {
 		t.Fatalf("output = %q, want a concrete additional_permissions example", result.Output)
 	}
-	if !strings.Contains(result.Output, "omit sandbox_permissions") {
-		t.Fatalf("output = %q, want guidance that the flag can simply be omitted", result.Output)
-	}
+	assertNamesOmitRemedy(t, "missing additional_permissions", result.Output)
 }
 
 // A well-formed additional_permissions payload must still reach the normal
@@ -144,3 +162,237 @@ func TestExecuteToolCallStillPromptsForValidAdditionalPermissions(t *testing.T)
 		t.Fatalf("OnPermissionRequest called %d times, want exactly 1 for a valid elevation request", promptCalls)
 	}
 }
+
+// runShellCall drives one shell tool call through the real registry (and so
+// through Registry.RunWithOptions) exactly as the agent loop would.
+func runShellCall(t *testing.T, root string, arguments string) ToolResult {
+	t.Helper()
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedExecCommandTool(root, nil, nil))
+	result, err := executeToolCall(
+		context.Background(),
+		registry,
+		ToolCall{ID: "c1", Name: "exec_command", Arguments: arguments},
+		PermissionModeUnsafe,
+		Options{Cwd: root},
+	)
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	return result
+}
+
+// TestAdditionalPermissionsRejectionsConverge is the regression guard for
+// #845/#847. A model that attaches a permission object to a command needing
+// none used to be told only "set sandbox_permissions", which pushed it into the
+// OTHER invalid shape (flag set, payload empty) and its "include a permission"
+// error pushed it straight back — the reported loop that burned turns on
+// `git branch --show-current`.
+//
+// The contract this pins is convergence, not tolerance: both shapes are still
+// REJECTED (nothing here grants access), but each rejection must name the one
+// follow-up call that works, and that follow-up must actually succeed.
+func TestAdditionalPermissionsRejectionsConverge(t *testing.T) {
+	root := t.TempDir()
+	const readOnly = `"cmd":"git --version"`
+
+	// Step 1 of the reported loop: a permission object with no flag.
+	first := runShellCall(t, root, `{`+readOnly+`,"additional_permissions":{"network":{"enabled":true}}}`)
+	if first.Status != tools.StatusError {
+		t.Fatalf("unflagged additional_permissions status = %q, want error (rejecting is correct)", first.Status)
+	}
+	assertNamesOmitRemedy(t, "unflagged additional_permissions", first.Output)
+
+	// Step 2 of the reported loop: the model keeps the flag but empties the
+	// payload. This must not be the dead end it was.
+	second := runShellCall(t, root, `{`+readOnly+`,"sandbox_permissions":"with_additional_permissions"}`)
+	if second.Status != tools.StatusError {
+		t.Fatalf("flag without payload status = %q, want error", second.Status)
+	}
+	assertNamesOmitRemedy(t, "flag without payload", second.Output)
+
+	// The call both errors point at must actually work.
+	converged := runShellCall(t, root, `{`+readOnly+`}`)
+	if converged.Status != tools.StatusOK {
+		t.Fatalf("the call both errors instruct the model to make failed: status=%q output=%q", converged.Status, converged.Output)
+	}
+}
+
+// assertNamesOmitRemedy pins the actionable half of the error text: the message
+// must spell out that BOTH fields can simply be dropped. "Set the flag" or
+// "include a permission" alone is what made the two errors chase each other.
+func assertNamesOmitRemedy(t *testing.T, label string, output string) {
+	t.Helper()
+	if !strings.Contains(output, "omit both sandbox_permissions and additional_permissions") {
+		t.Fatalf("%s error = %q, want it to say to omit both fields entirely", label, output)
+	}
+	if !strings.Contains(output, "retry") {
+		t.Fatalf("%s error = %q, want it to tell the model to retry", label, output)
+	}
+}
+
+// The empty-payload rejection carries the same remedy. It is pinned on the
+// validator directly because normalizeNoopAdditionalPermissions absorbs the
+// empty payload before executeToolCall reaches this branch;
+// inlineAdditionalPermissionsProfile is still the shared source of truth that
+// buildPermissionEvent and the grant path re-run, so its text must converge too.
+func TestEmptyAdditionalPermissionsErrorNamesOmitRemedy(t *testing.T) {
+	args := map[string]any{
+		"cmd":                 "git --version",
+		"sandbox_permissions": string(tools.SandboxPermissionsWithAdditionalPermissions),
+		"additional_permissions": map[string]any{
+			"network":     map[string]any{"enabled": false},
+			"file_system": map[string]any{"read": []any{}, "write": []any{}},
+		},
+	}
+	_, requested, err := inlineAdditionalPermissionsProfile(args, t.TempDir())
+	if !requested {
+		t.Fatal("requested = false, want true for an explicit with_additional_permissions call")
+	}
+	if err == nil {
+		t.Fatal("an empty additional_permissions payload was accepted; it must still be rejected")
+	}
+	assertNamesOmitRemedy(t, "empty payload", err.Error())
+}
+
+// A provider that materializes every optional property may send
+// "additional_permissions": null. That grants nothing and carries no flag, so it
+// is the field omitted — rejecting it stalled an ordinary command behind an
+// error the model could not act on.
+func TestExecuteToolCallTreatsNullAdditionalPermissionsAsOmitted(t *testing.T) {
+	result := runShellCall(t, t.TempDir(), `{"cmd":"git --version","additional_permissions":null}`)
+	if result.Status != tools.StatusOK {
+		t.Fatalf("null additional_permissions was rejected: status=%q output=%q", result.Status, result.Output)
+	}
+}
+
+// A null payload alongside the flag must still be rejected, and must land on
+// the same error as an absent payload rather than being quietly downgraded.
+func TestExecuteToolCallRejectsFlaggedNullAdditionalPermissions(t *testing.T) {
+	result := runShellCall(t, t.TempDir(),
+		`{"cmd":"git --version","sandbox_permissions":"with_additional_permissions","additional_permissions":null}`)
+	if result.Status != tools.StatusError {
+		t.Fatalf("flagged null status = %q, want error", result.Status)
+	}
+	if !strings.Contains(result.Output, "no additional_permissions object was provided") {
+		t.Fatalf("output = %q, want the missing-payload error", result.Output)
+	}
+	assertNamesOmitRemedy(t, "flagged null", result.Output)
+}
+
+func TestNormalizeProviderExpandedEmptyAdditionalPermissions(t *testing.T) {
+	for _, mode := range []string{
+		string(tools.SandboxPermissionsUseDefault),
+		string(tools.SandboxPermissionsWithAdditionalPermissions),
+	} {
+		args := map[string]any{
+			"command":             "./zero --version",
+			"sandbox_permissions": mode,
+			"additional_permissions": map[string]any{
+				"file_system": map[string]any{
+					"deny_read": []any{},
+					"entries":   []any{},
+					"read":      []any{},
+					"write":     []any{},
+				},
+				"network": map[string]any{"enabled": false},
+			},
+		}
+		normalizeNoopAdditionalPermissions(args, t.TempDir(), nil)
+		if _, exists := args["additional_permissions"]; exists {
+			t.Fatalf("mode %q retained empty additional_permissions: %#v", mode, args)
+		}
+		if got := args["sandbox_permissions"]; got != string(tools.SandboxPermissionsUseDefault) {
+			t.Fatalf("mode %q normalized to %q, want use_default", mode, got)
+		}
+	}
+}
+
+func TestExecuteToolCallNormalizesProviderExpandedEmptyAdditionalPermissions(t *testing.T) {
+	tool := &normalizationRecordingShellTool{}
+	registry := tools.NewRegistry()
+	registry.Register(tool)
+
+	result, err := executeToolCall(
+		context.Background(),
+		registry,
+		ToolCall{
+			ID:   "c1",
+			Name: "bash",
+			Arguments: `{"command":"./zero --version","sandbox_permissions":"with_additional_permissions",` +
+				`"additional_permissions":{"file_system":{"deny_read":[],"entries":[],"read":[],"write":[]},"network":{"enabled":false}}}`,
+		},
+		PermissionModeAuto,
+		Options{Cwd: t.TempDir()},
+	)
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusOK {
+		t.Fatalf("provider-expanded empty permissions were rejected: %s", result.Output)
+	}
+	if len(tool.calls) != 1 {
+		t.Fatalf("shell tool calls = %d, want 1", len(tool.calls))
+	}
+	args := tool.calls[0]
+	if _, exists := args["additional_permissions"]; exists {
+		t.Fatalf("executeToolCall retained empty additional_permissions: %#v", args)
+	}
+	if got := args["sandbox_permissions"]; got != string(tools.SandboxPermissionsUseDefault) {
+		t.Fatalf("sandbox mode = %q, want use_default", got)
+	}
+}
+
+func TestNormalizeAdditionalPermissionsPreservesRealRequest(t *testing.T) {
+	args := map[string]any{
+		"sandbox_permissions": string(tools.SandboxPermissionsWithAdditionalPermissions),
+		"additional_permissions": map[string]any{
+			"network": map[string]any{"enabled": true},
+		},
+	}
+	normalizeNoopAdditionalPermissions(args, t.TempDir(), nil)
+	if _, exists := args["additional_permissions"]; !exists {
+		t.Fatal("non-empty additional_permissions was removed")
+	}
+	if got := args["sandbox_permissions"]; got != string(tools.SandboxPermissionsWithAdditionalPermissions) {
+		t.Fatalf("sandbox mode changed to %q", got)
+	}
+}
+
+func TestNormalizeAdditionalPermissionsRemovesWorkspaceReadAlreadyCoveredBySandbox(t *testing.T) {
+	root := t.TempDir()
+	engine := sandbox.NewEngine(sandbox.EngineOptions{
+		WorkspaceRoot: root,
+		Policy:        sandbox.DefaultPolicy(),
+	})
+	args := map[string]any{
+		"command":             "./zero --version",
+		"sandbox_permissions": string(tools.SandboxPermissionsWithAdditionalPermissions),
+		"additional_permissions": map[string]any{
+			"file_system": map[string]any{
+				"entries": []any{
+					map[string]any{
+						"access": "read",
+						"path": map[string]any{
+							"type": "path",
+							"path": ".",
+						},
+					},
+				},
+				"deny_read": []any{},
+				"read":      []any{},
+				"write":     []any{},
+			},
+			"network": map[string]any{"enabled": false},
+		},
+	}
+
+	normalizeNoopAdditionalPermissions(args, root, engine)
+
+	if _, exists := args["additional_permissions"]; exists {
+		t.Fatalf("already-covered additional_permissions was retained: %#v", args)
+	}
+	if got := args["sandbox_permissions"]; got != string(tools.SandboxPermissionsUseDefault) {
+		t.Fatalf("sandbox mode changed to %q", got)
+	}
+}

internal/agent/compaction.go

@@ -413,6 +413,14 @@ func (state *compactionState) maybeCompact(
 	// the bodies of old, large tool results (the model has already acted on
 	// them). If that brings us back under threshold, skip the paid summarizer
 	// entirely and preserve recent turns verbatim.
+	if pruned, reclaimed := pruneSupersededReadResults(messages); reclaimed > 0 {
+		messages = pruned
+		size = state.calibratedTokens(estimateTokens(messages) + toolTokens)
+		if size <= state.threshold {
+			state.lowWaterMark = size
+			return messages
+		}
+	}
 	if pruned, reclaimed := pruneStaleToolOutput(messages, state.preserveLast); reclaimed > 0 {
 		messages = pruned
 		size = state.calibratedTokens(estimateTokens(messages) + toolTokens)

internal/agent/compaction_test.go

@@ -379,6 +379,43 @@ func TestRunNoCompactionWhenContextWindowZero(t *testing.T) {
 	}
 }
 
+func TestMaybeCompactStopsAfterSupersededReadsReachThreshold(t *testing.T) {
+	body := strings.Repeat("same source line\n", 1000)
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "system"},
+		toolCallWithArgs("old", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "old", Content: body},
+		toolCallWithArgs("new", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "new", Content: body},
+	}
+	pruned, reclaimed := pruneSupersededReadResults(messages)
+	if reclaimed <= 0 {
+		t.Fatal("test setup did not reclaim superseded read output")
+	}
+	prunedSize := estimateTokens(pruned)
+	if estimateTokens(messages) <= prunedSize {
+		t.Fatal("test setup does not cross the compaction threshold")
+	}
+
+	provider := &summarizeRecordingProvider{}
+	state := &compactionState{
+		enabled:      true,
+		threshold:    prunedSize,
+		preserveLast: 2,
+	}
+	got := state.maybeCompact(context.Background(), provider, messages, nil)
+
+	if provider.summarizeCalls != 0 {
+		t.Fatalf("cheap pruning should avoid the summarizer, got %d calls", provider.summarizeCalls)
+	}
+	if state.lowWaterMark != prunedSize {
+		t.Fatalf("lowWaterMark = %d, want %d", state.lowWaterMark, prunedSize)
+	}
+	if !strings.Contains(got[2].Content, "superseded identical") || got[4].Content != body {
+		t.Fatalf("unexpected pruned messages: %#v", got)
+	}
+}
+
 // reactiveProvider builds up history with a tool call on turn 1, then errors
 // with a context-limit message on turn 2 (once the history is large enough that
 // compaction can shrink it), then succeeds on the same-turn retry. Summary

internal/agent/deferred_loop_test.go

@@ -341,15 +341,15 @@ func TestPartitionToolsActiveHidesUnloadedExposesLoaded(t *testing.T) {
 	if search.Description != discovery || !strings.Contains(search.Description, "mcp") {
 		t.Fatalf("tool_search description must carry discovery source, got %q", search.Description)
 	}
-	if strings.Contains(search.Description, "mcp__srv__alpha") {
-		t.Fatalf("tool_search description must not list already-loaded tool names, got %q", search.Description)
+	if !strings.Contains(search.Description, "mcp__srv__alpha") {
+		t.Fatalf("stable tool_search catalog must retain already-loaded tool names, got %q", search.Description)
 	}
 	if !strings.Contains(search.Description, "mcp__srv__beta") {
 		t.Fatalf("tool_search description must list exact hidden tool names, got %q", search.Description)
 	}
 }
 
-func TestPartitionToolsActiveNothingHiddenEmptyReminder(t *testing.T) {
+func TestPartitionToolsActiveNothingHiddenKeepsStableCatalog(t *testing.T) {
 	registry := tools.NewRegistry()
 	registry.Register(fakeDeferredTool{name: "mcp__srv__alpha", desc: "alpha"})
 	registry.Register(fakeDeferredTool{name: "mcp__srv__beta", desc: "beta"})
@@ -368,9 +368,8 @@ func TestPartitionToolsActiveNothingHiddenEmptyReminder(t *testing.T) {
 	if !exposedNames["tool_search"] {
 		t.Fatalf("expected tool_search exposed on active path, got %#v", exposed)
 	}
-	// No hidden tools means no dynamic discovery text is needed.
-	if reminder != "" {
-		t.Fatalf("expected empty discovery text when nothing is hidden, got %q", reminder)
+	if !strings.Contains(reminder, "mcp__srv__alpha") || !strings.Contains(reminder, "mcp__srv__beta") {
+		t.Fatalf("stable catalog must retain all deferred names after loading, got %q", reminder)
 	}
 }
 

internal/agent/loop.go

@@ -656,6 +656,13 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		// between tool_results breaks strict provider replay) — same after-batch
 		// rationale as turnRequestedModel above.
 		var changedFilesThisBatch []string
+		// Images produced by tools this turn, held until every tool_result is
+		// recorded. They travel as user messages, and a user message between two
+		// tool_results breaks strict provider replay — Anthropic coalesces them
+		// into one user block list and requires the tool_result blocks first, so
+		// interleaving yields [tool_result, text, image, tool_result] and a 400.
+		// Same reason the self-correction feedback below is deferred.
+		var toolImageMessages []zeroruntime.Message
 		// Parallel read-ahead state: results for calls[precomputedStart:precomputedEnd]
 		// executed concurrently, consumed strictly in order below.
 		var precomputed []precomputedToolResult
@@ -709,6 +716,16 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				Content:    toolResult.Output,
 				ToolCallID: toolResult.ToolCallID,
 			})
+			// Images ride a following USER message rather than the tool result
+			// above. Every provider drops images on a tool-role message —
+			// Anthropic's tool_result content is a string, Gemini's is a
+			// functionResponse, and OpenAI guards its image parts to the user role
+			// — so attaching them there would silently deliver nothing. A separate
+			// message also keeps the one-tool-result-per-tool-call pairing intact,
+			// which the providers validate.
+			if imageMessage, ok := toolResultImageMessage(toolResult); ok {
+				toolImageMessages = append(toolImageMessages, imageMessage)
+			}
 
 			// A tool may demand the run ABORT — a canceled/timed-out ask_user prompt
 			// returns context.Canceled rather than fabricating a headless answer. Stop
@@ -719,11 +736,13 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 			if abortErr != nil {
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.Messages = copyMessages(messages)
 				return result, abortErr
 			}
 			if stopReason := stopReasonFromToolResult(toolResult); stopReason != "" {
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.FinalAnswer = toolResult.Output
 				result.StopReason = stopReason
 				result.Messages = copyMessages(messages)
@@ -747,6 +766,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				// messages stay valid for a strict provider replay (Anthropic
 				// rejects a tool_use with no answering tool_result).
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.FinalAnswer = toolFailureStopAnswer(call.Name, outcome.Count)
 				result.Messages = copyMessages(messages)
 				return result, nil
@@ -765,6 +785,10 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				postEditDiagnostics.enqueue(ctx, toolResult.ChangedFiles)
 			}
 		}
+		// Every tool_result for this turn is now recorded, including aborted
+		// placeholders, so the images can follow without splitting them.
+		messages = append(messages, toolImageMessages...)
+		toolImageMessages = nil
 
 		// Run post-edit self-correction once over the union of files this turn
 		// changed, then append any feedback after every tool_result is recorded so
@@ -1076,6 +1100,9 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			}, nil
 		}
 	}
+	if isShellCommandTool(call.Name) {
+		normalizeNoopAdditionalPermissions(args, options.Cwd, options.Sandbox)
+	}
 	// tool_search is the gateway to the allowlisted deferred tools, so a non-empty
 	// EnabledTools allowlist that omits it must NOT reject the call — otherwise the
 	// discovery tool exposed to the model rejects at dispatch time (an inescapable
@@ -1354,7 +1381,8 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 		Cwd:               options.Cwd,
 		// Per-session file version tracker so write_file/edit_file refuse to clobber
 		// a file that changed on disk outside Zero since it was last read.
-		FileTracker: options.FileTracker,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
 		// Post-edit diagnostics are NOT forwarded to the tools: they used to run
 		// synchronously inside edit_file/write_file and block every mutating tool
 		// call on the language server (≥300ms debounce floor, 10s cap). The loop
@@ -1406,6 +1434,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			result = registry.RebudgetAfterHook(call.Name, args, result)
 		}
 	}
+	result = registry.CommitFileObservation(result, options.FileTracker)
 	// Stamp the sandbox risk classification for this EXECUTED call so run-policy
 	// observers can see the risk of an allowed mutation. Prefer the preflight
 	// decision's classification when the sandbox evaluated the call; otherwise
@@ -1431,6 +1460,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 		Output:          result.Output,
 		Truncated:       result.Truncated,
 		Meta:            result.Meta,
+		Images:          result.Images,
 		Redacted:        result.Redacted,
 		ChangedFiles:    result.ChangedFiles,
 		ChangeSummaries: result.ChangeSummaries,
@@ -1617,9 +1647,15 @@ func sandboxRestrictedShellRetryCandidate(call ToolCall, args map[string]any, re
 
 func sandboxDeniedShellResult(result tools.Result) bool {
 	if result.ExecutionOutcome != nil {
-		// Typed denials must be handled by their exact capability path. Never
-		// turn a structured narrow denial into the legacy unrestricted retry.
-		return false
+		// Only a typed platform denial that explicitly requests unrestricted
+		// recovery may enter the legacy retry path. Narrow capability denials
+		// remain on their exact capability path.
+		denial := result.ExecutionOutcome.Denial
+		return denial != nil &&
+			denial.Source == execution.DenialSourcePlatformSandbox &&
+			denial.Capability.Kind == execution.CapabilityUnrestricted &&
+			denial.Recoverable &&
+			denial.NextAction == execution.DenialNextActionRequestApproval
 	}
 	return result.Status == tools.StatusError && result.Meta[tools.SandboxLikelyDeniedMeta] == "true"
 }
@@ -1684,20 +1720,21 @@ func sandboxRestrictionRetryReason(result tools.Result) string {
 
 func runToolForNetworkRetry(ctx context.Context, registry *tools.Registry, name string, toolCallID string, args map[string]any, permissionMode PermissionMode, options Options, progressCallback func(streamjson.Event)) tools.Result {
 	return registry.RunWithOptions(ctx, name, cloneArgs(args), tools.RunOptions{
-		PermissionGranted: true,
-		PermissionMode:    string(permissionMode),
-		Autonomy:          options.Autonomy,
-		Sandbox:           options.Sandbox,
-		ToolCallID:        toolCallID,
-		SessionID:         options.SessionID,
-		Model:             options.Model,
-		ReasoningEffort:   options.ReasoningEffort,
-		Depth:             options.Depth,
-		Cwd:               options.Cwd,
-		FileTracker:       options.FileTracker,
-		EnabledTools:      options.EnabledTools,
-		DisabledTools:     options.DisabledTools,
-		Progress:          progressCallback,
+		PermissionGranted:          true,
+		PermissionMode:             string(permissionMode),
+		Autonomy:                   options.Autonomy,
+		Sandbox:                    options.Sandbox,
+		ToolCallID:                 toolCallID,
+		SessionID:                  options.SessionID,
+		Model:                      options.Model,
+		ReasoningEffort:            options.ReasoningEffort,
+		Depth:                      options.Depth,
+		Cwd:                        options.Cwd,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
+		EnabledTools:               options.EnabledTools,
+		DisabledTools:              options.DisabledTools,
+		Progress:                   progressCallback,
 	})
 }
 
@@ -1712,20 +1749,21 @@ func unsandboxedRetryArgs(args map[string]any) map[string]any {
 
 func runToolForUnsandboxedRetry(ctx context.Context, registry *tools.Registry, name string, toolCallID string, args map[string]any, permissionMode PermissionMode, options Options, progressCallback func(streamjson.Event)) tools.Result {
 	return registry.RunWithOptions(ctx, name, args, tools.RunOptions{
-		PermissionGranted: true,
-		PermissionMode:    string(permissionMode),
-		Autonomy:          options.Autonomy,
-		Sandbox:           options.Sandbox,
-		ToolCallID:        toolCallID,
-		SessionID:         options.SessionID,
-		Model:             options.Model,
-		ReasoningEffort:   options.ReasoningEffort,
-		Depth:             options.Depth,
-		Cwd:               options.Cwd,
-		FileTracker:       options.FileTracker,
-		EnabledTools:      options.EnabledTools,
-		DisabledTools:     options.DisabledTools,
-		Progress:          progressCallback,
+		PermissionGranted:          true,
+		PermissionMode:             string(permissionMode),
+		Autonomy:                   options.Autonomy,
+		Sandbox:                    options.Sandbox,
+		ToolCallID:                 toolCallID,
+		SessionID:                  options.SessionID,
+		Model:                      options.Model,
+		ReasoningEffort:            options.ReasoningEffort,
+		Depth:                      options.Depth,
+		Cwd:                        options.Cwd,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
+		EnabledTools:               options.EnabledTools,
+		DisabledTools:              options.DisabledTools,
+		Progress:                   progressCallback,
 	})
 }
 
@@ -2742,21 +2780,89 @@ func shellCommandAdditionalPermissionsRequested(args map[string]any) bool {
 	return strings.TrimSpace(value) == string(tools.SandboxPermissionsWithAdditionalPermissions)
 }
 
+// normalizeNoopAdditionalPermissions treats a provider-expanded empty or
+// already-covered additional_permissions object as if it had been omitted.
+// Some strict-schema providers materialize every optional property and may add
+// a workspace read that the default sandbox already grants; rejecting either
+// no-op makes the model retry an otherwise valid command. Requests that broaden
+// access and malformed payloads are left untouched so validation stays closed.
+func normalizeNoopAdditionalPermissions(args map[string]any, basePath string, engine *sandbox.Engine) {
+	raw, exists := args["additional_permissions"]
+	if !exists {
+		return
+	}
+	// An explicit null is the field omitted, not a request: drop the key so the
+	// rest of the pipeline sees the same args a model that omitted it would send.
+	// sandbox_permissions is deliberately left alone — a flagged null must reach
+	// the same "no additional_permissions object was provided" error as a flagged
+	// absent field rather than being silently downgraded to a different outcome.
+	if raw == nil {
+		delete(args, "additional_permissions")
+		return
+	}
+	data, err := json.Marshal(raw)
+	if err != nil {
+		return
+	}
+	var profile sandbox.RequestPermissionProfile
+	if err := json.Unmarshal(data, &profile); err != nil {
+		return
+	}
+	normalized, err := sandbox.NormalizeRequestPermissionProfile(profile, basePath)
+	if err != nil {
+		return
+	}
+	noop := normalized.Empty()
+	if !noop && engine != nil {
+		if grantProfile, grantErr := sandbox.RequestPermissionGrantProfile(normalized); grantErr == nil {
+			noop = engine.CoversRequestPermissions(grantProfile)
+		}
+	}
+	if !noop {
+		return
+	}
+	delete(args, "additional_permissions")
+	if rawMode, ok := args["sandbox_permissions"].(string); ok &&
+		strings.TrimSpace(rawMode) == string(tools.SandboxPermissionsWithAdditionalPermissions) {
+		args["sandbox_permissions"] = string(tools.SandboxPermissionsUseDefault)
+	}
+}
+
+// omitAdditionalPermissionsHint is the one instruction that ends the retry loop
+// in #845/#847. Every additional_permissions rejection must carry it: the model
+// reaches these errors by attaching a permission object to a command that needs
+// none, so "omit it and retry" is the answer in practice, and an error that
+// only explains how to build a VALID permission object sends the model round
+// the loop again with a different invalid shape.
+const omitAdditionalPermissionsHint = "If this command does not need extra sandbox access — ordinary " +
+	"read-only commands such as `git branch --show-current` do not — omit both sandbox_permissions and " +
+	"additional_permissions entirely and retry; that is the fix in almost every case."
+
 func inlineAdditionalPermissionsProfile(args map[string]any, basePath string) (sandbox.RequestPermissionProfile, bool, error) {
 	if !shellCommandAdditionalPermissionsRequested(args) {
-		if _, exists := args["additional_permissions"]; exists {
-			return sandbox.RequestPermissionProfile{}, false, fmt.Errorf("additional_permissions requires sandbox_permissions set to %q", tools.SandboxPermissionsWithAdditionalPermissions)
+		// An explicit null grants nothing and carries no flag, so it is
+		// indistinguishable from an omitted field; rejecting it would be a pure
+		// false positive against providers that materialize every optional
+		// property.
+		if raw, exists := args["additional_permissions"]; exists && raw != nil {
+			return sandbox.RequestPermissionProfile{}, false, fmt.Errorf(
+				"additional_permissions was provided without sandbox_permissions set to %q, so it cannot be applied. %s "+
+					"Only if the command genuinely needs file or network access the sandbox denies, resend with "+
+					`sandbox_permissions: %q AND a non-empty additional_permissions, for example {"network": {"enabled": true}}`,
+				tools.SandboxPermissionsWithAdditionalPermissions,
+				omitAdditionalPermissionsHint,
+				tools.SandboxPermissionsWithAdditionalPermissions)
 		}
 		return sandbox.RequestPermissionProfile{}, false, nil
 	}
 	raw, ok := args["additional_permissions"]
 	if !ok || raw == nil {
 		return sandbox.RequestPermissionProfile{}, true, fmt.Errorf(
-			"sandbox_permissions was set to %q but no additional_permissions object was provided. "+
-				`Include one, for example additional_permissions: {"network": {"enabled": true}} or `+
-				`{"file_system": {"write": ["/path"]}}. If this command does not need elevated permissions, `+
-				"omit sandbox_permissions entirely and retry",
-			tools.SandboxPermissionsWithAdditionalPermissions)
+			"sandbox_permissions was set to %q but no additional_permissions object was provided. %s "+
+				`Otherwise include one, for example additional_permissions: {"network": {"enabled": true}} or `+
+				`{"file_system": {"write": ["/path"]}}`,
+			tools.SandboxPermissionsWithAdditionalPermissions,
+			omitAdditionalPermissionsHint)
 	}
 	data, err := json.Marshal(raw)
 	if err != nil {
@@ -2772,8 +2878,10 @@ func inlineAdditionalPermissionsProfile(args map[string]any, basePath string) (s
 	}
 	if normalized.Empty() {
 		return sandbox.RequestPermissionProfile{}, true, fmt.Errorf(
-			"additional_permissions must include at least one of network or file_system, for example " +
-				`{"network": {"enabled": true}} or {"file_system": {"write": ["/path"]}}`)
+			"additional_permissions granted nothing, so it cannot be applied. %s "+
+				`Otherwise include a real permission, for example {"network": {"enabled": true}} or `+
+				`{"file_system": {"write": ["/path"]}}`,
+			omitAdditionalPermissionsHint)
 	}
 	grantProfile, err := sandbox.RequestPermissionGrantProfile(normalized)
 	if err != nil {
@@ -2932,22 +3040,20 @@ func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMod
 	//   2. tool_search — always present, right after the stable block;
 	//   3. loaded deferred tools, alpha-sorted — APPENDED, so an unloaded->loaded
 	//      transition grows the tail instead of inserting into the eager block.
-	// (tool_search's discovery text still shrinks as tools load, so keeping it and
-	// the loaded tail AFTER the eager block preserves the eager tools' cache across a
-	// load; fully stabilizing the loader's own description is a scoped follow-up.)
+	// tool_search's compact catalog also stays byte-stable as tools load, so only
+	// the appended full-schema tail changes.
 	eager := make([]zeroruntime.ToolDefinition, 0, len(visible))
 	loadedTail := make([]zeroruntime.ToolDefinition, 0)
-	var hiddenTools []tools.Tool
+	var deferredCatalog []tools.Tool
 	for _, tool := range visible {
 		name := tool.Name()
 		if name == tools.ToolSearchToolName {
 			continue // added explicitly between the eager block and the loaded tail
 		}
 		if tools.IsDeferred(tool) {
+			deferredCatalog = append(deferredCatalog, tool)
 			if loaded[name] {
 				loadedTail = append(loadedTail, cachedRuntimeToolDefinition(defCache, tool))
-			} else {
-				hiddenTools = append(hiddenTools, tool)
 			}
 			continue
 		}
@@ -2960,15 +3066,16 @@ func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMod
 		return loadedTail[left].Name < loadedTail[right].Name
 	})
 
-	discovery := ""
-	if len(hiddenTools) > 0 {
-		discovery = tools.BuildToolSearchDescription(hiddenTools)
-	}
+	// Keep the catalog byte-stable as tools load. tool_search already redirects
+	// requests for an exposed tool back to the current tool list, so retaining
+	// loaded names costs only compact catalog lines and avoids invalidating the
+	// provider cache at the loader definition on every load.
+	discovery := tools.BuildToolSearchDescription(deferredCatalog)
 
 	// tool_search is guaranteed runnable on the active path, so it is ALWAYS exposed
 	// — even when a non-empty EnabledTools allowlist omits it (the operator
 	// allowlisted the deferred tools, not the loader). It sits right after the stable
-	// eager block and carries the discovery list for still-hidden tools.
+	// eager block and carries the stable deferred-tool catalog.
 	description := loader.Description()
 	if discovery != "" {
 		description = discovery
@@ -3207,3 +3314,37 @@ func copyMessages(messages []Message) []Message {
 	}
 	return copied
 }
+
+// toolResultImageMessage builds the user message that carries a tool's images
+// to the model, or reports false when the tool produced none.
+//
+// The text names the tool so the model can tell which call an image came from
+// when several ran in one turn — the images arrive detached from their tool
+// result, so nothing else associates them.
+func toolResultImageMessage(result ToolResult) (zeroruntime.Message, bool) {
+	images := make([]zeroruntime.ImageBlock, 0, len(result.Images))
+	for _, image := range result.Images {
+		if len(image.Data) == 0 {
+			continue
+		}
+		mediaType := zeroruntime.NormalizeImageMediaType(image.MediaType)
+		if mediaType == "" {
+			// Outside the provider allow-list. Dropping it beats sending bytes a
+			// provider will reject and failing the whole turn.
+			continue
+		}
+		images = append(images, zeroruntime.ImageBlock{MediaType: mediaType, Data: image.Data})
+	}
+	if len(images) == 0 {
+		return zeroruntime.Message{}, false
+	}
+	label := result.Name
+	if label == "" {
+		label = "tool"
+	}
+	return zeroruntime.Message{
+		Role:    zeroruntime.MessageRoleUser,
+		Content: "Image output from " + label + ":",
+		Images:  images,
+	}, true
+}

internal/agent/loop_test.go

@@ -64,6 +64,22 @@ func TestTypedExecutionOutcomeOverridesLegacySandboxHeuristics(t *testing.T) {
 		t.Fatal("narrow protected-metadata denial must not become an unrestricted retry")
 	}
 
+	nonRecoverableDenial := protectedDenial
+	nonRecoverableDenial.ExecutionOutcome = &execution.Outcome{
+		State: execution.StateDenied,
+		Kind:  execution.OutcomeEnforcementDenied,
+		Denial: &execution.Denial{
+			Capability:  execution.Capability{Kind: execution.CapabilityUnrestricted, Scope: "host"},
+			Source:      execution.DenialSourcePlatformSandbox,
+			Reason:      "sandbox enforcement failed closed",
+			Recoverable: false,
+			NextAction:  execution.DenialNextActionRequestApproval,
+		},
+	}
+	if sandboxRestrictedShellRetryCandidate(call, nil, nonRecoverableDenial, options) {
+		t.Fatal("non-recoverable sandbox denial must not become an unrestricted retry")
+	}
+
 	networkDenial := protectedDenial
 	networkDenial.ExecutionOutcome = &execution.Outcome{
 		State: execution.StateDenied,
@@ -288,6 +304,18 @@ func (tool *sandboxDeniedRetryTool) Run(_ context.Context, args map[string]any)
 	return tools.Result{
 		Status: tools.StatusError,
 		Output: "touch: cannot touch '/home/user/.npm/cache': Read-only file system",
+		ExecutionOutcome: &execution.Outcome{
+			State: execution.StateDenied,
+			Kind:  execution.OutcomeEnforcementDenied,
+			Exit:  &execution.Exit{Code: 1},
+			Denial: &execution.Denial{
+				Capability:  execution.Capability{Kind: execution.CapabilityUnrestricted, Scope: "host"},
+				Source:      execution.DenialSourcePlatformSandbox,
+				Reason:      "sandbox blocked command execution",
+				Recoverable: true,
+				NextAction:  execution.DenialNextActionRequestApproval,
+			},
+		},
 		Meta: map[string]string{
 			"exit_code":                    "1",
 			tools.SandboxLikelyDeniedMeta:  "true",
@@ -304,7 +332,8 @@ type sandboxDeniedExecCommandRetryTool struct {
 func (tool *sandboxDeniedExecCommandRetryTool) Name() string { return "exec_command" }
 
 type sandboxNetworkDeniedRetryTool struct {
-	calls []map[string]any
+	calls                      []map[string]any
+	deferFileObservationCommit []bool
 }
 
 func (tool *sandboxNetworkDeniedRetryTool) Name() string        { return "bash" }
@@ -327,6 +356,7 @@ func (tool *sandboxNetworkDeniedRetryTool) Run(ctx context.Context, args map[str
 }
 func (tool *sandboxNetworkDeniedRetryTool) RunWithOptions(ctx context.Context, args map[string]any, options tools.RunOptions) tools.Result {
 	tool.calls = append(tool.calls, cloneArgs(args))
+	tool.deferFileObservationCommit = append(tool.deferFileObservationCommit, options.DeferFileObservationCommit)
 	if shellNetworkAllowed(ctx, options.Sandbox, args) {
 		return tools.Result{Status: tools.StatusOK, Output: "server started"}
 	}
@@ -369,7 +399,8 @@ func agentNativeBackendStub() sandbox.Backend {
 }
 
 type sandboxNamespaceLimitedRetryTool struct {
-	calls []map[string]any
+	calls                      []map[string]any
+	deferFileObservationCommit []bool
 }
 
 func (tool *sandboxNamespaceLimitedRetryTool) Name() string        { return "bash" }
@@ -388,8 +419,12 @@ func (tool *sandboxNamespaceLimitedRetryTool) Parameters() tools.Schema {
 func (tool *sandboxNamespaceLimitedRetryTool) Safety() tools.Safety {
 	return tools.Safety{SideEffect: tools.SideEffectShell, Permission: tools.PermissionPrompt, Reason: "runs shell commands"}
 }
-func (tool *sandboxNamespaceLimitedRetryTool) Run(_ context.Context, args map[string]any) tools.Result {
+func (tool *sandboxNamespaceLimitedRetryTool) Run(ctx context.Context, args map[string]any) tools.Result {
+	return tool.RunWithOptions(ctx, args, tools.RunOptions{})
+}
+func (tool *sandboxNamespaceLimitedRetryTool) RunWithOptions(_ context.Context, args map[string]any, options tools.RunOptions) tools.Result {
 	tool.calls = append(tool.calls, cloneArgs(args))
+	tool.deferFileObservationCommit = append(tool.deferFileObservationCommit, options.DeferFileObservationCommit)
 	if args["sandbox_permissions"] == string(tools.SandboxPermissionsRequireEscalated) {
 		return tools.Result{Status: tools.StatusOK, Output: "stdout:\nUSER PID COMMAND\nanaxy 42 firefox\nanaxy 43 Discord"}
 	}
@@ -455,6 +490,9 @@ func TestRunRetriesShellUnsandboxedAfterSandboxNamespaceLimitedOutput(t *testing
 	if retryTool.calls[1]["sandbox_permissions"] != string(tools.SandboxPermissionsRequireEscalated) {
 		t.Fatalf("retry args = %#v, want require_escalated", retryTool.calls[1])
 	}
+	if len(retryTool.deferFileObservationCommit) != 2 || !retryTool.deferFileObservationCommit[1] {
+		t.Fatalf("retry defer flags = %#v, want retry observation deferred", retryTool.deferFileObservationCommit)
+	}
 	if len(requests) != 1 {
 		t.Fatalf("permission requests = %#v, want one unsandboxed retry approval", requests)
 	}
@@ -606,6 +644,9 @@ func TestRunRetriesNetworkDeniedShellWithNetworkGrant(t *testing.T) {
 	if _, escalated := retryTool.calls[1]["sandbox_permissions"]; escalated {
 		t.Fatalf("network retry must stay sandboxed, got retry args %#v", retryTool.calls[1])
 	}
+	if len(retryTool.deferFileObservationCommit) != 2 || !retryTool.deferFileObservationCommit[1] {
+		t.Fatalf("retry defer flags = %#v, want retry observation deferred", retryTool.deferFileObservationCommit)
+	}
 	if len(requests) != 1 || requests[0].Reason != sandbox.ReasonNetworkBlocked {
 		t.Fatalf("permission requests = %#v, want one network approval", requests)
 	}
@@ -2404,7 +2445,11 @@ func TestRunApprovedNetworkBashPromptAppliesTurnNetworkGrant(t *testing.T) {
 	root := t.TempDir()
 	command := "PATH=.:$PATH curl https://example.com"
 	if runtime.GOOS == "windows" {
-		command = "set PATH=.;%PATH% && curl https://example.com"
+		if windowsTestUsesPowerShell() {
+			command = `$env:PATH = '.;' + $env:PATH; curl.cmd https://example.com`
+		} else {
+			command = "set PATH=.;%PATH% && curl https://example.com"
+		}
 		fakeCurl := filepath.Join(root, "curl.cmd")
 		if err := os.WriteFile(fakeCurl, []byte("@echo fake curl %*\r\n"), 0o755); err != nil {
 			t.Fatal(err)
@@ -2525,13 +2570,17 @@ func TestRunDoesNotOfferPrefixApprovalForUnsafeBashCommand(t *testing.T) {
 
 func TestRunPromptsForDestructiveShellInsteadOfSandboxDeny(t *testing.T) {
 	root := t.TempDir()
+	command := "echo rm -rf /"
+	if runtime.GOOS == "windows" && windowsTestUsesPowerShell() {
+		command = `Write-Output 'rm -rf /'`
+	}
 	registry := tools.NewRegistry()
 	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
 				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "bash"},
-				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"command":"echo rm -rf /"}`},
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"command":` + quoteJSONString(command) + `}`},
 				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-1"},
 				{Type: zeroruntime.StreamEventDone},
 			},
@@ -2627,6 +2676,12 @@ func TestRunAlwaysAllowWithoutSandboxStillAllowsCall(t *testing.T) {
 	}
 }
 
+func windowsTestUsesPowerShell() bool {
+	executable, _ := tools.HostShellCommand("")
+	name := strings.ToLower(filepath.Base(executable))
+	return strings.Contains(name, "powershell") || strings.HasPrefix(name, "pwsh")
+}
+
 func containsPermissionDecision(decisions []PermissionDecisionAction, want PermissionDecisionAction) bool {
 	for _, decision := range decisions {
 		if decision == want {
@@ -3160,22 +3215,17 @@ func TestBuildSystemPromptInjectsHostShellContext(t *testing.T) {
 		t.Fatalf("expected operating system in environment block, got %q", prompt)
 	}
 	if runtime.GOOS == "windows" {
-		for _, want := range []string{"Windows cmd.exe syntax", "cwd argument", "MSYS binaries", "grep", "require_escalated", "use double quotes around the value"} {
-			if !strings.Contains(prompt, want) {
-				t.Fatalf("expected Windows shell guidance to mention %q, got %q", want, prompt)
-			}
+		wants := []string{"workdir/cwd", "MSYS binaries"}
+		if windowsTestUsesPowerShell() {
+			wants = append(wants, "PowerShell", "Get-ChildItem", "Select-String", "$env:NAME", "require_escalated")
+		} else {
+			wants = append(wants, "cmd.exe", "double quotes")
 		}
-		// The examples must themselves use the safe (double-quoted) form; a
-		// single-quoted example here would teach the model the exact syntax
-		// that fails under cmd.exe.
-		for _, want := range []string{`--jq ".a | b"`, `-run "A|B"`} {
+		for _, want := range wants {
 			if !strings.Contains(prompt, want) {
-				t.Fatalf("expected double-quoted example %q in Windows shell guidance, got %q", want, prompt)
+				t.Fatalf("expected selected Windows shell guidance to mention %q, got %q", want, prompt)
 			}
 		}
-		if strings.Contains(prompt, `'.a | b'`) || strings.Contains(prompt, `'A|B'`) {
-			t.Fatalf("Windows shell guidance must not show the unsafe single-quoted form, got %q", prompt)
-		}
 	} else if !strings.Contains(prompt, "/bin/sh syntax") {
 		t.Fatalf("expected POSIX shell guidance in prompt, got %q", prompt)
 	}

internal/agent/output_budget_propagation_test.go

@@ -3,6 +3,7 @@ package agent
 import (
 	"context"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"testing"
@@ -19,6 +20,16 @@ type propagationOutputTool struct {
 
 func TestOutputBudgetHookHelperProcess(t *testing.T) {
 	for index, arg := range os.Args {
+		if arg == "--zero-output-budget-hook-repeat" && index+1 < len(os.Args) {
+			repeats, err := strconv.Atoi(os.Args[index+1])
+			if err != nil {
+				os.Exit(2)
+			}
+			if _, err := os.Stdout.WriteString(strings.Repeat("hook feedback ", repeats)); err != nil {
+				os.Exit(2)
+			}
+			os.Exit(0)
+		}
 		if arg != "--zero-output-budget-hook" || index+1 >= len(os.Args) {
 			continue
 		}
@@ -30,25 +41,102 @@ func TestOutputBudgetHookHelperProcess(t *testing.T) {
 }
 
 func largeOutputBudgetHookDispatcher() *hooks.Dispatcher {
-	feedback := strings.Repeat("hook feedback ", 200)
+	return outputBudgetHookDispatcherFor("propagation_output", 200)
+}
+
+func outputBudgetHookDispatcherFor(toolName string, repeats int) *hooks.Dispatcher {
+	feedback := strings.Repeat("hook feedback ", repeats)
+	hookArgs := []string{
+		"-test.run=TestOutputBudgetHookHelperProcess",
+		"--",
+		"--zero-output-budget-hook",
+		feedback,
+	}
+	if repeats > 1_000 {
+		hookArgs = []string{
+			"-test.run=TestOutputBudgetHookHelperProcess",
+			"--",
+			"--zero-output-budget-hook-repeat",
+			strconv.Itoa(repeats),
+		}
+	}
 	return hooks.NewDispatcher(hooks.DispatcherOptions{Config: hooks.Config{
 		Enabled: true,
 		Hooks: []hooks.Definition{{
 			ID:      "large-feedback",
 			Event:   hooks.EventAfterTool,
-			Matcher: "propagation_output",
+			Matcher: toolName,
 			Command: os.Args[0],
-			Args: []string{
-				"-test.run=TestOutputBudgetHookHelperProcess",
-				"--",
-				"--zero-output-budget-hook",
-				feedback,
-			},
+			Args:    hookArgs,
 			Enabled: true,
 		}},
 	}})
 }
 
+func TestExecuteToolCallCommitsReadObservationAfterFinalBoundary(t *testing.T) {
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "target.txt")
+	if err := os.WriteFile(targetPath, []byte("known content\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	linkPath := filepath.Join(root, "small.txt")
+	if err := os.Symlink(targetPath, linkPath); err != nil {
+		t.Skipf("symlink unavailable: %v", err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(linkPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewReadFileTool(root))
+	tracker := tools.NewFileTracker()
+
+	result, abortErr := executeToolCall(context.Background(), registry, ToolCall{
+		ID: "read-small", Name: "read_file", Arguments: `{"path":"small.txt"}`,
+	}, PermissionModeAuto, Options{Cwd: root, FileTracker: tracker})
+	if abortErr != nil || result.Status != tools.StatusOK {
+		t.Fatalf("executeToolCall: result=%#v err=%v", result, abortErr)
+	}
+	if !tracker.SeenWhole(resolvedPath) {
+		t.Fatal("unmodified final read output was not committed as observed")
+	}
+}
+
+func TestExecuteToolCallDoesNotCommitReadObservationBeforeHookBudget(t *testing.T) {
+	t.Setenv("ZERO_TOOL_OUTPUT_CEILING_TOKENS", "80")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "target.txt")
+	if err := os.WriteFile(targetPath, []byte("known content\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	linkPath := filepath.Join(root, "small.txt")
+	if err := os.Symlink(targetPath, linkPath); err != nil {
+		t.Skipf("symlink unavailable: %v", err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(linkPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewReadFileTool(root))
+	tracker := tools.NewFileTracker()
+
+	result, abortErr := executeToolCall(context.Background(), registry, ToolCall{
+		ID: "read-hook", Name: "read_file", Arguments: `{"path":"small.txt"}`,
+	}, PermissionModeAuto, Options{
+		Cwd: root, FileTracker: tracker, Hooks: outputBudgetHookDispatcherFor("read_file", 20_000),
+	})
+	if abortErr != nil {
+		t.Fatalf("executeToolCall: %v", abortErr)
+	}
+	if !result.Truncated {
+		t.Fatalf("precondition: hook feedback was not truncated: %#v", result)
+	}
+	if tracker.SeenWhole(resolvedPath) {
+		t.Fatal("read observation committed before hook output was budgeted")
+	}
+}
+
 func (tool propagationOutputTool) Name() string        { return "propagation_output" }
 func (tool propagationOutputTool) Description() string { return "returns output for propagation tests" }
 func (tool propagationOutputTool) Parameters() tools.Schema {

internal/agent/prune.go

@@ -121,3 +121,67 @@ func toolNameForResult(messages []zeroruntime.Message, index int) string {
 func isPrunedPlaceholder(content string) bool {
 	return strings.HasPrefix(strings.TrimSpace(content), "[pruned ")
 }
+
+var supersedableReadTools = map[string]bool{
+	"read_file":          true,
+	"read_minified_file": true,
+	"grep":               true,
+	"glob":               true,
+	"list_directory":     true,
+}
+
+// pruneSupersededReadResults removes only older byte-identical results of the
+// same read call. It runs when context pressure already requires a rewrite, so
+// it does not trade a warm provider-cache prefix for a small apparent saving.
+func pruneSupersededReadResults(messages []zeroruntime.Message) ([]zeroruntime.Message, int) {
+	type seenResultKey struct {
+		call    string
+		content string
+	}
+	seen := map[seenResultKey]struct{}{}
+	out := messages
+	reclaimed := 0
+	copied := false
+
+	for index := len(messages) - 1; index >= 0; index-- {
+		message := messages[index]
+		if message.Role != zeroruntime.MessageRoleTool || isPrunedPlaceholder(message.Content) {
+			continue
+		}
+		call, ok := toolCallForResult(messages, index)
+		if !ok || !supersedableReadTools[call.Name] {
+			continue
+		}
+		key := seenResultKey{
+			call:    call.Name + "\x00" + strings.TrimSpace(call.Arguments),
+			content: message.Content,
+		}
+		if _, exists := seen[key]; exists {
+			placeholder := fmt.Sprintf("[superseded identical %s result — the newer result remains in context]", call.Name)
+			if !copied {
+				out = append([]zeroruntime.Message(nil), messages...)
+				copied = true
+			}
+			out[index].Content = placeholder
+			reclaimed += max(0, ApproxTextTokens(message.Content)-ApproxTextTokens(placeholder))
+			continue
+		}
+		seen[key] = struct{}{}
+	}
+	return out, reclaimed
+}
+
+func toolCallForResult(messages []zeroruntime.Message, resultIndex int) (zeroruntime.ToolCall, bool) {
+	id := messages[resultIndex].ToolCallID
+	if id == "" {
+		return zeroruntime.ToolCall{}, false
+	}
+	for index := resultIndex - 1; index >= 0; index-- {
+		for _, call := range messages[index].ToolCalls {
+			if call.ID == id {
+				return call, true
+			}
+		}
+	}
+	return zeroruntime.ToolCall{}, false
+}

internal/agent/prune_test.go

@@ -25,6 +25,13 @@ func toolCallMsg(id, name string) zeroruntime.Message {
 	}
 }
 
+func toolCallWithArgs(id, name, args string) zeroruntime.Message {
+	return zeroruntime.Message{
+		Role:      zeroruntime.MessageRoleAssistant,
+		ToolCalls: []zeroruntime.ToolCall{{ID: id, Name: name, Arguments: args}},
+	}
+}
+
 func TestPruneSkipsSmallSessions(t *testing.T) {
 	// Total reclaimable is under the gate → no pruning.
 	msgs := []zeroruntime.Message{
@@ -120,3 +127,69 @@ func TestPruneDoesNotMutateInput(t *testing.T) {
 		t.Fatal("pruneStaleToolOutput must not mutate the caller's slice")
 	}
 }
+
+func TestPruneSupersededReadResultsOnlyDropsIdenticalOlderReads(t *testing.T) {
+	body := strings.Repeat("same source line\n", 1000)
+	messages := []zeroruntime.Message{
+		toolCallWithArgs("old", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "old", Content: body},
+		toolCallWithArgs("different", "read_file", `{"path":"b.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "different", Content: body},
+		toolCallWithArgs("new", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "new", Content: body},
+	}
+	out, reclaimed := pruneSupersededReadResults(messages)
+	if reclaimed <= 0 || !strings.Contains(out[1].Content, "superseded identical") {
+		t.Fatalf("older duplicate was not pruned: reclaimed=%d output=%q", reclaimed, out[1].Content)
+	}
+	if out[3].Content != body || out[5].Content != body {
+		t.Fatal("different call and newest result must remain exact")
+	}
+	if messages[1].Content != body {
+		t.Fatal("input slice was mutated")
+	}
+}
+
+func TestPruneSupersededReadResultsKeepsChangedAndMutatingResults(t *testing.T) {
+	messages := []zeroruntime.Message{
+		toolCallWithArgs("r1", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "r1", Content: "version one"},
+		toolCallWithArgs("r2", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "r2", Content: "version two"},
+		toolCallWithArgs("e1", "edit_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e1", Content: "edited"},
+		toolCallWithArgs("e2", "edit_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e2", Content: "edited"},
+	}
+	out, reclaimed := pruneSupersededReadResults(messages)
+	if reclaimed != 0 {
+		t.Fatalf("unsafe results were pruned: %d", reclaimed)
+	}
+	for index := range messages {
+		if out[index].Content != messages[index].Content {
+			t.Fatalf("message %d changed unexpectedly", index)
+		}
+	}
+}
+
+func TestPruneSupersededReadResultsFindsMatchingBodyAcrossChangedRead(t *testing.T) {
+	bodyA := strings.Repeat("version a\n", 100)
+	bodyB := strings.Repeat("version b\n", 100)
+	messages := []zeroruntime.Message{
+		toolCallWithArgs("old-a", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "old-a", Content: bodyA},
+		toolCallWithArgs("middle-b", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "middle-b", Content: bodyB},
+		toolCallWithArgs("new-a", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "new-a", Content: bodyA},
+	}
+
+	out, reclaimed := pruneSupersededReadResults(messages)
+
+	if reclaimed <= 0 || !strings.Contains(out[1].Content, "superseded identical") {
+		t.Fatalf("older matching body was not pruned across a changed result: reclaimed=%d output=%q", reclaimed, out[1].Content)
+	}
+	if out[3].Content != bodyB || out[5].Content != bodyA {
+		t.Fatal("changed middle result and newest matching result must remain exact")
+	}
+}

internal/agent/specialist_delegation_test.go

@@ -26,6 +26,16 @@ func TestSpecialistDelegationContext(t *testing.T) {
 	if strings.Contains(got, "nameless") {
 		t.Fatalf("nameless entry should be skipped: %q", got)
 	}
+	for _, want := range []string{"reduce total context", "Do not delegate small direct work", "bounded assignment"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("missing evidence-driven delegation guidance %q: %q", want, got)
+		}
+	}
+	for _, unwanted := range []string{"delegate to it proactively", "launch several specialists in parallel"} {
+		if strings.Contains(got, unwanted) {
+			t.Fatalf("retained broad delegation guidance %q: %q", unwanted, got)
+		}
+	}
 }
 
 func TestSystemPromptIncludesDelegationOnlyWithSpecialists(t *testing.T) {

internal/agent/system_prompt.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/repomap"
+	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/workspaceseed"
 )
 
@@ -178,21 +179,19 @@ func approvedCommandPrefixContext(options Options) string {
 	return "## Approved Command Prefixes\n\nThe following command prefixes have already been approved and do not need another permission prompt:\n" + strings.Join(lines, "\n")
 }
 
-// specialistDelegationContext nudges the orchestrator to offload read-heavy or
-// parallelizable work to a specialist sub-agent via the Task tool, keeping large
-// tool outputs out of the main context. It renders only when specialists are
-// known (which is only where the Task tool is actually registered), so a run with
-// no delegatable specialists produces the previous prompt unchanged.
+// specialistDelegationContext describes when a specialist earns its extra
+// context and coordination cost. It renders only when specialists are known
+// (which is only where the Task tool is actually registered), so a run with no
+// delegatable specialists produces the previous prompt unchanged.
 func specialistDelegationContext(options Options) string {
 	if len(options.Specialists) == 0 {
 		return ""
 	}
 	var b strings.Builder
 	b.WriteString("<specialists>\n")
-	b.WriteString("Delegate focused or read-heavy work to a specialist sub-agent with the Task tool instead of doing it inline. ")
-	b.WriteString("When a request matches a specialist's purpose, delegate to it proactively — you do not need the user to ask first. ")
-	b.WriteString("This keeps large tool outputs — searches, file dumps, multi-step exploration — out of your own context, so you stay fast and token-efficient. ")
-	b.WriteString("Prefer delegating codebase search and exploration; for independent subtasks, launch several specialists in parallel. Handle small, direct edits yourself.\n")
+	b.WriteString("Use the Task tool when a specialist's focused context, expertise, or an independent parallel subtask is likely to improve quality or reduce total context. ")
+	b.WriteString("Do not delegate small direct work, duplicate exploration, or split sequential steps merely because a specialist is available. ")
+	b.WriteString("When delegating, give a bounded assignment and consume its concise evidence instead of importing a long transcript.\n")
 	b.WriteString("Available specialists (call Task with the matching name when the task fits its purpose):\n")
 	for _, info := range options.Specialists {
 		name := strings.TrimSpace(info.Name)
@@ -310,11 +309,7 @@ func workspaceContext(cwd string) string {
 	b.WriteString("<environment>\n")
 	b.WriteString("Working directory: " + cwd + "\n")
 	b.WriteString("Operating system: " + runtime.GOOS + "\n")
-	if runtime.GOOS == "windows" {
-		b.WriteString("Shell syntax: Windows cmd.exe syntax for exec_command/bash tools. To put | & > < etc inside an arg value, use double quotes around the value, not single quotes (single quotes do not protect metachars in cmd.exe): gh --jq \".a | b\", go test -run \"A|B\". Do not pipe to or invoke POSIX coreutils from Git for Windows (usr\\bin head/grep/tail/cat/...): they are MSYS binaries and fail under the write-restricted sandbox; use native Zero tools (grep, read_file, list_directory, glob) or cmd.exe findstr/more instead, or sandbox_permissions require_escalated only when host-level execution is truly required. Prefer the workdir/cwd argument over cd when changing directories.\n")
-	} else {
-		b.WriteString("Shell syntax: /bin/sh syntax for exec_command/bash tools; prefer the workdir/cwd argument instead of cd when changing directories.\n")
-	}
+	b.WriteString(tools.HostShellEnvironmentGuidance() + "\n")
 	if branch := gitBranchForPrompt(cwd); branch != "" {
 		b.WriteString("Git branch: " + branch + "\n")
 	}

internal/agent/system_prompt.md

@@ -30,16 +30,13 @@ work.
    read-before-edit discipline: inspect the target file and nearby callers,
    tests, or config before you modify behavior. Never edit a file you have not
    read.
-2. **Plan.** For multi-step work, call update_plan with an ordered checklist and
-   keep it live. The plan bar is the user's progress signal — call update_plan
-   after EACH concrete unit of work (every file written, every command run), not
-   just at coarse milestones: mark the finished item completed and the next one
-   in_progress before you start it. A plan stuck at 0/N while files are landing is
-   a bug, not economy — these calls are cheap, expected, and the update_plan cards
-   are hidden from the transcript, so frequent updates cost the user nothing and
-   never clutter the conversation. Keep at most one item in_progress, and never
-   batch the updates to the end of the turn. Skip the plan for trivial one-step
-   tasks.
+2. **Plan.** Use update_plan for implementation or investigation that has at
+   least three meaningful dependent steps, then keep it current at milestones.
+   Mark completed work and the next in-progress step together when practical;
+   do not spend separate turns updating it after every file or command. Keep at
+   most one item in_progress. Skip plans for simple lookups, explanations, code
+   navigation, and other short tasks. Never create a plan after the work is
+   already complete merely to describe what you did.
 3. **Implement.** Make focused changes that match the surrounding code's style,
    naming, and conventions. Prefer the smallest change that fully solves the
    problem. Avoid broad refactors, unrelated rewrites, dependency churn, and
@@ -54,11 +51,16 @@ work.
 ## Editing discipline
 
 - Choose the narrowest tool that safely accomplishes the step. Prefer native
-  file tools - read_file, list_directory, glob, grep, write_file, edit_file,
-  apply_patch - over shelling out to cat/sed/awk/python for file operations.
+  file tools - read_file, read_minified_file, list_directory, glob, grep,
+  write_file, edit_file, apply_patch - over shelling out to
+  cat/sed/awk/python for file operations.
   They are safer, reviewable, and produce clean diffs.
-- Make one tool call per file. Do not batch multi-file writes into a single
-  shell or script invocation.
+- Prefer read_minified_file when initially exploring source code; it preserves
+  code while removing comments and redundant whitespace. Use read_file when
+  exact text, comments, or line numbers are needed.
+- Keep edits focused and reviewable. A single patch may update several related
+  files when they form one coherent change; do not hide unrelated edits in a
+  bulk shell or script rewrite.
 - For edits to existing files, prefer edit_file or apply_patch with minimal,
   targeted diffs. Match the existing indentation, imports, and idioms. Match the
   file's comment density: do not add explanatory comments unless the user asks or

internal/agent/system_prompt_models.go

@@ -71,5 +71,6 @@ const geminiPromptAddendum = `<model_guidance>
   equivalent shell commands; they are safer and produce cleaner diffs.
 - Be concise and concrete. When you run a shell command with side effects, state
   in one short clause why it is needed.
-- Use update_plan for any multi-step task and keep it current.
+- Use update_plan only for work with at least three meaningful dependent steps;
+  skip it for simple lookups and never create one after the work is complete.
 </model_guidance>`

internal/agent/tool_result_images_test.go

@@ -0,0 +1,207 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+// imageTool returns a tool result carrying an image, the way a screenshot tool
+// should be able to.
+type imageTool struct {
+	media string
+	data  []byte
+}
+
+func (imageTool) Name() string        { return "capture" }
+func (imageTool) Description() string { return "Captures an image." }
+func (imageTool) Parameters() tools.Schema {
+	return tools.Schema{Type: "object", Properties: map[string]tools.PropertySchema{}}
+}
+func (imageTool) Safety() tools.Safety {
+	return tools.Safety{Permission: tools.PermissionAllow}
+}
+func (t imageTool) Run(context.Context, map[string]any) tools.Result {
+	return tools.Result{
+		Status: tools.StatusOK,
+		Output: "Captured a screenshot.",
+		Images: []zeroruntime.ImageBlock{{MediaType: t.media, Data: t.data}},
+	}
+}
+
+// A tool that produces an image must get that image in front of the model.
+//
+// It cannot ride the tool-result message: every provider drops images there.
+// Anthropic maps a tool result to a tool_result block with string content,
+// Gemini to a functionResponse, and OpenAI guards its image parts to the user
+// role explicitly. So the image has to arrive as a following user message,
+// which is also the only shape that keeps one tool result per tool call.
+func TestRunDeliversToolResultImagesToTheModel(t *testing.T) {
+	registry := tools.NewRegistry()
+	registry.Register(imageTool{media: "image/png", data: []byte("\x89PNG\r\n\x1a\nfake")})
+
+	provider := &mockProvider{
+		turns: [][]zeroruntime.StreamEvent{
+			{
+				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call_1", ToolName: "capture"},
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call_1", ArgumentsFragment: `{}`},
+				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call_1"},
+				{Type: zeroruntime.StreamEventDone},
+			},
+			{
+				{Type: zeroruntime.StreamEventText, Content: "I can see it."},
+				{Type: zeroruntime.StreamEventDone},
+			},
+		},
+	}
+
+	result, err := Run(context.Background(), "screenshot please", provider, Options{
+		Registry: registry,
+		MaxTurns: 2,
+	})
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	var carrier *zeroruntime.Message
+	for index := range result.Messages {
+		if len(result.Messages[index].Images) > 0 {
+			carrier = &result.Messages[index]
+			break
+		}
+	}
+	if carrier == nil {
+		t.Fatal("no message carried the tool's image; the model never saw it")
+	}
+	if carrier.Role != zeroruntime.MessageRoleUser {
+		t.Errorf("image rode a %q message; every provider only serializes images on the user role", carrier.Role)
+	}
+	if got := carrier.Images[0].MediaType; got != "image/png" {
+		t.Errorf("media type = %q, want image/png", got)
+	}
+
+	// The tool-result pairing must be untouched: one tool result per tool call.
+	toolResults := 0
+	for _, message := range result.Messages {
+		if message.Role == zeroruntime.MessageRoleTool {
+			toolResults++
+		}
+	}
+	if toolResults != 1 {
+		t.Errorf("got %d tool-result messages for 1 tool call", toolResults)
+	}
+}
+
+// textTool is a second, image-free tool so a turn can carry two calls.
+type textTool struct{}
+
+func (textTool) Name() string        { return "note" }
+func (textTool) Description() string { return "Notes something." }
+func (textTool) Parameters() tools.Schema {
+	return tools.Schema{Type: "object", Properties: map[string]tools.PropertySchema{}}
+}
+func (textTool) Safety() tools.Safety { return tools.Safety{Permission: tools.PermissionAllow} }
+func (textTool) Run(context.Context, map[string]any) tools.Result {
+	return tools.Result{Status: tools.StatusOK, Output: "noted"}
+}
+
+// Tool results for one assistant turn must stay contiguous. The image messages
+// are user-role, and a user message between two tool_results breaks strict
+// provider replay: Anthropic coalesces consecutive user content into one block
+// list and requires tool_result blocks first, so interleaving produces
+// [tool_result, text, image, tool_result] and the request is rejected.
+//
+// The first version of this feature appended each image immediately after its
+// own tool result, which is exactly that shape. A single-tool-call test passed
+// and said nothing about it.
+func TestRunKeepsToolResultsContiguousWhenAToolReturnsAnImage(t *testing.T) {
+	registry := tools.NewRegistry()
+	registry.Register(imageTool{media: "image/png", data: []byte("\x89PNG\r\n\x1a\nfake")})
+	registry.Register(textTool{})
+
+	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{
+		{
+			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "c1", ToolName: "capture"},
+			{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "c1", ArgumentsFragment: `{}`},
+			{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "c1"},
+			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "c2", ToolName: "note"},
+			{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "c2", ArgumentsFragment: `{}`},
+			{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "c2"},
+			{Type: zeroruntime.StreamEventDone},
+		},
+		{{Type: zeroruntime.StreamEventText, Content: "done"}, {Type: zeroruntime.StreamEventDone}},
+	}}
+
+	result, err := Run(context.Background(), "two calls", provider, Options{Registry: registry, MaxTurns: 2})
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	// Two separate ifs rather than a switch: a tool-role message that also
+	// carried images would match only the first arm of a switch, so a regression
+	// that put the image back on the tool result would read as "no image at all"
+	// instead of naming what actually happened.
+	type toolResult struct {
+		index int
+		id    string
+	}
+	var toolResults []toolResult
+	imageIndex := -1
+	for index, message := range result.Messages {
+		if message.Role == zeroruntime.MessageRoleTool {
+			toolResults = append(toolResults, toolResult{index: index, id: message.ToolCallID})
+		}
+		if len(message.Images) > 0 {
+			if imageIndex >= 0 {
+				t.Fatalf("image delivered twice, at %d and %d; recorded %s", imageIndex, index, messageShape(result.Messages))
+			}
+			imageIndex = index
+		}
+	}
+	if imageIndex < 0 {
+		t.Fatalf("the image never reached the model; recorded %s", messageShape(result.Messages))
+	}
+	if len(toolResults) != 2 {
+		t.Fatalf("got %d tool-result messages for 2 tool calls; recorded %s", len(toolResults), messageShape(result.Messages))
+	}
+	if toolResults[0].id != "c1" || toolResults[1].id != "c2" {
+		t.Errorf("tool results answered %q then %q, want c1 then c2", toolResults[0].id, toolResults[1].id)
+	}
+	// The contract Anthropic enforces: every tool_result block has to come before
+	// any other block in the user message it lands in. Anything wedged between
+	// the two results breaks that, which is the 400 this PR exists to avoid.
+	if toolResults[1].index != toolResults[0].index+1 {
+		t.Errorf("tool results at %d and %d are not adjacent; %q message at %d splits them; recorded %s",
+			toolResults[0].index, toolResults[1].index, result.Messages[toolResults[0].index+1].Role,
+			toolResults[0].index+1, messageShape(result.Messages))
+	}
+	// Follows the last tool result, deliberately NOT pinned to exactly last+1.
+	// appendUserBlocks coalesces consecutive user-role content, so
+	// [tool_result, tool_result, text, image] still maps to tool_result blocks
+	// first and replays fine; pinning would redden that valid shape for nothing.
+	if imageIndex <= toolResults[1].index {
+		t.Errorf("image message at %d does not follow the last tool result at %d; recorded %s",
+			imageIndex, toolResults[1].index, messageShape(result.Messages))
+	}
+}
+
+// messageShape renders the conversation as a compact role list so a failure says
+// what the ordering actually was instead of dumping whole messages.
+func messageShape(messages []zeroruntime.Message) string {
+	parts := make([]string, 0, len(messages))
+	for index, message := range messages {
+		part := fmt.Sprintf("%d:%s", index, message.Role)
+		if message.ToolCallID != "" {
+			part += "(" + message.ToolCallID + ")"
+		}
+		if len(message.Images) > 0 {
+			part += "+image"
+		}
+		parts = append(parts, part)
+	}
+	return "[" + strings.Join(parts, " ") + "]"
+}

internal/agent/types.go

@@ -68,8 +68,11 @@ type ToolResult struct {
 	Output     string
 	// Truncated reports that the tool's model-visible output omitted content.
 	// The full result may be recoverable through Meta["spill_path"].
-	Truncated    bool
-	Meta         map[string]string
+	Truncated bool
+	Meta      map[string]string
+	// Images the tool produced, delivered to the model as a following user
+	// message rather than on this result. See tools.Result.Images.
+	Images       []zeroruntime.ImageBlock
 	Redacted     bool
 	ChangedFiles []string
 	// ChangeSummaries are non-selectable generated-tree summaries emitted by

internal/cli/acp.go

@@ -27,6 +27,8 @@ Usage:
 Not meant to be run interactively — point your editor's ACP / external-agent
 setting at "zero acp".`
 
+var acpSignalContext = signalContext
+
 // runACP serves ACP over stdio so an editor can drive ZERO's agent core. It
 // speaks JSON-RPC 2.0 (newline-delimited JSON) on stdin/stdout; stderr stays free
 // for human-readable diagnostics. The session lifecycle maps onto ZERO's own
@@ -42,7 +44,9 @@ func runACP(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int
 		}
 	}
 
-	conn := acp.NewConn(deps.stdin, stdout)
+	// The process's own stdin belongs exclusively to this Conn for the life of
+	// the command, so cancellation may close it to interrupt an idle read.
+	conn := acp.NewOwnedConn(deps.stdin, stdout)
 	acp.NewAgent(conn, acp.Deps{
 		ResolveConfig: deps.resolveConfig,
 		DiscoverModels: func(ctx context.Context, profile config.ProviderProfile) ([]providermodeldiscovery.Model, error) {
@@ -73,9 +77,9 @@ func runACP(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int
 		AgentInfo:            acp.Implementation{Name: "zero", Version: version},
 	})
 
-	ctx, stop := signalContext()
+	ctx, stop := acpSignalContext()
 	defer stop()
-	if err := conn.Serve(ctx); err != nil && ctx.Err() == nil {
+	if err := conn.Serve(ctx); err != nil {
 		return writeAppError(stderr, "acp: "+err.Error(), exitCrash)
 	}
 	return exitSuccess

internal/cli/acp_test.go

@@ -0,0 +1,120 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+type acpTestReader func([]byte) (int, error)
+
+func (r acpTestReader) Read(p []byte) (int, error) { return r(p) }
+
+type acpTestWriter func([]byte) (int, error)
+
+func (w acpTestWriter) Write(p []byte) (int, error) { return w(p) }
+
+func installACPTestContext(t *testing.T) context.CancelFunc {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	previous := acpSignalContext
+	acpSignalContext = func() (context.Context, context.CancelFunc) {
+		return ctx, cancel
+	}
+	t.Cleanup(func() {
+		cancel()
+		acpSignalContext = previous
+	})
+	return cancel
+}
+
+func TestRunACPCancellationPreservesTerminalReadError(t *testing.T) {
+	cancel := installACPTestContext(t)
+	wantErr := errors.New("transport read failed")
+	reader := acpTestReader(func(p []byte) (int, error) {
+		return copy(p, `{"jsonrpc":"1.0","id":1}`+"\n"), wantErr
+	})
+	writeStarted := make(chan struct{}, 1)
+	releaseWrite := make(chan struct{})
+	var stdout bytes.Buffer
+	writer := acpTestWriter(func(p []byte) (int, error) {
+		writeStarted <- struct{}{}
+		<-releaseWrite
+		return stdout.Write(p)
+	})
+	var stderr bytes.Buffer
+	done := make(chan int, 1)
+	go func() {
+		done <- runACP(nil, writer, &stderr, fillAppDeps(appDeps{stdin: reader}))
+	}()
+
+	select {
+	case <-writeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not reach the response write")
+	}
+	// Keep Serve in the synchronous write until cancellation is observable. The
+	// regression requires the genuine read error to win over that cancellation.
+	cancel()
+	close(releaseWrite)
+
+	select {
+	case code := <-done:
+		if code != exitCrash {
+			t.Fatalf("exit code = %d, want crash %d", code, exitCrash)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not exit after terminal read error")
+	}
+	if got := stderr.String(); !strings.Contains(got, "acp: "+wantErr.Error()) {
+		t.Fatalf("stderr = %q, want terminal read error", got)
+	}
+}
+
+func TestRunACPIdleCancellationExitsCleanly(t *testing.T) {
+	cancel := installACPTestContext(t)
+	pipeReader, pipeWriter := io.Pipe()
+	t.Cleanup(func() { _ = pipeWriter.Close() })
+	readStarted := make(chan struct{}, 1)
+	reader := &acpNotifyingReadCloser{ReadCloser: pipeReader, readStarted: readStarted}
+	var stdout, stderr bytes.Buffer
+	done := make(chan int, 1)
+	go func() {
+		done <- runACP(nil, &stdout, &stderr, fillAppDeps(appDeps{stdin: reader}))
+	}()
+
+	select {
+	case <-readStarted:
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not begin reading")
+	}
+	cancel()
+
+	select {
+	case code := <-done:
+		if code != exitSuccess {
+			t.Fatalf("exit code = %d, want success %d; stderr: %s", code, exitSuccess, stderr.String())
+		}
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not exit after cancellation")
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+type acpNotifyingReadCloser struct {
+	io.ReadCloser
+	readStarted chan<- struct{}
+	once        sync.Once
+}
+
+func (r *acpNotifyingReadCloser) Read(p []byte) (int, error) {
+	r.once.Do(func() { r.readStarted <- struct{}{} })
+	return r.ReadCloser.Read(p)
+}

internal/cli/app.go

@@ -585,6 +585,9 @@ func fillAppDeps(deps appDeps) appDeps {
 	baseProbeProviderHealth := deps.probeProviderHealth
 	deps.probeProviderHealth = func(ctx context.Context, options providerhealth.Options) providerhealth.Result {
 		options.Profile = applyStoredProviderKeyAt(options.Profile, userConfigPath)
+		if options.OAuthResolver == nil {
+			options.OAuthResolver, _ = oauthLoginForProfile(options.Profile)
+		}
 		return baseProbeProviderHealth(ctx, options)
 	}
 	return deps

internal/cli/context.go

@@ -40,10 +40,11 @@ func runContext(args []string, stdout io.Writer, stderr io.Writer, deps appDeps)
 		return writeAppError(stderr, err.Error(), exitCrash)
 	}
 	report, err := contextreport.Build(contextreport.Options{
-		WorkspaceRoot: workspaceRoot,
-		Provider:      resolved.Provider,
-		Registry:      newCoreRegistry(workspaceRoot),
-		ContextWindow: modelContextWindow(modelRegistry, resolved.Provider.Model),
+		WorkspaceRoot:  workspaceRoot,
+		Provider:       resolved.Provider,
+		Registry:       newCoreRegistry(workspaceRoot),
+		ContextWindow:  modelContextWindow(modelRegistry, resolved.Provider.Model),
+		DeferThreshold: resolved.Tools.DeferThreshold,
 	})
 	if err != nil {
 		return writeAppError(stderr, err.Error(), exitCrash)

internal/cli/deferred_wiring_test.go

@@ -77,11 +77,10 @@ func TestRegisterToolSearchIfEligibleSkipsWhenThresholdZero(t *testing.T) {
 	}
 }
 
-func TestDeferredEligibleCountIgnoresCoreTools(t *testing.T) {
+func TestDeferredEligibleCountIncludesOptionalBuiltins(t *testing.T) {
 	registry := newCoreRegistry(t.TempDir())
-	// newCoreRegistry holds only built-ins; none implement Deferred().
-	if got := deferredEligibleCount(registry, agent.PermissionModeAuto, nil, nil); got != 0 {
-		t.Fatalf("deferredEligibleCount(core) = %d, want 0", got)
+	if got := deferredEligibleCount(registry, agent.PermissionModeAuto, nil, nil); got < 2 {
+		t.Fatalf("deferredEligibleCount(core) = %d, want at least 2 optional built-ins", got)
 	}
 }
 

internal/cli/mcp_config.go

@@ -308,6 +308,34 @@ func runMCPCheck(ctx context.Context, args []string, stdout io.Writer, stderr io
 	}
 	defer closeMCPRuntime(stderr, mcpRuntime)
 
+	// A connect failure does not come back as err. RegisterTools is deliberately
+	// best-effort so one unreachable server cannot stop Zero launching: it records
+	// the failure on the runtime and returns nil. That is right for startup and
+	// wrong to ignore here, because this is the command a user runs precisely when
+	// a server is misbehaving, and reporting "is reachable" for a server that never
+	// started sends them looking somewhere else.
+	for _, skipped := range mcpRuntime.Skipped() {
+		if skipped.Name != serverName {
+			continue
+		}
+		message := fmt.Sprintf("MCP server %s is not reachable", serverName)
+		if skipped.Err != nil {
+			message = fmt.Sprintf("%s: %s", message, redaction.ErrorMessage(skipped.Err, redaction.Options{}))
+		}
+		if options.json {
+			payload := struct {
+				ServerName string `json:"serverName"`
+				Status     string `json:"status"`
+				Error      string `json:"error,omitempty"`
+			}{ServerName: serverName, Status: "unreachable", Error: message}
+			if err := writePrettyJSON(stdout, redaction.RedactValue(payload, redaction.Options{})); err != nil {
+				return exitCrash
+			}
+			return exitCrash
+		}
+		return writeAppError(stderr, message, exitCrash)
+	}
+
 	items := mcpToolList(registry)
 	if options.json {
 		payload := struct {

internal/cli/mcp_trust_edge_test.go

@@ -6,6 +6,7 @@ package cli
 
 import (
 	"bytes"
+	"encoding/json"
 	"errors"
 	"os"
 	"path/filepath"
@@ -219,3 +220,81 @@ func TestRunMCPCheckNormalizeError(t *testing.T) {
 		t.Fatalf("want normalize error, got %q", got)
 	}
 }
+
+// TestRunMCPCheckReportsUnreachableServer covers the case the command exists
+// for: a server that fails to start.
+//
+// RegisterTools is best-effort by design, so a connect failure is recorded on
+// the runtime and registration returns nil. runMCPCheck used to inspect only
+// that nil error and then print "is reachable", which told the user their
+// broken server was fine. The command is spawned for real here rather than
+// stubbed, because the whole failure mode was a mismatch between what
+// registration returns and what it records.
+func TestRunMCPCheckReportsUnreachableServer(t *testing.T) {
+	setTrustConfigRoot(t)
+	deps := appDeps{
+		getwd: func() (string, error) { return t.TempDir(), nil },
+		resolveMCPConfig: func(_ string, _ bool) (config.MCPConfig, error) {
+			return config.MCPConfig{Servers: map[string]config.MCPServerConfig{
+				"broken": {Type: "stdio", Command: "zero-definitely-not-a-real-binary-xyz"},
+			}}, nil
+		},
+	}
+	var out, errBuf bytes.Buffer
+	if code := runWithDeps([]string{"mcp", "check", "broken"}, &out, &errBuf, deps); code == exitSuccess {
+		t.Fatalf("mcp check must fail for a server that did not start; stdout=%q stderr=%q", out.String(), errBuf.String())
+	}
+	if got := out.String(); strings.Contains(got, "is reachable") {
+		t.Fatalf("mcp check reported a failed server as reachable: %q", got)
+	}
+	if got := errBuf.String(); !strings.Contains(got, "not reachable") {
+		t.Fatalf("want an unreachable error naming the server, got %q", got)
+	}
+}
+
+// The --json contract for an unreachable server, which the text case above does
+// not touch.
+//
+// The JSON branch is a separate return path with its own payload, so a caller
+// parsing it would otherwise be relying on a shape nothing pins: reverting the
+// check leaves it emitting status "ok" with a tool count, which is valid JSON
+// and completely wrong.
+func TestRunMCPCheckReportsUnreachableServerJSON(t *testing.T) {
+	setTrustConfigRoot(t)
+	deps := appDeps{
+		getwd: func() (string, error) { return t.TempDir(), nil },
+		resolveMCPConfig: func(_ string, _ bool) (config.MCPConfig, error) {
+			return config.MCPConfig{Servers: map[string]config.MCPServerConfig{
+				"broken": {Type: "stdio", Command: "zero-definitely-not-a-real-binary-xyz"},
+			}}, nil
+		},
+	}
+	var out, errBuf bytes.Buffer
+	if code := runWithDeps([]string{"mcp", "check", "broken", "--json"}, &out, &errBuf, deps); code == exitSuccess {
+		t.Fatalf("mcp check --json must fail for a server that did not start; stdout=%q stderr=%q", out.String(), errBuf.String())
+	}
+	var payload struct {
+		ServerName string `json:"serverName"`
+		Status     string `json:"status"`
+		Error      string `json:"error"`
+		ToolCount  int    `json:"toolCount"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &payload); err != nil {
+		t.Fatalf("decode mcp check --json output %q: %v", out.String(), err)
+	}
+	if payload.ServerName != "broken" {
+		t.Fatalf("serverName = %q, want the server that was checked", payload.ServerName)
+	}
+	if payload.Status != "unreachable" {
+		t.Fatalf("status = %q, want %q", payload.Status, "unreachable")
+	}
+	if !strings.Contains(payload.Error, "not reachable") {
+		t.Fatalf("error = %q, want it to say the server is not reachable", payload.Error)
+	}
+	// A reachable payload carries a tool count; an unreachable one must not
+	// imply zero tools were found, which reads as a server that simply exposes
+	// none.
+	if payload.ToolCount != 0 {
+		t.Fatalf("toolCount = %d, want it absent from an unreachable payload", payload.ToolCount)
+	}
+}

internal/cli/observability_test.go

@@ -5,6 +5,8 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -12,6 +14,7 @@ import (
 	"time"
 
 	"github.com/Gitlawb/zero/internal/config"
+	"github.com/Gitlawb/zero/internal/oauth"
 	"github.com/Gitlawb/zero/internal/providerhealth"
 	"github.com/Gitlawb/zero/internal/sessions"
 )
@@ -109,6 +112,65 @@ func TestRunDoctorConnectivityProbesProvider(t *testing.T) {
 	}
 }
 
+func TestRunDoctorConnectivityUsesOAuthLogin(t *testing.T) {
+	tokenPath := filepath.Join(t.TempDir(), "oauth-tokens.json")
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("ZERO_OAUTH_STORAGE", "file")
+	t.Setenv("ZERO_OAUTH_TOKENS_PATH", tokenPath)
+	store, err := oauth.NewStore(oauth.StoreOptions{FilePath: tokenPath})
+	if err != nil {
+		t.Fatalf("NewStore: %v", err)
+	}
+	if err := store.Save(oauth.ProviderKey("xai"), oauth.Token{
+		AccessToken: "oauth-doctor-token",
+		ExpiresAt:   time.Now().Add(time.Hour),
+	}); err != nil {
+		t.Fatalf("seed OAuth token: %v", err)
+	}
+
+	var gotAuth string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":[]}`))
+	}))
+	defer server.Close()
+
+	profile := config.ProviderProfile{
+		Name:         "xai",
+		CatalogID:    "xai",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		BaseURL:      server.URL + "/v1",
+		Model:        "grok-4",
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	exitCode := runWithDeps([]string{"doctor", "--connectivity"}, &stdout, &stderr, appDeps{
+		getwd: func() (string, error) {
+			return t.TempDir(), nil
+		},
+		resolveConfig: func(string, config.Overrides) (config.ResolvedConfig, error) {
+			return config.ResolvedConfig{
+				Provider:       profile,
+				Providers:      []config.ProviderProfile{profile},
+				ActiveProvider: profile.Name,
+			}, nil
+		},
+		probeProviderHealth: providerhealth.Probe,
+		now:                 fixedCLITime("2026-07-29T20:00:00Z"),
+	})
+
+	if exitCode != exitSuccess {
+		t.Fatalf("doctor exit = %d, want success; stderr=%q\n%s", exitCode, stderr.String(), stdout.String())
+	}
+	if gotAuth != "Bearer oauth-doctor-token" {
+		t.Fatalf("Authorization = %q, want OAuth bearer", gotAuth)
+	}
+	if !strings.Contains(stdout.String(), "[pass] provider.connectivity") {
+		t.Fatalf("doctor did not report passing connectivity:\n%s", stdout.String())
+	}
+}
+
 func TestRunDoctorConnectivityReportsProviderHealthFailure(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer

internal/cli/provider_catalog_onboarding_test.go

@@ -19,6 +19,7 @@ func TestProviderCatalogRuntimeProvidersShowOnboardingSetupHints(t *testing.T) {
 		{id: "openai", name: "OpenAI", transport: "openai", defaultModel: "gpt-4.1"},
 		{id: "groq", name: "Groq", transport: "openai-compatible", defaultModel: "llama-3.3-70b-versatile"},
 		{id: "longcat", name: "LongCat", transport: "openai-compatible", defaultModel: "LongCat-2.0"},
+		{id: "fireworks", name: "Fireworks AI", transport: "openai-compatible", defaultModel: "accounts/fireworks/models/kimi-k2p7-code"},
 		{id: "ollama-cloud", name: "Ollama Cloud", transport: "openai-compatible", defaultModel: "qwen3-coder:480b"},
 		{id: "ollama", name: "Ollama Local", transport: "openai-compatible", defaultModel: "llama3.1"},
 	}

internal/config/command.go

@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"runtime"
 	"strings"
+	"sync"
 	"time"
 )
 
@@ -17,7 +18,11 @@ func LoadProviderCommand(command string) (FileConfig, error) {
 	stdout, stderr, err := runProviderCommand(command, providerCommandTimeout)
 	if err != nil {
 		if errors.Is(err, errProviderCommandTimeout) {
-			return FileConfig{}, fmt.Errorf("provider command timed out after 5s")
+			// Report which phase ran out of time, and anything the command
+			// managed to say. This used to be a bare string with the underlying
+			// error and stderr both dropped, which left a user whose command was
+			// slow on a cold machine with nothing to act on.
+			return FileConfig{}, fmt.Errorf("provider command timed out after %s: %w%s", providerCommandTimeout, err, commandOutput(stderr))
 		}
 		return FileConfig{}, fmt.Errorf("provider command failed: %w%s", err, commandOutput(stderr))
 	}
@@ -40,20 +45,111 @@ func LoadProviderCommand(command string) (FileConfig, error) {
 
 var errProviderCommandTimeout = errors.New("provider command timeout")
 
+// providerCommandDrainGrace bounds how long the timeout path waits for cmd.Wait
+// to return after the process tree has been terminated. Terminate normally makes
+// that immediate; this exists so a descendant that refuses to die cannot extend
+// a call whose deadline has already expired.
+const providerCommandDrainGrace = 2 * time.Second
+
+// syncBuffer serialises the command's I/O pump against reads from this package.
+// On the timeout path runProviderCommand can return while cmd.Wait is still
+// draining, so the buffers outlive the call and a plain bytes.Buffer would be
+// read and written concurrently.
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *syncBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+// snapshot copies out what has been written so far. A copy rather than the
+// buffer's own slice, which the pump may still append to.
+func (b *syncBuffer) snapshot() []byte {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return append([]byte(nil), b.buf.Bytes()...)
+}
+
+// awaitWithGrace waits for done and gives up after grace, reporting whether the
+// wait completed rather than expired.
+//
+// Split out from the timeout path so the bound can be asserted on its own. In
+// place it is effectively untestable: Terminate kills the tree, so Wait returns
+// promptly and an unbounded receive would behave identically in every test that
+// is not pathological, which is exactly how the old unbounded receive survived.
+func awaitWithGrace(done <-chan error, grace time.Duration) bool {
+	timer := time.NewTimer(grace)
+	defer timer.Stop()
+	select {
+	case <-done:
+		return true
+	case <-timer.C:
+		return false
+	}
+}
+
+// runProviderCommand runs a provider command under a real deadline.
+//
+// "Real" is the point: timeout used to bound only the wait, so the call could
+// take arbitrarily longer than it. Two phases sat outside it. Starting the
+// process ran before the clock began, and on Windows that is CREATE_SUSPENDED,
+// job-object creation and assignment, and a system-wide thread snapshot, none of
+// which is fast on a cold or contended machine. Draining after termination was
+// unbounded as well. Both are inside the budget now, so the deadline is an upper
+// bound rather than a floor.
 func runProviderCommand(command string, timeout time.Duration) ([]byte, []byte, error) {
 	cmd := shellCommand(command)
 	// Bound the time Wait spends draining I/O pipes after the process exits,
 	// in case an orphaned descendant still holds the write ends open.
 	cmd.WaitDelay = time.Second
 
-	var stdout bytes.Buffer
-	var stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
+	stdout := &syncBuffer{}
+	stderr := &syncBuffer{}
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr
 
-	proc, err := startCommandProcess(cmd)
-	if err != nil {
-		return nil, nil, err
+	// Armed before the process is started, so process creation is inside the
+	// budget rather than ahead of it.
+	deadline := time.NewTimer(timeout)
+	defer deadline.Stop()
+
+	type startResult struct {
+		proc *commandProcess
+		err  error
+	}
+	// Buffered, so the goroutine can finish and exit even when nobody is left
+	// waiting on it because the deadline already fired.
+	started := make(chan startResult, 1)
+	go func() {
+		proc, err := startCommandProcess(cmd)
+		started <- startResult{proc: proc, err: err}
+	}()
+
+	var proc *commandProcess
+	select {
+	case result := <-started:
+		if result.err != nil {
+			return stdout.snapshot(), stderr.snapshot(), result.err
+		}
+		proc = result.proc
+	case <-deadline.C:
+		// The start is still in flight and will eventually hand back whatever it
+		// created, so cleanup is handed off rather than abandoned. Wait reaps the
+		// process; without it a started-but-orphaned command becomes a zombie.
+		go func() {
+			result := <-started
+			if result.err != nil {
+				return
+			}
+			result.proc.Terminate()
+			_ = cmd.Wait()
+			result.proc.Close()
+		}()
+		return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: starting the command exceeded %s", errProviderCommandTimeout, timeout)
 	}
 	defer proc.Close()
 
@@ -62,9 +158,6 @@ func runProviderCommand(command string, timeout time.Duration) ([]byte, []byte,
 		done <- cmd.Wait()
 	}()
 
-	timer := time.NewTimer(timeout)
-	defer timer.Stop()
-
 	select {
 	case err := <-done:
 		if err != nil {
@@ -83,13 +176,19 @@ func runProviderCommand(command string, timeout time.Duration) ([]byte, []byte,
 			// and tests unable to tell which one happened. Callers that only ask
 			// errors.Is(err, errProviderCommandTimeout) are unaffected, so the
 			// message LoadProviderCommand reports is unchanged.
-			return stdout.Bytes(), stderr.Bytes(), fmt.Errorf("%w: %w", errProviderCommandTimeout, err)
+			return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: %w", errProviderCommandTimeout, err)
 		}
-		return stdout.Bytes(), stderr.Bytes(), err
-	case <-timer.C:
+		return stdout.snapshot(), stderr.snapshot(), err
+	case <-deadline.C:
 		proc.Terminate()
-		<-done
-		return stdout.Bytes(), stderr.Bytes(), errProviderCommandTimeout
+		// Bounded, unlike the bare receive this replaces. Terminate kills the
+		// tree so Wait almost always returns at once, but "almost always" was
+		// doing real work here: a tree that resists termination used to hold the
+		// call open indefinitely, long past the deadline that had just expired.
+		// Returning early leaves cmd.Wait running, which is why the buffers are
+		// synchronised.
+		awaitWithGrace(done, providerCommandDrainGrace)
+		return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: the command did not finish within %s", errProviderCommandTimeout, timeout)
 	}
 }
 

internal/config/command_test.go

@@ -414,3 +414,133 @@ func itoa(value int) string {
 	}
 	return string(digits[index:])
 }
+
+// The whole point of #811: providerCommandTimeout has to be an upper bound on
+// how long the call takes, not a floor. Process creation used to run before the
+// clock started and the post-termination drain was unbounded, so a slow or
+// contended machine could block startup for far longer than the error text
+// promised.
+//
+// This one guards the end-to-end contract against gross regressions. It is NOT
+// the assertion that pins the drain bound: Terminate kills the tree, so Wait
+// returns promptly and this passes even with the drain unbounded. That property
+// is pinned by TestAwaitWithGraceGivesUp, and the start-phase bound by
+// TestRunProviderCommandCountsProcessStartAgainstTheDeadline.
+func TestRunProviderCommandBoundsTotalDuration(t *testing.T) {
+	pidFile := filepath.Join(t.TempDir(), "bound.pid")
+	command := writeCommand(t, commandScript{SleepSeconds: 60, PidFile: pidFile})
+
+	const budget = 2 * time.Second
+	start := time.Now()
+	_, _, err := runProviderCommand(command, budget)
+	elapsed := time.Since(start)
+
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want the timeout sentinel", err)
+	}
+	// Budget, plus the bounded drain, plus room for a loaded runner. A failure
+	// here means some phase is outside the deadline again, which is the bug.
+	ceiling := budget + providerCommandDrainGrace + 8*time.Second
+	if elapsed > ceiling {
+		t.Fatalf("returned after %s with a %s budget; the timeout is not bounding the call (ceiling %s)", elapsed, budget, ceiling)
+	}
+	assertProcessTerminatedIfStarted(t, pidFile)
+}
+
+// The timeout error has to carry something an operator can act on. It used to be
+// a bare string with the underlying error and the command's stderr both dropped,
+// so a user whose provider command was slow got no clue which phase ran out or
+// what the command had said.
+func TestLoadProviderCommandTimeoutReportsDiagnostics(t *testing.T) {
+	command := writeCommand(t, commandScript{
+		Stderr:       "provider is warming up",
+		SleepSeconds: 30,
+		PidFile:      filepath.Join(t.TempDir(), "diag.pid"),
+	})
+
+	_, err := LoadProviderCommand(command)
+	if err == nil {
+		t.Fatal("LoadProviderCommand() error = nil, want timeout")
+	}
+	if !strings.Contains(err.Error(), "timed out") {
+		t.Fatalf("error = %q, want a timeout message", err.Error())
+	}
+	// Wrapped, so callers can still classify it.
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want errors.Is against the timeout sentinel", err)
+	}
+	// And it must say which phase, rather than only that time ran out.
+	if !strings.Contains(err.Error(), "did not finish") && !strings.Contains(err.Error(), "starting the command") {
+		t.Fatalf("error = %q, want it to name the phase that exceeded the deadline", err.Error())
+	}
+}
+
+// The output buffers are written by cmd.Wait's I/O pump, which keeps running
+// after the timeout path has returned them to the caller, so a plain
+// bytes.Buffer would be read and written concurrently. Asserted on the buffer
+// directly: driving it end to end does not reliably produce the overlap, because
+// a terminated command usually stops writing before the snapshot is taken, so
+// such a test passes with the locking removed and proves nothing.
+//
+// Only meaningful under -race, which CI runs.
+func TestSyncBufferAllowsConcurrentWriteAndSnapshot(t *testing.T) {
+	buffer := &syncBuffer{}
+	writing := make(chan struct{})
+	go func() {
+		defer close(writing)
+		for i := 0; i < 2000; i++ {
+			_, _ = buffer.Write([]byte("x"))
+		}
+	}()
+	for i := 0; i < 2000; i++ {
+		_ = buffer.snapshot()
+	}
+	<-writing
+	if len(buffer.snapshot()) != 2000 {
+		t.Fatalf("buffer holds %d bytes, want 2000", len(buffer.snapshot()))
+	}
+}
+
+// The drain after termination must be bounded. Asserted directly on the helper,
+// because in place it is untestable without a tree that refuses to die: Wait
+// normally returns at once, which is precisely why an unbounded receive sat
+// there unnoticed. A channel that never fires is the pathological case made
+// cheap.
+func TestAwaitWithGraceGivesUp(t *testing.T) {
+	never := make(chan error)
+	start := time.Now()
+	if awaitWithGrace(never, 50*time.Millisecond) {
+		t.Fatal("reported completion for a wait that never finished")
+	}
+	if elapsed := time.Since(start); elapsed > 5*time.Second {
+		t.Fatalf("gave up after %s, want roughly the grace period", elapsed)
+	}
+	// Still reports completion when the wait does finish, or the timeout path
+	// would always claim the tree hung.
+	done := make(chan error, 1)
+	done <- nil
+	if !awaitWithGrace(done, time.Second) {
+		t.Fatal("reported expiry for a wait that had already finished")
+	}
+}
+
+// Process creation has to be inside the budget. It used to run before the clock
+// started, and on Windows that phase is CREATE_SUSPENDED plus job-object setup
+// plus a system-wide thread snapshot, none of it fast on a contended machine.
+//
+// A budget that is already spent when the call begins can only be exceeded
+// during the start, so the phase named in the error is what distinguishes the
+// two orderings: with the clock started afterwards, the start would always
+// complete first and the failure would come from the wait instead.
+func TestRunProviderCommandCountsProcessStartAgainstTheDeadline(t *testing.T) {
+	command := writeCommand(t, commandScript{Stdout: `{"name":"cmd","provider":"openai","apiKey":"sk-x","model":"m"}`})
+
+	_, _, err := runProviderCommand(command, time.Nanosecond)
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want the timeout sentinel", err)
+	}
+	if !strings.Contains(err.Error(), "starting the command") {
+		t.Fatalf("error = %q, want the start phase to be the one that exceeded the deadline; "+
+			"anything else means process creation is outside the budget again", err.Error())
+	}
+}

internal/config/types.go

@@ -113,7 +113,7 @@ type PreferencesConfig struct {
 	// ZERO_THEME, so a /theme choice survives restart. Empty = unset (defaults auto).
 	Theme string `json:"theme,omitempty"`
 	// Recaps is a tri-state: nil (unset) defaults to ON; an explicit false means
-	// the user turned post-turn recaps off. A *bool is its own tri-state, so no
+	// the user turned idle recaps off. A *bool is its own tri-state, so no
 	// custom unmarshal is needed (unlike ToolsConfig.DeferThreshold's int).
 	Recaps *bool `json:"recaps,omitempty"`
 }
@@ -130,7 +130,7 @@ type RecentModelEntry struct {
 // MaxRecentModels caps the persisted/displayed recent-selection history.
 const MaxRecentModels = 5
 
-// RecapsEnabled reports whether post-turn recaps are on. Unset defaults to ON.
+// RecapsEnabled reports whether idle recaps are on. Unset defaults to ON.
 func (p PreferencesConfig) RecapsEnabled() bool {
 	return p.Recaps == nil || *p.Recaps
 }

internal/config/writer.go

@@ -546,7 +546,7 @@ func SetRecentModels(path string, entries []RecentModelEntry) (FileConfig, error
 	return cfg, nil
 }
 
-// SetRecapsEnabled persists the post-turn recap preference, mirroring
+// SetRecapsEnabled persists the idle recap preference, mirroring
 // SetFavoriteModels (read-modify-atomic-write).
 func SetRecapsEnabled(path string, enabled bool) (FileConfig, error) {
 	path = strings.TrimSpace(path)

internal/contextreport/contextreport.go

@@ -40,6 +40,7 @@ type Options struct {
 	Provider            config.ProviderProfile
 	Registry            *tools.Registry
 	ContextWindow       int
+	DeferThreshold      int
 	ProjectContextFiles []string
 }
 
@@ -56,6 +57,8 @@ type Report struct {
 	FreeTokens           int        `json:"freeTokens"`
 	UsedFraction         float64    `json:"usedFraction"`
 	ToolCount            int        `json:"toolCount"`
+	AvailableToolCount   int        `json:"availableToolCount,omitempty"`
+	DeferredToolCount    int        `json:"deferredToolCount,omitempty"`
 	ProjectGuidelineFile string     `json:"projectGuidelineFile,omitempty"`
 	Categories           []Category `json:"categories"`
 }
@@ -113,8 +116,10 @@ func Build(options Options) (Report, error) {
 		categories = append(categories, category(CategoryWorkspaceMap, "Workspace map", estimateTextTokens(workspaceMap), report.ContextWindow))
 	}
 
-	toolCount, toolTokens := estimateRegistryTools(options.Registry)
+	toolCount, availableTools, deferredTools, toolTokens := estimateRegistryTools(options.Registry, options.DeferThreshold)
 	report.ToolCount = toolCount
+	report.AvailableToolCount = availableTools
+	report.DeferredToolCount = deferredTools
 	if toolTokens > 0 {
 		categories = append(categories, category(CategoryTools, "Tools", toolTokens, report.ContextWindow))
 	}
@@ -175,7 +180,11 @@ func Format(report Report) string {
 		lines = append(lines, fmt.Sprintf("usage: %s tokens (context window unknown)", compactNumber(report.UsedTokens)))
 	}
 	if report.ToolCount > 0 {
-		lines = append(lines, fmt.Sprintf("tools: %d", report.ToolCount))
+		toolLine := fmt.Sprintf("tools: %d exposed", report.ToolCount)
+		if report.AvailableToolCount > report.ToolCount {
+			toolLine += fmt.Sprintf(", %d available, %d deferred", report.AvailableToolCount, report.DeferredToolCount)
+		}
+		lines = append(lines, toolLine)
 	}
 	if report.ProjectGuidelineFile != "" {
 		lines = append(lines, "project_guidelines: "+report.ProjectGuidelineFile)
@@ -212,29 +221,51 @@ func category(key string, name string, tokens int, contextWindow int) Category {
 	return cat
 }
 
-func estimateRegistryTools(registry *tools.Registry) (int, int) {
+func estimateRegistryTools(registry *tools.Registry, deferThreshold int) (int, int, int, int) {
 	if registry == nil {
-		return 0, 0
+		return 0, 0, 0, 0
 	}
 	all := registry.All()
 	sort.Slice(all, func(left int, right int) bool {
 		return all[left].Name() < all[right].Name()
 	})
-	total := 0
-	count := 0
+	var visible []tools.Tool
+	var deferred []tools.Tool
 	for _, tool := range all {
 		if tool.Safety().Permission == tools.PermissionDeny {
 			continue
 		}
-		count++
+		visible = append(visible, tool)
+		if tools.IsDeferred(tool) {
+			deferred = append(deferred, tool)
+		}
+	}
+	active := deferThreshold > 0 && len(deferred) >= deferThreshold
+	exposed := visible
+	if active {
+		exposed = make([]tools.Tool, 0, len(visible)-len(deferred)+1)
+		for _, tool := range visible {
+			if !tools.IsDeferred(tool) && tool.Name() != tools.ToolSearchToolName {
+				exposed = append(exposed, tool)
+			}
+		}
+		exposed = append(exposed, tools.NewToolSearchTool(registry))
+	}
+
+	total := 0
+	for _, tool := range exposed {
 		total += estimateTextTokens(tool.Name())
-		total += estimateTextTokens(tool.Description())
+		description := tool.Description()
+		if active && tool.Name() == tools.ToolSearchToolName {
+			description = tools.BuildToolSearchDescription(deferred)
+		}
+		total += estimateTextTokens(description)
 		if encoded, err := json.Marshal(tool.Parameters()); err == nil {
 			total += estimateTextTokens(string(encoded))
 		}
 		total += toolDefinitionOverheadTokens
 	}
-	return count, total
+	return len(exposed), len(visible), len(deferred), total
 }
 
 func readProjectGuidelines(root string, names []string) (string, string) {

internal/contextreport/contextreport_test.go

@@ -130,6 +130,35 @@ func TestBuildHasStableJSONContractAndCategoryMath(t *testing.T) {
 	}
 }
 
+func TestBuildReportsInitialDeferredToolSurface(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	for _, tool := range tools.CoreToolsScoped(root, nil) {
+		registry.Register(tool)
+	}
+
+	eager, err := Build(Options{WorkspaceRoot: root, Registry: registry})
+	if err != nil {
+		t.Fatal(err)
+	}
+	deferred, err := Build(Options{WorkspaceRoot: root, Registry: registry, DeferThreshold: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if deferred.DeferredToolCount < 3 {
+		t.Fatalf("DeferredToolCount = %d, want at least 3", deferred.DeferredToolCount)
+	}
+	if deferred.AvailableToolCount != eager.ToolCount {
+		t.Fatalf("available tools = %d, want eager total %d", deferred.AvailableToolCount, eager.ToolCount)
+	}
+	if deferred.ToolCount >= deferred.AvailableToolCount {
+		t.Fatalf("initial exposed tools = %d, available = %d; expected a smaller initial surface", deferred.ToolCount, deferred.AvailableToolCount)
+	}
+	if categoryByKey(deferred, CategoryTools).Tokens >= categoryByKey(eager, CategoryTools).Tokens {
+		t.Fatalf("deferred tool schemas did not reduce the initial context")
+	}
+}
+
 func TestBuildClampsFreeBudgetWhenOverContextWindow(t *testing.T) {
 	root := t.TempDir()
 	writeTestFile(t, root, "AGENTS.md", strings.Repeat("very large project rule\n", 1000))

internal/imageinput/clipboard.go

@@ -2,6 +2,7 @@ package imageinput
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"net/http"
 	"os"
@@ -16,6 +17,13 @@ import (
 // clipboard, or (nil, "", nil) when the clipboard has no image. Called when
 // text clipboard is empty (the user pasted a screenshot). The media type is
 // sniffed from the bytes, not trusted from the clipboard.
+// ErrClipboardImageUnreadable reports that the clipboard holds an image the host
+// has no way to extract. It is deliberately distinct from "no image on the
+// clipboard", which is an ordinary no-op: this one is actionable, and silence is
+// the wrong response to it.
+var ErrClipboardImageUnreadable = errors.New(
+	"the clipboard holds an image but no helper on this host can read it; on macOS install pngpaste (brew install pngpaste) or a Python with pyobjc")
+
 func ReadClipboardImage() ([]byte, string, error) {
 	data, err := readClipboardImageBytes()
 	if err != nil {
@@ -95,35 +103,71 @@ func readClipboardImageWindows() ([]byte, error) {
 
 // readClipboardImageDarwin uses osascript to check for and read a clipboard
 // image. Returns (nil, nil) when no image is present.
-func readClipboardImageDarwin() ([]byte, error) {
-	// Check clipboard info for image classes.
-	check := `osascript -e 'clipboard info'`
-	out, err := exec.Command("sh", "-c", check).Output()
-	if err != nil {
-		return nil, nil
+// darwinClipboardInfo reports what the pasteboard is currently offering, and
+// darwinClipboardExtract pulls the PNG bytes out of it.
+//
+// Both are vars so the two-step logic below can be driven in a test. The step
+// that matters, "the clipboard holds an image and nothing here can extract it",
+// only happens when the first succeeds and the second fails, which cannot be
+// arranged by stubbing the caller: a test that substitutes ReadClipboardImage
+// asserts the plumbing around this function rather than the decision inside it,
+// and stays green with that decision reverted.
+var (
+	darwinClipboardInfo = func() (string, error) {
+		out, err := exec.Command("sh", "-c", `osascript -e 'clipboard info'`).Output()
+		return string(out), err
 	}
-	info := string(out)
-	if !strings.Contains(info, "PNG") && !strings.Contains(info, "JPEG") && !strings.Contains(info, "TIFF") && !strings.Contains(info, "GIF") {
-		return nil, nil
-	}
-	// Write clipboard image to a temp file via AppleScript, then read it.
-	// Using pngpaste if available, falling back to a Python one-liner.
-	cmd := exec.Command("sh", "-c", `pngpaste - 2>/dev/null || python3 -c "
+	darwinClipboardExtract = func() ([]byte, error) {
+		// pngpaste if available, falling back to a Python one-liner. Neither
+		// ships with macOS: pngpaste is Homebrew-only and Apple dropped the
+		// bundled PyObjC, so a stock Mac fails here every time.
+		cmd := exec.Command("sh", "-c", `pngpaste - 2>/dev/null || python3 -c "
 import AppKit, sys
 pb = AppKit.NSPasteboard.generalPasteboard()
 data = pb.dataForType_(AppKit.NSPasteboardTypePNG)
 if data:
     sys.stdout.buffer.write(data.bytes())
 "`)
-	var stdout bytes.Buffer
-	cmd.Stdout = &stdout
-	if err := cmd.Run(); err != nil {
+		var stdout bytes.Buffer
+		cmd.Stdout = &stdout
+		if err := cmd.Run(); err != nil {
+			return nil, err
+		}
+		return stdout.Bytes(), nil
+	}
+)
+
+// darwinClipboardOffersImage reports whether the pasteboard info line names an
+// image class.
+func darwinClipboardOffersImage(info string) bool {
+	for _, class := range []string{"PNG", "JPEG", "TIFF", "GIF"} {
+		if strings.Contains(info, class) {
+			return true
+		}
+	}
+	return false
+}
+
+func readClipboardImageDarwin() ([]byte, error) {
+	info, err := darwinClipboardInfo()
+	if err != nil {
 		return nil, nil
 	}
-	if stdout.Len() == 0 {
+	if !darwinClipboardOffersImage(info) {
 		return nil, nil
 	}
-	return stdout.Bytes(), nil
+	// Past this point the clipboard is KNOWN to hold an image, because the probe
+	// above said so. A failure here is therefore not "no image", it is "there is
+	// an image and nothing on this host can extract it". Reporting that as
+	// absence is what left users staring at a paste that silently did nothing.
+	data, err := darwinClipboardExtract()
+	if err != nil {
+		return nil, ErrClipboardImageUnreadable
+	}
+	if len(data) == 0 {
+		return nil, ErrClipboardImageUnreadable
+	}
+	return data, nil
 }
 
 // readClipboardImageLinux tries wl-paste (Wayland) then xclip (X11) to read

internal/imageinput/clipboard_darwin_logic_test.go

@@ -0,0 +1,84 @@
+package imageinput
+
+import (
+	"errors"
+	"testing"
+)
+
+// Drives readClipboardImageDarwin's own decision rather than the plumbing around
+// it. Both shell steps are substituted, so this runs on any platform and, more
+// importantly, actually reaches the branch under test: a test that stubs
+// ReadClipboardImage instead stays green with the production change reverted,
+// which is how the first version of this coverage slipped through.
+func TestReadClipboardImageDarwinDistinguishesUnreadableFromAbsent(t *testing.T) {
+	restore := func() func() {
+		info, extract := darwinClipboardInfo, darwinClipboardExtract
+		return func() { darwinClipboardInfo, darwinClipboardExtract = info, extract }
+	}()
+	t.Cleanup(restore)
+
+	const pngInfo = `«class PNGf», «class 8BPS»`
+
+	t.Run("image present but no extractor is actionable", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return nil, errors.New("exit status 127") }
+
+		data, err := readClipboardImageDarwin()
+		if !errors.Is(err, ErrClipboardImageUnreadable) {
+			t.Fatalf("err = %v, want ErrClipboardImageUnreadable; a stock Mac gets silence instead of a remedy", err)
+		}
+		if data != nil {
+			t.Fatalf("data = %q, want none", data)
+		}
+	})
+
+	t.Run("extractor producing nothing is also actionable", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return nil, nil }
+
+		if _, err := readClipboardImageDarwin(); !errors.Is(err, ErrClipboardImageUnreadable) {
+			t.Fatalf("err = %v, want ErrClipboardImageUnreadable for an extractor that exits 0 with no bytes", err)
+		}
+	})
+
+	// The other half of the distinction, and the reason this cannot simply always
+	// report an error: an empty clipboard is an ordinary no-op, and turning that
+	// into a notice would make every stray Ctrl+V nag the user.
+	t.Run("no image on the clipboard stays silent", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return `«class utf8»`, nil }
+		darwinClipboardExtract = func() ([]byte, error) {
+			t.Fatal("extractor ran despite the clipboard offering no image")
+			return nil, nil
+		}
+
+		data, err := readClipboardImageDarwin()
+		if err != nil || data != nil {
+			t.Fatalf("data=%q err=%v, want a silent no-op", data, err)
+		}
+	})
+
+	t.Run("probe failure stays silent", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return "", errors.New("osascript missing") }
+		darwinClipboardExtract = func() ([]byte, error) {
+			t.Fatal("extractor ran despite the info probe failing")
+			return nil, nil
+		}
+
+		if data, err := readClipboardImageDarwin(); err != nil || data != nil {
+			t.Fatalf("data=%q err=%v, want a silent no-op", data, err)
+		}
+	})
+
+	t.Run("working extractor returns the bytes", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return []byte("png-bytes"), nil }
+
+		data, err := readClipboardImageDarwin()
+		if err != nil {
+			t.Fatalf("err = %v, want none", err)
+		}
+		if string(data) != "png-bytes" {
+			t.Fatalf("data = %q, want the extractor's bytes", data)
+		}
+	})
+}

internal/minify/minify.go

@@ -13,8 +13,10 @@ package minify
 
 import (
 	"bytes"
+	"go/ast"
 	"go/parser"
 	"go/printer"
+	"go/scanner"
 	"go/token"
 	"path/filepath"
 	"strings"
@@ -34,8 +36,11 @@ func File(path string, content []byte) Result {
 		if out, ok := minifyGo(content); ok {
 			return Result{Content: out, Language: "go", Applied: true}
 		}
-		// Unparsable Go (a snippet, generics edge, or syntax error): fall through
-		// to the safe generic path rather than risk a partial AST reprint.
+		if out, ok := minifyGoFragment(content); ok {
+			return Result{Content: out, Language: "go-fragment", Applied: true}
+		}
+		// An incomplete fragment that cannot be wrapped safely falls through to
+		// whitespace-only normalization; no source text is guessed or discarded.
 	} else if style, ok := commentStyles[ext]; ok {
 		// Strip comments with a string-aware lexer, then collapse the whitespace the
 		// removed comments left behind. The stripper only handles languages whose
@@ -46,6 +51,133 @@ func File(path string, content []byte) Result {
 	return Result{Content: minifyGeneric(content), Language: "text", Applied: false}
 }
 
+// Fragment minifies a bounded source range without assuming lexical state from
+// text outside the range. Go remains parser-validated; other languages use the
+// conservative whitespace-only transform because a range may begin inside a
+// multiline string or block comment.
+func Fragment(path string, content []byte) Result {
+	if strings.EqualFold(filepath.Ext(path), ".go") {
+		if out, ok := minifyGo(content); ok {
+			return Result{Content: out, Language: "go", Applied: true}
+		}
+		if out, ok := minifyGoFragment(content); ok {
+			return Result{Content: out, Language: "go-fragment", Applied: true}
+		}
+	}
+	return Result{Content: minifyGeneric(content), Language: "text", Applied: false}
+}
+
+// ContextualFragment minifies a bounded fragment after checking its starting
+// position against the complete source. A Go range that begins inside a string
+// or comment must remain verbatim apart from whitespace normalization: parsing
+// that fragment by itself would mistake literal text for Go syntax.
+func ContextualFragment(path string, source, content []byte, startOffset int) Result {
+	if strings.EqualFold(filepath.Ext(path), ".go") && goFragmentStartsInsideToken(source, startOffset) {
+		return Result{Content: minifyGeneric(content), Language: "text", Applied: false}
+	}
+	return Fragment(path, content)
+}
+
+func goFragmentStartsInsideToken(source []byte, startOffset int) bool {
+	if startOffset <= 0 || startOffset >= len(source) {
+		return false
+	}
+	fset := token.NewFileSet()
+	file := fset.AddFile("", fset.Base(), len(source))
+	var lexer scanner.Scanner
+	lexer.Init(file, source, nil, scanner.ScanComments)
+	for {
+		position, kind, literal := lexer.Scan()
+		if kind == token.EOF {
+			return false
+		}
+		if kind != token.STRING && kind != token.COMMENT {
+			continue
+		}
+		start := file.Offset(position)
+		if startOffset > start && startOffset < start+len(literal) {
+			return true
+		}
+	}
+}
+
+// minifyGoFragment handles bounded reads that do not contain a package clause.
+// It finds the longest complete declaration or statement prefix that the real
+// Go parser accepts, prints that prefix without comments, and preserves any
+// incomplete tail conservatively. Ranges are intentionally capped: repeatedly
+// parsing a large broken file would otherwise turn a cheap read into O(n²) work.
+func minifyGoFragment(content []byte) (string, bool) {
+	lines := strings.Split(strings.ReplaceAll(string(content), "\r\n", "\n"), "\n")
+	if len(lines) > 1 && lines[len(lines)-1] == "" {
+		lines = lines[:len(lines)-1]
+	}
+	if len(lines) > 512 {
+		return "", false
+	}
+	for end := len(lines); end > 0; end-- {
+		prefix := strings.Join(lines[:end], "\n")
+		if compact, ok := parseGoDeclarations(prefix); ok {
+			return joinCompactPrefix(compact, lines[end:]), true
+		}
+		if compact, ok := parseGoStatements(prefix); ok {
+			return joinCompactPrefix(compact, lines[end:]), true
+		}
+	}
+	return "", false
+}
+
+func parseGoDeclarations(fragment string) (string, bool) {
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "", "package compact\n"+fragment, parser.SkipObjectResolution)
+	if err != nil || len(file.Decls) == 0 {
+		return "", false
+	}
+	nodes := make([]ast.Node, len(file.Decls))
+	for i, declaration := range file.Decls {
+		nodes[i] = declaration
+	}
+	return printGoNodes(fset, nodes)
+}
+
+func parseGoStatements(fragment string) (string, bool) {
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "", "package compact\nfunc _(){\n"+fragment+"\n}", parser.SkipObjectResolution)
+	if err != nil || len(file.Decls) != 1 {
+		return "", false
+	}
+	function, ok := file.Decls[0].(*ast.FuncDecl)
+	if !ok || function.Body == nil || len(function.Body.List) == 0 {
+		return "", false
+	}
+	nodes := make([]ast.Node, len(function.Body.List))
+	for i, statement := range function.Body.List {
+		nodes[i] = statement
+	}
+	return printGoNodes(fset, nodes)
+}
+
+func printGoNodes(fset *token.FileSet, nodes []ast.Node) (string, bool) {
+	var buf bytes.Buffer
+	cfg := printer.Config{Mode: printer.TabIndent, Tabwidth: 1}
+	for i, node := range nodes {
+		if i > 0 {
+			buf.WriteByte('\n')
+		}
+		if err := cfg.Fprint(&buf, fset, node); err != nil {
+			return "", false
+		}
+	}
+	return strings.TrimSpace(buf.String()), true
+}
+
+func joinCompactPrefix(compact string, remainder []string) string {
+	tail := minifyGeneric([]byte(strings.Join(remainder, "\n")))
+	if tail == "" {
+		return compact
+	}
+	return compact + "\n" + tail
+}
+
 // minifyGo parses Go WITHOUT comments (omitting parser.ParseComments leaves them
 // unattached) and reprints the AST, yielding valid, comment-free, gofmt-shaped
 // source with tab indentation (1 char per level). It returns ok=false on any

internal/minify/minify_test.go

@@ -39,17 +39,58 @@ func Greet(name string) string {
 	}
 }
 
-func TestMinifyGoFallsBackOnUnparsableGo(t *testing.T) {
-	// A snippet (no package clause) cannot parse as a file -> safe generic path.
+func TestMinifyGoStatementFragment(t *testing.T) {
 	r := File("snippet.go", []byte("x := 1   \n\n\n// keep me\ny := 2\n"))
-	if r.Applied {
-		t.Fatalf("expected fallback for unparsable Go, got %+v", r)
+	if !r.Applied || r.Language != "go-fragment" {
+		t.Fatalf("expected parsed Go fragment, got %+v", r)
 	}
 	if strings.Contains(r.Content, "\n\n\n") {
-		t.Errorf("generic should collapse blank runs:\n%q", r.Content)
+		t.Errorf("fragment should collapse blank runs:\n%q", r.Content)
 	}
-	if !strings.Contains(r.Content, "// keep me") {
-		t.Errorf("generic must NOT strip comments (unsafe without a parser): %q", r.Content)
+	if strings.Contains(r.Content, "keep me") || !strings.Contains(r.Content, "y := 2") {
+		t.Errorf("fragment was not compacted safely: %q", r.Content)
+	}
+}
+
+func TestMinifyGoFragmentAccepts512LinesWithFinalNewline(t *testing.T) {
+	src := strings.Repeat("x++\n", 512)
+	r := File("snippet.go", []byte(src))
+	if !r.Applied || r.Language != "go-fragment" {
+		t.Fatalf("expected 512-line fragment to remain eligible, got %+v", r)
+	}
+	if got := strings.Count(r.Content, "x++"); got != 512 {
+		t.Fatalf("compacted statement count = %d, want 512", got)
+	}
+}
+
+func TestMinifyGoDeclarationPrefixPreservesIncompleteTail(t *testing.T) {
+	src := `func Handle737(n int) (int, error) {
+	if n%2 == 1 {
+		return 0, errBad
+	}
+	return n + 737, nil
+}
+
+// Handle738 begins outside the requested range.
+func Handle738(n int) (int, error) {
+	if n%2 == 1 {`
+	r := File("range.go", []byte(src))
+	if !r.Applied || r.Language != "go-fragment" {
+		t.Fatalf("expected declaration-prefix compaction, got %+v", r)
+	}
+	if strings.Contains(r.Content, "Handle737 returns") || !strings.Contains(r.Content, "return n + 737") {
+		t.Fatalf("complete declaration was not compacted correctly:\n%s", r.Content)
+	}
+	if !strings.Contains(r.Content, "func Handle738") || !strings.Contains(r.Content, "if n%2 == 1 {") {
+		t.Fatalf("incomplete tail was not preserved:\n%s", r.Content)
+	}
+}
+
+func TestMinifyGoLargeInvalidInputFallsBackConservatively(t *testing.T) {
+	src := strings.Repeat("x := 1 // keep\n", 513)
+	r := File("broken.go", []byte(src))
+	if r.Applied || !strings.Contains(r.Content, "// keep") {
+		t.Fatalf("large invalid input must retain conservative fallback: %+v", r)
 	}
 }
 

internal/providercatalog/catalog.go

@@ -138,6 +138,7 @@ var descriptors = []Descriptor{
 	openAICompat("groq", "Groq", "https://api.groq.com/openai/v1", "llama-3.3-70b-versatile", []string{"GROQ_API_KEY"}),
 	openAICompat("deepseek", "DeepSeek", "https://api.deepseek.com/v1", "deepseek-chat", []string{"DEEPSEEK_API_KEY"}),
 	openAICompat("together", "Together AI", "https://api.together.xyz/v1", "meta-llama/Llama-3.3-70B-Instruct-Turbo", []string{"TOGETHER_API_KEY"}),
+	openAICompat("fireworks", "Fireworks AI", "https://api.fireworks.ai/inference/v1", "accounts/fireworks/models/kimi-k2p7-code", []string{"FIREWORKS_API_KEY"}, "fireworks-ai"),
 	openAICompat("dashscope", "DashScope", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", "qwen-plus", []string{"DASHSCOPE_API_KEY", "QWEN_API_KEY"}, "qwen"),
 	openAICompat("moonshot", "Moonshot AI", "https://api.moonshot.ai/v1", "kimi-k2-0905-preview", []string{"MOONSHOT_API_KEY"}, "kimi"),
 	openAICompat("atlascloud", "Atlas Cloud", "https://api.atlascloud.ai/v1", "qwen/qwen3.5-flash", []string{"ATLASCLOUD_API_KEY"}, "atlas cloud", "atlas"),

internal/providercatalog/catalog_test.go

@@ -22,6 +22,7 @@ var expectedCatalogIDs = []string{
 	"groq",
 	"deepseek",
 	"together",
+	"fireworks",
 	"dashscope",
 	"moonshot",
 	"atlascloud",
@@ -155,6 +156,28 @@ func TestLongCatDescriptor(t *testing.T) {
 	}
 }
 
+func TestFireworksDescriptor(t *testing.T) {
+	descriptor, err := Require("fireworks")
+	if err != nil {
+		t.Fatalf("Require(fireworks) error = %v", err)
+	}
+	if descriptor.Name != "Fireworks AI" {
+		t.Fatalf("Name = %q, want Fireworks AI", descriptor.Name)
+	}
+	if descriptor.DefaultBaseURL != "https://api.fireworks.ai/inference/v1" {
+		t.Fatalf("DefaultBaseURL = %q, want Fireworks OpenAI-compatible endpoint", descriptor.DefaultBaseURL)
+	}
+	if descriptor.DefaultModel != "accounts/fireworks/models/kimi-k2p7-code" {
+		t.Fatalf("DefaultModel = %q, want accounts/fireworks/models/kimi-k2p7-code", descriptor.DefaultModel)
+	}
+	if descriptor.Transport != TransportOpenAICompatible {
+		t.Fatalf("Transport = %q, want %q", descriptor.Transport, TransportOpenAICompatible)
+	}
+	if !reflect.DeepEqual(descriptor.AuthEnvVars, []string{"FIREWORKS_API_KEY"}) {
+		t.Fatalf("AuthEnvVars = %#v, want FIREWORKS_API_KEY", descriptor.AuthEnvVars)
+	}
+}
+
 func TestAtlasCloudDescriptor(t *testing.T) {
 	descriptor, err := Require("atlascloud")
 	if err != nil {
@@ -346,7 +369,7 @@ func TestListByTransportPreservesCatalogOrder(t *testing.T) {
 		TransportBedrock:         {"bedrock"},
 		TransportVertex:          {"vertex"},
 		TransportAnthropicCompat: {"minimax", "minimaxi-cn", "opencode-go-anthropic-compatible", "custom-anthropic-compatible"},
-		TransportOpenAICompat:    {"gitlawb-opengateway", "aimlapi", "ollama-cloud", "ollama", "lmstudio", "openrouter", "huggingface", "chatgpt", "groq", "deepseek", "together", "dashscope", "moonshot", "atlascloud", "longcat", "nvidia-nim", "mistral", "github", "xai", "venice", "xiaomi-mimo", "bankr", "zai", "zai-cn", "kilocode", "opencode", "opencode-go", "atomic-chat", "chatgpt-proxy", "custom-openai-compatible"},
+		TransportOpenAICompat:    {"gitlawb-opengateway", "aimlapi", "ollama-cloud", "ollama", "lmstudio", "openrouter", "huggingface", "chatgpt", "groq", "deepseek", "together", "fireworks", "dashscope", "moonshot", "atlascloud", "longcat", "nvidia-nim", "mistral", "github", "xai", "venice", "xiaomi-mimo", "bankr", "zai", "zai-cn", "kilocode", "opencode", "opencode-go", "atomic-chat", "chatgpt-proxy", "custom-openai-compatible"},
 	}
 
 	for transport, wantIDs := range cases {

internal/providerhealth/providerhealth.go

@@ -46,12 +46,13 @@ const (
 const defaultTimeout = 5 * time.Second
 
 type Options struct {
-	Profile      config.ProviderProfile
-	Connectivity bool
-	HTTPClient   *http.Client
-	Resolver     Resolver
-	Timeout      time.Duration
-	UserAgent    string
+	Profile       config.ProviderProfile
+	Connectivity  bool
+	HTTPClient    *http.Client
+	Resolver      Resolver
+	OAuthResolver providerio.TokenResolver
+	Timeout       time.Duration
+	UserAgent     string
 }
 
 type Resolver interface {
@@ -207,11 +208,26 @@ func Probe(ctx context.Context, options Options) Result {
 		"providerKind": metadata.ProviderKind,
 	}, profile))
 
-	if credentialRequired(profile, metadata.ProviderKind) && !hasCredential(profile) {
+	oauthConfigured := options.OAuthResolver != nil
+	if oauthConfigured {
+		var resolveErr error
+		profile, oauthConfigured, resolveErr = profileWithOAuthCredential(ctx, profile, options.OAuthResolver, false)
+		if resolveErr != nil {
+			result.add(check("provider.auth", "Provider auth", StatusFail, CategoryAuth, "Provider OAuth credential could not be resolved: "+resolveErr.Error(), map[string]any{
+				"oauthLogin": true,
+			}, profile))
+			return result.finalize()
+		}
+	}
+	if credentialRequired(profile, metadata.ProviderKind) && !hasCredential(profile) && !oauthConfigured {
 		result.add(check("provider.auth", "Provider auth", StatusFail, CategoryAuth, fmt.Sprintf("Provider %s requires API credentials.", providerName(profile)), credentialDetails(profile), profile))
 		return result.finalize()
 	}
-	if hasCredential(profile) {
+	if oauthConfigured {
+		result.add(check("provider.auth", "Provider auth", StatusPass, CategoryAuth, fmt.Sprintf("Provider %s has OAuth credentials configured.", providerName(profile)), map[string]any{
+			"oauthLogin": true,
+		}, profile))
+	} else if hasCredential(profile) {
 		result.add(check("provider.auth", "Provider auth", StatusPass, CategoryAuth, fmt.Sprintf("Provider %s has credentials configured.", providerName(profile)), credentialDetails(profile), profile))
 	} else {
 		result.add(check("provider.auth", "Provider auth", StatusPass, CategoryAuth, fmt.Sprintf("Provider %s does not require API credentials.", providerName(profile)), credentialDetails(profile), profile))
@@ -286,9 +302,35 @@ func connectivityCheck(ctx context.Context, profile config.ProviderProfile, kind
 	if err != nil {
 		return classifyTransportError(err, profile)
 	}
-	defer func() {
-		_ = response.Body.Close()
-	}()
+	defer func(body io.ReadCloser) {
+		_ = body.Close()
+	}(response.Body)
+	if response.StatusCode == http.StatusUnauthorized && options.OAuthResolver != nil {
+		refreshed, ok, refreshErr := profileWithOAuthCredential(requestCtx, options.Profile, options.OAuthResolver, true)
+		if refreshErr != nil {
+			return check("provider.connectivity", "Provider connectivity", StatusFail, CategoryAuth, "Provider OAuth credential refresh failed: "+refreshErr.Error(), map[string]any{
+				"statusCode": response.StatusCode,
+			}, profile)
+		}
+		if ok {
+			_ = response.Body.Close()
+			profile = refreshed
+			request, allowLoopbackOrPrivate, err = healthRequest(requestCtx, profile, kind, options)
+			if err != nil {
+				return check("provider.connectivity", "Provider connectivity", StatusFail, CategoryConfig, err.Error(), nil, profile)
+			}
+			if options.HTTPClient == nil {
+				client = newConnectivityClient(timeout, options.Resolver, sensitiveAuthHeaderNames(profile, kind), allowLoopbackOrPrivate)
+			}
+			response, err = client.Do(request)
+			if err != nil {
+				return classifyTransportError(err, profile)
+			}
+			defer func(body io.ReadCloser) {
+				_ = body.Close()
+			}(response.Body)
+		}
+	}
 
 	body, err := io.ReadAll(io.LimitReader(response.Body, 64*1024))
 	if err != nil {
@@ -320,6 +362,23 @@ func connectivityCheck(ctx context.Context, profile config.ProviderProfile, kind
 	}, profile)
 }
 
+func profileWithOAuthCredential(ctx context.Context, profile config.ProviderProfile, resolver providerio.TokenResolver, forceRefresh bool) (config.ProviderProfile, bool, error) {
+	if resolver == nil {
+		return profile, false, nil
+	}
+	header, value, ok, err := resolver(ctx, forceRefresh)
+	if err != nil || !ok {
+		return profile, false, err
+	}
+	if strings.TrimSpace(header) == "" {
+		header = "Authorization"
+	}
+	profile.AuthHeader = header
+	profile.AuthScheme = ""
+	profile.AuthHeaderValue = value
+	return profile, true, nil
+}
+
 func healthRequest(ctx context.Context, profile config.ProviderProfile, kind config.ProviderKind, options Options) (*http.Request, bool, error) {
 	baseURL, err := resolvedBaseURL(profile, kind)
 	if err != nil {
@@ -748,6 +807,9 @@ func redact(message string, profile config.ProviderProfile) string {
 
 func providerSecrets(profile config.ProviderProfile) []string {
 	secrets := []string{profile.APIKey, profile.AuthHeaderValue}
+	if fields := strings.Fields(profile.AuthHeaderValue); len(fields) == 2 {
+		secrets = append(secrets, fields[1])
+	}
 	for _, value := range profile.CustomHeaders {
 		if strings.TrimSpace(value) != "" {
 			secrets = append(secrets, value)

internal/providerhealth/providerhealth_test.go

@@ -180,6 +180,182 @@ func TestProbeResolvedKindConnectivityAuthErrorRedactsSecret(t *testing.T) {
 	}
 }
 
+func TestProbeConnectivityUsesOAuthCredential(t *testing.T) {
+	var gotAuth string
+	resolverCalled := false
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		gotAuth = r.Header.Get("Authorization")
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Status:     "200 OK",
+			Body:       io.NopCloser(strings.NewReader(`{"data":[]}`)),
+			Header:     make(http.Header),
+		}, nil
+	})}
+
+	result := Probe(context.Background(), Options{
+		Profile: config.ProviderProfile{
+			Name:         "xai",
+			CatalogID:    "xai",
+			ProviderKind: config.ProviderKindOpenAICompatible,
+			BaseURL:      "https://api.example.com/v1",
+			Model:        "grok-4",
+		},
+		Connectivity: true,
+		HTTPClient:   client,
+		Resolver:     staticResolver{addr: netip.MustParseAddr("93.184.216.34")},
+		OAuthResolver: func(context.Context, bool) (string, string, bool, error) {
+			resolverCalled = true
+			return "Authorization", "Bearer oauth-test-token", true, nil
+		},
+	})
+
+	if result.Status != StatusPass {
+		t.Fatalf("Status = %q, want pass: %#v", result.Status, result.Checks)
+	}
+	if !resolverCalled {
+		t.Fatal("OAuth resolver was not called")
+	}
+	if gotAuth != "Bearer oauth-test-token" {
+		t.Fatalf("Authorization = %q, want OAuth bearer", gotAuth)
+	}
+}
+
+func TestProbeConnectivityOAuthCredentialsAreRedacted(t *testing.T) {
+	const (
+		staticKey  = "STATICKEYVALUE1234567890abcdef"
+		oauthToken = "hf_VASANTHSENTINEL0011223344"
+	)
+	var authHeaders []string
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		authHeaders = append(authHeaders, r.Header.Get("Authorization"))
+		return &http.Response{
+			StatusCode: http.StatusUnauthorized,
+			Status:     "401 Unauthorized",
+			Body:       io.NopCloser(strings.NewReader(`{"error":{"message":"invalid credentials ` + staticKey + ` and ` + oauthToken + `"}}`)),
+			Header:     make(http.Header),
+		}, nil
+	})}
+
+	result := Probe(context.Background(), Options{
+		Profile: config.ProviderProfile{
+			Name:         "xai",
+			CatalogID:    "xai",
+			ProviderKind: config.ProviderKindOpenAICompatible,
+			BaseURL:      "https://api.example.com/v1",
+			APIKey:       staticKey,
+			Model:        "grok-4",
+		},
+		Connectivity: true,
+		HTTPClient:   client,
+		Resolver:     staticResolver{addr: netip.MustParseAddr("93.184.216.34")},
+		OAuthResolver: func(context.Context, bool) (string, string, bool, error) {
+			return "Authorization", "Bearer " + oauthToken, true, nil
+		},
+	})
+
+	if len(authHeaders) != 2 {
+		t.Fatalf("Authorization headers = %#v, want initial request and one refresh retry", authHeaders)
+	}
+	for _, header := range authHeaders {
+		if header != "Bearer "+oauthToken {
+			t.Fatalf("Authorization = %q, want OAuth bearer", header)
+		}
+	}
+	check := result.Check("provider.connectivity")
+	if check == nil || check.Category != CategoryAuth {
+		t.Fatalf("provider.connectivity = %#v, want auth failure", check)
+	}
+	if strings.Contains(check.Message, staticKey) {
+		t.Fatalf("static API key leaked in message: %q", check.Message)
+	}
+	if strings.Contains(check.Message, oauthToken) {
+		t.Fatalf("OAuth token leaked in message: %q", check.Message)
+	}
+	if strings.Count(check.Message, "[REDACTED]") != 2 {
+		t.Fatalf("expected both credentials to be redacted, got %q", check.Message)
+	}
+}
+
+func TestProbeWithoutConnectivityRejectsUnavailableOAuthCredential(t *testing.T) {
+	resolverCalled := false
+	result := Probe(context.Background(), Options{
+		Profile: config.ProviderProfile{
+			Name:         "xai",
+			CatalogID:    "xai",
+			ProviderKind: config.ProviderKindOpenAICompatible,
+			BaseURL:      "https://api.example.com/v1",
+			Model:        "grok-4",
+		},
+		OAuthResolver: func(context.Context, bool) (string, string, bool, error) {
+			resolverCalled = true
+			return "", "", false, nil
+		},
+	})
+
+	if !resolverCalled {
+		t.Fatal("OAuth resolver was not called")
+	}
+	if result.Status != StatusFail {
+		t.Fatalf("Status = %q, want fail: %#v", result.Status, result.Checks)
+	}
+	check := result.Check("provider.auth")
+	if check == nil || check.Status != StatusFail || check.Category != CategoryAuth {
+		t.Fatalf("provider.auth = %#v, want auth failure", check)
+	}
+}
+
+func TestProbeConnectivityRefreshesOAuthCredentialAfterUnauthorized(t *testing.T) {
+	var authHeaders []string
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		authHeaders = append(authHeaders, r.Header.Get("Authorization"))
+		status := http.StatusOK
+		body := `{"data":[]}`
+		if len(authHeaders) == 1 {
+			status = http.StatusUnauthorized
+			body = `{"error":{"message":"expired"}}`
+		}
+		return &http.Response{
+			StatusCode: status,
+			Status:     http.StatusText(status),
+			Body:       io.NopCloser(strings.NewReader(body)),
+			Header:     make(http.Header),
+		}, nil
+	})}
+
+	var refreshFlags []bool
+	result := Probe(context.Background(), Options{
+		Profile: config.ProviderProfile{
+			Name:         "xai",
+			CatalogID:    "xai",
+			ProviderKind: config.ProviderKindOpenAICompatible,
+			BaseURL:      "https://api.example.com/v1",
+			Model:        "grok-4",
+		},
+		Connectivity: true,
+		HTTPClient:   client,
+		Resolver:     staticResolver{addr: netip.MustParseAddr("93.184.216.34")},
+		OAuthResolver: func(_ context.Context, forceRefresh bool) (string, string, bool, error) {
+			refreshFlags = append(refreshFlags, forceRefresh)
+			token := "stale-token"
+			if forceRefresh {
+				token = "fresh-token"
+			}
+			return "Authorization", "Bearer " + token, true, nil
+		},
+	})
+
+	if result.Status != StatusPass {
+		t.Fatalf("Status = %q, want pass after refresh: %#v", result.Status, result.Checks)
+	}
+	if len(refreshFlags) != 2 || refreshFlags[0] || !refreshFlags[1] {
+		t.Fatalf("OAuth refresh flags = %#v, want [false true]", refreshFlags)
+	}
+	if len(authHeaders) != 2 || authHeaders[0] != "Bearer stale-token" || authHeaders[1] != "Bearer fresh-token" {
+		t.Fatalf("Authorization headers = %#v, want stale then fresh bearer", authHeaders)
+	}
+}
+
 func TestProbeConnectivityClassifiesTimeout(t *testing.T) {
 	client := &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
 		return nil, context.DeadlineExceeded

internal/providermodelcatalog/catalog.go

@@ -122,6 +122,14 @@ var curatedModels = map[string][]Model{
 		{ID: "deepseek-ai/DeepSeek-R1", Description: "reasoning model"},
 		{ID: "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8", Description: "multimodal model"},
 	},
+	"fireworks": {
+		// Serverless-only curated set: ordinary API-key setups hit /inference/v1
+		// and cannot use on-demand deployment IDs.
+		{ID: "accounts/fireworks/models/kimi-k2p7-code", Description: "catalog default"},
+		{ID: "accounts/fireworks/models/deepseek-v4-flash", Description: "fast coding model"},
+		{ID: "accounts/fireworks/models/gpt-oss-120b", Description: "general model"},
+		{ID: "accounts/fireworks/models/deepseek-v4-pro", Description: "reasoning model"},
+	},
 	"dashscope": {
 		{ID: "qwen-plus", Description: "catalog default"},
 		{ID: "qwen-max", Description: "strong general model"},

internal/providermodelcatalog/catalog_test.go

@@ -28,6 +28,11 @@ func TestModelsAreProviderScoped(t *testing.T) {
 			want:     []string{"llama-3.3-70b-versatile", "openai/gpt-oss-120b"},
 			notWant:  []string{"gpt-4.1", "claude-sonnet-4.5"},
 		},
+		{
+			provider: "fireworks",
+			want:     []string{"accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/deepseek-v4-flash"},
+			notWant:  []string{"gpt-4.1", "llama-3.3-70b-versatile"},
+		},
 		{
 			provider: "chatgpt",
 			want:     []string{"gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"},

internal/providermodelcatalog/remote.go

@@ -132,6 +132,8 @@ func ModelsDevProviderID(provider providercatalog.Descriptor) string {
 		return "zai"
 	case "minimaxi-cn":
 		return "minimax"
+	case "fireworks":
+		return "fireworks-ai"
 	default:
 		return strings.TrimSpace(provider.ID)
 	}

internal/providermodelcatalog/remote_test.go

@@ -131,6 +131,7 @@ func TestModelsDevProviderIDMapsZeroAliases(t *testing.T) {
 		"ollama-cloud": "ollama-cloud",
 		"zai-cn":       "zai",
 		"minimaxi-cn":  "minimax",
+		"fireworks":    "fireworks-ai",
 	}
 	for zeroID, want := range tests {
 		provider, ok := providercatalog.Get(zeroID)

internal/providers/providerio/auth.go

@@ -25,7 +25,9 @@ type TokenResolver func(ctx context.Context, forceRefresh bool) (header string,
 //
 // base carries the API-key auth config (key + default header/scheme). setExtra
 // (optional) sets the provider's non-auth headers on every attempt. Transient
-// retries (429/503/529) are handled by the inner SendWithRetry.
+// retries are handled by the inner SendWithRetry: 429/503/529 on their own
+// budget, and provably pre-send transport failures (refused or timed-out
+// connect, DNS, TLS handshake) on a separate, shorter one.
 func SendWithAuthRetry(
 	ctx context.Context,
 	client *http.Client,

internal/providers/providerio/retry.go

@@ -3,6 +3,9 @@ package providerio
 import (
 	"bytes"
 	"context"
+	"errors"
+	"io"
+	"net"
 	"net/http"
 	"strconv"
 	"strings"
@@ -17,13 +20,22 @@ import (
 // (previously only the OpenAI provider retried; Anthropic and Gemini surfaced the
 // first failure).
 //
-// What is retried: ONLY 429 (rate limit) and 503 (service unavailable) — the
-// statuses where the server explicitly did NOT accept the request, so replaying
-// it cannot duplicate work. Other 5xx (500/502/504) and transport/network errors
-// are NOT retried: a completion POST is non-idempotent and may have reached and
-// been processed by the server, so replaying it could duplicate
-// (billable) work. Only the INITIAL request is ever in scope; once the response
-// body starts streaming it is never re-issued.
+// What is retried: 429 (rate limit) and 503 (service unavailable) — the statuses
+// where the server explicitly did NOT accept the request — plus PROVABLY
+// pre-send transport failures (DNS resolution, a refused/unreachable dial, a TLS
+// handshake timeout) where no request bytes ever left this host. In every one of
+// those cases we KNOW the server did not receive and process the request, so a
+// replay cannot duplicate work. Other 5xx (500/502/504) and every ambiguous or
+// post-send transport error (connection reset, broken pipe, EOF, a generic i/o
+// timeout, context deadline) are NOT retried: a completion POST is
+// non-idempotent and may already have reached and been processed by the server,
+// so replaying it could duplicate (billable) work. Only the INITIAL request is
+// ever in scope; once the response body starts streaming it is never re-issued.
+// Pre-send classification is by syscall errno (portable across POSIX and
+// Windows), scoped to an Op=="dial" *net.OpError so the same errno raised on a
+// post-send read/write can't be misread as pre-send. NXDOMAIN is treated as
+// permanent (not retried), and the pre-send path fails fast on its own
+// sub-second schedule rather than the seconds-long 429 backoff.
 
 const defaultMaxRetryAttempts = 6
 
@@ -37,12 +49,32 @@ const maxBackoff = 30 * time.Second
 // schedule is 2s, 4s, 8s, 16s, then maxBackoff. A var so tests can shrink it.
 var retryBackoffBase = 2 * time.Second
 
+// preSendMaxAttempts bounds retries of a provably pre-send transport failure.
+// Unlike a 429 (whose window is measured in seconds), a refused/unreachable dial
+// either recovers within a few hundred ms or is a deterministic misconfiguration
+// (wrong host/port, dead local daemon) that will never recover — so a short,
+// low-count schedule fails fast instead of stalling the agent ~60s on the
+// rate-limit schedule. This bounds the pre-send path independently of the caller's
+// maxAttempts, which is tuned for 429/503.
+const preSendMaxAttempts = 3
+
+// preSendBackoffBase is the first wait before replaying a pre-send transport
+// failure. Modeled on the mid-stream reconnect base (internal/agent/reconnect.go),
+// it is sub-second so a transient dial blip recovers quickly and a permanent one
+// fails fast. A var so tests can shrink it.
+var preSendBackoffBase = 500 * time.Millisecond
+
 // SendWithRetry issues an HTTP request, retrying ONLY the safe-to-replay server
 // responses (429 and 503, see ShouldRetryStatus) up to maxAttempts — backing off
 // between tries and honoring a server Retry-After header and context
-// cancellation. Other 5xx and transport/network errors are returned immediately,
-// never replayed (see the package note). The request is rebuilt from body each
-// attempt; setHeader (if non-nil) sets headers on every attempt.
+// cancellation. The one transport-error exception is a PROVABLY pre-send failure
+// (see isPreSendTransportError): a refused/unreachable dial or DNS failure where
+// no request bytes left this host, retried on its own short schedule
+// (preSendMaxAttempts / preSendBackoff). Every other 5xx and every ambiguous or
+// post-send transport error is returned immediately, never replayed, because a
+// non-idempotent completion POST may already have been received. The request is
+// rebuilt from body each attempt; setHeader (if non-nil) sets headers on every
+// attempt.
 //
 // It returns the final *http.Response (which the caller inspects for a non-2xx
 // status, exactly as before) or an error for a network failure / context
@@ -60,7 +92,47 @@ func SendWithRetry(
 	if maxAttempts <= 0 {
 		maxAttempts = defaultMaxRetryAttempts
 	}
-	for attempt := 1; ; attempt++ {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	// Redirects are still FOLLOWED, so a redirecting gateway keeps working, but
+	// entering one makes that attempt non-retryable. The hazard is that client.Do
+	// can transmit the original POST to the first host, follow a 307/308, and then
+	// fail the dial to the redirect target: that error is an Op=="dial" error, so
+	// isPreSendTransportError would read it as "nothing was sent" and replay a
+	// completion the first host already received. Observing the redirect rather
+	// than blocking it keeps both properties, since a request that was redirected
+	// is never replayed while redirecting endpoints stay usable. The caller's own
+	// CheckRedirect still runs and still decides whether to proceed.
+	redirected := false
+	callerCheckRedirect := client.CheckRedirect
+	redirectAwareClient := *client
+	redirectAwareClient.CheckRedirect = func(request *http.Request, via []*http.Request) error {
+		redirected = true
+		if callerCheckRedirect != nil {
+			return callerCheckRedirect(request, via)
+		}
+		// Mirror net/http's default policy, which a nil CheckRedirect would have
+		// applied: stop after 10 hops.
+		if len(via) >= 10 {
+			return errors.New("stopped after 10 redirects")
+		}
+		return nil
+	}
+	// The two retry budgets are fully independent, each with its own counter and
+	// its own backoff ordinal, because they answer different questions: a
+	// dial/DNS/TLS failure is a fast local blip (preSendMaxAttempts, sub-second
+	// schedule) while a 429/503 is a server-side window measured in seconds
+	// (maxAttempts, retryBackoffBase). A single shared loop counter coupled them
+	// in both directions: status retries starved the pre-send budget, and
+	// pre-send retries shortened the status window and started its backoff at a
+	// later rung. Neither kind of failure now consumes or advances the other.
+	preSendAttempts := 0
+	statusAttempts := 0
+	for {
+		// Per attempt: only a redirect entered by THIS attempt can make its own
+		// transport error unsafe to replay.
+		redirected = false
 		request, err := http.NewRequestWithContext(ctx, method, url, bytes.NewReader(body))
 		if err != nil {
 			return nil, err
@@ -70,32 +142,78 @@ func SendWithRetry(
 		}
 
 		connectSpan := trace.FromContext(ctx).Span(trace.SpanProviderConnect)
-		response, err := client.Do(request)
+		response, err := redirectAwareClient.Do(request)
 		connectSpan.End()
 		if err != nil {
-			// A transport failure on a POST does NOT mean the server didn't receive
-			// it — the request may have arrived and be generating a (billable,
-			// non-idempotent) completion while only the response/connection failed.
-			// Replaying it could duplicate that work, so surface the error instead
-			// of retrying. Only 429/503 responses (below), where we KNOW the request
-			// was not accepted, are safe to retry.
+			// Context cancellation always surfaces as cancellation, never a retry.
 			if ctx.Err() != nil {
 				return nil, ctx.Err()
 			}
+			// A transport failure on a POST does NOT usually mean the server didn't
+			// receive it — the request may have arrived and be generating a
+			// (billable, non-idempotent) completion while only the response or
+			// connection failed. Replaying that could duplicate work, so it is
+			// surfaced immediately. The one safe exception is a PROVABLY pre-send
+			// failure (see isPreSendTransportError): the request never left this
+			// host, so a replay cannot duplicate anything — exactly like a 429/503
+			// where we KNOW the request was not accepted. The pre-send path uses
+			// its own short bound and sub-second schedule (preSendMaxAttempts /
+			// preSendBackoff), not the seconds-long 429 schedule, so a permanent
+			// dial failure fails fast instead of stalling the agent for ~60s.
+			// A redirect means the original POST already left this host, so the
+			// dial that failed belongs to a later hop and replaying would duplicate
+			// a completion the first host may already have processed.
+			if isPreSendTransportError(err) && !redirected {
+				preSendAttempts++
+				if preSendAttempts < preSendMaxAttempts {
+					if r := trace.FromContext(ctx); r != nil {
+						r.Counter(trace.CounterRetryCount, 1)
+					}
+					if preSendBackoff(ctx, preSendAttempts) {
+						continue
+					}
+					return nil, ctx.Err()
+				}
+			}
 			return nil, err
 		}
 
-		if ShouldRetryStatus(response.StatusCode) && attempt < maxAttempts {
-			if r := trace.FromContext(ctx); r != nil {
-				r.Counter(trace.CounterRetryCount, 1)
+		// Deliberately NOT guarded on `redirected`, unlike the transport-error
+		// branch above. The two differ in what is known about the request. A
+		// transport failure after a redirect leaves it unknown whether the
+		// redirect target received and began processing the POST, so replaying
+		// could duplicate billable work. Here every hop answered: a 307/308 is the
+		// origin declining and delegating, and a retryable status is the target
+		// declining as well, so nothing accepted the request and a replay
+		// duplicates nothing.
+		//
+		// The exposure is also identical to a retryable status with no redirect in
+		// play, which this package has always retried. Guarding on redirects here
+		// would not close a gap, it would make a rate-limited completion behind a
+		// redirecting gateway fail outright instead of backing off.
+		// The transport hop succeeded, so the connect phase is healthy again and
+		// the pre-send budget starts over. It bounds CONSECUTIVE connect failures,
+		// not the lifetime of the call: without this reset, two early dial retries
+		// followed by a 429 and then one more dial blip would surface a transport
+		// error while the status budget still had room, which is the coupling
+		// these two counters were split apart to remove. Total work stays bounded,
+		// since every reset costs a status attempt and those are capped.
+		preSendAttempts = 0
+
+		if ShouldRetryStatus(response.StatusCode) {
+			statusAttempts++
+			if statusAttempts < maxAttempts {
+				if r := trace.FromContext(ctx); r != nil {
+					r.Counter(trace.CounterRetryCount, 1)
+				}
+				wait := RetryAfter(response)
+				_ = response.Body.Close()
+				if Backoff(ctx, statusAttempts, wait) {
+					continue
+				}
+				// Backoff aborted: the only reason it returns false is ctx cancellation.
+				return nil, ctx.Err()
 			}
-			wait := RetryAfter(response)
-			_ = response.Body.Close()
-			if Backoff(ctx, attempt, wait) {
-				continue
-			}
-			// Backoff aborted: the only reason it returns false is ctx cancellation.
-			return nil, ctx.Err()
 		}
 
 		// Success, a non-retryable status, or retries exhausted on a retryable
@@ -109,6 +227,119 @@ func SendWithRetry(
 	}
 }
 
+// isPreSendTransportError reports whether a transport error PROVES no request
+// bytes reached the server, so replaying the request cannot duplicate a
+// billable completion. Only narrow, unambiguous pre-connect failures qualify: a
+// recoverable DNS lookup failure, a refused/unreachable dial, and a TLS
+// handshake timeout (the handshake completes before any HTTP request bytes are
+// written).
+//
+// The refused/unreachable errnos (ECONNREFUSED/ENETUNREACH/EHOSTUNREACH) are
+// matched by syscall errno via errors.Is — portable across platforms, since Go
+// maps the WSA* codes on Windows too — but ONLY when carried by an Op=="dial"
+// *net.OpError. errors.Is matches an errno anywhere in the chain regardless of
+// which socket operation raised it, and the kernel raises these same errnos on
+// an established connection when a route drops mid-generation; scoping to the
+// dial phase is what makes "no request bytes were sent" structural rather than
+// argued, so a post-send read/write can never replay a non-idempotent POST.
+// NXDOMAIN is treated as permanent (deterministic) and is NOT retried.
+//
+// Ambiguous or post-send failures are deliberately excluded and checked FIRST,
+// so an error that is both is never treated as pre-send: a reset or broken pipe
+// can follow a request that was already sent, and a bare "i/o timeout" covers
+// read timeouts after send as well as dial timeouts, so none of these prove the
+// request was not received and a non-idempotent POST must not be replayed on
+// them.
+func isPreSendTransportError(err error) bool {
+	if err == nil {
+		return false
+	}
+	// DNS resolution precedes any connection, so a lookup failure proves nothing
+	// was sent — but only retry a lookup that could plausibly succeed on a replay.
+	// NXDOMAIN (IsNotFound) is authoritative and deterministic (a mistyped or
+	// non-existent host), so retrying it just stalls the agent through the whole
+	// backoff schedule before failing anyway; a timeout or temporary SERVFAIL is
+	// worth another try. errors.As unwraps url.Error/OpError to reach the DNSError.
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return !dnsErr.IsNotFound
+	}
+	// Post-send / ambiguous failures, excluded first. EOF and reset are matched
+	// by identity so wording (or a hostname containing "eof") can't fool them.
+	if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) || isConnResetErrno(err) {
+		return false
+	}
+	// A CONNECT-phase timeout is provably pre-send for the same structural reason
+	// a refused dial is: the connection was never established, so no request
+	// bytes left this host. It has to be admitted BEFORE the wording exclusions
+	// below, because net surfaces it with "i/o timeout" in the message, which the
+	// blanket exclusion would otherwise reject. The gate is what keeps that safe:
+	// a post-send read timeout is also Timeout(), but carries Op "read", so it
+	// never reaches here.
+	if opErr := connectOpError(err); opErr != nil && opErr.Timeout() {
+		return true
+	}
+	msg := strings.ToLower(err.Error())
+	if strings.Contains(msg, "connection reset") ||
+		strings.Contains(msg, "broken pipe") ||
+		strings.Contains(msg, "i/o timeout") {
+		return false
+	}
+	// A refused/unreachable connection is provably pre-send ONLY when it was
+	// raised during the DIAL (connection-establishment) phase. The same errnos
+	// are also raised by the kernel on an ESTABLISHED connection — when a route
+	// drops or an ICMP unreachable arrives mid-generation — which is post-send.
+	// errors.Is matches an errno anywhere in the chain regardless of the
+	// operation, so we first require an Op=="dial" *net.OpError: that makes "no
+	// request bytes left this host" structural, so a post-send read/write carrying
+	// one of these can never replay a non-idempotent POST. dialPreSendErrnos is
+	// platform-specific: on Windows a refused dial carries the raw WSA* errno
+	// (WSAECONNREFUSED etc.), which does NOT satisfy errors.Is against the POSIX
+	// syscall.ECONNREFUSED, so the Windows list adds those codes. The string
+	// markers only catch a POSIX dial error already flattened past its errno.
+	if connectOpError(err) != nil {
+		for _, errno := range dialPreSendErrnos {
+			if errors.Is(err, errno) {
+				return true
+			}
+		}
+		switch {
+		case strings.Contains(msg, "connection refused"),
+			strings.Contains(msg, "network is unreachable"),
+			strings.Contains(msg, "no route to host"):
+			return true
+		}
+	}
+	// A TLS handshake times out after the TCP dial connects but before any HTTP
+	// request bytes are written, so it is structurally pre-send. net/http surfaces
+	// it as its own error string, not a *net.OpError, so it is matched by wording
+	// independent of the dial gate.
+	if strings.Contains(msg, "tls handshake timeout") {
+		return true
+	}
+	return false
+}
+
+// connectOpError returns the outermost *net.OpError in err's chain when it comes
+// from the connection-establishment phase, else nil. Go tags a direct dial with
+// Op "dial" and a failed CONNECT through an HTTP proxy with Op "proxyconnect";
+// a failure on an already-established connection carries Op "read"/"write".
+// This is how isPreSendTransportError scopes the pre-send match to the connect
+// phase so a post-send failure can't be misclassified as pre-send.
+//
+// "proxyconnect" belongs here for the same reason "dial" does: when HTTPS_PROXY
+// is set and the CONNECT fails, the tunnel to the model host was never built, so
+// no request bytes reached it. Omitting it meant every pre-send failure behind a
+// corporate proxy fell through to no-retry, which is the environment where
+// transient connect failures are most common.
+func connectOpError(err error) *net.OpError {
+	var opErr *net.OpError
+	if errors.As(err, &opErr) && (opErr.Op == "dial" || opErr.Op == "proxyconnect") {
+		return opErr
+	}
+	return nil
+}
+
 // ShouldRetryStatus reports whether an HTTP status is safe to retry for a
 // non-idempotent completion POST: 429 (Too Many Requests), 503 (Service
 // Unavailable), and 529 (Anthropic's "overloaded"). All mean the server
@@ -137,6 +368,39 @@ func Backoff(ctx context.Context, attempt int, retryAfter time.Duration) bool {
 	}
 }
 
+// preSendBackoff waits before pre-send retry attempt N (1-based) on a short
+// sub-second schedule (500ms, 1s, ...), returning false if the context is
+// cancelled during the wait. Separate from Backoff's seconds-long rate-limit
+// schedule because a pre-send dial failure recovers in milliseconds or never.
+func preSendBackoff(ctx context.Context, attempt int) bool {
+	timer := time.NewTimer(preSendBackoffWait(attempt))
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-timer.C:
+		return true
+	}
+}
+
+// preSendBackoffWait computes the pre-send wait before retry attempt N (1-based):
+// exponential from preSendBackoffBase (500ms, 1s, 2s, ...), capped at maxBackoff.
+// The exponent is clamped so a large attempt count cannot overflow.
+func preSendBackoffWait(attempt int) time.Duration {
+	exponent := attempt - 1
+	if exponent > 5 {
+		exponent = 5
+	}
+	if exponent < 0 {
+		exponent = 0
+	}
+	wait := preSendBackoffBase * time.Duration(1<<exponent)
+	if wait > maxBackoff {
+		wait = maxBackoff
+	}
+	return wait
+}
+
 // backoffWait computes the wait before retry attempt N (1-based): Retry-After
 // when supplied, else exponential from retryBackoffBase, both capped at
 // maxBackoff. The exponent is clamped so a large attempt count cannot overflow.

internal/providers/providerio/retry_dialerrno.go

@@ -0,0 +1,32 @@
+//go:build !windows && !plan9
+
+package providerio
+
+import (
+	"errors"
+	"syscall"
+)
+
+// dialPreSendErrnos are the syscall errnos a refused or unreachable DIAL raises
+// on this platform. On POSIX the standard syscall constants are exactly what the
+// net package surfaces, so matching them via errors.Is is sufficient. Plan 9 is
+// excluded because it does not define these BSD-style errno constants (it uses
+// string errors), so the constants below would not compile there; Zero targets
+// linux/darwin/windows, so no Plan 9 variant is needed.
+var dialPreSendErrnos = []error{
+	syscall.ECONNREFUSED,
+	syscall.ENETUNREACH,
+	syscall.EHOSTUNREACH,
+	// A connect timeout is normally caught by the Timeout() check on the connect
+	// gate; this covers the case where the errno survives but the timeout flag
+	// does not, e.g. an error rebuilt from the errno alone.
+	syscall.ETIMEDOUT,
+}
+
+// isConnResetErrno reports whether err carries a connection-reset errno, the
+// post-send exclusion in isPreSendTransportError. It lives here (per platform)
+// so retry.go references no syscall constants and stays buildable on Plan 9,
+// which defines none of them.
+func isConnResetErrno(err error) bool {
+	return errors.Is(err, syscall.ECONNRESET)
+}

internal/providers/providerio/retry_dialerrno_plan9.go

@@ -0,0 +1,15 @@
+//go:build plan9
+
+package providerio
+
+// Plan 9 has no BSD-style errno constants (it uses string errors), so the
+// errno-based classification is unavailable here: isConnResetErrno returns false
+// and dialPreSendErrnos is empty. retry.go still classifies via its string
+// markers on this platform, the pre-send inclusions (connection refused /
+// network unreachable / no route to host) and the separate post-send
+// "connection reset" exclusion each keep working through the wording checks.
+// Zero targets linux/darwin/windows, so this variant only keeps the package
+// building on Plan 9 rather than adding real support.
+var dialPreSendErrnos = []error{}
+
+func isConnResetErrno(error) bool { return false }

internal/providers/providerio/retry_dialerrno_windows.go

@@ -0,0 +1,40 @@
+//go:build windows
+
+package providerio
+
+import (
+	"errors"
+	"syscall"
+
+	"golang.org/x/sys/windows"
+)
+
+// dialPreSendErrnos are the errnos a refused or unreachable DIAL raises on
+// Windows. A real Windows dial failure carries the raw Winsock error
+// (WSAECONNREFUSED = 10061, WSAENETUNREACH = 10051, WSAEHOSTUNREACH = 10065), and
+// errors.Is against the POSIX syscall.ECONNREFUSED returns FALSE there because
+// Go's Windows syscall.ECONNREFUSED is a distinct value the net package never
+// produces. So the WSA codes must be matched explicitly, or a refused dial would
+// silently never be retried on Windows. The POSIX constants stay in the list too
+// so an error built with them (e.g. a test fixture) still classifies.
+var dialPreSendErrnos = []error{
+	syscall.ECONNREFUSED,
+	syscall.ENETUNREACH,
+	syscall.EHOSTUNREACH,
+	syscall.ETIMEDOUT,
+	windows.WSAECONNREFUSED,
+	windows.WSAENETUNREACH,
+	windows.WSAEHOSTUNREACH,
+	// Same reasoning as the POSIX ETIMEDOUT entry, with the Winsock code a real
+	// Windows connect timeout actually carries.
+	windows.WSAETIMEDOUT,
+}
+
+// isConnResetErrno reports whether err carries a connection-reset errno, the
+// post-send exclusion in isPreSendTransportError. It matches the same
+// syscall.ECONNRESET the shared path used before the errno classification was
+// split out per platform, so behavior on Windows is unchanged; it lives here
+// so retry.go references no syscall constants and stays buildable on Plan 9.
+func isConnResetErrno(err error) bool {
+	return errors.Is(err, syscall.ECONNRESET)
+}

internal/providers/providerio/retry_test.go

@@ -1,15 +1,34 @@
+//go:build !plan9
+
 package providerio
 
 import (
 	"context"
 	"errors"
+	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"sync/atomic"
+	"syscall"
 	"testing"
 	"time"
 )
 
+// wrapDialErrno builds the error shape a dial failure has (a *net.OpError
+// wrapping an *os.SyscallError wrapping the errno) so errors.Is reaches the
+// errno exactly as in production. These fixtures use the POSIX syscall.Exxx
+// constants, which do NOT reproduce a real Windows dial: that carries distinct
+// windows.WSA* errnos (Go's syscall.ECONNREFUSED is a value the net package
+// never produces on Windows). They still classify on Windows only because
+// dialPreSendErrnos there also lists the POSIX constants for exactly this
+// fixture reason; the real Windows dial branch is covered separately by
+// TestIsPreSendTransportErrorRealRefusedDial, which makes an actual refused dial.
+func wrapDialErrno(op string, errno syscall.Errno) error {
+	return &net.OpError{Op: op, Net: "tcp", Err: os.NewSyscallError("connectex", errno)}
+}
+
 type roundTripperFunc func(*http.Request) (*http.Response, error)
 
 func (f roundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
@@ -35,6 +54,152 @@ func TestSendWithRetryDoesNotReplayTransportErrors(t *testing.T) {
 	}
 }
 
+// A PROVABLY pre-send transport failure (no request bytes left this host) is
+// safe to replay and must be retried, bounded by preSendMaxAttempts (its own
+// short schedule), unlike an ambiguous post-send failure. Real dial failures
+// arrive as an Op=="dial" *net.OpError, so the errno cases are the production
+// shape on every platform (Windows included); the string case exercises the
+// wording fallback for a dial error already flattened past its errno.
+func TestSendWithRetryReplaysProvablyPreSendErrors(t *testing.T) {
+	shrinkBackoff(t)
+	cases := map[string]error{
+		"errno refused (dial)":      wrapDialErrno("dial", syscall.ECONNREFUSED),
+		"errno network unreachable": wrapDialErrno("dial", syscall.ENETUNREACH),
+		"errno host unreachable":    wrapDialErrno("dial", syscall.EHOSTUNREACH),
+		"dial string fallback":      &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connect: connection refused")},
+		"tls handshake timeout":     errors.New("net/http: TLS handshake timeout"),
+		"dns timeout":               &net.DNSError{Err: "server misbehaving", Name: "nope.invalid", IsTimeout: true},
+	}
+	for name, transportErr := range cases {
+		t.Run(name, func(t *testing.T) {
+			var calls int32
+			client := &http.Client{Transport: roundTripperFunc(func(*http.Request) (*http.Response, error) {
+				atomic.AddInt32(&calls, 1)
+				return nil, transportErr
+			})}
+			// maxAttempts=6 (the default) proves the pre-send path is bounded by
+			// preSendMaxAttempts, not the caller's 429-tuned maxAttempts.
+			resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "http://example.invalid", []byte("{}"), nil, 6)
+			if resp != nil {
+				_ = resp.Body.Close()
+			}
+			if err == nil {
+				t.Fatal("expected the transport error to surface after retries are exhausted")
+			}
+			if got := atomic.LoadInt32(&calls); got != preSendMaxAttempts {
+				t.Fatalf("pre-send error tried %d times, want %d (preSendMaxAttempts)", got, preSendMaxAttempts)
+			}
+		})
+	}
+}
+
+// An ambiguous transport failure that could have followed a sent request must
+// NOT be replayed: a non-idempotent completion POST could duplicate billable
+// work. This is the safety line the fix must not cross.
+func TestSendWithRetryDoesNotReplayAmbiguousTransportErrors(t *testing.T) {
+	for name, transportErr := range map[string]error{
+		"generic i/o timeout": errors.New("dial tcp 1.2.3.4:443: i/o timeout"),
+		"broken pipe":         errors.New("write tcp: broken pipe"),
+		"unexpected eof":      io.ErrUnexpectedEOF,
+		// The pre-send errnos are also raised on an ESTABLISHED connection: a route
+		// dropping mid-generation surfaces on the pending read/write, which is
+		// post-send. Scoping to Op=="dial" must keep these from replaying the POST.
+		"host unreachable on read is post-send": wrapDialErrno("read", syscall.EHOSTUNREACH),
+		"net unreachable on write is post-send": wrapDialErrno("write", syscall.ENETUNREACH),
+		// NXDOMAIN is authoritative and deterministic, so retrying it would only
+		// stall the agent before failing anyway.
+		"dns nxdomain": &net.DNSError{Err: "no such host", Name: "nope.invalid", IsNotFound: true},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var calls int32
+			client := &http.Client{Transport: roundTripperFunc(func(*http.Request) (*http.Response, error) {
+				atomic.AddInt32(&calls, 1)
+				return nil, transportErr
+			})}
+			resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "http://example.invalid", []byte("{}"), nil, 3)
+			if resp != nil {
+				_ = resp.Body.Close()
+			}
+			if err == nil {
+				t.Fatal("expected the transport error to surface")
+			}
+			if got := atomic.LoadInt32(&calls); got != 1 {
+				t.Fatalf("ambiguous transport error replayed %d times, want 1 (no retry)", got)
+			}
+		})
+	}
+}
+
+// A REAL refused dial (nothing listening on the target) must classify as
+// pre-send on every platform. This is the regression the errno-constant fixtures
+// miss: on Windows the kernel raises WSAECONNREFUSED, which errors.Is does NOT
+// match against syscall.ECONNREFUSED, so before dialPreSendErrnos carried the WSA
+// codes a refused dial returned false here and Windows never retried it. Using a
+// real Dial exercises the platform's true error shape.
+func TestIsPreSendTransportErrorRealRefusedDial(t *testing.T) {
+	// Reserve an ephemeral port, then close it, so a dial there is refused.
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	addr := ln.Addr().String()
+	if cerr := ln.Close(); cerr != nil {
+		t.Fatalf("close listener: %v", cerr)
+	}
+	conn, dialErr := (&net.Dialer{Timeout: 2 * time.Second}).Dial("tcp", addr)
+	if dialErr == nil {
+		_ = conn.Close()
+		t.Skip("expected a refused dial but the port accepted a connection")
+	}
+	if !isPreSendTransportError(dialErr) {
+		t.Fatalf("real refused dial not classified pre-send: %v", dialErr)
+	}
+}
+
+func TestIsPreSendTransportError(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil", nil, false},
+		// DNS: a lookup that could recover is pre-send; NXDOMAIN is permanent.
+		{"dns timeout", &net.DNSError{Err: "server misbehaving", Name: "x.invalid", IsTimeout: true}, true},
+		{"dns temporary", &net.DNSError{Err: "server misbehaving", Name: "x.invalid", IsTemporary: true}, true},
+		{"dns nxdomain is permanent", &net.DNSError{Err: "no such host", Name: "x.invalid", IsNotFound: true}, false},
+		{"tls handshake timeout", errors.New("net/http: TLS handshake timeout"), true},
+		// Errno-wrapped DIAL failures: how a real refused/unreachable dial arrives
+		// on EVERY platform, including Windows where the wording differs entirely.
+		{"errno refused (dial)", wrapDialErrno("dial", syscall.ECONNREFUSED), true},
+		{"errno network unreachable (dial)", wrapDialErrno("dial", syscall.ENETUNREACH), true},
+		{"errno host unreachable (dial)", wrapDialErrno("dial", syscall.EHOSTUNREACH), true},
+		{"dial operror string fallback", &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connect: connection refused")}, true},
+		// The SAME errnos raised on a post-send read/write are NOT pre-send — the
+		// kernel reports them on an established connection when a route drops.
+		{"host unreachable on read is post-send", wrapDialErrno("read", syscall.EHOSTUNREACH), false},
+		{"net unreachable on write is post-send", wrapDialErrno("write", syscall.ENETUNREACH), false},
+		{"errno reset is post-send", wrapDialErrno("read", syscall.ECONNRESET), false},
+		// A refused/unreachable error already flattened past its *net.OpError can't
+		// be proven pre-send, so it is NOT retried (conservative direction).
+		{"flattened refused, no opError", errors.New("dial tcp 127.0.0.1:1: connect: connection refused"), false},
+		{"connection reset", errors.New("read tcp: connection reset by peer"), false},
+		{"broken pipe", errors.New("write tcp: broken pipe"), false},
+		{"unexpected eof", io.ErrUnexpectedEOF, false},
+		{"eof", io.EOF, false},
+		{"generic io timeout", errors.New("dial tcp: i/o timeout"), false},
+		{"context deadline", context.DeadlineExceeded, false},
+		// Exclusion is checked before inclusion, even for a dial OpError: an "i/o
+		// timeout" in the message wins over the refused wording.
+		{"exclusion wins over inclusion", &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connection refused / i/o timeout")}, false},
+		{"unrelated", errors.New("some other error"), false},
+	}
+	for _, c := range cases {
+		if got := isPreSendTransportError(c.err); got != c.want {
+			t.Errorf("%s: isPreSendTransportError(%v) = %v, want %v", c.name, c.err, got, c.want)
+		}
+	}
+}
+
 func TestShouldRetryStatus(t *testing.T) {
 	cases := map[int]bool{
 		http.StatusOK:                  false,
@@ -94,12 +259,17 @@ func TestBackoffWaitsThenReturnsTrue(t *testing.T) {
 	}
 }
 
-// shrinkBackoff makes retry waits negligible for the duration of a test.
+// shrinkBackoff makes both retry schedules (429 and pre-send) negligible for the
+// duration of a test.
 func shrinkBackoff(t *testing.T) {
 	t.Helper()
-	saved := retryBackoffBase
+	savedRetry, savedPreSend := retryBackoffBase, preSendBackoffBase
 	retryBackoffBase = time.Millisecond
-	t.Cleanup(func() { retryBackoffBase = saved })
+	preSendBackoffBase = time.Millisecond
+	t.Cleanup(func() {
+		retryBackoffBase = savedRetry
+		preSendBackoffBase = savedPreSend
+	})
 }
 
 func TestBackoffWaitSchedule(t *testing.T) {
@@ -126,6 +296,30 @@ func TestBackoffWaitSchedule(t *testing.T) {
 	}
 }
 
+// The pre-send schedule is sub-second and doubles, far shorter than the 429
+// schedule: a permanent dial failure fails in ~1.5s across preSendMaxAttempts
+// (500ms + 1s) instead of stalling the agent ~60s on 2/4/8/16/30s. This is the
+// second half of the fix for a mistyped host / dead local daemon hanging a turn.
+func TestPreSendBackoffWaitSchedule(t *testing.T) {
+	cases := []struct {
+		attempt int
+		want    time.Duration
+	}{
+		{1, 500 * time.Millisecond},
+		{2, 1 * time.Second},
+		{3, 2 * time.Second},
+		// The exponent clamps at 5 (500ms<<5 = 16s) so a large attempt count can't
+		// overflow; in practice preSendMaxAttempts caps retries at attempt 2, so
+		// only the 500ms/1s rungs are ever reached.
+		{50, 16 * time.Second},
+	}
+	for _, c := range cases {
+		if got := preSendBackoffWait(c.attempt); got != c.want {
+			t.Errorf("preSendBackoffWait(%d) = %v, want %v", c.attempt, got, c.want)
+		}
+	}
+}
+
 func TestSendWithRetryRetriesThenSucceeds(t *testing.T) {
 	shrinkBackoff(t)
 	var hits int32
@@ -193,3 +387,316 @@ func TestSendWithRetryReturnsLastResponseAfterMaxAttempts(t *testing.T) {
 		t.Fatalf("server hit %d times, want 2 (maxAttempts)", got)
 	}
 }
+
+// Redirects are still followed, so a gateway that answers the completion endpoint
+// with a 307/308 keeps working: the caller gets the final response, not the 3xx.
+func TestSendWithRetryFollowsRedirects(t *testing.T) {
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) == 1 {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("a redirected completion must succeed: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (the redirect should have been followed)", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("transport called %d times, want 2 (origin then redirect target)", got)
+	}
+}
+
+// Once an attempt has entered a redirect, the original POST has already left this
+// host, so a dial failure on the redirect hop must NOT be replayed even though it
+// arrives as an Op=="dial" error that isPreSendTransportError would otherwise
+// treat as provably pre-send. Replaying it would re-bill a completion the first
+// host may already have processed.
+func TestSendWithRetryDoesNotReplayAfterRedirect(t *testing.T) {
+	shrinkBackoff(t)
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) == 1 {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}
+		// The dial to the redirect target fails: pre-send in shape, but post-send
+		// in fact, because the origin already received the POST.
+		return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 6)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+	if err == nil {
+		t.Fatal("expected the redirect-hop dial failure to surface as an error")
+	}
+	// Exactly two: the origin request and the single redirect hop. A third would
+	// mean the redirected POST was replayed.
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("redirected POST was replayed: transport called %d times, want 2", got)
+	}
+}
+
+// A caller that supplies its own CheckRedirect keeps it: the retry path observes
+// redirects, it does not take the decision away from the caller.
+func TestSendWithRetryPreservesCallerRedirectPolicy(t *testing.T) {
+	var policyCalls int32
+	client := &http.Client{
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			atomic.AddInt32(&policyCalls, 1)
+			return http.ErrUseLastResponse
+		},
+		Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}),
+	}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("caller policy asked to stop at the 3xx, so it must surface: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusTemporaryRedirect {
+		t.Fatalf("status = %d, want the 307 surfaced per the caller's policy", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&policyCalls); got != 1 {
+		t.Fatalf("caller CheckRedirect called %d times, want 1 (it must not be discarded)", got)
+	}
+}
+
+// The pre-send retry budget is independent of the 429/503 status retries: two
+// rate-limit responses must not consume the pre-send allowance, so the first
+// refused dial after them still gets its own preSendMaxAttempts tries.
+func TestSendWithRetryPreSendBudgetSurvivesStatusRetries(t *testing.T) {
+	shrinkBackoff(t)
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) <= 2 {
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		}
+		return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://x.invalid/v1", []byte("{}"), nil, 6)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+	if err == nil {
+		t.Fatal("expected the exhausted pre-send failure to surface as an error")
+	}
+	// Two status responses (calls 1-2), then the pre-send failure gets its own
+	// budget: preSendMaxAttempts=3 means it retries twice more before returning.
+	if got := atomic.LoadInt32(&calls); got != 2+preSendMaxAttempts {
+		t.Fatalf("pre-send budget eaten by status retries: transport called %d times, want %d (2 status + %d pre-send)", got, 2+preSendMaxAttempts, preSendMaxAttempts)
+	}
+}
+
+// The inverse sequence: pre-send retries must not consume the 429/503 budget or
+// advance its backoff rung either. Two safely replayed refused dials followed by
+// rate limiting must still leave the status path its full maxAttempts window,
+// otherwise a couple of dial blips silently shorten every later rate-limit wait.
+func TestSendWithRetryStatusBudgetSurvivesPreSendRetries(t *testing.T) {
+	shrinkBackoff(t)
+	const maxAttempts = 3
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) <= 2 {
+			return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+		}
+		return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://x.invalid/v1", []byte("{}"), nil, maxAttempts)
+	if err != nil {
+		t.Fatalf("exhausted status retries surface the response, not an error: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("status = %d, want 429", resp.StatusCode)
+	}
+	// Calls 1-2 are the retried dial failures; the status path then gets its own
+	// full window (maxAttempts requests) before the 429 is surfaced.
+	if got := atomic.LoadInt32(&calls); got != 2+maxAttempts {
+		t.Fatalf("status budget eaten by pre-send retries: transport called %d times, want %d (2 pre-send + %d status)", got, 2+maxAttempts, maxAttempts)
+	}
+}
+
+// A redirect followed by a RETRYABLE STATUS is still retried, and deliberately
+// so. This is the case a reviewer flagged as a possible replay of billable work,
+// and the asymmetry with the transport-error guard above is intentional rather
+// than an oversight, so it is pinned here.
+//
+// The two situations differ in what is known about the request:
+//
+//   - Transport error after a redirect: the original POST reached the origin and
+//     the dial to the redirect target then failed, so whether the target received
+//     and began processing it is UNKNOWN. Replaying could duplicate work, which
+//     is why that path refuses to retry.
+//   - Retryable status after a redirect: every hop answered. A 307/308 is the
+//     origin declining to process and delegating, and a 429/503/529 is the target
+//     declining as well. Nothing accepted the request, so replaying duplicates
+//     nothing.
+//
+// The risk here is also exactly the risk of a 429 without any redirect, which
+// this package has always retried; the redirect adds no new ambiguity. Refusing
+// to retry would instead make a rate-limited completion behind a redirecting
+// gateway fail outright rather than back off.
+func TestSendWithRetryRetriesRedirectedRetryableStatus(t *testing.T) {
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		switch atomic.AddInt32(&calls, 1) {
+		case 1, 3:
+			// The origin declines and delegates, both times.
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		case 2:
+			// The target declines too: rate limited, so nothing was accepted.
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		default:
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+		}
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("a rate-limited completion behind a redirect must still retry: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 after the retry succeeded", resp.StatusCode)
+	}
+	// origin, target(429), origin, target(200).
+	if got := atomic.LoadInt32(&calls); got != 4 {
+		t.Fatalf("transport called %d times, want 4 (redirect, 429, redirect, 200)", got)
+	}
+}
+
+// A CONNECT-phase timeout is provably pre-send: the connection was never
+// established, so no request bytes left this host. It reaches the classifier
+// carrying "i/o timeout", which the blanket wording exclusion rejects, so
+// admitting it depends on the connect gate running first.
+//
+// The post-send counterpart is the point of the table: a read timeout is also
+// Timeout(), and must stay excluded, or a reply that timed out mid-generation
+// would replay a completion the server already billed.
+func TestPreSendClassifiesConnectTimeouts(t *testing.T) {
+	timeoutErr := &timeoutError{}
+	for name, testCase := range map[string]struct {
+		err  error
+		want bool
+	}{
+		"dial timeout": {
+			err:  &net.OpError{Op: "dial", Net: "tcp", Err: timeoutErr},
+			want: true,
+		},
+		"proxy connect timeout": {
+			err:  &net.OpError{Op: "proxyconnect", Net: "tcp", Err: timeoutErr},
+			want: true,
+		},
+		"read timeout stays post-send": {
+			err:  &net.OpError{Op: "read", Net: "tcp", Err: timeoutErr},
+			want: false,
+		},
+		"write timeout stays post-send": {
+			err:  &net.OpError{Op: "write", Net: "tcp", Err: timeoutErr},
+			want: false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if got := isPreSendTransportError(testCase.err); got != testCase.want {
+				t.Fatalf("isPreSendTransportError(%v) = %v, want %v", testCase.err, got, testCase.want)
+			}
+		})
+	}
+}
+
+// A failed CONNECT through an HTTP proxy is pre-send for the same structural
+// reason a refused dial is, but net tags it Op "proxyconnect", so a gate
+// matching only "dial" left every pre-send failure behind a corporate proxy
+// unretried.
+func TestPreSendClassifiesProxyConnectRefusal(t *testing.T) {
+	err := &net.OpError{Op: "proxyconnect", Net: "tcp", Err: syscall.ECONNREFUSED}
+	if !isPreSendTransportError(err) {
+		t.Fatal("a refused proxy CONNECT was not classified pre-send; no request bytes reached the model host")
+	}
+	// The op still has to be a connect phase. The same errno on an established
+	// connection is post-send and must not replay a POST.
+	post := &net.OpError{Op: "read", Net: "tcp", Err: syscall.ECONNREFUSED}
+	if isPreSendTransportError(post) {
+		t.Fatal("a read-phase error was classified pre-send")
+	}
+}
+
+// timeoutError is a net.Error whose Timeout() is true, matching the shape
+// net/http surfaces for a connect deadline.
+type timeoutError struct{}
+
+func (timeoutError) Error() string   { return "i/o timeout" }
+func (timeoutError) Timeout() bool   { return true }
+func (timeoutError) Temporary() bool { return true }
+
+// The pre-send budget bounds CONSECUTIVE connect failures, not the lifetime of
+// the call. Without a reset on a successful hop, an early run of dial blips
+// permanently spends the budget, so a later blip surfaces as a transport error
+// while the status budget still has room. That is the coupling the two counters
+// were split apart to remove, in the one ordering the earlier tests did not
+// cover: pre-send, then status, then pre-send again.
+func TestPreSendBudgetResetsAfterSuccessfulHop(t *testing.T) {
+	refused := &net.OpError{Op: "dial", Net: "tcp", Err: syscall.ECONNREFUSED}
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		switch atomic.AddInt32(&calls, 1) {
+		case 1, 2:
+			// Two connect failures, spending the pre-send budget under the old
+			// lifetime accounting.
+			return nil, refused
+		case 3:
+			// A hop that reaches the server. It declines, so the request was not
+			// accepted and retrying stays safe.
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		case 4:
+			// One more connect blip. With a lifetime cap this surfaces as an
+			// error; the call should still recover.
+			return nil, refused
+		default:
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+		}
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("interleaved connect and status failures returned %v; the pre-send budget did not reset after the hop that reached the server", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&calls); got != 5 {
+		t.Fatalf("transport called %d times, want 5 (dial, dial, 429, dial, 200)", got)
+	}
+}

internal/sandbox/analyzer.go

@@ -27,11 +27,22 @@ var destructivePrograms = map[string]bool{
 	"mkfs": true, "fdisk": true, "shred": true, "dd": true, "parted": true,
 }
 
+var powerShellRemoveItemPrograms = map[string]bool{
+	"remove-item": true,
+	"ri":          true,
+	"rd":          true,
+	"rmdir":       true,
+	"del":         true,
+	"erase":       true,
+	"rm":          true,
+}
+
 // networkPrograms are commands that perform network egress/ingress.
 var networkPrograms = map[string]bool{
 	"curl": true, "wget": true, "ssh": true, "scp": true, "sftp": true,
 	"rsync": true, "nc": true, "ncat": true, "netcat": true, "telnet": true,
-	"ftp": true,
+	"ftp": true, "iwr": true, "irm": true, "invoke-webrequest": true,
+	"invoke-restmethod": true,
 }
 
 var localServerPrograms = map[string]bool{
@@ -172,7 +183,10 @@ func analyzeInto(script string, result *AnalysisResult, seen map[string]bool, de
 		if commandUsesNetwork(prog, rest) {
 			result.Network = true
 		}
-		if destructivePrograms[prog] || (prog == "rm" && hasRecursiveForce(rest)) || (prog == "find" && hasFindDelete(rest)) {
+		if destructivePrograms[prog] ||
+			(prog == "rm" && hasRecursiveForce(rest)) ||
+			(powerShellRemoveItemPrograms[prog] && hasPowerShellRecursiveForce(rest)) ||
+			(prog == "find" && hasFindDelete(rest)) {
 			result.Destructive = true
 		}
 		return true
@@ -479,6 +493,19 @@ func hasRecursiveForce(args []*syntax.Word) bool {
 	return recursive && force
 }
 
+func hasPowerShellRecursiveForce(args []*syntax.Word) bool {
+	recursive, force := false, false
+	for _, arg := range args {
+		switch strings.ToLower(wordText(arg)) {
+		case "-recurse", "-r":
+			recursive = true
+		case "-force":
+			force = true
+		}
+	}
+	return recursive && force
+}
+
 func hasFindDelete(args []*syntax.Word) bool {
 	for _, arg := range args {
 		if wordText(arg) == "-delete" {

internal/sandbox/analyzer_test.go

@@ -45,6 +45,27 @@ func TestAnalyzeCommand(t *testing.T) {
 		{name: "sudo dynamic flag then rm -rf", script: `sudo "$maybe" rm -rf /tmp/x`, destructive: true},
 
 		{name: "curl", script: "curl https://example.com", network: true},
+		{name: "PowerShell iwr alias", script: "iwr https://example.com", network: true},
+		{name: "PowerShell irm alias", script: "irm https://example.com", network: true},
+		{name: "PowerShell Invoke-WebRequest", script: "Invoke-WebRequest https://example.com", network: true},
+		{name: "PowerShell Invoke-RestMethod", script: "Invoke-RestMethod https://example.com", network: true},
+		{name: "PowerShell Remove-Item recursive force", script: `Remove-Item -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell rm recursive force", script: `rm -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell ri recursive force", script: `ri -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell rd recursive force", script: `rd -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell rmdir recursive force", script: `rmdir -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell del recursive force", script: `del -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell erase recursive force", script: `erase -Recurse -Force 'C:\temp\x'`, destructive: true},
+		{name: "PowerShell ambiguous force abbreviation", script: `Remove-Item -Recurse -f 'C:\temp\x'`, destructive: false},
+		{name: "PowerShell Remove-Item without recurse", script: `Remove-Item -Force 'C:\temp\x'`, destructive: false},
+		{name: "Windows curl cmd", script: "curl.cmd https://example.com", network: true},
+		{name: "Windows curl exe", script: "curl.exe https://example.com", network: true},
+		{name: "Windows drive path curl exe", script: `'C:\tools\curl.exe' https://example.com`, network: true},
+		{name: "Windows UNC path curl exe", script: `'\\server\share\curl.exe' https://example.com`, network: true},
+		{name: "Windows dot relative path curl exe", script: `'.\curl.exe' https://example.com`, network: true},
+		{name: "Windows relative path curl exe", script: `'tools\curl.exe' https://example.com`, network: true},
+		{name: "Windows drive relative path curl exe", script: `'C:curl.exe' https://example.com`, network: true},
+		{name: "Windows npm cmd", script: "npm.cmd install", network: true},
 		{name: "wget piped to shell", script: "wget -qO- https://x.test | sh", network: true},
 		{name: "python http server", script: "python3 -m http.server 8000", network: true},
 		{name: "python pip install", script: "python3 -m pip install requests", network: true},

internal/sandbox/engine_test.go

@@ -74,6 +74,25 @@ func TestEngineBashAllowGrantDoesNotBypassNetworkPrompt(t *testing.T) {
 	}
 }
 
+func TestEngineClassifiesPowerShellCurlCommandAsNetwork(t *testing.T) {
+	engine := NewEngine(EngineOptions{
+		WorkspaceRoot: t.TempDir(),
+		Policy:        DefaultPolicy(),
+	})
+	decision := engine.Evaluate(context.Background(), Request{
+		ToolName:       "bash",
+		SideEffect:     SideEffectShell,
+		Permission:     PermissionPrompt,
+		PermissionMode: PermissionModeAsk,
+		Args: map[string]any{
+			"command": `$env:PATH = '.;' + $env:PATH; curl.cmd https://example.com`,
+		},
+	})
+	if decision.Action != ActionPrompt || decision.Reason != ReasonNetworkBlocked || !HasRiskCategory(decision.Risk, "network") {
+		t.Fatalf("PowerShell curl command decision = %#v, want network prompt", decision)
+	}
+}
+
 func TestUnsandboxedExecutionAllowedPreservesDeniedReads(t *testing.T) {
 	root := t.TempDir()
 	policy := DefaultPolicy()

internal/sandbox/manager_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"reflect"
 	"runtime"
+	"strings"
 	"testing"
 )
 
@@ -378,7 +379,31 @@ func TestCredentialDenyReadPathsIn(t *testing.T) {
 	home := t.TempDir()
 	awsDir := filepath.Join(home, ".aws")
 	gcloudDir := filepath.Join(home, ".config", "gcloud")
-	if err := mkdirAll(awsDir, gcloudDir); err != nil {
+	npmrc := filepath.Join(home, ".npmrc")
+	ghHosts := filepath.Join(home, ".config", "gh", "hosts.yml")
+	netrc := filepath.Join(home, ".netrc")
+	dockerConfig := filepath.Join(home, ".docker", "config.json")
+	kubeConfig := filepath.Join(home, ".kube", "config")
+	zeroConfig := filepath.Join(home, ".config", "zero")
+	if err := mkdirAll(
+		awsDir,
+		gcloudDir,
+		filepath.Dir(ghHosts),
+		filepath.Dir(dockerConfig),
+		filepath.Dir(kubeConfig),
+		filepath.Dir(zeroConfig),
+	); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{npmrc, ghHosts, netrc, dockerConfig, kubeConfig, zeroConfig} {
+		if path == zeroConfig {
+			continue
+		}
+		if err := os.WriteFile(path, []byte("{}"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.MkdirAll(zeroConfig, 0o755); err != nil {
 		t.Fatal(err)
 	}
 	keyFile := filepath.Join(home, "sa-key.json")
@@ -387,7 +412,17 @@ func TestCredentialDenyReadPathsIn(t *testing.T) {
 	}
 
 	paths := credentialDenyReadPathsIn(home, keyFile, nil)
-	for _, want := range normalizeProfilePaths([]string{awsDir, gcloudDir, keyFile}) {
+	for _, want := range normalizeProfilePaths([]string{
+		awsDir,
+		gcloudDir,
+		keyFile,
+		npmrc,
+		ghHosts,
+		netrc,
+		dockerConfig,
+		kubeConfig,
+		zeroConfig,
+	}) {
 		if !stringSliceContains(paths, want) {
 			t.Errorf("credential deny paths = %#v, want %q included", paths, want)
 		}
@@ -418,3 +453,58 @@ func TestCredentialDenyReadPathsIn(t *testing.T) {
 		t.Errorf("credential deny paths without home = %#v, want key file included", homeless)
 	}
 }
+
+func TestCredentialDenyReadPathsForEnvironmentHonorsConfigOverrides(t *testing.T) {
+	root := t.TempDir()
+	configHome := filepath.Join(root, "xdg")
+	npmrc := filepath.Join(root, "npm", "userconfig")
+	ghConfigDir := filepath.Join(root, "gh")
+	cloudSDKConfig := filepath.Join(root, "gcloud")
+	netrc := filepath.Join(root, "netrc")
+	dockerConfigDir := filepath.Join(root, "docker")
+	kubeConfigA := filepath.Join(root, "kube", "a")
+	kubeConfigB := filepath.Join(root, "kube", "b")
+	zeroConfig := filepath.Join(configHome, "zero")
+	filePaths := []string{
+		npmrc,
+		filepath.Join(ghConfigDir, "hosts.yml"),
+		netrc,
+		filepath.Join(dockerConfigDir, "config.json"),
+		kubeConfigA,
+		kubeConfigB,
+		zeroConfig,
+	}
+	if err := os.MkdirAll(cloudSDKConfig, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range filePaths {
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if path == zeroConfig {
+			if err := os.MkdirAll(path, 0o755); err != nil {
+				t.Fatal(err)
+			}
+			continue
+		}
+		if err := os.WriteFile(path, []byte("{}"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	got := credentialDenyReadPathsForEnvironment(credentialPathEnvironment{
+		ConfigHome:      configHome,
+		CloudSDKConfig:  cloudSDKConfig,
+		NPMUserConfig:   npmrc,
+		GHConfigDir:     ghConfigDir,
+		Netrc:           netrc,
+		DockerConfigDir: dockerConfigDir,
+		KubeConfig:      strings.Join([]string{kubeConfigA, kubeConfigB}, string(filepath.ListSeparator)),
+	}, nil)
+	wantPaths := append(filePaths, cloudSDKConfig)
+	for _, want := range normalizeProfilePaths(wantPaths) {
+		if !stringSliceContains(got, want) {
+			t.Errorf("credential deny paths = %#v, want override %q included", got, want)
+		}
+	}
+}

internal/sandbox/profile.go

@@ -145,9 +145,10 @@ func permissionProfileReadRoots(workspaceRoot string, policy Policy, scope *Scop
 }
 
 // credentialDenyReadPaths returns default deny-read entries for well-known
-// credential stores (~/.aws, ~/.config/gcloud, ~/.azure, and the file
-// GOOGLE_APPLICATION_CREDENTIALS points to) so sandboxed commands cannot read
-// cloud secrets under the read-all workspace posture. Two deliberate limits:
+// credential stores so sandboxed commands cannot read secrets under the
+// read-all workspace posture. This includes tool configuration files that can
+// carry credentials and are now discoverable through the preserved caller
+// environment. Two deliberate limits:
 //
 //   - Windows is skipped: a non-empty profile DenyRead switches the Windows
 //     runner onto the capability-SID/ACL deny path and away from the
@@ -166,23 +167,114 @@ func credentialDenyReadPaths(policy Policy) []string {
 	// A failed home lookup only drops the home-based candidates; the
 	// GOOGLE_APPLICATION_CREDENTIALS target must be protected regardless.
 	home, _ := os.UserHomeDir()
-	return credentialDenyReadPathsIn(home, os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"), policy.AllowRead)
+	return credentialDenyReadPathsForEnvironment(credentialPathEnvironment{
+		Home:              home,
+		ConfigHome:        os.Getenv("XDG_CONFIG_HOME"),
+		CloudSDKConfig:    os.Getenv("CLOUDSDK_CONFIG"),
+		GoogleCredentials: os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"),
+		NPMUserConfig:     firstNonEmpty(os.Getenv("NPM_CONFIG_USERCONFIG"), os.Getenv("npm_config_userconfig")),
+		GHConfigDir:       os.Getenv("GH_CONFIG_DIR"),
+		Netrc:             os.Getenv("NETRC"),
+		DockerConfigDir:   os.Getenv("DOCKER_CONFIG"),
+		KubeConfig:        os.Getenv("KUBECONFIG"),
+	}, policy.AllowRead)
 }
 
 // credentialDenyReadPathsIn is the pure core of credentialDenyReadPaths,
 // separated so tests can exercise it against a synthetic home directory.
 func credentialDenyReadPathsIn(home string, googleCredentials string, allowRead []string) []string {
+	return credentialDenyReadPathsForEnvironment(credentialPathEnvironment{
+		Home:              home,
+		GoogleCredentials: googleCredentials,
+	}, allowRead)
+}
+
+type credentialPathEnvironment struct {
+	Home              string
+	ConfigHome        string
+	CloudSDKConfig    string
+	GoogleCredentials string
+	NPMUserConfig     string
+	GHConfigDir       string
+	Netrc             string
+	DockerConfigDir   string
+	KubeConfig        string
+}
+
+func credentialDenyReadPathsForEnvironment(env credentialPathEnvironment, allowRead []string) []string {
 	var candidates []string
-	if home = strings.TrimSpace(home); home != "" {
+	home := strings.TrimSpace(env.Home)
+	configHome := strings.TrimSpace(env.ConfigHome)
+	if configHome == "" && home != "" {
+		configHome = filepath.Join(home, ".config")
+	}
+	if home != "" {
 		candidates = append(candidates,
 			filepath.Join(home, ".aws"),
-			filepath.Join(home, ".config", "gcloud"),
 			filepath.Join(home, ".azure"),
+			// git's credential store backend, which holds host passwords and
+			// personal access tokens in cleartext. Denied rather than the whole
+			// of ~/.ssh, because these cost nothing functionally: git reads them
+			// through a credential helper for authentication, not for identity,
+			// so a sandboxed git still works and simply cannot authenticate as
+			// the user. SSH key material is a harder trade and is tracked
+			// separately (#815).
+			filepath.Join(home, ".git-credentials"),
 		)
 	}
-	if target := strings.TrimSpace(googleCredentials); target != "" {
+	npmUserConfig := strings.TrimSpace(env.NPMUserConfig)
+	if npmUserConfig == "" && home != "" {
+		npmUserConfig = filepath.Join(home, ".npmrc")
+	}
+	netrc := strings.TrimSpace(env.Netrc)
+	if netrc == "" && home != "" {
+		netrc = filepath.Join(home, ".netrc")
+	}
+	dockerConfigDir := strings.TrimSpace(env.DockerConfigDir)
+	if dockerConfigDir == "" && home != "" {
+		dockerConfigDir = filepath.Join(home, ".docker")
+	}
+	candidates = append(candidates, npmUserConfig, netrc)
+	if dockerConfigDir != "" {
+		candidates = append(candidates, filepath.Join(dockerConfigDir, "config.json"))
+	}
+	if configHome != "" {
+		candidates = append(candidates,
+			filepath.Join(configHome, "zero"),
+			// The XDG location of the same git credential store. Denying the file
+			// rather than the directory is deliberate: ~/.config/git also holds
+			// the global git config, which userGitConfigReadPaths grants on
+			// purpose so a sandboxed git can read user.name and aliases instead
+			// of failing outright.
+			filepath.Join(configHome, "git", "credentials"),
+		)
+	}
+	cloudSDKConfig := strings.TrimSpace(env.CloudSDKConfig)
+	if cloudSDKConfig == "" && configHome != "" {
+		cloudSDKConfig = filepath.Join(configHome, "gcloud")
+	}
+	if cloudSDKConfig != "" {
+		candidates = append(candidates, cloudSDKConfig)
+	}
+	ghConfigDir := strings.TrimSpace(env.GHConfigDir)
+	if ghConfigDir == "" && configHome != "" {
+		ghConfigDir = filepath.Join(configHome, "gh")
+	}
+	if ghConfigDir != "" {
+		candidates = append(candidates, filepath.Join(ghConfigDir, "hosts.yml"))
+	}
+	if target := strings.TrimSpace(env.GoogleCredentials); target != "" {
 		candidates = append(candidates, target)
 	}
+	kubeConfig := strings.TrimSpace(env.KubeConfig)
+	if kubeConfig == "" && home != "" {
+		kubeConfig = filepath.Join(home, ".kube", "config")
+	}
+	for _, path := range filepath.SplitList(kubeConfig) {
+		if path = strings.TrimSpace(path); path != "" {
+			candidates = append(candidates, path)
+		}
+	}
 	allowRoots := normalizeProfilePaths(allowRead)
 	out := make([]string, 0, len(candidates))
 	for _, path := range normalizeProfilePaths(candidates) {
@@ -206,11 +298,12 @@ func credentialDenyReadPathsIn(home string, googleCredentials string, allowRead
 
 // userGitConfigReadPaths returns the user's global git config FILES so a
 // sandboxed git can read identity and config (user.name/email, aliases) instead
-// of failing with "unable to access ~/.gitconfig". It is deliberately the config
-// files only — not the ~/.config/git directory, which can hold an XDG credential
-// store — so credentials and the rest of HOME stay unreadable. Granted at the
-// macOS-seatbelt read rule (not the cross-platform PermissionProfile) so the
-// HOME-dependent paths don't leak into the platform-agnostic policy snapshot.
+// of failing with "unable to access ~/.gitconfig". On macOS, where reads are
+// allow-listed, granting only these files avoids exposing the surrounding
+// configuration directory. Linux uses a read-all profile with explicit
+// credential deny rules. The paths are granted at the macOS seatbelt read rule
+// rather than the cross-platform PermissionProfile so HOME-dependent paths
+// don't leak into the platform-agnostic policy snapshot.
 func userGitConfigReadPaths() []string {
 	home, err := os.UserHomeDir()
 	if err != nil || strings.TrimSpace(home) == "" {

internal/sandbox/profile_test.go

@@ -0,0 +1,93 @@
+package sandbox
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// git's credential store holds host passwords and personal access tokens in
+// cleartext, in one of two locations depending on whether the user is on the
+// XDG layout. Neither was denied, so a sandboxed command could read them
+// (#815).
+//
+// Scoped to the credential files on purpose. Denying ~/.ssh as well would stop
+// a sandboxed git push over SSH from working, which is a functional trade that
+// issue tracks separately; these two cost nothing, because git reads them for
+// authentication rather than identity.
+func TestCredentialDenyReadPathsCoversGitCredentialStores(t *testing.T) {
+	home := t.TempDir()
+	configHome := filepath.Join(home, ".config")
+	if err := os.MkdirAll(filepath.Join(configHome, "git"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	// The builder only emits paths that exist, so these have to be real.
+	gitCredentials := filepath.Join(home, ".git-credentials")
+	xdgCredentials := filepath.Join(configHome, "git", "credentials")
+	gitConfig := filepath.Join(configHome, "git", "config")
+	for _, path := range []string{gitCredentials, xdgCredentials, gitConfig} {
+		if err := os.WriteFile(path, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	denied := credentialDenyReadPathsForEnvironment(credentialPathEnvironment{
+		Home:       home,
+		ConfigHome: configHome,
+	}, nil)
+	covered := func(target string) bool {
+		norm := normalizeProfilePath(target)
+		for _, entry := range denied {
+			if entry == norm || pathWithinRoot(entry, norm) {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !covered(gitCredentials) {
+		t.Fatalf("~/.git-credentials is readable; deny list = %v", denied)
+	}
+	if !covered(xdgCredentials) {
+		t.Fatalf("~/.config/git/credentials is readable; deny list = %v", denied)
+	}
+	// The global git config must stay readable. userGitConfigReadPaths grants it
+	// deliberately so a sandboxed git can read user.name and aliases rather than
+	// failing with "unable to access", so denying the directory instead of the
+	// credential file would break that on purpose-built setups.
+	if covered(gitConfig) {
+		t.Fatalf("~/.config/git/config was denied; a sandboxed git loses its identity config")
+	}
+}
+
+// An explicit read grant still wins, matching how every other entry behaves: a
+// user who deliberately scopes a workspace over one of these paths is not
+// overridden by the default deny.
+//
+// Asserted from both sides on purpose. Checking only that the path is absent
+// under an allowRead is satisfied just as well by a deny rule that was never
+// added, so the run without allowRead has to establish that there is something
+// there for the grant to override.
+func TestGitCredentialDenyYieldsToExplicitAllowRead(t *testing.T) {
+	home := t.TempDir()
+	gitCredentials := filepath.Join(home, ".git-credentials")
+	if err := os.WriteFile(gitCredentials, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	target := normalizeProfilePath(gitCredentials)
+	listed := func(entries []string) bool {
+		for _, entry := range entries {
+			if entry == target {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !listed(credentialDenyReadPathsForEnvironment(credentialPathEnvironment{Home: home}, nil)) {
+		t.Fatalf("~/.git-credentials is not denied without an allowRead; nothing for the grant to override")
+	}
+	if listed(credentialDenyReadPathsForEnvironment(credentialPathEnvironment{Home: home}, []string{home})) {
+		t.Fatalf("explicit allowRead %q did not re-include the credential store", home)
+	}
+}

internal/sandbox/runner.go

@@ -1027,6 +1027,13 @@ func scrubSensitiveEnv(env []string, additionalKeys ...string) []string {
 		"GH_TOKEN",
 		"ZERO_WEBSEARCH_API_KEY",
 		"ZERO_DAEMON_REMOTE_TOKEN",
+		// The file form of the same bridge token. TokenFromEnv accepts either,
+		// so scrubbing only the inline variable left the pointer readable, and
+		// the default sandbox posture is read-all. There is no fallback
+		// location to guess at, the path comes from this variable alone, so
+		// removing it closes the leak rather than half of it. Same reasoning as
+		// GOOGLE_APPLICATION_CREDENTIALS below.
+		"ZERO_DAEMON_REMOTE_TOKEN_FILE",
 	}
 	for _, descriptor := range providercatalog.All() {
 		for _, key := range descriptor.AuthEnvVars {

internal/sandbox/runner_test.go

@@ -699,6 +699,11 @@ func TestScrubSensitiveEnv(t *testing.T) {
 		"XAI_API_KEY=xai-12345",
 		"HUGGINGFACE_API_KEY=hf_12345",
 		"GOOGLE_APPLICATION_CREDENTIALS=/home/user/sa-key.json",
+		// Both forms of the daemon bridge token. The inline one was already
+		// scrubbed; the file form was not, which left a sandboxed command the
+		// path to read it from (#677).
+		"ZERO_DAEMON_REMOTE_TOKEN=bridge-token-inline",
+		"ZERO_DAEMON_REMOTE_TOKEN_FILE=/home/user/.zero/remote-token",
 		"COMPANY_LLM_SECRET=custom-secret",
 		"ZERO_OAUTH_MY_SVC_CLIENT_SECRET=oauth-secret",
 		"zero_oauth_second_client_secret=case-insensitive-secret",

internal/sandbox/runner_windows_integration_test.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -266,6 +267,74 @@ func TestWindowsRestrictedTokenNestedPipeCapture(t *testing.T) {
 	}
 }
 
+// TestWindowsRestrictedTokenPowerShell exercises the default Windows shell
+// shape end to end under the write-restricted token. It covers PowerShell
+// initialization, a native pipeline (which creates IPC objects), UTF-8 output,
+// and workspace write enforcement.
+func TestWindowsRestrictedTokenPowerShell(t *testing.T) {
+	if os.Getenv("ZERO_SANDBOX_REAL_SMOKE") != "1" {
+		t.Skip("set ZERO_SANDBOX_REAL_SMOKE=1 to run real Windows sandbox smoke tests")
+	}
+	runnerExe := realSmokeExecutable(t, "ZERO_WINDOWS_COMMAND_RUNNER_EXE", WindowsSandboxCommandRunnerName)
+	powerShell := realSmokePowerShell(t)
+
+	root := t.TempDir()
+	outside := t.TempDir()
+	sandboxHome := filepath.Join(root, ".zero-sandbox")
+	profile := PermissionProfile{
+		FileSystem: FileSystemPolicy{
+			Kind:                 FileSystemRestricted,
+			ReadRoots:            []string{root},
+			WriteRoots:           []WritableRoot{{Root: root}},
+			IncludePlatformRoots: true,
+			AllowTemp:            true,
+		},
+		Network: NetworkPolicy{Mode: NetworkDeny},
+	}
+	config := WindowsSandboxCommandArgsOptions{
+		SandboxHome:       sandboxHome,
+		CommandCWD:        root,
+		WorkspaceRoots:    []string{root},
+		PermissionProfile: profile,
+		SandboxLevel:      WindowsSandboxLevelUnelevated,
+	}
+
+	insideMarker := filepath.Join(root, "powershell-ok.txt")
+	script := "$ErrorActionPreference='Stop'; " +
+		"[Console]::OutputEncoding=[System.Text.Encoding]::UTF8; " +
+		"$values = 1,2,3 | ForEach-Object { $_ * 2 }; " +
+		"[IO.File]::WriteAllText(" + powershellSingleQuote(insideMarker) + ", (($values -join ',') + ' ✓'))"
+	runWindowsRealSmokeCommand(t, runnerExe, config, []string{
+		powerShell, "-NoLogo", "-NoProfile", "-Command", script,
+	}, 0)
+	if bytes, err := os.ReadFile(insideMarker); err != nil || strings.TrimSpace(string(bytes)) != "2,4,6 ✓" {
+		t.Fatalf("PowerShell sandbox marker = %q, %v; want pipeline output", bytes, err)
+	}
+
+	outsideMarker := filepath.Join(outside, "powershell-denied.txt")
+	deniedScript := "$ErrorActionPreference='Stop'; " +
+		"[IO.File]::WriteAllText(" + powershellSingleQuote(outsideMarker) + ", 'leaked')"
+	runWindowsRealSmokeCommand(t, runnerExe, config, []string{
+		powerShell, "-NoLogo", "-NoProfile", "-Command", deniedScript,
+	}, 1)
+	if _, err := os.Stat(outsideMarker); err == nil {
+		t.Fatal("sandboxed PowerShell wrote outside every granted root")
+	} else if !os.IsNotExist(err) {
+		t.Fatalf("stat outside PowerShell marker: %v", err)
+	}
+}
+
+func realSmokePowerShell(t *testing.T) string {
+	t.Helper()
+	for _, candidate := range []string{"pwsh.exe", "pwsh", "powershell.exe", "powershell"} {
+		if path, err := exec.LookPath(candidate); err == nil {
+			return path
+		}
+	}
+	t.Skip("PowerShell is unavailable")
+	return ""
+}
+
 func realSmokeExecutable(t *testing.T, envKey string, fallbackName string) string {
 	t.Helper()
 	if path := os.Getenv(envKey); path != "" {
@@ -318,6 +387,127 @@ func runWindowsRealSmokeCommand(t *testing.T, runnerExe string, base WindowsSand
 	}
 }
 
+// The write jail must hold on a path whose DACL grants Everyone write access.
+//
+// A WRITE_RESTRICTED token runs TWO checks for a write and needs both to pass:
+// the normal one against its enabled SIDs, and a second against its RESTRICTED
+// SID list. The jail is built on the second check only succeeding where Zero has
+// explicitly ACL'd a capability SID. Putting the World SID (S-1-1-0) in the
+// restricted list breaks that globally — every principal is a member of
+// Everyone, so on a DACL that grants Everyone write, the restricted half passes
+// for free and confinement collapses back to the ordinary user's own
+// permissions, which is precisely the boundary the sandbox exists to be
+// stricter than.
+//
+// The runner already states this rule for the SIDs it refuses to add ("None of
+// the granted SIDs can be added to the restricted list without collapsing the
+// write jail"); Everyone was in the list anyway, since the original sandbox
+// baseline.
+//
+// Realistic rather than theoretical: administrators open share roots with
+// Everyone:F, and third-party installers ship loose ACLs. It needs no privilege,
+// no symlink and no race. Checked and ruled out: C:\Users\Public\Documents
+// grants BATCH, not Everyone, so the common "public folder" case is not this.
+func TestWindowsRestrictedTokenDeniesWritesToEveryoneWritablePaths(t *testing.T) {
+	if os.Getenv("ZERO_SANDBOX_REAL_SMOKE") != "1" {
+		t.Skip("set ZERO_SANDBOX_REAL_SMOKE=1 to run real Windows sandbox smoke tests")
+	}
+	runnerExe := realSmokeExecutable(t, "ZERO_WINDOWS_COMMAND_RUNNER_EXE", WindowsSandboxCommandRunnerName)
+
+	root := t.TempDir()
+	outside := t.TempDir()
+	everyoneDir := filepath.Join(outside, "everyone-writable")
+	if err := os.MkdirAll(everyoneDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll everyone-writable: %v", err)
+	}
+	// Granted through the production ACL applier, so the hostile DACL is built
+	// the same way a real one is rather than by a test-only shortcut.
+	snapshot, applied, err := applyWindowsACLPathGroup(windowsACLPathGroup{
+		Path: everyoneDir,
+		Entries: []WindowsACLEntry{{
+			Action:     WindowsACLAllowWrite,
+			Path:       everyoneDir,
+			Capability: "S-1-1-0",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("grant Everyone write: %v", err)
+	}
+	if !applied {
+		t.Fatal("precondition: the Everyone grant did not apply, so there is no bypass to test for")
+	}
+	t.Cleanup(func() { _ = rollbackWindowsACLSnapshots([]windowsACLSnapshot{snapshot}) })
+
+	sandboxHome := filepath.Join(root, ".zero-sandbox")
+	// No DenyRead on purpose: that is what makes the runner choose the
+	// WRITE_RESTRICTED token, which is the default posture and the one whose
+	// restricted-SID list this test is about.
+	profile := PermissionProfile{
+		FileSystem: FileSystemPolicy{
+			Kind:                 FileSystemRestricted,
+			ReadRoots:            []string{root},
+			WriteRoots:           []WritableRoot{{Root: root, ProtectedMetadataNames: []string{".git", ".zero", ".agents"}}},
+			IncludePlatformRoots: true,
+			AllowTemp:            true,
+		},
+		Network: NetworkPolicy{Mode: NetworkDeny},
+	}
+	config := WindowsSandboxCommandArgsOptions{
+		SandboxHome:       sandboxHome,
+		CommandCWD:        root,
+		WorkspaceRoots:    []string{root},
+		PermissionProfile: profile,
+		SandboxLevel:      WindowsSandboxLevelUnelevated,
+	}
+
+	// Granted root first. A jail that denies everything would satisfy the two
+	// assertions below while being useless, and this separates the two outcomes.
+	insideMarker := filepath.Join(root, "write-ok.txt")
+	runWindowsRealSmokeCommand(t, runnerExe, config, []string{
+		"cmd.exe", "/d", "/s", "/c", "echo ok>" + insideMarker,
+	}, 0)
+	if contents, err := os.ReadFile(insideMarker); err != nil || strings.TrimSpace(string(contents)) != "ok" {
+		t.Fatalf("sandboxed write to a granted root = %q, %v; want ok", contents, err)
+	}
+
+	// Control: an ordinary directory outside every granted root. This is the
+	// behaviour the Everyone case must match.
+	controlMarker := filepath.Join(outside, "control-denied.txt")
+	runWindowsRealSmokeCommand(t, runnerExe, config, deniedWriteCommand(controlMarker), deniedWriteExitCode)
+	if _, err := os.Stat(controlMarker); err == nil {
+		t.Fatal("precondition: the sandbox allowed a write to an ordinary path outside every granted root, so this test cannot measure the Everyone case")
+	}
+
+	// The assertion. Same as the control in every respect except the DACL.
+	everyoneMarker := filepath.Join(everyoneDir, "everyone-denied.txt")
+	runWindowsRealSmokeCommand(t, runnerExe, config, deniedWriteCommand(everyoneMarker), deniedWriteExitCode)
+	if _, err := os.Stat(everyoneMarker); err == nil {
+		t.Error("the sandbox wrote outside every granted root because the path grants Everyone write; the restricted-SID list is satisfied by a SID every principal carries")
+	} else if !os.IsNotExist(err) {
+		t.Errorf("stat the Everyone-writable marker: %v", err)
+	}
+}
+
+// deniedWriteExitCode is chosen so a denial cannot be confused with the runner
+// failing to start the command at all.
+//
+// The obvious spelling of these assertions is `echo leaked>path` expecting exit
+// 1, but the runner itself exits 1 for its own errors — a failed marker
+// validation, a bad argument, a token it could not build. A test written that
+// way passes both when the sandbox denies the write and when nothing ever ran,
+// and the second case proves nothing while looking identical to success. On a
+// test whose whole job is catching a confinement regression, that is a failure
+// mode to design out rather than hope about.
+//
+// 77 is arbitrary beyond being outside the range the runner produces for itself.
+const deniedWriteExitCode = 77
+
+// deniedWriteCommand attempts a write and reports deniedWriteExitCode when the
+// redirect is refused, so the exit code also proves cmd.exe actually ran.
+func deniedWriteCommand(marker string) []string {
+	return []string{"cmd.exe", "/d", "/s", "/c", "echo leaked>" + marker + " || exit " + strconv.Itoa(deniedWriteExitCode)}
+}
+
 func powershellSingleQuote(value string) string {
 	out := "'"
 	for _, r := range value {

internal/sandbox/runtime_state.go

@@ -27,13 +27,10 @@ var fallbackSandboxRuntimes = struct {
 }{roots: make(map[string]string)}
 
 type SandboxRuntime struct {
-	Root   string `json:"root,omitempty"`
-	Home   string `json:"home,omitempty"`
-	Cache  string `json:"cache,omitempty"`
-	Config string `json:"config,omitempty"`
-	Data   string `json:"data,omitempty"`
-	State  string `json:"state,omitempty"`
-	Temp   string `json:"temp,omitempty"`
+	Root  string `json:"root,omitempty"`
+	Cache string `json:"cache,omitempty"`
+	Data  string `json:"data,omitempty"`
+	Temp  string `json:"temp,omitempty"`
 }
 
 func prepareSandboxRuntime(workspaceRoot string) (SandboxRuntime, func(), error) {
@@ -75,21 +72,15 @@ func prepareSandboxRuntime(workspaceRoot string) (SandboxRuntime, func(), error)
 		}
 	}()
 	runtimeState := SandboxRuntime{
-		Root:   root,
-		Home:   filepath.Join(root, "home"),
-		Cache:  filepath.Join(root, "cache"),
-		Config: filepath.Join(root, "config"),
-		Data:   filepath.Join(root, "data"),
-		State:  filepath.Join(root, "state"),
-		Temp:   filepath.Join(root, "tmp"),
+		Root:  root,
+		Cache: filepath.Join(root, "cache"),
+		Data:  filepath.Join(root, "data"),
+		Temp:  filepath.Join(root, "tmp"),
 	}
 	directories := []string{
 		runtimeState.Root,
-		runtimeState.Home,
 		runtimeState.Cache,
-		runtimeState.Config,
 		runtimeState.Data,
-		runtimeState.State,
 		runtimeState.Temp,
 		filepath.Join(runtimeState.Cache, "npm"),
 		filepath.Join(runtimeState.Cache, "yarn"),
@@ -207,16 +198,11 @@ func sandboxRuntimeEnvironment(env []string, runtimeState *SandboxRuntime) []str
 		return env
 	}
 	overrides := []string{
-		"HOME=" + runtimeState.Home,
 		"XDG_CACHE_HOME=" + runtimeState.Cache,
-		"XDG_CONFIG_HOME=" + runtimeState.Config,
-		"XDG_DATA_HOME=" + runtimeState.Data,
-		"XDG_STATE_HOME=" + runtimeState.State,
 		"TMPDIR=" + runtimeState.Temp,
 		"TMP=" + runtimeState.Temp,
 		"TEMP=" + runtimeState.Temp,
 		"npm_config_cache=" + filepath.Join(runtimeState.Cache, "npm"),
-		"NPM_CONFIG_USERCONFIG=" + filepath.Join(runtimeState.Config, "npmrc"),
 		"YARN_CACHE_FOLDER=" + filepath.Join(runtimeState.Cache, "yarn"),
 		"COREPACK_HOME=" + filepath.Join(runtimeState.Cache, "corepack"),
 		"PIP_CACHE_DIR=" + filepath.Join(runtimeState.Cache, "pip"),

internal/sandbox/runtime_state_test.go

@@ -2,7 +2,9 @@ package sandbox
 
 import (
 	"os"
+	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 )
@@ -22,12 +24,18 @@ func TestPrepareSandboxRuntimeStaysOutsideWorkspace(t *testing.T) {
 	if pathWithinRoot(workspace, runtimeState.Root) {
 		t.Fatalf("runtime root %q must stay outside workspace %q", runtimeState.Root, workspace)
 	}
-	for _, path := range []string{runtimeState.Home, runtimeState.Cache, runtimeState.Config, runtimeState.Data, runtimeState.State, runtimeState.Temp} {
+	for _, path := range []string{runtimeState.Cache, runtimeState.Data, runtimeState.Temp, filepath.Join(runtimeState.Data, "cargo")} {
 		info, err := os.Stat(path)
 		if err != nil || !info.IsDir() {
 			t.Fatalf("managed runtime directory %q was not prepared: %v", path, err)
 		}
 	}
+	for _, name := range []string{"home", "config", "state"} {
+		path := filepath.Join(runtimeState.Root, name)
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("obsolete synthetic runtime directory %q exists: %v", path, err)
+		}
+	}
 }
 
 func TestPrepareSandboxRuntimeCleansExpiredSibling(t *testing.T) {
@@ -116,34 +124,63 @@ func TestCleanupSandboxRuntimeSkipsActiveLease(t *testing.T) {
 	}
 }
 
-func TestSandboxRuntimeEnvironmentUsesManagedState(t *testing.T) {
+func TestSandboxRuntimeEnvironmentPreservesUserConfiguration(t *testing.T) {
 	root := filepath.Join(t.TempDir(), "runtime")
 	runtimeState := SandboxRuntime{
-		Root:   root,
-		Home:   filepath.Join(root, "home"),
-		Cache:  filepath.Join(root, "cache"),
-		Config: filepath.Join(root, "config"),
-		Data:   filepath.Join(root, "data"),
-		State:  filepath.Join(root, "state"),
-		Temp:   filepath.Join(root, "tmp"),
+		Root:  root,
+		Cache: filepath.Join(root, "cache"),
+		Data:  filepath.Join(root, "data"),
+		Temp:  filepath.Join(root, "tmp"),
 	}
 	env := sandboxRuntimeEnvironment([]string{
-		"HOME=/workspace",
+		"HOME=/home/user",
 		"XDG_CACHE_HOME=/host/cache",
+		"XDG_CONFIG_HOME=/home/user/.config",
+		"XDG_DATA_HOME=/home/user/.local/share",
+		"XDG_STATE_HOME=/home/user/.local/state",
+		"NPM_CONFIG_USERCONFIG=/home/user/.npmrc",
 		"PATH=/usr/bin",
 	}, &runtimeState)
 
 	for key, want := range map[string]string{
-		"HOME":                  runtimeState.Home,
-		"XDG_CACHE_HOME":        runtimeState.Cache,
-		"XDG_CONFIG_HOME":       runtimeState.Config,
-		"XDG_DATA_HOME":         runtimeState.Data,
-		"XDG_STATE_HOME":        runtimeState.State,
-		"TMPDIR":                runtimeState.Temp,
-		"npm_config_cache":      filepath.Join(runtimeState.Cache, "npm"),
-		"NPM_CONFIG_USERCONFIG": filepath.Join(runtimeState.Config, "npmrc"),
-		"YARN_CACHE_FOLDER":     filepath.Join(runtimeState.Cache, "yarn"),
-		"COREPACK_HOME":         filepath.Join(runtimeState.Cache, "corepack"),
+		"HOME":                  "/home/user",
+		"XDG_CONFIG_HOME":       "/home/user/.config",
+		"XDG_DATA_HOME":         "/home/user/.local/share",
+		"XDG_STATE_HOME":        "/home/user/.local/state",
+		"NPM_CONFIG_USERCONFIG": "/home/user/.npmrc",
+	} {
+		if got := envListValue(env, key, ""); got != want {
+			t.Fatalf("%s = %q, want %q; env=%#v", key, got, want, env)
+		}
+	}
+}
+
+func TestSandboxRuntimeEnvironmentUsesManagedWritableState(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "runtime")
+	runtimeState := SandboxRuntime{
+		Root:  root,
+		Cache: filepath.Join(root, "cache"),
+		Data:  filepath.Join(root, "data"),
+		Temp:  filepath.Join(root, "tmp"),
+	}
+	env := sandboxRuntimeEnvironment([]string{
+		"XDG_CACHE_HOME=/host/cache",
+		"TMPDIR=/host/tmp",
+		"PATH=/usr/bin",
+	}, &runtimeState)
+
+	for key, want := range map[string]string{
+		"XDG_CACHE_HOME":    runtimeState.Cache,
+		"TMPDIR":            runtimeState.Temp,
+		"TMP":               runtimeState.Temp,
+		"TEMP":              runtimeState.Temp,
+		"npm_config_cache":  filepath.Join(runtimeState.Cache, "npm"),
+		"YARN_CACHE_FOLDER": filepath.Join(runtimeState.Cache, "yarn"),
+		"COREPACK_HOME":     filepath.Join(runtimeState.Cache, "corepack"),
+		"PIP_CACHE_DIR":     filepath.Join(runtimeState.Cache, "pip"),
+		"GOCACHE":           filepath.Join(runtimeState.Cache, "go-build"),
+		"GOMODCACHE":        filepath.Join(runtimeState.Data, "go-mod"),
+		"CARGO_HOME":        filepath.Join(runtimeState.Data, "cargo"),
 	} {
 		if got := envListValue(env, key, ""); got != want {
 			t.Fatalf("%s = %q, want %q; env=%#v", key, got, want, env)
@@ -154,9 +191,93 @@ func TestSandboxRuntimeEnvironmentUsesManagedState(t *testing.T) {
 	}
 }
 
+func TestSandboxRuntimeEnvironmentPreservesGitGlobalIgnore(t *testing.T) {
+	git, err := exec.LookPath("git")
+	if err != nil {
+		t.Skip("git is unavailable")
+	}
+	root := t.TempDir()
+	home := filepath.Join(root, "home")
+	configHome := filepath.Join(home, ".config")
+	repository := filepath.Join(root, "repository")
+	runtimeRoot := filepath.Join(root, "runtime")
+	for _, directory := range []string{
+		filepath.Join(configHome, "git"),
+		repository,
+		filepath.Join(runtimeRoot, "cache"),
+		filepath.Join(runtimeRoot, "data"),
+		filepath.Join(runtimeRoot, "tmp"),
+	} {
+		if err := os.MkdirAll(directory, 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(configHome, "git", "ignore"), []byte("ignored.txt\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(repository, "ignored.txt"), []byte("ignored\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(repository, "visible.txt"), []byte("visible\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	runtimeState := SandboxRuntime{
+		Root:  runtimeRoot,
+		Cache: filepath.Join(runtimeRoot, "cache"),
+		Data:  filepath.Join(runtimeRoot, "data"),
+		Temp:  filepath.Join(runtimeRoot, "tmp"),
+	}
+	inherited := append(os.Environ(),
+		"GIT_CONFIG_GLOBAL="+filepath.Join(root, "missing-global-config"),
+		"GIT_DIR="+filepath.Join(root, "wrong-repository"),
+		"GIT_CONFIG_COUNT=1",
+		"GIT_CONFIG_KEY_0=core.excludesFile",
+		"GIT_CONFIG_VALUE_0="+filepath.Join(root, "missing-ignore"),
+	)
+	env := sandboxRuntimeEnvironment(upsertEnvList(withoutGitEnvironmentOverrides(inherited),
+		"HOME="+home,
+		"XDG_CONFIG_HOME="+configHome,
+		"GIT_CONFIG_NOSYSTEM=1",
+		"GIT_TERMINAL_PROMPT=0",
+	), &runtimeState)
+	runGit := func(args ...string) string {
+		t.Helper()
+		command := exec.Command(git, args...)
+		command.Dir = repository
+		command.Env = env
+		output, err := command.CombinedOutput()
+		if err != nil {
+			t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, output)
+		}
+		return string(output)
+	}
+	runGit("init", "--quiet")
+	status := runGit("status", "--short", "--untracked-files=all")
+	if strings.Contains(status, "ignored.txt") {
+		t.Fatalf("global ignore was not honored:\n%s", status)
+	}
+	if !strings.Contains(status, "visible.txt") {
+		t.Fatalf("non-ignored file is missing from status:\n%s", status)
+	}
+}
+
+func withoutGitEnvironmentOverrides(env []string) []string {
+	out := make([]string, 0, len(env))
+	for _, value := range env {
+		key, _, ok := strings.Cut(value, "=")
+		if ok && strings.HasPrefix(strings.ToUpper(key), "GIT_") {
+			continue
+		}
+		out = append(out, value)
+	}
+	return out
+}
+
 func TestEngineCommandPlanCarriesManagedRuntime(t *testing.T) {
 	workspace := t.TempDir()
 	cacheRoot := t.TempDir()
+	t.Setenv("HOME", filepath.Join(t.TempDir(), "home"))
 	original := sandboxUserCacheDir
 	sandboxUserCacheDir = func() (string, error) { return cacheRoot, nil }
 	t.Cleanup(func() { sandboxUserCacheDir = original })
@@ -189,8 +310,8 @@ func TestEngineCommandPlanCarriesManagedRuntime(t *testing.T) {
 	} else if !inUse {
 		t.Fatal("command plan runtime must be marked in use")
 	}
-	if got := envListValue(plan.Env, "HOME", ""); got != plan.PermissionProfile.Runtime.Home {
-		t.Fatalf("HOME = %q, want managed home %q", got, plan.PermissionProfile.Runtime.Home)
+	if got := envListValue(plan.Env, "HOME", ""); got != os.Getenv("HOME") {
+		t.Fatalf("HOME = %q, want caller home %q", got, os.Getenv("HOME"))
 	}
 	foundWriteRoot := false
 	for _, root := range plan.PermissionProfile.FileSystem.WriteRoots {

internal/sandbox/safe_command.go

@@ -430,25 +430,70 @@ func shellDashCPayload(program string, fields []string) string {
 // name: it strips shell quoting/escaping characters (", ', `, \) wherever they
 // appear in the token (including embedded ones like `vi\m` or `v"i"m`), strips
 // leading command-substitution markers, removes any directory prefix (so
-// /usr/bin/vim and C:\tools\vim.exe match "vim"), and lowercases. This closes
-// path/quote/substitution evasions of the detector.
+// /usr/bin/vim and C:\tools\vim.exe match "vim"), removes Windows executable
+// suffixes, and lowercases. This closes path/quote/substitution evasions of the
+// detector and keeps curl.exe/npm.cmd equivalent to curl/npm for risk analysis.
 func normalizeProgramToken(field string) string {
 	token := strings.TrimSpace(field)
 	token = strings.TrimLeft(token, "$(")
 	token = strings.TrimRight(token, ")")
-	// Strip shell quoting/escaping characters (", ', `, \) wherever they appear
-	// in the token — surrounding, embedded, or as a mid-word escape — so
-	// "vim", v"i"m, 'v'im, and vi\m all collapse to the program name. This is
-	// done BEFORE the directory-prefix trim so an escape can't masquerade as a
-	// path separator (e.g. vi\m must become vim, not m).
-	token = stripChars(token, "\"'`\\")
-	// Strip a directory prefix so /usr/bin/vim reduces to the basename. (A
-	// Windows-style backslash path separator is already removed above, so only
-	// the POSIX separator remains to split on.)
-	if i := strings.LastIndex(token, "/"); i >= 0 {
-		token = token[i+1:]
+	// PowerShell commonly invokes drive-letter, UNC, and relative paths. Extract
+	// their basename while backslashes still carry path-separator meaning;
+	// removing them first would turn C:\tools\curl.exe into c:toolscurl.exe and
+	// bypass the canonical curl risk entry.
+	pathToken := stripChars(token, "\"'`")
+	if windowsPathBasename, ok := windowsExecutablePathBasename(pathToken); ok {
+		token = windowsPathBasename
+	} else {
+		// Strip shell quoting/escaping characters (", ', `, \) wherever they
+		// appear in the token — surrounding, embedded, or as a mid-word escape
+		// — so "vim", v"i"m, 'v'im, and vi\m all collapse to the program name.
+		token = stripChars(token, "\"'`\\")
+		// Strip a directory prefix so /usr/bin/vim reduces to the basename.
+		if i := strings.LastIndex(token, "/"); i >= 0 {
+			token = token[i+1:]
+		}
 	}
-	return strings.ToLower(token)
+	token = strings.ToLower(token)
+	for _, suffix := range []string{".exe", ".cmd", ".bat", ".com"} {
+		if strings.HasSuffix(token, suffix) {
+			return strings.TrimSuffix(token, suffix)
+		}
+	}
+	return token
+}
+
+func windowsExecutablePathBasename(token string) (string, bool) {
+	drivePath := len(token) >= 3 &&
+		((token[0] >= 'a' && token[0] <= 'z') || (token[0] >= 'A' && token[0] <= 'Z')) &&
+		token[1] == ':'
+	uncPath := strings.HasPrefix(token, `\\`)
+	explicitRelativePath := strings.HasPrefix(token, `.\`) || strings.HasPrefix(token, `..\`)
+	backslashRelativePath := strings.ContainsRune(token, '\\') && hasWindowsExecutableSuffix(token)
+	if !drivePath && !uncPath && !explicitRelativePath && !backslashRelativePath {
+		return "", false
+	}
+	index := strings.LastIndexAny(token, `\/`)
+	if index >= 0 {
+		if index+1 >= len(token) {
+			return "", false
+		}
+		return token[index+1:], true
+	}
+	if drivePath && len(token) > 2 {
+		return token[2:], true
+	}
+	return "", false
+}
+
+func hasWindowsExecutableSuffix(token string) bool {
+	token = strings.ToLower(token)
+	for _, suffix := range []string{".exe", ".cmd", ".bat", ".com"} {
+		if strings.HasSuffix(token, suffix) {
+			return true
+		}
+	}
+	return false
 }
 
 // stripChars returns s with every rune in cutset removed.

internal/sandbox/windows_token_windows.go

@@ -88,19 +88,55 @@ func createWindowsRestrictedTokenFromBase(base windows.Token, capabilitySIDs []w
 	if err != nil {
 		return 0, err
 	}
-	worldSID, err := windows.CreateWellKnownSid(windows.WinWorldSid)
-	if err != nil {
-		return 0, fmt.Errorf("create world SID: %w", err)
-	}
-
 	entries := make([]windows.SIDAndAttributes, 0, len(capabilitySIDs)+2)
 	for _, sid := range capabilitySIDs {
 		entries = append(entries, windows.SIDAndAttributes{Sid: sid.sid})
 	}
-	entries = append(entries,
-		windows.SIDAndAttributes{Sid: sidFromBytes(logonSID)},
-		windows.SIDAndAttributes{Sid: worldSID},
-	)
+	entries = append(entries, windows.SIDAndAttributes{Sid: sidFromBytes(logonSID)})
+
+	// The World SID (S-1-1-0, Everyone) is added ONLY to the token that does not
+	// carry WRITE_RESTRICTED, and putting it back unconditionally would reopen a
+	// write-jail bypass.
+	//
+	// A restricted SID is a key to every object whose DACL names it. That is why
+	// the runner refuses to add the user SID, Administrators or SYSTEM — "each
+	// has write access nearly everywhere". Everyone is the broadest of the lot:
+	// every principal carries it, so under WRITE_RESTRICTED the second
+	// (restricted-SID) check passes for free on any path whose DACL grants
+	// Everyone write, and confinement falls back to the ordinary user's own
+	// permissions — the exact boundary this token exists to be stricter than. It
+	// needs no privilege, no symlink and no race: an Everyone-writable directory
+	// is enough, and share roots opened with Everyone:F and loose installer ACLs
+	// supply them. It was present from the original sandbox baseline,
+	// uncommented, and under WRITE_RESTRICTED nothing depends on it, because that
+	// flag already exempts reads from the restricted-SID check.
+	//
+	// Without the flag it IS load-bearing and cannot simply be dropped. The
+	// restricted-SID check then applies to READS too, and default Windows DACLs
+	// grant BUILTIN\Users rather than anything in this list, so a token without
+	// Everyone cannot open cmd.exe — the process dies at launch with
+	// STATUS_ACCESS_DENIED (0xC0000022) before it runs anything. That path is
+	// only taken when the profile configures DenyRead, which is already the
+	// posture that trades capability for read-deny enforcement (#612).
+	//
+	// So the bypass survives for DenyRead profiles, deliberately and narrowly,
+	// rather than being traded for a sandbox that cannot start a command. Closing
+	// it there needs a different mechanism (a read-side grant that is not a
+	// universal group), tracked separately.
+	//
+	// The logon SID above stays in both modes: it is this token's own rather than
+	// a broad group, and broadenWindowsRestrictedTokenDefaultDacl depends on it so
+	// the process can use pipes and events it creates for itself.
+	//
+	// Anything added here needs the same scrutiny — Authenticated Users, Users,
+	// INTERACTIVE and BATCH would each produce this bypass on a DACL naming them.
+	if !writeRestricted {
+		worldSID, err := windows.CreateWellKnownSid(windows.WinWorldSid)
+		if err != nil {
+			return 0, fmt.Errorf("create world SID: %w", err)
+		}
+		entries = append(entries, windows.SIDAndAttributes{Sid: worldSID})
+	}
 
 	// WRITE_RESTRICTED scopes the restricted-SID check to write-type accesses:
 	// reads use only the normal token identity, so the sandboxed process can

internal/sessions/goal.go

@@ -0,0 +1,422 @@
+package sessions
+
+import (
+	"fmt"
+	"strings"
+	"unicode/utf8"
+)
+
+const (
+	GoalObjectiveMaxLength            = 4_000
+	GoalMaxConsecutiveContinuations   = 20
+	goalContinuationLimitStatusReason = "automatic continuation limit reached"
+)
+
+func validateGoalObjective(objective string) (string, error) {
+	objective = strings.TrimSpace(objective)
+	if objective == "" {
+		return "", fmt.Errorf("goal objective is required")
+	}
+	if utf8.RuneCountInString(objective) > GoalObjectiveMaxLength {
+		return "", fmt.Errorf("goal objective cannot exceed %d characters", GoalObjectiveMaxLength)
+	}
+	return objective, nil
+}
+
+// CreateGoal persists a new active goal for a session. It refuses to replace an
+// existing goal so callers must make replacement an explicit user decision.
+func (store *Store) CreateGoal(sessionID, objective string, tokenBudget int) (Metadata, Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, Event{}, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	var err error
+	objective, err = validateGoalObjective(objective)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if tokenBudget < 0 {
+		return Metadata{}, Event{}, fmt.Errorf("goal token budget cannot be negative")
+	}
+
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if session.Goal != nil {
+		return Metadata{}, Event{}, fmt.Errorf("session already has a goal")
+	}
+	now := store.timestamp()
+	session.Goal = &Goal{
+		Objective:         objective,
+		Status:            GoalStatusActive,
+		TokenBudget:       tokenBudget,
+		ContinuationLimit: GoalMaxConsecutiveContinuations,
+		CreatedAt:         now,
+		UpdatedAt:         now,
+	}
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, Event{}, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalCreated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	return loaded, event, nil
+}
+
+// UpdateGoal changes a goal's lifecycle state. Terminal goals remain available
+// for status/history until the user explicitly clears them.
+func (store *Store) UpdateGoal(sessionID string, status GoalStatus, reason string) (Metadata, Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, Event{}, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	if !validGoalStatus(status) {
+		return Metadata{}, Event{}, fmt.Errorf("invalid goal status %q", status)
+	}
+
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if session.Goal == nil {
+		return Metadata{}, Event{}, fmt.Errorf("session has no goal")
+	}
+	session.Goal.Status = status
+	session.Goal.StatusReason = strings.TrimSpace(reason)
+	if status == GoalStatusActive {
+		session.Goal.ContinuationCount = 0
+		if session.Goal.ContinuationLimit <= 0 {
+			session.Goal.ContinuationLimit = GoalMaxConsecutiveContinuations
+		}
+	}
+	session.Goal.UpdatedAt = store.timestamp()
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, Event{}, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalUpdated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	return loaded, event, nil
+}
+
+// EditGoal replaces the objective and optional budget without resetting usage or
+// lifecycle timestamps. User-facing command handling owns confirmation.
+func (store *Store) EditGoal(sessionID, objective string, tokenBudget int) (Metadata, Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, Event{}, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	var err error
+	objective, err = validateGoalObjective(objective)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if tokenBudget < 0 {
+		return Metadata{}, Event{}, fmt.Errorf("goal token budget cannot be negative")
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if session.Goal == nil {
+		return Metadata{}, Event{}, fmt.Errorf("session has no goal")
+	}
+	session.Goal.Objective = objective
+	session.Goal.TokenBudget = tokenBudget
+	session.Goal.Status = GoalStatusActive
+	session.Goal.StatusReason = ""
+	session.Goal.ContinuationCount = 0
+	if session.Goal.ContinuationLimit <= 0 {
+		session.Goal.ContinuationLimit = GoalMaxConsecutiveContinuations
+	}
+	if tokenBudget > 0 && session.Goal.TokensUsed >= tokenBudget {
+		session.Goal.Status = GoalStatusBudgetLimited
+		session.Goal.StatusReason = "token budget reached"
+	}
+	session.Goal.UpdatedAt = store.timestamp()
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, Event{}, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalUpdated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	return loaded, event, nil
+}
+
+// ResetGoalContinuations starts a fresh autonomous-run allowance after explicit
+// user input. It makes the safety bound consecutive rather than lifetime-wide.
+func (store *Store) ResetGoalContinuations(sessionID string) (Metadata, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, err
+	}
+	if session.Goal == nil || session.Goal.Status != GoalStatusActive {
+		return session, nil
+	}
+	changed := false
+	if session.Goal.ContinuationCount != 0 {
+		session.Goal.ContinuationCount = 0
+		changed = true
+	}
+	if session.Goal.ContinuationLimit <= 0 {
+		session.Goal.ContinuationLimit = GoalMaxConsecutiveContinuations
+		changed = true
+	}
+	if !changed {
+		return session, nil
+	}
+	session.Goal.UpdatedAt = store.timestamp()
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, err
+	}
+	return session, nil
+}
+
+// ReserveGoalContinuation atomically reserves one automatic continuation. Once
+// the persisted consecutive-run limit is exhausted it pauses the goal before
+// another provider request can start, even when the provider reports no usage.
+func (store *Store) ReserveGoalContinuation(sessionID string) (Metadata, *Event, bool, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, nil, false, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, nil, false, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, false, err
+	}
+	if session.Goal == nil || session.Goal.Status != GoalStatusActive {
+		return session, nil, false, nil
+	}
+	limit := session.Goal.ContinuationLimit
+	if limit <= 0 {
+		limit = GoalMaxConsecutiveContinuations
+		session.Goal.ContinuationLimit = limit
+	}
+	if session.Goal.ContinuationCount < limit {
+		session.Goal.ContinuationCount++
+		session.Goal.UpdatedAt = store.timestamp()
+		if err := store.writeMetadata(session); err != nil {
+			return Metadata{}, nil, false, err
+		}
+		return session, nil, true, nil
+	}
+
+	session.Goal.Status = GoalStatusPaused
+	session.Goal.StatusReason = goalContinuationLimitStatusReason
+	session.Goal.UpdatedAt = store.timestamp()
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, nil, false, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalUpdated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, nil, false, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, false, err
+	}
+	return loaded, &event, false, nil
+}
+
+// AddGoalUsage accounts tokens consumed while a goal is active. Reaching the
+// optional budget pauses the goal before another autonomous turn can start.
+func (store *Store) AddGoalUsage(sessionID string, tokens int) (Metadata, *Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, nil, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	if tokens < 0 {
+		return Metadata{}, nil, fmt.Errorf("goal token usage cannot be negative")
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	if session.Goal == nil || tokens == 0 {
+		return session, nil, nil
+	}
+	session.Goal.TokensUsed += tokens
+	session.Goal.UpdatedAt = store.timestamp()
+	budgetReached := false
+	if session.Goal.Status == GoalStatusActive &&
+		session.Goal.TokenBudget > 0 &&
+		session.Goal.TokensUsed >= session.Goal.TokenBudget {
+		session.Goal.Status = GoalStatusBudgetLimited
+		session.Goal.StatusReason = "token budget reached"
+		budgetReached = true
+	}
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, nil, err
+	}
+	if !budgetReached {
+		return session, nil, nil
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalUpdated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	return loaded, &event, nil
+}
+
+// PauseGoalIfActive pauses a goal only while it is still active. It is used by
+// cancellation paths where an in-flight agent may have completed or blocked the
+// goal immediately before the cancellation reached the runtime.
+func (store *Store) PauseGoalIfActive(sessionID, reason string) (Metadata, *Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, nil, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	if session.Goal == nil || session.Goal.Status != GoalStatusActive {
+		return session, nil, nil
+	}
+	session.Goal.Status = GoalStatusPaused
+	session.Goal.StatusReason = strings.TrimSpace(reason)
+	session.Goal.UpdatedAt = store.timestamp()
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, nil, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalUpdated,
+		Payload: session.Goal,
+	})
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, nil, err
+	}
+	return loaded, &event, nil
+}
+
+// ClearGoal removes the current goal while preserving an audit event.
+func (store *Store) ClearGoal(sessionID string) (Metadata, Event, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, Event{}, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	if session.Goal == nil {
+		return Metadata{}, Event{}, fmt.Errorf("session has no goal")
+	}
+	cleared := cloneGoal(session.Goal)
+	session.Goal = nil
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, Event{}, err
+	}
+	event, err := store.appendEventLocked(sessionID, AppendEventInput{
+		Type:    EventGoalCleared,
+		Payload: cleared,
+	})
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	loaded, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, Event{}, err
+	}
+	return loaded, event, nil
+}
+
+func validGoalStatus(status GoalStatus) bool {
+	switch status {
+	case GoalStatusActive, GoalStatusPaused, GoalStatusBlocked, GoalStatusBudgetLimited, GoalStatusUsageLimited, GoalStatusComplete:
+		return true
+	default:
+		return false
+	}
+}
+
+func cloneGoal(goal *Goal) *Goal {
+	if goal == nil {
+		return nil
+	}
+	copy := *goal
+	return &copy
+}

internal/sessions/goal_test.go

@@ -0,0 +1,382 @@
+package sessions
+
+import (
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestGoalLifecyclePersistsInSessionMetadata(t *testing.T) {
+	now := time.Date(2026, 7, 24, 10, 0, 0, 0, time.UTC)
+	store := NewStore(StoreOptions{
+		RootDir: t.TempDir(),
+		Now: func() time.Time {
+			now = now.Add(time.Second)
+			return now
+		},
+	})
+	session, err := store.Create(CreateInput{SessionID: "goal_session"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	created, event, err := store.CreateGoal(session.SessionID, "Ship the release", 1_000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Type != EventGoalCreated {
+		t.Fatalf("create event = %q, want %q", event.Type, EventGoalCreated)
+	}
+	if created.Goal == nil || created.Goal.Objective != "Ship the release" ||
+		created.Goal.Status != GoalStatusActive || created.Goal.TokenBudget != 1_000 {
+		t.Fatalf("created goal = %#v", created.Goal)
+	}
+
+	accounted, _, err := store.AddGoalUsage(session.SessionID, 250)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if accounted.Goal.TokensUsed != 250 || accounted.Goal.Status != GoalStatusActive {
+		t.Fatalf("accounted goal = %#v", accounted.Goal)
+	}
+
+	paused, event, err := store.UpdateGoal(session.SessionID, GoalStatusPaused, "user interrupted")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Type != EventGoalUpdated || paused.Goal.Status != GoalStatusPaused ||
+		paused.Goal.StatusReason != "user interrupted" {
+		t.Fatalf("paused goal/event = %#v / %#v", paused.Goal, event)
+	}
+
+	loaded, err := store.Get(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded == nil || loaded.Goal == nil || loaded.Goal.Status != GoalStatusPaused {
+		t.Fatalf("reloaded session = %#v", loaded)
+	}
+
+	cleared, event, err := store.ClearGoal(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Type != EventGoalCleared || cleared.Goal != nil {
+		t.Fatalf("cleared goal/event = %#v / %#v", cleared.Goal, event)
+	}
+}
+
+func TestGoalBudgetPausesAtLimit(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "budget_session"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Stay bounded", 100); err != nil {
+		t.Fatal(err)
+	}
+
+	updated, event, err := store.AddGoalUsage(session.SessionID, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated.Goal.Status != GoalStatusBudgetLimited || updated.Goal.StatusReason != "token budget reached" {
+		t.Fatalf("budgeted goal = %#v", updated.Goal)
+	}
+	if event == nil || event.Type != EventGoalUpdated {
+		t.Fatalf("budget transition event = %#v", event)
+	}
+}
+
+func TestGoalContinuationLimitStopsWithoutProviderUsage(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "continuation_limit"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Stay bounded without usage events", 0); err != nil {
+		t.Fatal(err)
+	}
+
+	for continuation := 1; continuation <= GoalMaxConsecutiveContinuations; continuation++ {
+		updated, event, reserved, err := store.ReserveGoalContinuation(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !reserved || event != nil {
+			t.Fatalf("continuation %d: reserved=%v event=%#v", continuation, reserved, event)
+		}
+		if updated.Goal.ContinuationCount != continuation {
+			t.Fatalf("continuation count = %d, want %d", updated.Goal.ContinuationCount, continuation)
+		}
+		if updated.Goal.TokensUsed != 0 {
+			t.Fatalf("provider-independent guard unexpectedly recorded tokens: %#v", updated.Goal)
+		}
+	}
+
+	stopped, event, reserved, err := store.ReserveGoalContinuation(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if reserved || event == nil || stopped.Goal.Status != GoalStatusPaused ||
+		stopped.Goal.StatusReason != goalContinuationLimitStatusReason {
+		t.Fatalf("unbounded continuation was not stopped: goal=%#v event=%#v reserved=%v", stopped.Goal, event, reserved)
+	}
+	reloaded, err := store.Get(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if reloaded.Goal.ContinuationCount != GoalMaxConsecutiveContinuations ||
+		reloaded.Goal.Status != GoalStatusPaused {
+		t.Fatalf("continuation guard did not persist: %#v", reloaded.Goal)
+	}
+
+	resumed, _, err := store.UpdateGoal(session.SessionID, GoalStatusActive, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resumed.Goal.ContinuationCount != 0 {
+		t.Fatalf("explicit resume did not reset consecutive continuations: %#v", resumed.Goal)
+	}
+}
+
+func TestResetGoalContinuationsPersistsOnlyActiveChanges(t *testing.T) {
+	newStore := func(t *testing.T) (*Store, Metadata) {
+		t.Helper()
+		now := time.Date(2026, 7, 26, 10, 0, 0, 0, time.UTC)
+		store := NewStore(StoreOptions{
+			RootDir: t.TempDir(),
+			Now: func() time.Time {
+				now = now.Add(time.Second)
+				return now
+			},
+		})
+		session, err := store.Create(CreateInput{SessionID: "reset_goal"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return store, session
+	}
+	pinMetadataTime := func(t *testing.T, store *Store, sessionID string) time.Time {
+		t.Helper()
+		path := store.metadataPath(sessionID)
+		sentinel := time.Date(2001, 2, 3, 4, 5, 6, 0, time.UTC)
+		if err := os.Chtimes(path, sentinel, sentinel); err != nil {
+			t.Fatal(err)
+		}
+		info, err := os.Stat(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return info.ModTime()
+	}
+	assertMetadataTime := func(t *testing.T, store *Store, sessionID string, want time.Time) {
+		t.Helper()
+		info, err := os.Stat(store.metadataPath(sessionID))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !info.ModTime().Equal(want) {
+			t.Fatalf("metadata was rewritten: modtime=%s want=%s", info.ModTime(), want)
+		}
+	}
+
+	t.Run("no goal is a no-op", func(t *testing.T) {
+		store, session := newStore(t)
+		modTime := pinMetadataTime(t, store, session.SessionID)
+		updated, err := store.ResetGoalContinuations(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if updated.Goal != nil {
+			t.Fatalf("no-goal reset created a goal: %#v", updated.Goal)
+		}
+		assertMetadataTime(t, store, session.SessionID, modTime)
+	})
+
+	t.Run("inactive goal is a no-op", func(t *testing.T) {
+		store, session := newStore(t)
+		if _, _, err := store.CreateGoal(session.SessionID, "Pause safely", 0); err != nil {
+			t.Fatal(err)
+		}
+		if _, _, reserved, err := store.ReserveGoalContinuation(session.SessionID); err != nil || !reserved {
+			t.Fatalf("reserve continuation: reserved=%v err=%v", reserved, err)
+		}
+		paused, _, err := store.UpdateGoal(session.SessionID, GoalStatusPaused, "user paused")
+		if err != nil {
+			t.Fatal(err)
+		}
+		modTime := pinMetadataTime(t, store, session.SessionID)
+		updated, err := store.ResetGoalContinuations(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if updated.Goal.ContinuationCount != 1 || updated.Goal.UpdatedAt != paused.Goal.UpdatedAt {
+			t.Fatalf("inactive goal changed during reset: before=%#v after=%#v", paused.Goal, updated.Goal)
+		}
+		assertMetadataTime(t, store, session.SessionID, modTime)
+	})
+
+	t.Run("already reset active goal is a no-op", func(t *testing.T) {
+		store, session := newStore(t)
+		created, _, err := store.CreateGoal(session.SessionID, "Stay reset", 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		modTime := pinMetadataTime(t, store, session.SessionID)
+		updated, err := store.ResetGoalContinuations(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if updated.Goal.ContinuationCount != 0 ||
+			updated.Goal.ContinuationLimit != GoalMaxConsecutiveContinuations ||
+			updated.Goal.UpdatedAt != created.Goal.UpdatedAt {
+			t.Fatalf("already-reset goal changed: before=%#v after=%#v", created.Goal, updated.Goal)
+		}
+		assertMetadataTime(t, store, session.SessionID, modTime)
+	})
+
+	t.Run("active goal reset persists", func(t *testing.T) {
+		store, session := newStore(t)
+		if _, _, err := store.CreateGoal(session.SessionID, "Reset progress", 0); err != nil {
+			t.Fatal(err)
+		}
+		reserved, _, ok, err := store.ReserveGoalContinuation(session.SessionID)
+		if err != nil || !ok {
+			t.Fatalf("reserve continuation: reserved=%v err=%v", ok, err)
+		}
+		updated, err := store.ResetGoalContinuations(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if updated.Goal.ContinuationCount != 0 ||
+			updated.Goal.ContinuationLimit != GoalMaxConsecutiveContinuations ||
+			updated.Goal.UpdatedAt == reserved.Goal.UpdatedAt {
+			t.Fatalf("active reset did not persist: before=%#v after=%#v", reserved.Goal, updated.Goal)
+		}
+		reloaded, err := store.Get(session.SessionID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if reloaded.Goal == nil || *reloaded.Goal != *updated.Goal {
+			t.Fatalf("active reset was not durable: updated=%#v reloaded=%#v", updated.Goal, reloaded.Goal)
+		}
+	})
+}
+
+func TestGoalObjectiveLengthIsBounded(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "objective_limit"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	tooLong := strings.Repeat("g", GoalObjectiveMaxLength+1)
+	if _, _, err := store.CreateGoal(session.SessionID, tooLong, 0); err == nil ||
+		!strings.Contains(err.Error(), "cannot exceed") {
+		t.Fatalf("oversized objective error = %v", err)
+	}
+}
+
+func TestEditGoalUpdatesStateAndRejectsInvalidInputWithoutMutation(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "edit_goal"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Original objective", 1_000); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.AddGoalUsage(session.SessionID, 250); err != nil {
+		t.Fatal(err)
+	}
+
+	edited, event, err := store.EditGoal(session.SessionID, "Updated objective", 500)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Type != EventGoalUpdated {
+		t.Fatalf("edit event = %q, want %q", event.Type, EventGoalUpdated)
+	}
+	if edited.Goal == nil ||
+		edited.Goal.Objective != "Updated objective" ||
+		edited.Goal.TokenBudget != 500 ||
+		edited.Goal.TokensUsed != 250 ||
+		edited.Goal.Status != GoalStatusActive ||
+		edited.Goal.StatusReason != "" {
+		t.Fatalf("edited goal = %#v", edited.Goal)
+	}
+
+	limited, _, err := store.EditGoal(session.SessionID, "Stay within budget", 200)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if limited.Goal == nil ||
+		limited.Goal.Status != GoalStatusBudgetLimited ||
+		limited.Goal.StatusReason != "token budget reached" ||
+		limited.Goal.TokensUsed != 250 {
+		t.Fatalf("budget-limited goal = %#v", limited.Goal)
+	}
+
+	before := *limited.Goal
+	eventsBefore, err := store.ReadEvents(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.EditGoal(session.SessionID, "   ", 200); err == nil {
+		t.Fatal("EditGoal should reject an empty objective")
+	}
+	if _, _, err := store.EditGoal(session.SessionID, "Invalid budget", -1); err == nil {
+		t.Fatal("EditGoal should reject a negative token budget")
+	}
+	after, err := store.Get(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if after == nil || after.Goal == nil || *after.Goal != before {
+		t.Fatalf("invalid edit mutated goal: before=%#v after=%#v", before, after)
+	}
+	eventsAfter, err := store.ReadEvents(session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(eventsAfter) != len(eventsBefore) {
+		t.Fatalf("invalid edit appended events: before=%d after=%d", len(eventsBefore), len(eventsAfter))
+	}
+}
+
+func TestCreateGoalRefusesImplicitReplacement(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "replace_session"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "First", 0); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Second", 0); err == nil {
+		t.Fatal("CreateGoal should require an explicit clear before replacement")
+	}
+}
+
+func TestPauseGoalIfActiveDoesNotOverwriteTerminalState(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "terminal_session"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Finish", 0); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.UpdateGoal(session.SessionID, GoalStatusComplete, ""); err != nil {
+		t.Fatal(err)
+	}
+
+	updated, event, err := store.PauseGoalIfActive(session.SessionID, "cancelled")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event != nil || updated.Goal.Status != GoalStatusComplete {
+		t.Fatalf("terminal goal changed during cancellation: goal=%#v event=%#v", updated.Goal, event)
+	}
+}

internal/sessions/session_title_test.go

@@ -43,7 +43,7 @@ func TestUpdateTitle(t *testing.T) {
 		t.Fatalf("title not trimmed/stored: %q", updated.Title)
 	}
 	if updated.UpdatedAt != before.UpdatedAt {
-		t.Fatalf("UpdatedAt must not change on retitle: before=%q after=%q", before.UpdatedAt, updated.UpdatedAt)
+		t.Fatalf("UpdatedAt must not change on rename: before=%q after=%q", before.UpdatedAt, updated.UpdatedAt)
 	}
 	if updated.EventCount != before.EventCount {
 		t.Fatalf("EventCount changed: before=%d after=%d", before.EventCount, updated.EventCount)
@@ -67,7 +67,7 @@ func TestUpdateTitle(t *testing.T) {
 
 	// An unchanged title is a no-op (still succeeds).
 	if _, err := store.UpdateTitle(session.SessionID, "Clean Generated Title"); err != nil {
-		t.Fatalf("no-op retitle should succeed: %v", err)
+		t.Fatalf("no-op rename should succeed: %v", err)
 	}
 
 	// An invalid session id is rejected.
@@ -76,6 +76,30 @@ func TestUpdateTitle(t *testing.T) {
 	}
 }
 
+func TestUpdateTitleIfCurrent(t *testing.T) {
+	store := newTitleTestStore(t)
+	session, err := store.Create(CreateInput{Title: "Automatic title"})
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+
+	updated, applied, err := store.UpdateTitleIfCurrent(session.SessionID, "Automatic title", "Generated title")
+	if err != nil || !applied || updated.Title != "Generated title" {
+		t.Fatalf("matching update = (%#v, %v, %v)", updated, applied, err)
+	}
+
+	if _, err := store.UpdateTitle(session.SessionID, "Manual title"); err != nil {
+		t.Fatalf("manual rename: %v", err)
+	}
+	updated, applied, err = store.UpdateTitleIfCurrent(session.SessionID, "Generated title", "Late generated title")
+	if err != nil {
+		t.Fatalf("stale update: %v", err)
+	}
+	if applied || updated.Title != "Manual title" {
+		t.Fatalf("stale update should preserve manual title: (%#v, %v)", updated, applied)
+	}
+}
+
 func TestUpdateModel(t *testing.T) {
 	store := newTitleTestStore(t)
 	session, err := store.Create(CreateInput{ModelID: "model-a"})

internal/sessions/store.go

@@ -45,6 +45,9 @@ const (
 	EventSpecDraft          EventType = "spec_draft"
 	EventSpecApproved       EventType = "spec_approved"
 	EventSpecRejected       EventType = "spec_rejected"
+	EventGoalCreated        EventType = "goal_created"
+	EventGoalUpdated        EventType = "goal_updated"
+	EventGoalCleared        EventType = "goal_cleared"
 )
 
 type SessionKind string
@@ -65,6 +68,29 @@ const (
 	SpecStatusRejected SpecStatus = "rejected"
 )
 
+type GoalStatus string
+
+const (
+	GoalStatusActive        GoalStatus = "active"
+	GoalStatusPaused        GoalStatus = "paused"
+	GoalStatusBlocked       GoalStatus = "blocked"
+	GoalStatusBudgetLimited GoalStatus = "budget_limited"
+	GoalStatusUsageLimited  GoalStatus = "usage_limited"
+	GoalStatusComplete      GoalStatus = "complete"
+)
+
+type Goal struct {
+	Objective         string     `json:"objective"`
+	Status            GoalStatus `json:"status"`
+	StatusReason      string     `json:"statusReason,omitempty"`
+	TokenBudget       int        `json:"tokenBudget,omitempty"`
+	TokensUsed        int        `json:"tokensUsed,omitempty"`
+	ContinuationCount int        `json:"continuationCount,omitempty"`
+	ContinuationLimit int        `json:"continuationLimit,omitempty"`
+	CreatedAt         string     `json:"createdAt"`
+	UpdatedAt         string     `json:"updatedAt"`
+}
+
 type Metadata struct {
 	SessionID           string      `json:"sessionId"`
 	SessionKind         SessionKind `json:"sessionKind,omitempty"`
@@ -91,6 +117,7 @@ type Metadata struct {
 	SpecRejectReason    string      `json:"specRejectReason,omitempty"`
 	SpecSourceSessionID string      `json:"specSourceSessionId,omitempty"`
 	SpecImplSessionID   string      `json:"specImplSessionId,omitempty"`
+	Goal                *Goal       `json:"goal,omitempty"`
 	CreatedAt           string      `json:"createdAt"`
 	UpdatedAt           string      `json:"updatedAt"`
 	EventCount          int         `json:"eventCount"`
@@ -123,6 +150,7 @@ type CreateInput struct {
 	SpecRejectReason    string
 	SpecSourceSessionID string
 	SpecImplSessionID   string
+	Goal                *Goal
 }
 
 type ForkInput struct {
@@ -279,6 +307,7 @@ func (store *Store) Create(input CreateInput) (Metadata, error) {
 		SpecRejectReason:    strings.TrimSpace(input.SpecRejectReason),
 		SpecSourceSessionID: strings.TrimSpace(input.SpecSourceSessionID),
 		SpecImplSessionID:   strings.TrimSpace(input.SpecImplSessionID),
+		Goal:                cloneGoal(input.Goal),
 		CreatedAt:           timestamp,
 		UpdatedAt:           timestamp,
 		EventCount:          0,
@@ -690,7 +719,7 @@ func (store *Store) appendPreparedEventsLocked(sessionID string, inputs []prepar
 // serialized under the same per-session lock as AppendEvent and re-reads the
 // latest metadata under that lock before rewriting, so a concurrent append can't
 // clobber the new title (nor the title clobber a concurrent append's event
-// count/timestamp). UpdatedAt is deliberately left untouched: a retitle is not
+// count/timestamp). UpdatedAt is deliberately left untouched: a rename is not
 // activity, so it must not reorder the session in the resumable list. A blank
 // title is rejected so a failed model generation can never erase a useful
 // first-message title, and an unchanged title is a no-op (no rewrite/fsync).
@@ -722,6 +751,40 @@ func (store *Store) UpdateTitle(sessionID string, title string) (Metadata, error
 	return session, nil
 }
 
+// UpdateTitleIfCurrent replaces a session title only when it still matches
+// expected. It lets background automatic naming avoid overwriting a newer manual
+// rename while keeping the check and write under the same per-session lock.
+func (store *Store) UpdateTitleIfCurrent(sessionID string, expected string, title string) (Metadata, bool, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, false, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	trimmed := strings.TrimSpace(title)
+	if trimmed == "" {
+		return Metadata{}, false, fmt.Errorf("zero session title is required")
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, false, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, false, err
+	}
+	if session.Title != strings.TrimSpace(expected) {
+		return session, false, nil
+	}
+	if session.Title == trimmed {
+		return session, true, nil
+	}
+	session.Title = trimmed
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, false, err
+	}
+	return session, true, nil
+}
+
 // UpdateModel replaces a session's selected model without changing its activity
 // timestamp or event counters. An empty model clears the session override.
 func (store *Store) UpdateModel(sessionID string, modelID string) (Metadata, error) {

internal/specialist/exec.go

@@ -167,10 +167,13 @@ const permissionModeUnsafe = "unsafe"
 var readOnlySpecialistTools = map[string]bool{
 	"read_file":          true,
 	"read_minified_file": true,
-	"list_directory":     true,
-	"grep":               true,
-	"glob":               true,
-	"update_plan":        true,
+	// Reads one image file through read_file's own path scoping and mutates
+	// nothing, so it carries the same auto-approval as the other pure readers.
+	"view_image":     true,
+	"list_directory": true,
+	"grep":           true,
+	"glob":           true,
+	"update_plan":    true,
 }
 
 // IsReadOnlySpecialist reports whether the named specialist resolves to a

internal/specialist/exec_test.go

@@ -255,7 +255,7 @@ func TestBuildArgsDefaultsToReadOnlyToolAllowlist(t *testing.T) {
 	if err != nil {
 		t.Fatalf("BuildArgs returned error: %v", err)
 	}
-	if !containsSequence(result.Args, []string{"--enabled-tools", "glob,grep,list_directory,read_file,read_minified_file"}) {
+	if !containsSequence(result.Args, []string{"--enabled-tools", "glob,grep,list_directory,read_file,read_minified_file,view_image"}) {
 		t.Fatalf("args missing default read-only allowlist: %#v", result.Args)
 	}
 }

internal/specialist/manifest.go

@@ -82,9 +82,9 @@ var knownMetadataKeys = map[string]bool{
 }
 
 var toolCategories = map[string][]string{
-	"read-only": {"read_file", "read_minified_file", "list_directory", "grep", "glob"},
-	"edit":      {"read_file", "read_minified_file", "list_directory", "grep", "glob", "write_file", "edit_file", "apply_patch"},
-	"execute":   {"read_file", "read_minified_file", "list_directory", "grep", "glob", "exec_command", "write_stdin", "bash"},
+	"read-only": {"read_file", "read_minified_file", "view_image", "list_directory", "grep", "glob"},
+	"edit":      {"read_file", "read_minified_file", "view_image", "list_directory", "grep", "glob", "write_file", "edit_file", "apply_patch"},
+	"execute":   {"read_file", "read_minified_file", "view_image", "list_directory", "grep", "glob", "exec_command", "write_stdin", "bash"},
 	"plan":      {"update_plan"},
 }
 
@@ -102,6 +102,7 @@ var defaultToolSelection = []string{"read-only"}
 var knownToolNames = map[string]bool{
 	"read_file":           true,
 	"read_minified_file":  true,
+	"view_image":          true,
 	"list_directory":      true,
 	"glob":                true,
 	"grep":                true,

internal/specialist/view_image_category_test.go

@@ -0,0 +1,31 @@
+package specialist
+
+import (
+	"slices"
+	"testing"
+)
+
+// view_image is a pure workspace-scoped read, so every category that already
+// grants read_file should grant it too. Categories are what specialist authors
+// actually write ("tools: [execute]"), so an omission here silently denies a
+// specialist the ability to look at a screenshot it just captured.
+func TestToolCategoriesIncludeViewImageWhereverReadFileIsGranted(t *testing.T) {
+	for category, names := range toolCategories {
+		if !slices.Contains(names, "read_file") {
+			continue
+		}
+		if !slices.Contains(names, "view_image") {
+			t.Errorf("category %q grants read_file but not view_image", category)
+		}
+	}
+}
+
+func TestResolveToolsExpandsExecuteToIncludeViewImage(t *testing.T) {
+	resolved, err := ResolveTools([]string{"execute"})
+	if err != nil {
+		t.Fatalf("ResolveTools: %v", err)
+	}
+	if !slices.Contains(resolved, "view_image") {
+		t.Errorf("execute resolved to %v, missing view_image", resolved)
+	}
+}

internal/swarm/lifecycle.go

@@ -12,6 +12,12 @@ import (
 // team is at its slot cap the member is queued and launches when a slot frees
 // (it stays pending in the coordinator until then).
 func (s *Swarm) Spawn(pol Policy, teamName, agentType, task, cwd string) (string, error) {
+	release, err := s.beginLifecycleAdmission()
+	if err != nil {
+		return "", err
+	}
+	defer release()
+
 	def, err := s.registry.Lookup(agentType)
 	if err != nil {
 		return "", err
@@ -23,15 +29,44 @@ func (s *Swarm) Spawn(pol Policy, teamName, agentType, task, cwd string) (string
 	}
 	s.rememberCwd(id, cwd)
 	spec := s.buildSpec(pol, id, id, team, def, task, cwd)
-	s.dispatch(spec)
+	s.dispatchAdmitted(spec)
 	return id, nil
 }
 
+// beginLifecycleAdmission admits one unit of lifecycle work if shutdown has not
+// begun. On success it returns a release func the caller MUST call exactly once
+// (a deferred call is the norm) — Close blocks until every admitted unit has
+// released. On shutdown it returns a nil func and ErrSwarmClosed, and there is
+// nothing to release.
+//
+// It deliberately does NOT keep lifecycleMu held for the caller's duration, which
+// an earlier revision did. Close needs the write lock before it can cancel, so a
+// launcher that blocks in Launch until its context is cancelled would deadlock
+// against every Close caller: the launch holds the read lock while Close waits
+// for the write lock to issue the cancellation neither side can reach. Holding the
+// lock only across the flag check and the counter increment keeps the ordering
+// guarantee (no admission once closed is set) without letting external launcher
+// code sit inside the critical section.
+//
+// The read lock is enough to make the WaitGroup safe: Close flips closed under
+// the write lock, so an Add here either completes before Close acquires it (and is
+// therefore visible to the later Wait) or observes closed and is refused.
+func (s *Swarm) beginLifecycleAdmission() (func(), error) {
+	s.lifecycleMu.RLock()
+	defer s.lifecycleMu.RUnlock()
+	if s.closed {
+		return nil, ErrSwarmClosed
+	}
+	s.lifecycleWork.Add(1)
+	return s.lifecycleWork.Done, nil
+}
+
 // dispatch admits a spec to its team (launching now or queuing for a slot).
-func (s *Swarm) dispatch(spec MemberSpec) {
+// The caller must hold an admission ticket from beginLifecycleAdmission.
+func (s *Swarm) dispatchAdmitted(spec MemberSpec) {
 	t := s.team(spec.Team)
 	if t.admit(spec) {
-		s.launch(t, spec)
+		s.launchAdmitted(t, spec)
 	}
 	// Otherwise the spec is queued; the coordinator task stays pending until a
 	// slot frees and afterExit launches it.
@@ -39,17 +74,73 @@ func (s *Swarm) dispatch(spec MemberSpec) {
 
 // launch starts a member for spec and supervises it. A synchronous launch
 // failure fails the task and frees the slot.
-func (s *Swarm) launch(t *Team, spec MemberSpec) {
-	handle, err := s.launcher.Launch(s.baseCtx, spec)
+// The caller must hold an admission ticket from beginLifecycleAdmission.
+func (s *Swarm) launchAdmitted(t *Team, spec MemberSpec) {
+	handle, err := s.launchMemberAdmitted(spec)
 	if err != nil {
 		_ = s.coord.Fail(spec.TaskID, "launch: "+err.Error())
-		s.afterExit(t)
+		if err == ErrSwarmClosed {
+			t.releaseSlot()
+			return
+		}
+		s.afterExitAdmitted(t)
 		return
 	}
-	m := &Member{ID: spec.ID, AgentType: spec.AgentType, TaskID: spec.TaskID, handle: handle}
-	t.addMember(m)
-	_ = s.coord.SetStatus(spec.TaskID, StatusRunning)
-	go s.watch(t, m, spec)
+
+	committed := s.commitLaunch(handle, func() {
+		m := &Member{ID: spec.ID, AgentType: spec.AgentType, TaskID: spec.TaskID, handle: handle}
+		t.addMember(m)
+		_ = s.coord.SetStatus(spec.TaskID, StatusRunning)
+		s.watchers.Add(1)
+		go func() {
+			defer s.watchers.Done()
+			s.watch(t, m, spec)
+		}()
+	})
+	if !committed {
+		_ = s.coord.Fail(spec.TaskID, "launch: "+ErrSwarmClosed.Error())
+		t.releaseSlot()
+	}
+}
+
+// commitLaunch closes the window between MemberLauncher.Launch returning and the
+// swarm taking ownership of the handle it produced. Launch is external code and
+// therefore runs without lifecycleMu held, so Close may have won after
+// launchMemberAdmitted's pre-check but before Launch returned. adopt runs under
+// the read lock so the shutdown check and everything the caller does to take
+// ownership (registration, status transition, watcher Add, handle swap) are
+// atomic with respect to Close setting closed and beginning its waits.
+//
+// It reports whether the handle was adopted. When shutdown won, the handle is
+// reaped before returning false: its launch context was already cancelled by
+// Close, and MemberHandle has no separate cancellation operation — Launch's
+// context is its cancellation contract — so waiting is how a
+// successfully-created process/goroutine avoids being abandoned. The caller
+// records the terminal outcome for the task it was launching.
+func (s *Swarm) commitLaunch(handle MemberHandle, adopt func()) bool {
+	s.lifecycleMu.RLock()
+	if s.closed {
+		s.lifecycleMu.RUnlock()
+		_, _ = handle.Wait()
+		return false
+	}
+	defer s.lifecycleMu.RUnlock()
+	adopt()
+	return true
+}
+
+// launchMemberAdmitted re-checks shutdown at the last internal boundary before
+// invoking the external launcher. A lifecycle ticket proves the operation won
+// admission before Close, but the caller may not reach its launch until after
+// Close has set closed; in that case no new member should be started.
+func (s *Swarm) launchMemberAdmitted(spec MemberSpec) (MemberHandle, error) {
+	s.lifecycleMu.RLock()
+	closed := s.closed
+	s.lifecycleMu.RUnlock()
+	if closed {
+		return nil, ErrSwarmClosed
+	}
+	return s.launcher.Launch(s.baseCtx, spec)
 }
 
 // watch awaits a member, applies bounded relaunch on temporary failures, records
@@ -60,42 +151,98 @@ func (s *Swarm) launch(t *Team, spec MemberSpec) {
 // life (Member.ID == MemberSpec.ID); a retry never reuses the struct for a
 // different spec.
 func (s *Swarm) watch(t *Team, m *Member, spec MemberSpec) {
-	res, err := m.handle.Wait()
-	if err != nil {
-		if isRetryable(err) && m.restarts < maxMemberRestarts {
-			if nh, relErr := s.launcher.Launch(s.baseCtx, spec); relErr == nil {
-				m.restarts++
-				m.handle = nh
-				go s.watch(t, m, spec)
-				return
+	for {
+		res, err := m.handle.Wait()
+		if err != nil {
+			if isRetryable(err) && m.restarts < maxMemberRestarts && s.relaunchAdmitted(m, spec) {
+				continue
 			}
-			// fall through to record the original error if relaunch fails
+			// Fall through if shutdown started or the relaunch failed.
+			// res.SessionID is preserved by the handle even on error, so a member that
+			// ran then failed stays drillable; a pure launch error carries an empty id.
+			_ = s.coord.FailWithSession(m.TaskID, memberError(err), res.SessionID)
+		} else {
+			_ = s.coord.CompleteWithSession(m.TaskID, res.Result, res.SessionID)
 		}
-		// res.SessionID is preserved by the handle even on error, so a member that
-		// ran then failed stays drillable; a pure launch error carries an empty id.
-		_ = s.coord.FailWithSession(m.TaskID, memberError(err), res.SessionID)
-	} else {
-		_ = s.coord.CompleteWithSession(m.TaskID, res.Result, res.SessionID)
+		break
 	}
 	t.removeMember(m.ID)
 	s.afterExit(t)
 }
 
+// relaunchAdmitted performs one bounded relaunch of an existing member's spec,
+// reporting whether the member was relaunched and its new handle adopted. A
+// relaunch is lifecycle work like any other, so it runs the same three gates an
+// initial launch does: admission (refused outright once shutdown began), the
+// pre-Launch re-check, and the post-Launch commit — the last of which matters
+// because the production FuncLauncher returns a live handle immediately without
+// consulting its context, so a Close landing between the pre-check and the return
+// would otherwise resume supervising a member started after shutdown. When any
+// gate refuses, the caller records the member's terminal failure instead.
+func (s *Swarm) relaunchAdmitted(m *Member, spec MemberSpec) bool {
+	release, err := s.beginLifecycleAdmission()
+	if err != nil {
+		return false
+	}
+	defer release()
+	handle, err := s.launchMemberAdmitted(spec)
+	if err != nil {
+		return false
+	}
+	return s.commitLaunch(handle, func() {
+		m.restarts++
+		m.handle = handle
+	})
+}
+
 // afterExit releases the just-vacated slot and launches the next queued spec, if
 // any. Each exit drains at most one queued member; that member's own exit drains
 // the next, so the queue empties one-per-slot without unbounded recursion.
 func (s *Swarm) afterExit(t *Team) {
+	release, err := s.beginLifecycleAdmission()
+	if err != nil {
+		t.releaseSlot()
+		return
+	}
+	defer release()
+	s.afterExitAdmitted(t)
+}
+
+// afterExitAdmitted drains at most one queued spec while lifecycle admission is
+// held open. The caller must hold an admission ticket from beginLifecycleAdmission.
+func (s *Swarm) afterExitAdmitted(t *Team) {
 	next, ok := t.onExit()
 	if !ok {
 		return
 	}
-	s.launch(t, next)
+	// This call's own ticket only proves shutdown hadn't begun when it was
+	// granted; Close may have set closed in the meantime, and t.onExit above
+	// already removed next from t.queue, so Close's clearQueue sweep can no
+	// longer see it (nor will it wait for one, since this ticket is what Close's
+	// lifecycleWork.Wait() is blocked on). Re-check before launching so a dequeue
+	// that straddles the shutdown boundary fails the task in place of a launch a
+	// shutting-down swarm never wanted started.
+	s.lifecycleMu.RLock()
+	closed := s.closed
+	s.lifecycleMu.RUnlock()
+	if closed {
+		t.releaseSlot()
+		_ = s.coord.Fail(next.TaskID, ErrSwarmClosed.Error())
+		return
+	}
+	s.launchAdmitted(t, next)
 }
 
 // Handoff transfers a task to a fresh member of toAgentType, delivering a note to
 // the new member's inbox and marking the original task handed-off. It returns the
 // new task id. A handoff of an already-terminal task is rejected (fail closed).
 func (s *Swarm) Handoff(pol Policy, teamName, taskID, toAgentType, note string) (string, error) {
+	release, err := s.beginLifecycleAdmission()
+	if err != nil {
+		return "", err
+	}
+	defer release()
+
 	task, ok := s.coord.Get(taskID)
 	if !ok {
 		return "", fmt.Errorf("%w: %s", ErrUnknownTask, taskID)
@@ -131,7 +278,7 @@ func (s *Swarm) Handoff(pol Policy, teamName, taskID, toAgentType, note string)
 	// Retire the original task (it has been re-delegated).
 	_ = s.coord.SetStatus(taskID, StatusHandedOff)
 	spec := s.buildSpec(pol, newID, newID, team, def, handoffTask, cwd)
-	s.dispatch(spec)
+	s.dispatchAdmitted(spec)
 	return newID, nil
 }
 
@@ -139,6 +286,12 @@ func (s *Swarm) Handoff(pol Policy, teamName, taskID, toAgentType, note string)
 // (e.g. a crashed worker) onto fresh members of toAgentType, returning the
 // adopted task ids. Terminal tasks and tasks with a live owner are left alone.
 func (s *Swarm) AdoptOrphans(pol Policy, teamName, toAgentType string) ([]string, error) {
+	release, err := s.beginLifecycleAdmission()
+	if err != nil {
+		return nil, err
+	}
+	defer release()
+
 	def, err := s.registry.Lookup(toAgentType)
 	if err != nil {
 		return nil, err
@@ -161,7 +314,7 @@ func (s *Swarm) AdoptOrphans(pol Policy, teamName, toAgentType string) ([]string
 		cwd := s.cwdFor(task.ID)
 		s.rememberCwd(task.ID, cwd)
 		spec := s.buildSpec(pol, newAgent, task.ID, team, def, task.Description, cwd)
-		s.dispatch(spec)
+		s.dispatchAdmitted(spec)
 		adopted = append(adopted, task.ID)
 	}
 	return adopted, nil

internal/swarm/lifecycle_test.go

@@ -2,6 +2,7 @@ package swarm
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"sync"
 	"testing"
@@ -217,6 +218,141 @@ func TestPermanentErrorNoRetry(t *testing.T) {
 	}
 }
 
+func TestLifecycleAdmissionRejectedAfterClose(t *testing.T) {
+	l := newLauncher(okFor)
+	sw := newSwarmFor(t, l)
+	sw.Close()
+
+	if _, err := sw.Spawn(Policy{}, "team", "teammate", "task", ""); !errors.Is(err, ErrSwarmClosed) {
+		t.Fatalf("Spawn after Close error = %v, want ErrSwarmClosed", err)
+	}
+	if _, err := sw.Handoff(Policy{}, "team", "task", "teammate", "note"); !errors.Is(err, ErrSwarmClosed) {
+		t.Fatalf("Handoff after Close error = %v, want ErrSwarmClosed", err)
+	}
+	if _, err := sw.AdoptOrphans(Policy{}, "team", "teammate"); !errors.Is(err, ErrSwarmClosed) {
+		t.Fatalf("AdoptOrphans after Close error = %v, want ErrSwarmClosed", err)
+	}
+	if got := len(l.recorded()); got != 0 {
+		t.Fatalf("launches after Close = %d, want 0", got)
+	}
+}
+
+func TestCloseDoesNotLaunchQueuedMembers(t *testing.T) {
+	gate := make(chan struct{})
+	l := newLauncher(okFor)
+	l.gate = gate
+	sw := newSwarmFor(t, l)
+
+	var ids []string
+	for i := 0; i < 3; i++ {
+		id, err := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+		if err != nil {
+			t.Fatalf("Spawn %d: %v", i, err)
+		}
+		ids = append(ids, id)
+	}
+	if got := len(l.recorded()); got != 2 {
+		t.Fatalf("initial launches = %d, want 2 with one queued", got)
+	}
+
+	sw.Close()
+	if got := len(l.recorded()); got != 2 {
+		t.Fatalf("launches after Close = %d, want queued member not launched", got)
+	}
+	for _, id := range ids {
+		task, ok := sw.Coordinator().Get(id)
+		if !ok || !task.Status.terminal() {
+			t.Fatalf("task %s after Close = %+v, want terminal", id, task)
+		}
+	}
+}
+
+func TestClosePreventsMemberRetry(t *testing.T) {
+	started := make(chan struct{}, maxMemberRestarts+1)
+	release := make(chan struct{})
+	l := FuncLauncher{Run: func(context.Context, MemberSpec) (MemberResult, error) {
+		started <- struct{}{}
+		<-release
+		return MemberResult{}, ErrMemberTemporary
+	}}
+	sw := newSwarmFor(t, l)
+	_, err := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+	if err != nil {
+		t.Fatalf("Spawn: %v", err)
+	}
+	select {
+	case <-started:
+	case <-time.After(3 * time.Second):
+		t.Fatal("initial member did not start")
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	waitFor(t, "swarm closed state", func() bool {
+		sw.lifecycleMu.RLock()
+		defer sw.lifecycleMu.RUnlock()
+		return sw.closed
+	})
+	close(release)
+	select {
+	case <-closed:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Close did not return after retryable member exit")
+	}
+	select {
+	case <-started:
+		t.Fatal("member retried after Close")
+	default:
+	}
+}
+
+func TestCloseWaitsForMemberWatchers(t *testing.T) {
+	release := make(chan struct{})
+	l := FuncLauncher{Run: func(context.Context, MemberSpec) (MemberResult, error) {
+		<-release
+		return MemberResult{Result: "done"}, nil
+	}}
+	sw := newSwarmFor(t, l)
+	id, err := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+	if err != nil {
+		t.Fatalf("Spawn: %v", err)
+	}
+	waitFor(t, "task running", func() bool {
+		task, ok := sw.Coordinator().Get(id)
+		return ok && task.Status == StatusRunning
+	})
+
+	const callers = 3
+	closing := make(chan struct{}, callers)
+	closed := make(chan struct{}, callers)
+	for i := 0; i < callers; i++ {
+		go func() {
+			closing <- struct{}{}
+			sw.Close()
+			closed <- struct{}{}
+		}()
+	}
+	for i := 0; i < callers; i++ {
+		<-closing
+	}
+	select {
+	case <-closed:
+		t.Fatal("a Close caller returned before the member watcher exited")
+	case <-time.After(50 * time.Millisecond):
+	}
+	close(release)
+	for i := 0; i < callers; i++ {
+		select {
+		case <-closed:
+		case <-time.After(3 * time.Second):
+			t.Fatal("all Close callers did not return after the member watcher exited")
+		}
+	}
+}
+
 func TestHandoffDeliversNoteAndRetiresOriginal(t *testing.T) {
 	gate := make(chan struct{})
 	l := newLauncher(okFor)
@@ -364,3 +500,587 @@ func TestSpawnUnknownAgentType(t *testing.T) {
 		t.Fatal("Spawn with unknown agent type must error")
 	}
 }
+
+// blockingLauncher blocks inside Launch until its context is cancelled — the
+// shape of a real launcher that waits on a slot, a daemon connection, or a
+// sandbox handshake before it can return a handle.
+type blockingLauncher struct {
+	entered chan struct{}
+	once    sync.Once
+}
+
+func (l *blockingLauncher) Launch(ctx context.Context, spec MemberSpec) (MemberHandle, error) {
+	l.once.Do(func() { close(l.entered) })
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+
+// TestCloseCancelsLauncherBlockedInLaunch is the regression test for holding
+// lifecycle admission across MemberLauncher.Launch. When admission was a read lock
+// held for the caller's whole duration, this deadlocked: the spawn sat inside
+// Launch waiting for its context, while Close waited for the write lock it needed
+// before it could cancel that very context. Neither side could progress, so both
+// the spawn and every Close caller hung.
+//
+// Admission is now a counted ticket, so Close can flip the flag, cancel, and then
+// wait the ticket out.
+func TestCloseCancelsLauncherBlockedInLaunch(t *testing.T) {
+	launcher := &blockingLauncher{entered: make(chan struct{})}
+	sw := newSwarmFor(t, launcher)
+
+	spawned := make(chan error, 1)
+	go func() {
+		_, err := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+		spawned <- err
+	}()
+	select {
+	case <-launcher.entered:
+	case <-time.After(3 * time.Second):
+		t.Fatal("launcher never entered Launch")
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	select {
+	case <-closed:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Close deadlocked against a launcher blocked in Launch")
+	}
+	select {
+	case <-spawned:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Spawn never returned after Close cancelled the launch context")
+	}
+}
+
+// TestCloseWaitsForAdmittedSpawn pins the other half of the contract: Close is a
+// barrier, so it must not return while an admitted spawn is still running. Without
+// the lifecycleWork wait, Close could finish while this launch was mid-flight.
+func TestCloseWaitsForAdmittedSpawn(t *testing.T) {
+	entered := make(chan struct{})
+	finish := make(chan struct{})
+	launcher := &gatedLaunchLauncher{entered: entered, finish: finish}
+	sw := newSwarmFor(t, launcher)
+
+	go func() {
+		_, _ = sw.Spawn(Policy{}, "team", "teammate", "task", "")
+	}()
+	select {
+	case <-entered:
+	case <-time.After(3 * time.Second):
+		t.Fatal("launcher never entered Launch")
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	select {
+	case <-closed:
+		t.Fatal("Close returned while an admitted spawn was still in flight")
+	case <-time.After(200 * time.Millisecond):
+	}
+	close(finish)
+	select {
+	case <-closed:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Close did not return after the admitted spawn finished")
+	}
+}
+
+// TestAdmittedDispatchDoesNotLaunchAfterClose covers an operation that won a
+// lifecycle ticket before shutdown but did not reach dispatch until after Close
+// set closed. The ticket keeps Close from returning early, but it must not permit
+// a new external launch with the already-cancelled swarm context.
+func TestAdmittedDispatchDoesNotLaunchAfterClose(t *testing.T) {
+	l := newLauncher(okFor)
+	sw := newSwarmFor(t, l)
+	sw.maxTeamSize = 1
+
+	if _, err := sw.coord.Register("late-task", "late-agent", "team", "late work"); err != nil {
+		t.Fatalf("Register late task: %v", err)
+	}
+	release, err := sw.beginLifecycleAdmission()
+	if err != nil {
+		t.Fatalf("beginLifecycleAdmission: %v", err)
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	waitFor(t, "swarm closed state", func() bool {
+		sw.lifecycleMu.RLock()
+		defer sw.lifecycleMu.RUnlock()
+		return sw.closed
+	})
+
+	sw.dispatchAdmitted(MemberSpec{
+		ID: "late-agent", TaskID: "late-task", AgentType: "teammate", Team: "team",
+	})
+	release()
+
+	select {
+	case <-closed:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Close did not return after the admitted dispatch finished")
+	}
+	if got := len(l.recorded()); got != 0 {
+		t.Fatalf("launches after closed was set = %d, want 0", got)
+	}
+	team := sw.team("team")
+	if got := team.Running(); got != 0 {
+		t.Fatalf("team running after rejected launch = %d, want 0", got)
+	}
+	task, ok := sw.Coordinator().Get("late-task")
+	if !ok {
+		t.Fatal("late task vanished")
+	}
+	if task.Status != StatusFailed || !strings.Contains(task.Err, ErrSwarmClosed.Error()) {
+		t.Fatalf("late task after Close = %+v, want failed with ErrSwarmClosed", task)
+	}
+}
+
+// TestCloseBetweenLaunchPrecheckAndReturn rejects and reaps a handle created by
+// a Launch that straddles shutdown. The launch has passed the pre-check when it
+// enters the gate; Close then sets closed and cancels its context before the
+// launcher is allowed to return successfully.
+func TestCloseBetweenLaunchPrecheckAndReturn(t *testing.T) {
+	launcher := &closeRaceLauncher{
+		entered: make(chan struct{}),
+		finish:  make(chan struct{}),
+		waited:  make(chan struct{}),
+	}
+	sw := newSwarmFor(t, launcher)
+
+	spawned := make(chan string, 1)
+	go func() {
+		id, _ := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+		spawned <- id
+	}()
+	select {
+	case <-launcher.entered:
+	case <-time.After(3 * time.Second):
+		t.Fatal("launcher never entered Launch")
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	waitFor(t, "swarm closed state", func() bool {
+		sw.lifecycleMu.RLock()
+		defer sw.lifecycleMu.RUnlock()
+		return sw.closed
+	})
+	close(launcher.finish)
+
+	var id string
+	select {
+	case id = <-spawned:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Spawn did not return after Launch")
+	}
+	select {
+	case <-closed:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Close did not return after late handle was reaped")
+	}
+	select {
+	case <-launcher.waited:
+	default:
+		t.Fatal("late handle was not reaped")
+	}
+
+	team := sw.team("team")
+	if got := team.Running(); got != 0 {
+		t.Fatalf("team running after close-raced Launch = %d, want 0", got)
+	}
+	if got := len(team.liveAgents()); got != 0 {
+		t.Fatalf("registered members after close-raced Launch = %d, want 0", got)
+	}
+	task, ok := sw.Coordinator().Get(id)
+	if !ok {
+		t.Fatal("task vanished")
+	}
+	if task.Status != StatusFailed || !strings.Contains(task.Err, ErrSwarmClosed.Error()) {
+		t.Fatalf("task after close-raced Launch = %+v, want failed with ErrSwarmClosed", task)
+	}
+}
+
+type closeRaceLauncher struct {
+	entered chan struct{}
+	finish  chan struct{}
+	waited  chan struct{}
+	once    sync.Once
+}
+
+func (l *closeRaceLauncher) Launch(ctx context.Context, spec MemberSpec) (MemberHandle, error) {
+	l.once.Do(func() { close(l.entered) })
+	<-l.finish
+	return &closeRaceHandle{id: spec.ID, ctx: ctx, waited: l.waited}, nil
+}
+
+type closeRaceHandle struct {
+	id     string
+	ctx    context.Context
+	waited chan struct{}
+	once   sync.Once
+}
+
+func (h *closeRaceHandle) ID() string { return h.id }
+
+func (h *closeRaceHandle) Wait() (MemberResult, error) {
+	<-h.ctx.Done()
+	h.once.Do(func() { close(h.waited) })
+	return MemberResult{}, h.ctx.Err()
+}
+
+// TestCloseBetweenRetryLaunchPrecheckAndReturn is the retry counterpart of
+// TestCloseBetweenLaunchPrecheckAndReturn: a bounded relaunch wins admission and
+// passes the pre-check, then Close lands while the launcher is inside Launch. The
+// relaunched handle must be reaped rather than adopted, so the watcher never
+// resumes supervising a member started after shutdown began — a relaunch whose
+// member goes on to succeed must not be recorded as the task's outcome.
+func TestCloseBetweenRetryLaunchPrecheckAndReturn(t *testing.T) {
+	launcher := &retryCloseRaceLauncher{
+		entered: make(chan struct{}),
+		finish:  make(chan struct{}),
+		late:    &retryLateHandle{id: "teammate-1"},
+	}
+	sw := newSwarmFor(t, launcher)
+
+	id, err := sw.Spawn(Policy{}, "team", "teammate", "task", "")
+	if err != nil {
+		t.Fatalf("Spawn: %v", err)
+	}
+	// The first member exits retryable, so the watcher is now inside the relaunch.
+	select {
+	case <-launcher.entered:
+	case <-time.After(3 * time.Second):
+		t.Fatal("launcher never entered the relaunch Launch")
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	waitFor(t, "swarm closed state", func() bool {
+		sw.lifecycleMu.RLock()
+		defer sw.lifecycleMu.RUnlock()
+		return sw.closed
+	})
+	close(launcher.finish)
+
+	select {
+	case <-closed:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Close did not return after the late relaunch handle was reaped")
+	}
+	if got := launcher.launchCount(); got != 2 {
+		t.Fatalf("launch attempts = %d, want 2 (initial + one relaunch)", got)
+	}
+	if got := launcher.late.waitCount(); got != 1 {
+		t.Fatalf("late relaunch handle waits = %d, want 1 (reaped, not supervised)", got)
+	}
+
+	team := sw.team("team")
+	if got := team.Running(); got != 0 {
+		t.Fatalf("team running after close-raced relaunch = %d, want 0", got)
+	}
+	if got := len(team.liveAgents()); got != 0 {
+		t.Fatalf("registered members after close-raced relaunch = %d, want 0", got)
+	}
+	task, ok := sw.Coordinator().Get(id)
+	if !ok {
+		t.Fatal("task vanished")
+	}
+	if task.Status != StatusFailed {
+		t.Fatalf("task after close-raced relaunch = %+v, want failed, not the late member's outcome", task)
+	}
+	if task.Result != "" {
+		t.Fatalf("task result after close-raced relaunch = %q, want the late member's result discarded", task.Result)
+	}
+}
+
+// retryCloseRaceLauncher fails its first member with a retryable error, then
+// blocks inside the relaunch's Launch until the test releases it.
+type retryCloseRaceLauncher struct {
+	mu      sync.Mutex
+	calls   int
+	entered chan struct{}
+	finish  chan struct{}
+	late    *retryLateHandle
+	once    sync.Once
+}
+
+func (l *retryCloseRaceLauncher) Launch(_ context.Context, spec MemberSpec) (MemberHandle, error) {
+	l.mu.Lock()
+	l.calls++
+	first := l.calls == 1
+	l.mu.Unlock()
+	if first {
+		return &temporaryHandle{id: spec.ID}, nil
+	}
+	l.once.Do(func() { close(l.entered) })
+	<-l.finish
+	return l.late, nil
+}
+
+func (l *retryCloseRaceLauncher) launchCount() int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.calls
+}
+
+// temporaryHandle exits immediately with a retryable error, driving the watcher
+// into its bounded relaunch path.
+type temporaryHandle struct{ id string }
+
+func (h *temporaryHandle) ID() string { return h.id }
+
+func (h *temporaryHandle) Wait() (MemberResult, error) {
+	return MemberResult{}, ErrMemberTemporary
+}
+
+// retryLateHandle models a member whose work does not consult the cancelled
+// launch context and reports success. Adopting it after shutdown would record a
+// post-close result on the task, so a correct shutdown reaps it exactly once and
+// discards what it returns.
+type retryLateHandle struct {
+	id    string
+	mu    sync.Mutex
+	waits int
+}
+
+func (h *retryLateHandle) ID() string { return h.id }
+
+func (h *retryLateHandle) Wait() (MemberResult, error) {
+	h.mu.Lock()
+	h.waits++
+	h.mu.Unlock()
+	return MemberResult{Result: "late result", SessionID: "late-session"}, nil
+}
+
+func (h *retryLateHandle) waitCount() int {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.waits
+}
+
+func TestCloseRacesLifecycleAdmission(t *testing.T) {
+	gate := make(chan struct{})
+	l := newLauncher(okFor)
+	l.gate = gate
+	sw := newSwarmFor(t, l)
+
+	const spawns = 64
+	start := make(chan struct{})
+	results := make(chan struct {
+		id  string
+		err error
+	}, spawns)
+	var callers sync.WaitGroup
+	callers.Add(spawns)
+	for i := 0; i < spawns; i++ {
+		go func() {
+			defer callers.Done()
+			<-start
+			id, err := sw.Spawn(Policy{}, "team", "teammate", "racing task", "")
+			results <- struct {
+				id  string
+				err error
+			}{id: id, err: err}
+		}()
+	}
+	closed := make(chan struct{})
+	go func() {
+		<-start
+		sw.Close()
+		close(closed)
+	}()
+
+	close(start)
+	callers.Wait()
+	<-closed
+	close(results)
+
+	for result := range results {
+		if result.err != nil {
+			if !errors.Is(result.err, ErrSwarmClosed) {
+				t.Fatalf("Spawn racing Close error = %v, want ErrSwarmClosed", result.err)
+			}
+			continue
+		}
+		task, ok := sw.Coordinator().Get(result.id)
+		if !ok || !task.Status.terminal() {
+			t.Fatalf("admitted task %q after Close = %+v, want terminal", result.id, task)
+		}
+	}
+	for _, task := range sw.Coordinator().List() {
+		if !task.Status.terminal() {
+			t.Fatalf("task %q remained %s after Close", task.ID, task.Status)
+		}
+	}
+}
+
+// TestCloseFailsQueuedSpecOnLateCreatedTeam is the regression test for queue
+// sweeping after shutdown begins. Spawn/Handoff/AdoptOrphans calls that obtained
+// tickets before closed flipped can still create a team and append to its queue.
+// Close must wait for those calls before both snapshotting teams and sweeping
+// their queues, or a late-created team's queued task remains pending forever.
+//
+// This drives that interleaving directly: two operations obtain tickets before
+// Close, then the first creates and fills a previously unseen one-slot team and
+// the second queues behind it after Close has flipped closed.
+func TestCloseFailsQueuedSpecOnLateCreatedTeam(t *testing.T) {
+	sw := newSwarmFor(t, newLauncher(okFor))
+	sw.maxTeamSize = 1
+
+	if _, err := sw.coord.Register("late-task", "late-agent", "team", "late work"); err != nil {
+		t.Fatalf("Register late task: %v", err)
+	}
+	firstRelease, err := sw.beginLifecycleAdmission()
+	if err != nil {
+		t.Fatalf("first beginLifecycleAdmission: %v", err)
+	}
+	secondRelease, err := sw.beginLifecycleAdmission()
+	if err != nil {
+		firstRelease()
+		t.Fatalf("second beginLifecycleAdmission: %v", err)
+	}
+	runningSpec := MemberSpec{ID: "running-agent", TaskID: "running-task", AgentType: "teammate", Team: "team"}
+	queuedSpec := MemberSpec{ID: "late-agent", TaskID: "late-task", AgentType: "teammate", Team: "team"}
+
+	closed := make(chan struct{})
+	go func() {
+		sw.Close()
+		close(closed)
+	}()
+	waitFor(t, "swarm closed state", func() bool {
+		sw.lifecycleMu.RLock()
+		defer sw.lifecycleMu.RUnlock()
+		return sw.closed
+	})
+	select {
+	case <-closed:
+		t.Fatal("Close returned while an admitted ticket was still open")
+	default:
+	}
+
+	// Neither operation touched a team before Close took its old, buggy snapshot.
+	// Finish the team-admission portion of both operations while their tickets are
+	// still held: the first creates the team and fills its only slot; the second
+	// appends to that late-created team's queue.
+	team := sw.team("team")
+	if !team.admit(runningSpec) {
+		t.Fatal("first spec should take the late-created team's only slot")
+	}
+	firstRelease()
+	if team.admit(queuedSpec) {
+		t.Fatal("second spec should queue on the late-created team")
+	}
+	secondRelease()
+
+	select {
+	case <-closed:
+	case <-time.After(3 * time.Second):
+		t.Fatal("Close did not return after the admitted ticket released")
+	}
+
+	if got := team.QueueDepth(); got != 0 {
+		t.Fatalf("queue depth after Close = %d, want 0 (late spec swept)", got)
+	}
+	task, ok := sw.Coordinator().Get("late-task")
+	if !ok {
+		t.Fatal("late-queued task vanished")
+	}
+	if task.Status != StatusFailed {
+		t.Fatalf("late-queued task status = %v, want %v (failed, not stranded)", task.Status, StatusFailed)
+	}
+	if !strings.Contains(task.Err, ErrSwarmClosed.Error()) {
+		t.Fatalf("late-queued task err = %q, want it to mention %q", task.Err, ErrSwarmClosed.Error())
+	}
+}
+
+// TestAfterExitAdmittedFailsDequeuedSpecAfterClose is the regression test for
+// jatmn's second #776 finding: afterExitAdmitted used to dequeue a queued spec
+// (t.onExit) and launch it unconditionally once its own ticket was granted,
+// even though Close can flip closed in the gap between that dequeue — which
+// makes the spec invisible to Close's clearQueue sweep — and the launch. A
+// launcher that performs work before honoring its cancelled context could then
+// start a brand new worker after shutdown had already begun.
+func TestAfterExitAdmittedFailsDequeuedSpecAfterClose(t *testing.T) {
+	l := newLauncher(okFor)
+	sw := newSwarmFor(t, l)
+
+	if _, err := sw.coord.Register("queued-task", "queued-agent", "team", "queued work"); err != nil {
+		t.Fatalf("Register: %v", err)
+	}
+	spec := MemberSpec{ID: "queued-agent", TaskID: "queued-task", AgentType: "teammate", Team: "team"}
+
+	// Occupy the only slot, then queue spec behind it.
+	team := &Team{Name: "team", members: map[string]*Member{}, maxSize: 1}
+	if !team.admit(MemberSpec{ID: "running-agent", TaskID: "running-task"}) {
+		t.Fatal("first spec should take the only slot")
+	}
+	if team.admit(spec) {
+		t.Fatal("second spec should queue, not launch, over the cap")
+	}
+
+	// Simulate shutdown racing in between this call's ticket admission (already
+	// granted, hence no beginLifecycleAdmission call here) and its dequeue+launch,
+	// exactly like the finding describes: closed is already set by the time
+	// afterExitAdmitted's post-dequeue check runs.
+	sw.lifecycleMu.Lock()
+	sw.closed = true
+	sw.lifecycleMu.Unlock()
+
+	sw.afterExitAdmitted(team) // running-agent "exits" -> dequeues spec
+
+	if got := team.Running(); got != 0 {
+		t.Fatalf("team running after close-raced drain = %d, want 0 (slot released, not held for a launch)", got)
+	}
+	task, ok := sw.Coordinator().Get("queued-task")
+	if !ok {
+		t.Fatal("dequeued task vanished")
+	}
+	if task.Status != StatusFailed {
+		t.Fatalf("dequeued task status = %v, want %v (failed, not launched)", task.Status, StatusFailed)
+	}
+	if !strings.Contains(task.Err, ErrSwarmClosed.Error()) {
+		t.Fatalf("dequeued task err = %q, want it to mention %q", task.Err, ErrSwarmClosed.Error())
+	}
+	for _, s := range l.recorded() {
+		if s.ID == "queued-agent" {
+			t.Fatal("a spec dequeued after shutdown began must never launch")
+		}
+	}
+}
+
+// gatedLaunchLauncher blocks in Launch until the test releases it, ignoring
+// context cancellation so the test controls exactly when the admitted work ends.
+type gatedLaunchLauncher struct {
+	entered chan struct{}
+	finish  chan struct{}
+	once    sync.Once
+}
+
+func (l *gatedLaunchLauncher) Launch(_ context.Context, spec MemberSpec) (MemberHandle, error) {
+	l.once.Do(func() { close(l.entered) })
+	<-l.finish
+	return &funcHandle{id: spec.ID, done: closedChan()}, nil
+}
+
+func closedChan() chan struct{} {
+	ch := make(chan struct{})
+	close(ch)
+	return ch
+}

internal/swarm/scheduler.go

@@ -121,11 +121,12 @@ type Scheduler struct {
 	ctx    context.Context
 	cancel context.CancelFunc
 
-	mu     sync.Mutex
-	jobs   map[string]*scheduledJob
-	closed bool
-	seq    atomic.Uint64
-	wg     sync.WaitGroup
+	mu        sync.Mutex
+	jobs      map[string]*scheduledJob
+	closed    bool
+	seq       atomic.Uint64
+	wg        sync.WaitGroup
+	closeOnce sync.Once
 }
 
 // newScheduler builds a Scheduler bound to sw. Its context derives from the
@@ -229,15 +230,13 @@ func (s *Scheduler) List() []JobStatus {
 // Close cancels every job and waits for their loops to exit. Safe to call more
 // than once.
 func (s *Scheduler) Close() {
-	s.mu.Lock()
-	if s.closed {
+	s.closeOnce.Do(func() {
+		s.mu.Lock()
+		s.closed = true
+		s.cancel()
 		s.mu.Unlock()
-		return
-	}
-	s.closed = true
-	s.cancel()
-	s.mu.Unlock()
-	s.wg.Wait()
+		s.wg.Wait()
+	})
 }
 
 // run is one job's timing loop. It requests a fresh one-shot ticker per interval

internal/swarm/scheduler_test.go

@@ -164,6 +164,25 @@ func TestSchedulerCloseStopsJobs(t *testing.T) {
 	}
 }
 
+func TestSchedulerCreatedAfterSwarmCloseIsClosed(t *testing.T) {
+	sw := newSwarmFor(t, newLauncher(okFor))
+	sw.Close()
+
+	sched := sw.Scheduler()
+	sched.mu.Lock()
+	closed := sched.closed
+	sched.mu.Unlock()
+	if !closed {
+		t.Fatal("scheduler created after Swarm.Close was not closed")
+	}
+	if _, err := sched.Add(Policy{}, "team", "teammate", "t", "", Schedule{Every: time.Hour}); err == nil {
+		t.Fatal("Add on a scheduler created after Swarm.Close should fail")
+	}
+	if got := len(sched.List()); got != 0 {
+		t.Fatalf("scheduler created after Swarm.Close has %d jobs, want 0", got)
+	}
+}
+
 func TestSchedulerAddRejectedAfterContextCancel(t *testing.T) {
 	sw := newSwarmFor(t, newLauncher(okFor))
 	sched := sw.Scheduler()

internal/swarm/team.go

@@ -64,6 +64,18 @@ type Swarm struct {
 	baseCtx context.Context
 	cancel  context.CancelFunc
 
+	// lifecycleMu guards closed and orders admission against shutdown. It is held
+	// only for the flag check plus the lifecycleWork increment — never across a
+	// launcher call, which would deadlock Close (see beginLifecycleAdmission).
+	lifecycleMu sync.RWMutex
+	closed      bool
+	// lifecycleWork counts admitted-but-unfinished lifecycle operations (spawn,
+	// handoff, adoption, retry, queue drain). Close waits it out so no admitted
+	// operation is still touching the swarm when Close returns.
+	lifecycleWork sync.WaitGroup
+	watchers      sync.WaitGroup
+	closeOnce     sync.Once
+
 	mu        sync.Mutex
 	teams     map[string]*Team
 	taskCwd   map[string]string // taskID -> cwd, for handoff/adoption relaunch
@@ -137,31 +149,93 @@ func New(opts Options) (*Swarm, error) {
 }
 
 // Close cancels every running member's context and releases resources. It is
-// safe to call more than once. The scheduler is closed first so no new spawn
-// fires after shutdown begins.
+// safe to call more than once. It closes lifecycle admission before canceling
+// members, fails queued tasks, and waits for every member watcher to exit.
 func (s *Swarm) Close() {
-	s.mu.Lock()
-	sched := s.scheduler
-	s.mu.Unlock()
-	if sched != nil {
-		sched.Close()
-	}
-	if s.cancel != nil {
-		s.cancel()
-	}
+	s.closeOnce.Do(func() {
+		// Closing admission and cancelling are separate steps on purpose. The flag
+		// flips under lifecycleMu so no further work is admitted, and the lock is
+		// released BEFORE cancelling: a member already being launched holds no lock
+		// here, but it may be blocked inside MemberLauncher.Launch waiting for the
+		// context this cancel provides, and it can only release its admission ticket
+		// once that cancellation lands.
+		s.lifecycleMu.Lock()
+		s.closed = true
+		s.mu.Lock()
+		sched := s.scheduler
+		s.mu.Unlock()
+		s.lifecycleMu.Unlock()
+
+		if s.cancel != nil {
+			s.cancel()
+		}
+		if sched != nil {
+			sched.Close()
+		}
+		// Wait for every already-admitted lifecycle operation (spawn, handoff,
+		// adoption, retry, queue drain) to finish BEFORE sweeping queues below.
+		// Such work can create teams as well as append to their queues, so snapshot
+		// the teams only after every ticket is back. At that point no team or queue
+		// can gain a new entry, and the sweep cannot miss late-admitted work.
+		s.lifecycleWork.Wait()
+		s.mu.Lock()
+		teams := make([]*Team, 0, len(s.teams))
+		for _, team := range s.teams {
+			teams = append(teams, team)
+		}
+		s.mu.Unlock()
+		for _, team := range teams {
+			for _, spec := range team.clearQueue() {
+				_ = s.coord.Fail(spec.TaskID, ErrSwarmClosed.Error())
+			}
+		}
+		// Every watcher is added while its admitting lifecycle ticket is still held,
+		// so lifecycleWork.Wait above also orders every Add before this Wait. The
+		// watcher itself can outlive that ticket, which is why both waits are needed.
+		s.watchers.Wait()
+	})
 }
 
 // Scheduler returns the swarm's recurring-spawn scheduler, creating it on first
 // use. Scheduling is opt-in: until a job is added the scheduler does nothing.
+//
+// The post-close handoff between this method and Close relies on the ORDER in
+// which each reads/writes s.scheduler and s.closed, not on holding one lock across
+// both: Close takes lifecycleMu.Lock() (excluding this RLock), sets closed, reads
+// whatever s.scheduler currently is, and only THEN releases lifecycleMu and calls
+// sched.Close() on what it captured. So a call here either:
+//   - runs entirely before Close's write lock — sees closed == false, and the
+//     scheduler it creates/returns is exactly the one Close's later snapshot will
+//     capture and close; or
+//   - runs entirely after Close's write lock — sees closed == true (memory model:
+//     the RLock/Lock pair orders the read after Close's write) and closes the
+//     scheduler itself here, because Close already captured its own snapshot
+//     (possibly nil, if this call is what first creates one) and will not look
+//     again.
+//
+// Either way exactly one of the two call sites closes the scheduler that ends up
+// installed, and neither can observe a "created after close but never closed"
+// scheduler — that would require reading closed == false here while also reading
+// a scheduler Close had already passed over, which the lock ordering rules out.
 func (s *Swarm) Scheduler() *Scheduler {
+	s.lifecycleMu.RLock()
+	closed := s.closed
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.scheduler == nil {
 		s.scheduler = newScheduler(s)
 	}
-	return s.scheduler
+	sched := s.scheduler
+	s.mu.Unlock()
+	s.lifecycleMu.RUnlock()
+	if closed {
+		sched.Close()
+	}
+	return sched
 }
 
+// ErrSwarmClosed reports lifecycle work submitted after shutdown begins.
+var ErrSwarmClosed = errors.New("swarm: closed")
+
 // rememberCwd records a task's working dir so a handoff/adoption relaunch keeps it.
 func (s *Swarm) rememberCwd(taskID, cwd string) {
 	s.mu.Lock()
@@ -288,6 +362,22 @@ func (t *Team) onExit() (MemberSpec, bool) {
 	return MemberSpec{}, false
 }
 
+func (t *Team) releaseSlot() {
+	t.mu.Lock()
+	if t.running > 0 {
+		t.running--
+	}
+	t.mu.Unlock()
+}
+
+func (t *Team) clearQueue() []MemberSpec {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	queued := t.queue
+	t.queue = nil
+	return queued
+}
+
 func (t *Team) addMember(m *Member) {
 	t.mu.Lock()
 	t.members[m.ID] = m

internal/tools/apply_patch.go

@@ -80,8 +80,19 @@ func (tool applyPatchTool) RunWithOptions(ctx context.Context, args map[string]a
 		return errorResult("Error applying patch: " + err.Error())
 	}
 	var createdTargets []string
+	var fullySuppliedTargets []string
+	wholeBefore := map[string]bool{}
 	if options.FileTracker != nil {
 		createdTargets = missingPatchTargets(applyRoot, patch)
+		fullySuppliedTargets = completeCreatedPatchTargets(applyRoot, patch)
+		for _, path := range patchHeaderPaths(patch) {
+			if path == "" || path == "/dev/null" {
+				continue
+			}
+			if absolute, _, rerr := resolveWorkspaceTargetPath(applyRoot, path); rerr == nil {
+				wholeBefore[absolute] = options.FileTracker.SeenWhole(absolute)
+			}
+		}
 	}
 
 	command := exec.CommandContext(ctx, "git", "apply", "--whitespace=nowarn", patchPath)
@@ -102,13 +113,28 @@ func (tool applyPatchTool) RunWithOptions(ctx context.Context, args map[string]a
 	result := okResult(summary)
 	result.ChangedFiles = changedFilesFromPatch(relativeRoot, patch)
 	result.Display = Display{Summary: summary, Kind: "diff", Preview: capPreviewDiff(patch)}
-	// git apply already rejects a patch whose context drifted, so it has its own
-	// staleness guard. Drop any tracked baseline for the files it rewrote so a
-	// subsequent edit_file/write_file re-reads instead of false-flagging the
-	// patch's own change as an external modification.
+	fullySupplied := make(map[string]bool, len(fullySuppliedTargets))
+	for _, absolute := range fullySuppliedTargets {
+		fullySupplied[absolute] = true
+	}
+	// Re-baseline files changed by this tool. When the model had already seen the
+	// whole input (or supplied a complete new file), the exact patch plus that
+	// input determines the whole output, so a follow-up edit needs no wasted read.
+	// Partial observations remain conservative and are cleared by Record.
 	for _, changed := range result.ChangedFiles {
 		if absolute, _, rerr := resolveScopedPath(tool.workspaceRoot, tool.scope, changed); rerr == nil {
-			options.FileTracker.Forget(absolute)
+			content, readErr := os.ReadFile(absolute)
+			if readErr != nil {
+				options.FileTracker.Forget(absolute)
+				continue
+			}
+			info, _ := os.Stat(absolute)
+			wasWhole := wholeBefore[absolute] || fullySupplied[absolute]
+			options.FileTracker.Record(absolute, content, info)
+			if wasWhole {
+				lines := lineCount(string(content))
+				options.FileTracker.RecordSeenRange(absolute, 1, lines, lines)
+			}
 		}
 	}
 	recordCreatedPatchTargets(options.FileTracker, createdTargets)
@@ -134,6 +160,60 @@ func missingPatchTargets(root string, patch string) []string {
 	return missing
 }
 
+// completeCreatedPatchTargets returns only files whose full contents are
+// supplied by a /dev/null creation patch. A missing rename/copy destination is
+// created by git too, but its bytes come from an unread source and must not gain
+// whole-file observation credit.
+func completeCreatedPatchTargets(root string, patch string) []string {
+	seen := map[string]bool{}
+	var created []string
+	oldRemaining, newRemaining := 0, 0
+	inHunk := false
+	fromDevNull := false
+	for _, line := range strings.Split(strings.ReplaceAll(patch, "\r\n", "\n"), "\n") {
+		if inHunk && (oldRemaining > 0 || newRemaining > 0) {
+			switch {
+			case strings.HasPrefix(line, "-"):
+				oldRemaining--
+			case strings.HasPrefix(line, "+"):
+				newRemaining--
+			case strings.HasPrefix(line, "\\"):
+			default:
+				oldRemaining--
+				newRemaining--
+			}
+			continue
+		}
+		inHunk = false
+		switch {
+		case strings.HasPrefix(line, "diff --git "):
+			fromDevNull = false
+		case strings.HasPrefix(line, "@@"):
+			oldRemaining, newRemaining = parseHunkCounts(line)
+			inHunk = oldRemaining > 0 || newRemaining > 0
+		case strings.HasPrefix(line, "--- "):
+			fromDevNull = patchFileHeaderPath(line) == "/dev/null"
+		case strings.HasPrefix(line, "+++ "):
+			path := patchFileHeaderPath(line)
+			if !fromDevNull || path == "" || path == "/dev/null" {
+				fromDevNull = false
+				continue
+			}
+			fromDevNull = false
+			absolute, _, err := resolveWorkspaceTargetPath(root, stripPatchPrefix(path))
+			if err != nil || seen[absolute] {
+				continue
+			}
+			if _, err := os.Stat(absolute); !os.IsNotExist(err) {
+				continue
+			}
+			seen[absolute] = true
+			created = append(created, absolute)
+		}
+	}
+	return created
+}
+
 func recordCreatedPatchTargets(tracker *FileTracker, missingBefore []string) {
 	if tracker == nil {
 		return
@@ -240,15 +320,7 @@ func patchHeaderPaths(patch string) []string {
 			oldRemaining, newRemaining = parseHunkCounts(line)
 			inHunk = oldRemaining > 0 || newRemaining > 0
 		case strings.HasPrefix(line, "--- "), strings.HasPrefix(line, "+++ "):
-			// Take everything after the fixed 4-char prefix instead of splitting on
-			// spaces, so a path that contains spaces survives. Drop a trailing
-			// tab-delimited timestamp (unified-diff convention) and unquote a
-			// C-quoted git path (git quotes names with spaces/specials) (L18).
-			rest := line[len("--- "):] // "--- " and "+++ " are both 4 bytes
-			if tab := strings.IndexByte(rest, '\t'); tab >= 0 {
-				rest = rest[:tab]
-			}
-			if p := strings.TrimSpace(unquoteGitPath(rest)); p != "" && p != "/dev/null" {
+			if p := patchFileHeaderPath(line); p != "" && p != "/dev/null" {
 				paths = append(paths, stripPatchPrefix(p))
 			}
 		}
@@ -256,6 +328,17 @@ func patchHeaderPaths(patch string) []string {
 	return paths
 }
 
+func patchFileHeaderPath(line string) string {
+	if len(line) < len("--- ") {
+		return ""
+	}
+	rest := line[len("--- "):] // "--- " and "+++ " are both 4 bytes
+	if tab := strings.IndexByte(rest, '\t'); tab >= 0 {
+		rest = rest[:tab]
+	}
+	return strings.TrimSpace(unquoteGitPath(rest))
+}
+
 // parseHunkCounts reads the old/new line counts from a "@@ -a,b +c,d @@" header.
 // A missing count (e.g. "@@ -a +c @@") means 1 per unified-diff convention.
 //

internal/tools/args.go

@@ -132,6 +132,34 @@ func intPtr(value int) *int {
 	return &value
 }
 
+// sandboxPermissionsDescription and additionalPermissionsDescription are shared
+// by every shell tool (bash, exec_command) so the two fields cannot drift apart.
+//
+// Both lead with "omit" on purpose. The pair used to be described only in terms
+// of what each value does, which left a model that had used
+// with_additional_permissions once (say, for `gh issue create`) no instruction
+// to stop attaching a permission object to the next, ordinary command. That
+// attachment is then rejected — correctly, but the rejection alone does not tell
+// the model that dropping the field is the fix, so it flips between an
+// unflagged permission object and a flagged empty one and never converges
+// (#845, #847). Making "omit it" the first sentence of both descriptions stops
+// the invalid shape from being emitted in the first place; the validator errors
+// are the backstop, not the teacher.
+//
+// These ride on every turn's exec_command schema, so they are kept close to the
+// length of the text they replaced; TestEagerToolSchemaTokenBudget is the ratchet.
+const (
+	sandboxPermissionsDescription = "Per-command sandbox override. Omit it unless the command needs access the " +
+		"sandbox does not already give it; use `with_additional_permissions` with a non-empty " +
+		"`additional_permissions` for sandboxed file/network access, or `require_escalated` only when the command " +
+		"must run outside the sandbox, such as host/global process, socket, service, or desktop state hidden by " +
+		"sandbox namespaces."
+
+	additionalPermissionsDescription = "Extra sandbox access. Omit this field entirely unless `sandbox_permissions` " +
+		"is `with_additional_permissions`; sending it with any other mode is rejected, as is an empty or all-false " +
+		"object. Example: {\"network\": {\"enabled\": true}}."
+)
+
 func additionalPermissionsProperties() map[string]PropertySchema {
 	return requestPermissionsProfileSchema().Properties
 }

internal/tools/bash.go

@@ -43,16 +43,17 @@ func NewScopedBashTool(workspaceRoot string, scope PathScope) Tool {
 		baseTool: baseTool{
 			name:        "bash",
 			description: "Execute a shell command inside the workspace (or an explicitly granted extra directory) after permission is granted. " + shellGuidance,
+			deferred:    true,
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
 					"command":             {Type: "string", Description: "Shell command to execute using the host shell. " + shellGuidance},
 					"cwd":                 {Type: "string", Description: "Directory to run the command in. Relative paths stay in the workspace; use an absolute path to run in a granted extra directory. Defaults to workspace root. Prefer cwd over cd when changing directories.", Default: "."},
 					"timeout_ms":          {Type: "integer", Description: "Command timeout in milliseconds.", Default: defaultBashTimeoutMS, Minimum: intPtr(1), Maximum: intPtr(maxBashTimeoutMS)},
-					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions` for sandboxed file/network access, or `require_escalated` only when the command must run outside the sandbox, such as host/global process, socket, service, or desktop state hidden by sandbox namespaces.", Default: string(SandboxPermissionsUseDefault)},
+					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: sandboxPermissionsDescription, Default: string(SandboxPermissionsUseDefault)},
 					"additional_permissions": {
 						Type:        "object",
-						Description: "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`.",
+						Description: additionalPermissionsDescription,
 						Properties:  additionalPermissionsProperties(),
 					},
 					"justification": {Type: "string", Description: "User-facing approval question for `require_escalated`; omit otherwise."},
@@ -106,7 +107,7 @@ func (tool bashTool) run(ctx context.Context, args map[string]any, engine *zeroS
 	// unsandboxed) can actually bypass the MSYS guard instead of being
 	// hard-blocked by the same check it was meant to escalate past.
 	commandEngine := commandEngineForSandboxPermissions(engine, sandboxPermissions)
-	if issue := detectShellCommandIssue(commandText, runtime.GOOS); issue != nil && !msysGuardBypassed(issue, commandEngine) {
+	if issue := detectShellCommandIssueForRuntime(commandText, detectShellRuntime(runtime.GOOS)); issue != nil && !msysGuardBypassed(issue, commandEngine) {
 		return shellIssueBlockResult(*issue)
 	}
 
@@ -293,23 +294,19 @@ func shellIssueBlockResult(issue shellIssue) Result {
 }
 
 // buildBashCommand returns the exec.Cmd and the sandbox plan for running
-// commandText. On Windows, when the command is not wrapped by the sandbox
-// engine (plan.Wrapped == false), it also overrides the child's raw command
-// line so commandText reaches cmd.exe unescaped; see
-// zeroSandbox.WindowsShellCommandLine for why that matters. The wrapped case
-// gets the same treatment inside the sandboxed runner process itself
-// (internal/sandbox/windows_process_windows.go), since that command line is
-// built there, not here.
+// commandText. PowerShell is preferred on Windows, with cmd.exe retained as
+// the fallback. Only cmd.exe needs the raw command-line override.
 func buildBashCommand(ctx context.Context, commandText string, absoluteCwd string, engine *zeroSandbox.Engine) (*exec.Cmd, zeroSandbox.CommandPlan, error) {
+	hostShell := detectShellRuntime(runtime.GOOS)
 	spec := zeroSandbox.CommandSpec{
-		Name: shellExecutable(),
-		Args: shellArguments(commandText),
+		Name: hostShell.Executable,
+		Args: hostShell.arguments(commandText),
 		Dir:  absoluteCwd,
 	}
 	if engine != nil {
 		command, plan, err := engine.CommandContext(ctx, spec)
 		if err == nil {
-			applyWindowsShellCommandLine(command, commandText, plan.Wrapped)
+			applyWindowsShellCommandLine(command, commandText, plan.Wrapped, hostShell.Kind == shellKindCmd)
 		}
 		return command, plan, err
 	}
@@ -333,7 +330,7 @@ func buildBashCommand(ctx context.Context, commandText string, absoluteCwd strin
 	}
 	command := exec.CommandContext(ctx, spec.Name, spec.Args...)
 	command.Dir = spec.Dir
-	applyWindowsShellCommandLine(command, commandText, plan.Wrapped)
+	applyWindowsShellCommandLine(command, commandText, plan.Wrapped, hostShell.Kind == shellKindCmd)
 	return command, plan, nil
 }
 
@@ -385,20 +382,6 @@ func interactiveBlockResult(detection zeroSandbox.InteractiveCommandResult) Resu
 	}
 }
 
-func shellExecutable() string {
-	if runtime.GOOS == "windows" {
-		return "cmd.exe"
-	}
-	return "/bin/sh"
-}
-
-func shellArguments(command string) []string {
-	if runtime.GOOS == "windows" {
-		return zeroSandbox.WindowsShellArgs(command)
-	}
-	return []string{"-c", command}
-}
-
 func commandExitCode(err error) int {
 	if err == nil {
 		return 0
@@ -621,7 +604,7 @@ func truncateHeadTailWithTotal(value string, total, maxBytes int) (string, int,
 
 func formatBashOutputWithShellHint(stdout string, stderr string, exitCode int, meta map[string]string) string {
 	output := formatBashOutput(stdout, stderr, exitCode)
-	if issue := detectShellOutputIssue(stdout+"\n"+stderr, runtime.GOOS); issue != nil {
+	if issue := detectShellOutputIssueForRuntime(stdout+"\n"+stderr, detectShellRuntime(runtime.GOOS)); issue != nil {
 		meta["shell_issue"] = issue.Kind
 		output = appendShellIssueHint(output, *issue)
 	}

internal/tools/bash_proc_unix.go

@@ -36,6 +36,6 @@ func hardenProcessLifetime(command *exec.Cmd) {
 	}
 }
 
-// applyWindowsShellCommandLine is a no-op outside Windows; there is no
-// cmd.exe command-line-parsing quirk to work around here.
-func applyWindowsShellCommandLine(command *exec.Cmd, commandText string, wrapped bool) {}
+// applyWindowsShellCommandLine is a no-op outside Windows.
+func applyWindowsShellCommandLine(command *exec.Cmd, commandText string, wrapped bool, cmdFallback bool) {
+}

internal/tools/bash_proc_windows.go

@@ -31,15 +31,12 @@ func hardenProcessLifetime(command *exec.Cmd) {
 	}
 }
 
-// applyWindowsShellCommandLine overrides command's raw child command line so
-// commandText reaches cmd.exe unescaped instead of auto-quoted the way
-// exec.Cmd would normally encode a single Args element. Skipped when wrapped
-// is true: the sandbox engine then routes execution through a separate
-// zero-windows-command-runner process, which builds its own child command
-// line from scratch (internal/sandbox/windows_process_windows.go) rather than
-// inheriting whatever this outer exec.Cmd is configured with.
-func applyWindowsShellCommandLine(command *exec.Cmd, commandText string, wrapped bool) {
-	if wrapped {
+// applyWindowsShellCommandLine overrides the cmd.exe fallback's raw child
+// command line so commandText reaches cmd.exe unescaped. PowerShell consumes
+// ordinary argv quoting and must not take this path. Wrapped commands are
+// handled after unwrapping by the Windows sandbox runner.
+func applyWindowsShellCommandLine(command *exec.Cmd, commandText string, wrapped bool, cmdFallback bool) {
+	if wrapped || !cmdFallback {
 		return
 	}
 	command.SysProcAttr = &syscall.SysProcAttr{CmdLine: zeroSandbox.WindowsShellCommandLine(commandText)}

internal/tools/bash_tool_test.go

@@ -124,11 +124,15 @@ func TestBashToolDescribesHostShellSyntax(t *testing.T) {
 	}
 
 	if runtime.GOOS == "windows" {
-		if !strings.Contains(description, "cmd.exe") || !strings.Contains(description, "cwd") {
-			t.Fatalf("expected Windows cmd.exe and cwd guidance in bash description, got %q", description)
-		}
-		if !strings.Contains(description, "double quotes") || !strings.Contains(description, `--jq ".a | b"`) {
-			t.Fatalf("expected the double-quote metacharacter rule in bash description, got %q", description)
+		shell := detectShellRuntime(runtime.GOOS)
+		if shell.Kind == shellKindPowerShell {
+			for _, want := range []string{"powershell", "cwd", "get-childitem", "select-string", "$env:name"} {
+				if !strings.Contains(description, want) {
+					t.Fatalf("expected Windows PowerShell guidance %q in bash description, got %q", want, description)
+				}
+			}
+		} else if !strings.Contains(description, "cmd.exe") || !strings.Contains(description, "cwd") {
+			t.Fatalf("expected Windows cmd.exe fallback guidance in bash description, got %q", description)
 		}
 		return
 	}
@@ -455,13 +459,14 @@ func TestBashToolReturnsNonzeroExitAsError(t *testing.T) {
 	if result.Status != StatusError {
 		t.Fatalf("expected error status, got %s", result.Status)
 	}
-	for _, want := range []string{"stdout:\nbefore failure", "stderr:\nfailure details", "exit_code: 7"} {
+	wantExitCode := strconv.Itoa(helperFailureExitCode())
+	for _, want := range []string{"stdout:\nbefore failure", "stderr:\nfailure details", "exit_code: " + wantExitCode} {
 		if !strings.Contains(result.Output, want) {
 			t.Fatalf("expected output to contain %q, got %q", want, result.Output)
 		}
 	}
-	if result.Meta["exit_code"] != "7" {
-		t.Fatalf("expected exit_code metadata 7, got %q", result.Meta["exit_code"])
+	if result.Meta["exit_code"] != wantExitCode {
+		t.Fatalf("expected exit_code metadata %s, got %q", wantExitCode, result.Meta["exit_code"])
 	}
 	if result.ExecutionOutcome == nil || result.ExecutionOutcome.State != execution.StateFailed || result.ExecutionOutcome.Kind != execution.OutcomeApplicationFailure {
 		t.Fatalf("execution outcome = %#v, want failed/application_failure", result.ExecutionOutcome)
@@ -578,10 +583,16 @@ func TestBashToolRequireEscalatedMsysGuard(t *testing.T) {
 	}
 	registry := NewRegistry()
 	registry.Register(NewScopedBashTool(root, nil))
+	msysCommand := "cat somefile.txt"
+	if detectShellRuntime(runtime.GOOS).Kind == shellKindPowerShell {
+		// cat is a native Get-Content alias in PowerShell. Use a name that
+		// still resolves to an incompatible Git-for-Windows MSYS executable.
+		msysCommand = "grep pattern somefile.txt"
+	}
 
 	t.Run("default sandboxing still blocks an MSYS-prone command", func(t *testing.T) {
 		result := registry.RunWithOptions(context.Background(), "bash", map[string]any{
-			"command": "cat somefile.txt",
+			"command": msysCommand,
 		}, RunOptions{
 			PermissionGranted: true,
 			Sandbox:           newEngine(),
@@ -594,7 +605,7 @@ func TestBashToolRequireEscalatedMsysGuard(t *testing.T) {
 
 	t.Run("approved require_escalated bypasses the MSYS guard", func(t *testing.T) {
 		result := registry.RunWithOptions(context.Background(), "bash", map[string]any{
-			"command":             "cat somefile.txt",
+			"command":             msysCommand,
 			"sandbox_permissions": string(SandboxPermissionsRequireEscalated),
 		}, RunOptions{
 			PermissionGranted: true,
@@ -614,7 +625,14 @@ func TestBashToolRequireEscalatedMsysGuard(t *testing.T) {
 
 	t.Run("approved require_escalated still blocks an unrelated syntax issue", func(t *testing.T) {
 		result := registry.RunWithOptions(context.Background(), "bash", map[string]any{
-			"command":             `cd /d/tmp/zero-pr-158 && dir`,
+			// No `&&` here on purpose. The POSIX-style path is what this case is
+			// about, and on Windows PowerShell 5.1 a chained command trips the
+			// separate windows_powershell_version preflight first, which shadows
+			// the block being asserted. That only shows up on 5.1: the runners
+			// have PowerShell 7, where && is valid and the version check does not
+			// fire, so the substitution kept this green in CI while failing on the
+			// shell a stock Windows box actually gets.
+			"command":             `cd /d/tmp/zero-pr-158`,
 			"sandbox_permissions": string(SandboxPermissionsRequireEscalated),
 		}, RunOptions{
 			PermissionGranted: true,
@@ -648,8 +666,9 @@ func TestBashToolIgnoresMsysMarkersInCommandArgumentsAfterFailure(t *testing.T)
 		"command": command,
 	})
 
-	if result.Status != StatusError || result.Meta["exit_code"] != "7" {
-		t.Fatalf("expected the helper's real exit 7 failure, got %s: %#v", result.Status, result)
+	wantExitCode := strconv.Itoa(helperFailureExitCode())
+	if result.Status != StatusError || result.Meta["exit_code"] != wantExitCode {
+		t.Fatalf("expected the helper failure exit %s, got %s: %#v", wantExitCode, result.Status, result)
 	}
 	if result.Meta["shell_issue"] == "windows_msys_sandbox" {
 		t.Fatalf("expected the MSYS marker in the command's own argument text to be ignored, got %#v", result)
@@ -860,6 +879,9 @@ func TestBashToolRunsCommandLineForLoopSyntax(t *testing.T) {
 	if runtime.GOOS != "windows" {
 		t.Skip("cmd.exe command-line vs batch-file parsing is Windows-specific")
 	}
+	if detectShellRuntime(runtime.GOOS).Kind != shellKindCmd {
+		t.Skip("cmd.exe fallback is not selected")
+	}
 	root := t.TempDir()
 
 	result := NewScopedBashTool(root, nil).Run(context.Background(), map[string]any{
@@ -881,6 +903,10 @@ func helperCommand(name string) string {
 	return executable + " --zero-bash-helper " + name
 }
 
+func helperFailureExitCode() int {
+	return 7
+}
+
 func shellQuote(value string) string {
 	if runtime.GOOS == "windows" {
 		return value

internal/tools/edit_file.go

@@ -74,6 +74,11 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	if cerr := options.FileTracker.CheckConflict(absolutePath, contentBytes); cerr != nil {
 		return errorResult(fileConflictMessage(relativePath))
 	}
+	if options.FileTracker != nil {
+		if _, tracked := options.FileTracker.Version(absolutePath); !tracked {
+			return errorResult(fileUnseenMessage(relativePath))
+		}
+	}
 	content := string(contentBytes)
 	occurrences := strings.Count(content, oldString)
 
@@ -131,7 +136,11 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	if !replaceAll && occurrences > 1 {
 		return errorResult(fmt.Sprintf("Error: old_string matches %d locations in %s. Either make old_string more specific, or pass replace_all: true to replace every occurrence.", occurrences, relativePath))
 	}
+	if options.FileTracker != nil && !allOccurrencesSeen(options.FileTracker, absolutePath, content, oldString, replaceAll) {
+		return errorResult(fileUnseenMessage(relativePath))
+	}
 
+	previouslySeenWhole := options.FileTracker.SeenWhole(absolutePath)
 	updated := strings.Replace(content, oldString, newString, 1)
 	replacedCount := 1
 	if replaceAll {
@@ -141,12 +150,14 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	if updated == content {
 		return okResult("No changes: new_string is identical to old_string.")
 	}
+	editedSpans := replacementByteSpans(content, oldString, newString, replaceAll)
 	if err := recheckScopedWriteTarget(tool.workspaceRoot, tool.scope, requestedPath); err != nil {
 		return errorResult("Error writing " + relativePath + ": " + err.Error())
 	}
 	if err := os.WriteFile(absolutePath, []byte(updated), 0o644); err != nil {
 		return errorResult("Error writing " + relativePath + ": " + err.Error())
 	}
+	modelKnownContent := updated
 	// Optional format-on-write (ZERO_FORMAT_ON_WRITE). Must run BEFORE the
 	// FileTracker re-baseline: recording pre-format content would make the very
 	// next edit look like an external modification and trip the conflict guard.
@@ -155,6 +166,15 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	// compare against the current on-disk state, not the pre-edit version.
 	newInfo, _ := os.Stat(absolutePath)
 	options.FileTracker.Record(absolutePath, []byte(updated), newInfo)
+	if updated == modelKnownContent {
+		if previouslySeenWhole {
+			options.FileTracker.RecordSeenRange(absolutePath, 1, lineCount(updated), lineCount(updated))
+		} else {
+			for _, span := range editedSpans {
+				options.FileTracker.RecordSeenBytes(absolutePath, span.start, span.end, len(updated))
+			}
+		}
+	}
 
 	suffix := ""
 	if replacedCount != 1 {
@@ -169,3 +189,54 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	result.Display = Display{Summary: fmt.Sprintf("Edited %s", relativePath), Kind: "diff", Preview: boundedUnifiedDiff(relativePath, content, updated)}
 	return result
 }
+
+// replacementByteSpans returns every half-open post-edit byte range whose exact
+// contents came from newString. Offsets are translated from the original with a
+// cumulative delta so replace_all remains correct after earlier replacements.
+func replacementByteSpans(content, oldString, newString string, replaceAll bool) []lineRange {
+	spans := make([]lineRange, 0, 1)
+	offset := 0
+	delta := 0
+	for {
+		index := strings.Index(content[offset:], oldString)
+		if index < 0 {
+			return spans
+		}
+		index += offset
+		start := index + delta
+		spans = append(spans, lineRange{start: start, end: start + len(newString)})
+		if !replaceAll {
+			return spans
+		}
+		offset = index + len(oldString)
+		delta += len(newString) - len(oldString)
+	}
+}
+
+func allOccurrencesSeen(tracker *FileTracker, path, content, oldString string, replaceAll bool) bool {
+	offset := 0
+	for {
+		index := strings.Index(content[offset:], oldString)
+		if index < 0 {
+			return true
+		}
+		index += offset
+		start, end := lineSpanForOffset(content, index, len(oldString))
+		if !tracker.SeenBytes(path, index, index+len(oldString)) && !tracker.SeenRange(path, start, end) {
+			return false
+		}
+		if !replaceAll {
+			return true
+		}
+		offset = index + len(oldString)
+	}
+}
+
+func lineSpanForOffset(content string, offset, length int) (int, int) {
+	if offset < 0 {
+		return 1, 1
+	}
+	start := strings.Count(content[:offset], "\n") + 1
+	end := start + strings.Count(content[offset:min(len(content), offset+length)], "\n")
+	return start, end
+}

internal/tools/exec_command.go

@@ -91,10 +91,10 @@ func NewScopedExecCommandTool(workspaceRoot string, scope PathScope, manager *ex
 					"cwd":                 {Type: "string", Description: "Alias for workdir. Prefer workdir.", Default: "."},
 					"yield_time_ms":       {Type: "integer", Description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.", Default: defaultExecYieldTimeMS, Minimum: intPtr(1), Maximum: intPtr(maxExecYieldTimeMS)},
 					"max_output_tokens":   {Type: "integer", Description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.", Default: defaultMaxOutputTokens, Minimum: intPtr(1), Maximum: intPtr(maxExecOutputTokenRequest)},
-					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions` for sandboxed file/network access, or `require_escalated` only when the command must run outside the sandbox, such as host/global process, socket, service, or desktop state hidden by sandbox namespaces.", Default: string(SandboxPermissionsUseDefault)},
+					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: sandboxPermissionsDescription, Default: string(SandboxPermissionsUseDefault)},
 					"additional_permissions": {
 						Type:        "object",
-						Description: "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`.",
+						Description: additionalPermissionsDescription,
 						Properties:  additionalPermissionsProperties(),
 					},
 					"justification": {Type: "string", Description: "User-facing approval question for `require_escalated`; omit otherwise."},
@@ -173,7 +173,7 @@ func (tool execCommandTool) run(ctx context.Context, args map[string]any, engine
 	// unsandboxed) can actually bypass the MSYS guard instead of being
 	// hard-blocked by the same check it was meant to escalate past.
 	commandEngine := commandEngineForSandboxPermissions(engine, sandboxPermissions)
-	if issue := detectShellCommandIssue(commandText, runtimeGOOS()); issue != nil && !msysGuardBypassed(issue, commandEngine) {
+	if issue := detectShellCommandIssueForRuntime(commandText, detectShellRuntime(runtimeGOOS())); issue != nil && !msysGuardBypassed(issue, commandEngine) {
 		return shellIssueBlockResult(*issue)
 	}
 	if interactive := zeroSandbox.DetectInteractiveCommand(commandText, runtimeGOOS()); interactive.Interactive {
@@ -459,7 +459,7 @@ func execToolResultWithBudget(input execToolResultInput, directBudget bool) Resu
 	}
 	body := formatExecCommandOutput(output, input.sessionID, input.exited, input.exitCode, input.interrupted)
 	if status == StatusError && input.exited && !input.interrupted {
-		if issue := detectShellOutputIssue(output, runtimeGOOS()); issue != nil {
+		if issue := detectShellOutputIssueForRuntime(output, detectShellRuntime(runtimeGOOS())); issue != nil {
 			meta["shell_issue"] = issue.Kind
 			body = appendShellIssueHint(body, *issue)
 		}

internal/tools/exec_command_test.go

@@ -18,7 +18,7 @@ import (
 )
 
 func TestIndependentExecCommandConstructorsShareDefaultManager(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	execTool := NewScopedExecCommandTool(root, nil, nil)
 	writeTool := NewWriteStdinTool(nil)
 
@@ -76,17 +76,21 @@ func TestExecCommandToolDescribesHostShellSyntax(t *testing.T) {
 	description := strings.ToLower(strings.Join(descriptionParts, " "))
 
 	if runtime.GOOS == "windows" {
-		if !strings.Contains(description, "cmd.exe") || !strings.Contains(description, "cwd") {
-			t.Fatalf("expected Windows cmd.exe and cwd guidance in exec_command description, got %q", description)
-		}
-		if !strings.Contains(description, "double quotes") || !strings.Contains(description, `--jq ".a | b"`) {
-			t.Fatalf("expected the double-quote metacharacter rule in exec_command description, got %q", description)
+		shell := detectShellRuntime(runtime.GOOS)
+		if shell.Kind == shellKindPowerShell {
+			for _, want := range []string{"powershell", "cwd", "get-childitem", "select-string", "$env:name"} {
+				if !strings.Contains(description, want) {
+					t.Fatalf("expected Windows PowerShell guidance %q in exec_command description, got %q", want, description)
+				}
+			}
+		} else if !strings.Contains(description, "cmd.exe") || !strings.Contains(description, "cwd") {
+			t.Fatalf("expected Windows cmd.exe fallback guidance in exec_command description, got %q", description)
 		}
 	}
 }
 
 func TestExecCommandReturnsSessionAndWriteStdinPollsCompletion(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 	writeTool := NewWriteStdinTool(manager)
@@ -134,7 +138,7 @@ func TestExecCommandReturnsSessionAndWriteStdinPollsCompletion(t *testing.T) {
 }
 
 func TestExecCommandRequireEscalatedBypassesNativeSandboxAfterApproval(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	registry := NewRegistry()
 	registry.Register(NewScopedExecCommandTool(root, nil, manager))
@@ -183,7 +187,7 @@ func TestExecCommandRequireEscalatedBypassesMsysGuardAfterApproval(t *testing.T)
 	if runtime.GOOS != "windows" {
 		t.Skip("windows-only MSYS sandbox guard")
 	}
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	registry := NewRegistry()
 	registry.Register(NewScopedExecCommandTool(root, nil, manager))
@@ -192,9 +196,15 @@ func TestExecCommandRequireEscalatedBypassesMsysGuardAfterApproval(t *testing.T)
 		Policy:        sandbox.DefaultPolicy(),
 		Backend:       sandbox.Backend{Name: sandbox.BackendUnavailable, Message: "native sandbox unavailable"},
 	})
+	msysCommand := "cat somefile.txt"
+	if detectShellRuntime(runtime.GOOS).Kind == shellKindPowerShell {
+		// cat is a native Get-Content alias in PowerShell, so use an executable
+		// name that still exercises the MSYS guard.
+		msysCommand = "grep pattern somefile.txt"
+	}
 
 	result := registry.RunWithOptions(context.Background(), ExecCommandToolName, map[string]any{
-		"cmd":                 "cat somefile.txt",
+		"cmd":                 msysCommand,
 		"sandbox_permissions": string(SandboxPermissionsRequireEscalated),
 	}, RunOptions{
 		PermissionGranted: true,
@@ -204,8 +214,8 @@ func TestExecCommandRequireEscalatedBypassesMsysGuardAfterApproval(t *testing.T)
 
 	// Assert on the preflight block sentinel (exit_code "-1", set only by
 	// shellIssueBlockResult) rather than shell_issue: once the guard is
-	// bypassed, "cat somefile.txt" actually runs, and its real,
-	// PATH-dependent output could otherwise trip the unrelated
+	// bypassed, the command actually runs, and its real, PATH-dependent output
+	// could otherwise trip the unrelated
 	// post-execution detectShellOutputIssue heuristic and make this
 	// assertion flaky for reasons unrelated to the guard under test.
 	if result.Meta["exit_code"] == "-1" {
@@ -214,7 +224,7 @@ func TestExecCommandRequireEscalatedBypassesMsysGuardAfterApproval(t *testing.T)
 }
 
 func TestExecCommandReturnsExitCodeWhenCommandCompletesDuringInitialYield(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 
@@ -253,7 +263,7 @@ func TestExecCommandReportsWorkspaceChanges(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("uses POSIX shell syntax")
 	}
-	root := t.TempDir()
+	root := execTestRoot(t)
 	result := NewScopedExecCommandTool(root, nil, newExecSessionManager()).Run(context.Background(), map[string]any{
 		"cmd":           "mkdir -p src node_modules/pkg && printf 'export {}' > src/main.ts && printf generated > node_modules/pkg/index.js",
 		"yield_time_ms": 30000,
@@ -284,8 +294,9 @@ func TestExecCommandApplicationFailureHasTypedOutcome(t *testing.T) {
 	if result.ExecutionOutcome == nil || result.ExecutionOutcome.State != execution.StateFailed || result.ExecutionOutcome.Kind != execution.OutcomeApplicationFailure {
 		t.Fatalf("execution outcome = %#v, want failed/application_failure", result.ExecutionOutcome)
 	}
-	if result.ExecutionOutcome.Exit == nil || result.ExecutionOutcome.Exit.Code != 7 {
-		t.Fatalf("execution exit = %#v, want code 7", result.ExecutionOutcome.Exit)
+	wantExitCode := helperFailureExitCode()
+	if result.ExecutionOutcome.Exit == nil || result.ExecutionOutcome.Exit.Code != wantExitCode {
+		t.Fatalf("execution exit = %#v, want code %d", result.ExecutionOutcome.Exit, wantExitCode)
 	}
 }
 
@@ -316,6 +327,26 @@ func TestExecCommandUsesStructuredAdapterDenial(t *testing.T) {
 	}
 }
 
+func TestExecCommandDoesNotInferNativeSandboxDenialFromOutput(t *testing.T) {
+	result := execToolResult(execToolResultInput{
+		commandText: "touch \"$HOME/probe\"",
+		output:      "touch: cannot touch '/home/user/probe': Read-only file system",
+		exited:      true,
+		exitCode:    1,
+		enforcement: execution.Enforcement{Backend: string(sandbox.BackendLinuxBwrap), Level: string(sandbox.EnforcementNative)},
+	})
+
+	if result.ExecutionOutcome == nil || result.ExecutionOutcome.State != execution.StateFailed || result.ExecutionOutcome.Kind != execution.OutcomeApplicationFailure {
+		t.Fatalf("execution outcome = %#v, want failed/application_failure", result.ExecutionOutcome)
+	}
+	if result.ExecutionOutcome.Denial != nil {
+		t.Fatalf("command output created a typed denial: %#v", result.ExecutionOutcome.Denial)
+	}
+	if result.Meta[SandboxLikelyDeniedMeta] == "true" {
+		t.Fatalf("command output created sandbox-denial metadata: %#v", result.Meta)
+	}
+}
+
 func executionRequestHasCapability(request execution.Request, kind execution.CapabilityKind, scope string) bool {
 	for _, capability := range request.Capabilities {
 		if capability.Kind == kind && (scope == "" || capability.Scope == scope) {
@@ -326,7 +357,7 @@ func executionRequestHasCapability(request execution.Request, kind execution.Cap
 }
 
 func TestExecCommandForegroundServerReturnsSessionAndServesHTTP(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 	writeTool := NewWriteStdinTool(manager)
@@ -380,7 +411,7 @@ func parseListeningAddress(output string) string {
 }
 
 func TestExecCommandReapsFinishedUnpolledSession(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := execution.NewProcessManager(execution.ProcessManagerOptions{CompletedRetention: 10 * time.Millisecond})
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 
@@ -506,7 +537,7 @@ func TestWriteStdinInterruptTerminatesSession(t *testing.T) {
 }
 
 func TestWriteStdinRejectsInputForNonTTYSession(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 	writeTool := NewWriteStdinTool(manager)
@@ -537,9 +568,43 @@ func TestWriteStdinRejectsInputForNonTTYSession(t *testing.T) {
 	manager.Stop(sessionID)
 }
 
+// execTestRoot is t.TempDir with a cleanup that tolerates Windows still holding
+// the directory.
+//
+// A terminated process does not release its handles the instant the session
+// reports it exited, and Windows refuses to remove a directory with an open
+// handle where POSIX does not. t.TempDir's own cleanup removes once and fails
+// the test on a sharing violation, which turns ordinary teardown timing into a
+// test failure with nothing actually wrong underneath it.
+func execTestRoot(t *testing.T) string {
+	t.Helper()
+
+	root, err := os.MkdirTemp("", "zero-exec-test-")
+	if err != nil {
+		t.Fatalf("create test root: %v", err)
+	}
+	t.Cleanup(func() {
+		deadline := time.Now().Add(10 * time.Second)
+		for {
+			if err := os.RemoveAll(root); err == nil {
+				return
+			}
+			if time.Now().After(deadline) {
+				// Deliberately not a failure. The directory is under the OS temp
+				// root and the process holding it has already been terminated, so
+				// the worst case is a stale directory, not a broken test.
+				t.Logf("test root %s still held after the cleanup deadline; leaving it", root)
+				return
+			}
+			time.Sleep(50 * time.Millisecond)
+		}
+	})
+	return root
+}
+
 func TestWriteStdinStopIntentTerminatesNonTTYSession(t *testing.T) {
 	for _, chars := range []string{`\u0003`, "exit\n"} {
-		root := t.TempDir()
+		root := execTestRoot(t)
 		manager := newExecSessionManager()
 		execTool := NewScopedExecCommandTool(root, nil, manager)
 		writeTool := NewWriteStdinTool(manager)
@@ -556,16 +621,46 @@ func TestWriteStdinStopIntentTerminatesNonTTYSession(t *testing.T) {
 			t.Fatalf("session_id is not numeric: %v", err)
 		}
 
-		result := writeTool.Run(context.Background(), map[string]any{
-			"session_id":    sessionID,
-			"chars":         chars,
-			"yield_time_ms": 1000,
-		})
-		if result.Status != StatusOK {
-			t.Fatalf("stop input %q status = %s: %s", chars, result.Status, result.Output)
-		}
-		if result.Meta["session_id"] != "" {
-			t.Fatalf("stop input %q should not leave session running, meta=%#v output=%q", chars, result.Meta, result.Output)
+		// Re-send the stop until the session reports it has exited, rather than
+		// waiting a fixed slice and asserting on whatever is true by then.
+		//
+		// A single 1s yield used to be enough because the session ran under
+		// cmd.exe. Under PowerShell the tree is slower to stand up and tear down,
+		// and the FIRST stop in a fresh process pays the interpreter's cold start,
+		// so it routinely returns with termination already under way but not
+		// finished. The old assertion read that as "the stop did not work" and
+		// failed, intermittently, on whichever of the two inputs happened to run
+		// first. CI never saw it because the runners have PowerShell 7 while a
+		// stock Windows box only has 5.1.
+		//
+		// Repeating the same input rather than polling with empty chars is
+		// deliberate: Terminate is a no-op against an already-dead tree, so it is
+		// safe to repeat, and it keeps the interrupt flag that an empty-chars poll
+		// would drop, which is what the interrupted assertion below needs.
+		var result Result
+		// Every poll's output is kept, not just the last one. Each Continue
+		// returns only what the session produced since the previous collection,
+		// so a marker printed just before the poll that observes the exit lands
+		// in the earlier result and would be invisible to a check against the
+		// final one alone.
+		var collected strings.Builder
+		deadline := time.Now().Add(30 * time.Second)
+		for {
+			result = writeTool.Run(context.Background(), map[string]any{
+				"session_id":    sessionID,
+				"chars":         chars,
+				"yield_time_ms": 500,
+			})
+			collected.WriteString(result.Output)
+			if result.Status != StatusOK {
+				t.Fatalf("stop input %q status = %s: %s", chars, result.Status, result.Output)
+			}
+			if result.Meta["session_id"] == "" {
+				break
+			}
+			if time.Now().After(deadline) {
+				t.Fatalf("stop input %q left the session running past the deadline, meta=%#v output=%q", chars, result.Meta, result.Output)
+			}
 		}
 		if result.Meta["exit_code"] == "" {
 			t.Fatalf("stop input %q should report exit_code, meta=%#v output=%q", chars, result.Meta, result.Output)
@@ -573,6 +668,17 @@ func TestWriteStdinStopIntentTerminatesNonTTYSession(t *testing.T) {
 		if result.Meta["interrupted"] != "true" {
 			t.Fatalf("stop input %q should report interrupted metadata, meta=%#v output=%q", chars, result.Meta, result.Output)
 		}
+		// The session has to have been killed rather than allowed to finish.
+		// Without this the retry loop makes the test unfalsifiable: the helper
+		// sleeps 5s, well inside the deadline, so a terminate that did nothing at
+		// all would let the sleep end on its own and every assertion above would
+		// still hold. The interrupted flag does not close the hole either, since
+		// it echoes the request rather than the outcome. The helper prints this
+		// line only on the way out of a completed sleep, so its absence is what
+		// separates the two, and it says nothing about how long the loop took.
+		if strings.Contains(collected.String(), "long sleep finished") {
+			t.Fatalf("stop input %q let the session run to completion instead of terminating it, output=%q", chars, collected.String())
+		}
 	}
 }
 
@@ -612,7 +718,7 @@ func TestExecCommandTTYSessionAcceptsInputOnLinux(t *testing.T) {
 	if runtime.GOOS != "linux" {
 		t.Skip("pty transport is currently implemented for linux")
 	}
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager)
 	writeTool := NewWriteStdinTool(manager)
@@ -650,7 +756,7 @@ func TestExecCommandTTYSessionAcceptsInputOnLinux(t *testing.T) {
 }
 
 func TestExecSessionSnapshotsAndStopAll(t *testing.T) {
-	root := t.TempDir()
+	root := execTestRoot(t)
 	manager := newExecSessionManager()
 	execTool := NewScopedExecCommandTool(root, nil, manager).(execCommandTool)
 

internal/tools/file_safety_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"testing"
 )
@@ -79,6 +80,147 @@ func TestEditFileSucceedsWhenUnchangedAndRebaselines(t *testing.T) {
 	}
 }
 
+func TestApplyPatchPreservesWholeFileObservationForFollowUpEdit(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "f.txt")
+	if err := os.WriteFile(path, []byte("alpha\nbeta\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := safetyRegistry(t, dir)
+	registry.Register(NewScopedApplyPatchTool(dir, nil))
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	if result := registry.RunWithOptions(context.Background(), "read_file", map[string]any{"path": "f.txt"}, opts); result.Status != StatusOK {
+		t.Fatalf("read_file failed: %s", result.Output)
+	}
+	patch := strings.Join([]string{
+		"diff --git a/f.txt b/f.txt",
+		"--- a/f.txt",
+		"+++ b/f.txt",
+		"@@ -1,2 +1,2 @@",
+		"-alpha",
+		"+gamma",
+		" beta",
+		"",
+	}, "\n")
+	if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": patch}, opts); result.Status != StatusOK {
+		if gitApplyUnavailable(result.Output) {
+			t.Skipf("git binary unavailable: %s", result.Output)
+		}
+		t.Fatalf("apply_patch failed: %s", result.Output)
+	}
+
+	result := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "f.txt", "old_string": "beta", "new_string": "delta",
+	}, opts)
+	if result.Status != StatusOK {
+		t.Fatalf("follow-up edit should not require a wasted re-read: %s", result.Output)
+	}
+}
+
+func TestApplyPatchRenameOrCopyDoesNotCreditUnreadDestination(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		patch string
+	}{
+		{
+			name: "rename",
+			patch: strings.Join([]string{
+				"diff --git a/source.txt b/destination.txt",
+				"similarity index 100%",
+				"rename from source.txt",
+				"rename to destination.txt",
+				"",
+			}, "\n"),
+		},
+		{
+			name: "copy",
+			patch: strings.Join([]string{
+				"diff --git a/source.txt b/destination.txt",
+				"similarity index 100%",
+				"copy from source.txt",
+				"copy to destination.txt",
+				"",
+			}, "\n"),
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.WriteFile(filepath.Join(dir, "source.txt"), []byte("unread source\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			registry := safetyRegistry(t, dir)
+			registry.Register(NewScopedApplyPatchTool(dir, nil))
+			tracker := NewFileTracker()
+			opts := grantedOpts(tracker)
+
+			if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": tc.patch}, opts); result.Status != StatusOK {
+				if gitApplyUnavailable(result.Output) {
+					t.Skipf("git binary unavailable: %s", result.Output)
+				}
+				t.Fatalf("apply_patch failed: %s", result.Output)
+			}
+			destination, err := filepath.EvalSymlinks(filepath.Join(dir, "destination.txt"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if tracker.SeenWhole(destination) {
+				t.Fatal("rename/copy destination was credited as fully seen without a read")
+			}
+			result := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+				"path": "destination.txt", "content": "blind overwrite\n", "overwrite": true,
+			}, opts)
+			if result.Status != StatusError || !strings.Contains(result.Output, "has not been read exactly") {
+				t.Fatalf("blind destination overwrite was not refused: %#v", result)
+			}
+		})
+	}
+}
+
+func TestApplyPatchCompleteCreationCreditsSuppliedFile(t *testing.T) {
+	dir := t.TempDir()
+	registry := safetyRegistry(t, dir)
+	registry.Register(NewScopedApplyPatchTool(dir, nil))
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+	patch := strings.Join([]string{
+		"diff --git a/new.txt b/new.txt",
+		"new file mode 100644",
+		"--- /dev/null",
+		"+++ b/new.txt",
+		"@@ -0,0 +1 @@",
+		"+supplied content",
+		"",
+	}, "\n")
+	if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": patch}, opts); result.Status != StatusOK {
+		if gitApplyUnavailable(result.Output) {
+			t.Skipf("git binary unavailable: %s", result.Output)
+		}
+		t.Fatalf("apply_patch failed: %s", result.Output)
+	}
+	created, err := filepath.EvalSymlinks(filepath.Join(dir, "new.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !tracker.SeenWhole(created) {
+		t.Fatal("complete /dev/null creation was not credited as supplied content")
+	}
+	result := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "new.txt", "old_string": "supplied", "new_string": "updated",
+	}, opts)
+	if result.Status != StatusOK {
+		t.Fatalf("follow-up edit of supplied file failed: %s", result.Output)
+	}
+	updated, err := os.ReadFile(filepath.Join(dir, "new.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := strings.ReplaceAll(string(updated), "\r\n", "\n"), "updated content\n"; got != want {
+		t.Fatalf("follow-up edit content = %q, want %q", got, want)
+	}
+}
+
 func TestWriteFileOverwriteRefusedWhenChangedOnDisk(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "f.txt")
@@ -103,7 +245,7 @@ func TestWriteFileOverwriteRefusedWhenChangedOnDisk(t *testing.T) {
 	}
 }
 
-func TestWriteFileOverwriteAllowedForUntrackedFile(t *testing.T) {
+func TestWriteFileOverwriteRequiresExactRead(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "f.txt")
 	if err := os.WriteFile(path, []byte("v1\n"), 0o644); err != nil {
@@ -112,15 +254,161 @@ func TestWriteFileOverwriteAllowedForUntrackedFile(t *testing.T) {
 	registry := safetyRegistry(t, dir)
 	tracker := NewFileTracker()
 
-	// Never read through a tool → no baseline → overwrite is the model's call.
+	// Never read through a tool: an overwrite would discard unseen content.
 	res := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
 		"path": "f.txt", "content": "v3\n", "overwrite": true,
 	}, grantedOpts(tracker))
-	if res.Status != StatusOK {
-		t.Fatalf("untracked overwrite should be allowed, got %q", res.Output)
+	if res.Status != StatusError || !strings.Contains(res.Output, "has not been read exactly") {
+		t.Fatalf("unseen overwrite should be refused, got %q", res.Output)
 	}
-	if got, _ := os.ReadFile(path); string(got) != "v3\n" {
-		t.Fatalf("file = %q, want v3", got)
+	if got, _ := os.ReadFile(path); string(got) != "v1\n" {
+		t.Fatalf("file = %q, want original content", got)
+	}
+}
+
+func TestEditFileAllowsSeenRangeAndRejectsUnseenRange(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "f.txt")
+	if err := os.WriteFile(path, []byte("alpha\nbeta\ngamma\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	if res := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "f.txt", "start_line": 2, "end_line": 2,
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("partial read failed: %s", res.Output)
+	}
+	if res := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "f.txt", "old_string": "gamma", "new_string": "delta",
+	}, opts); res.Status != StatusError || !strings.Contains(res.Output, "has not been read exactly") {
+		t.Fatalf("unseen edit should be refused, got %q", res.Output)
+	}
+	if res := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "f.txt", "old_string": "beta", "new_string": "bravo",
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("seen-range edit should succeed, got %q", res.Output)
+	}
+	if content, err := os.ReadFile(path); err != nil || !strings.Contains(string(content), "bravo") {
+		t.Fatalf("seen-range edit did not update the file: content=%q err=%v", content, err)
+	}
+}
+
+func TestCanonicalLimitedReadAuthorizesEdit(t *testing.T) {
+	dir := t.TempDir()
+	var source strings.Builder
+	for line := 1; line <= 1000; line++ {
+		source.WriteString("line ")
+		source.WriteString(strconv.Itoa(line))
+		source.WriteByte('\n')
+	}
+	path := filepath.Join(dir, "f.txt")
+	if err := os.WriteFile(path, []byte(source.String()), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	read := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "f.txt", "offset": 500, "limit": 10,
+	}, opts)
+	if read.Status != StatusOK || read.Truncated {
+		t.Fatalf("bounded canonical read must be exact: status=%s truncated=%v meta=%#v", read.Status, read.Truncated, read.Meta)
+	}
+	if read.Meta["seen_lines"] != "500-509" {
+		t.Fatalf("bounded canonical read did not receive exact-read credit: %#v", read.Meta)
+	}
+
+	edit := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "f.txt", "old_string": "line 505", "new_string": "updated 505",
+	}, opts)
+	if edit.Status != StatusOK {
+		t.Fatalf("edit inside canonical read range was refused: %s", edit.Output)
+	}
+}
+
+func TestEditFileReplaceAllRecordsEveryShiftedReplacementSpan(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "f.txt")
+	if err := os.WriteFile(path, []byte("before\nneedle\nmiddle\nneedle\nafter\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	if res := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "f.txt", "start_line": 2, "end_line": 4,
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("partial read failed: %q", res.Output)
+	}
+	if res := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path":        "f.txt",
+		"old_string":  "needle",
+		"new_string":  "left\nright",
+		"replace_all": true,
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("replace_all failed: %q", res.Output)
+	}
+	// This follow-up targets both generated "right" lines. It succeeds only if
+	// replace_all recorded the shifted second replacement as seen.
+	if res := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path":        "f.txt",
+		"old_string":  "right",
+		"new_string":  "done",
+		"replace_all": true,
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("follow-up edit of every replacement should succeed: %q", res.Output)
+	}
+	if content, err := os.ReadFile(path); err != nil || strings.Count(string(content), "done") != 2 {
+		t.Fatalf("unexpected follow-up content: content=%q err=%v", content, err)
+	}
+}
+
+func TestWriteFileCanOverwriteNewlyCreatedEmptyFile(t *testing.T) {
+	dir := t.TempDir()
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	if res := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+		"path": "empty.txt", "content": "",
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("empty create failed: %q", res.Output)
+	}
+	if res := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+		"path": "empty.txt", "content": "now populated\n", "overwrite": true,
+	}, opts); res.Status != StatusOK {
+		t.Fatalf("empty overwrite should succeed: %q", res.Output)
+	}
+	if content, err := os.ReadFile(filepath.Join(dir, "empty.txt")); err != nil || string(content) != "now populated\n" {
+		t.Fatalf("unexpected overwritten content: content=%q err=%v", content, err)
+	}
+}
+
+func TestMinifiedReadDoesNotAuthorizeExactEdit(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "f.go")
+	if err := os.WriteFile(path, []byte("package p\n\nvar value = 1\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := NewRegistry()
+	registry.Register(NewScopedReadMinifiedFileTool(dir, nil))
+	registry.Register(NewScopedEditFileTool(dir, nil))
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+
+	if res := registry.RunWithOptions(context.Background(), "read_minified_file", map[string]any{"path": "f.go"}, opts); res.Status != StatusOK {
+		t.Fatalf("minified read failed: %s", res.Output)
+	}
+	res := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "f.go", "old_string": "var value = 1", "new_string": "var value = 2",
+	}, opts)
+	if res.Status != StatusError || !strings.Contains(res.Output, "has not been read exactly") {
+		t.Fatalf("minified view must not authorize exact edit, got %q", res.Output)
 	}
 }
 

internal/tools/file_tools_test.go

@@ -38,6 +38,108 @@ func TestReadFileToolReadsLineRanges(t *testing.T) {
 	}
 }
 
+func TestReadFileToolReadsCanonicalLineRange(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\ngamma\ndelta")
+
+	result := NewScopedReadFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path":   "notes.txt",
+		"offset": 2,
+		"limit":  2,
+	})
+
+	if result.Status != StatusOK {
+		t.Fatalf("expected ok status, got %s: %s", result.Status, result.Output)
+	}
+	if result.Truncated {
+		t.Fatalf("canonical limit defines the requested range and must not mark it truncated: %#v", result.Meta)
+	}
+	if !strings.Contains(result.Output, "2 | beta") || !strings.Contains(result.Output, "3 | gamma") {
+		t.Fatalf("canonical range returned the wrong lines: %q", result.Output)
+	}
+	if strings.Contains(result.Output, "alpha") || strings.Contains(result.Output, "delta") {
+		t.Fatalf("canonical range leaked outside requested slice: %q", result.Output)
+	}
+}
+
+func TestReadFileToolCanonicalOffsetPastEnd(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta")
+
+	result := NewScopedReadFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "notes.txt", "offset": 10,
+	})
+
+	if result.Status != StatusOK || !strings.Contains(result.Output, "offset 10 is past the end") {
+		t.Fatalf("expected canonical out-of-range message, got status=%s output=%q", result.Status, result.Output)
+	}
+	if strings.Contains(result.Output, "start_line") {
+		t.Fatalf("out-of-range message exposed legacy argument: %q", result.Output)
+	}
+}
+
+func TestReadFileToolMixedLegacyRangesPreferLines(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\ngamma\ndelta")
+
+	result := NewScopedReadFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path":        "notes.txt",
+		"start_line":  2,
+		"end_line":    3,
+		"max_lines":   2,
+		"byte_offset": 0,
+		"byte_limit":  readFileByteChunkMax,
+	})
+
+	if result.Status != StatusOK {
+		t.Fatalf("mixed legacy range should recover, got %s: %s", result.Status, result.Output)
+	}
+	if !strings.Contains(result.Output, "2 | beta") || !strings.Contains(result.Output, "3 | gamma") {
+		t.Fatalf("mixed legacy range did not prefer lines: %q", result.Output)
+	}
+}
+
+func TestReadFileToolCombinesLegacyStartWithCanonicalLimit(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\ngamma\ndelta")
+
+	result := NewScopedReadFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "notes.txt", "start_line": 2, "limit": 2,
+	})
+
+	if result.Status != StatusOK || result.Truncated {
+		t.Fatalf("mixed compatible range should be exact, got status=%s truncated=%v: %s", result.Status, result.Truncated, result.Output)
+	}
+	if !strings.Contains(result.Output, "2 | beta") || !strings.Contains(result.Output, "3 | gamma") {
+		t.Fatalf("mixed compatible range returned the wrong lines: %q", result.Output)
+	}
+	if strings.Contains(result.Output, "alpha") || strings.Contains(result.Output, "delta") {
+		t.Fatalf("mixed compatible range leaked outside requested slice: %q", result.Output)
+	}
+}
+
+func TestFileToolSchemasExposeOnlyCanonicalArguments(t *testing.T) {
+	readProperties := NewScopedReadFileTool(t.TempDir(), nil).Parameters().Properties
+	for _, want := range []string{"path", "offset", "limit", "byte_offset", "byte_limit"} {
+		if _, ok := readProperties[want]; !ok {
+			t.Fatalf("read_file schema missing %q", want)
+		}
+	}
+	for _, legacy := range []string{"start_line", "end_line", "max_lines"} {
+		if _, ok := readProperties[legacy]; ok {
+			t.Fatalf("read_file schema must not expose legacy argument %q", legacy)
+		}
+	}
+
+	grepProperties := NewScopedGrepTool(t.TempDir(), nil).Parameters().Properties
+	if _, ok := grepProperties["case_insensitive"]; !ok {
+		t.Fatal("grep schema missing case_insensitive")
+	}
+	if _, ok := grepProperties["-i"]; ok {
+		t.Fatal("grep schema must not expose the -i alias")
+	}
+}
+
 func TestReadFileToolMarksTruncation(t *testing.T) {
 	root := t.TempDir()
 	writeTestFile(t, filepath.Join(root, "notes.txt"), "a\nb\nc\nd\ne")
@@ -52,7 +154,7 @@ func TestReadFileToolMarksTruncation(t *testing.T) {
 	}
 	// The cut must be visible in the rendered output, not just the Truncated flag,
 	// and must tell the model where to continue.
-	if !strings.Contains(result.Output, "[truncated:") || !strings.Contains(result.Output, "start_line=3") {
+	if !strings.Contains(result.Output, "[truncated:") || !strings.Contains(result.Output, "offset=3") {
 		t.Fatalf("expected truncation marker pointing to the next line, got %q", result.Output)
 	}
 }
@@ -68,7 +170,7 @@ func TestReadFileToolAppliesByteBudget(t *testing.T) {
 	if result.Status != StatusOK || !result.Truncated {
 		t.Fatalf("expected ok+truncated, got status=%s truncated=%v", result.Status, result.Truncated)
 	}
-	if !strings.Contains(result.Output, "output exceeded") || !strings.Contains(result.Output, "start_line") {
+	if !strings.Contains(result.Output, "output exceeded") || !strings.Contains(result.Output, "offset/limit") {
 		t.Fatalf("expected byte-budget continuation hint, got %q", result.Output[len(result.Output)-200:])
 	}
 	if result.Meta["raw_bytes"] == "" || result.Meta["emitted_bytes"] == "" {

internal/tools/file_tracker.go

@@ -5,6 +5,7 @@ import (
 	"encoding/hex"
 	"errors"
 	"os"
+	"sort"
 	"sync"
 	"time"
 )
@@ -34,6 +35,7 @@ type FileVersion struct {
 type FileTracker struct {
 	mu       sync.Mutex
 	versions map[string]FileVersion
+	seen     map[string]fileObservation
 	// created preserves the order in which brand-new files (paths that did not
 	// exist before a write tool created them) were first written this session.
 	// A map would lose that order and complicates de-duplication, so a slice
@@ -43,7 +45,36 @@ type FileTracker struct {
 }
 
 func NewFileTracker() *FileTracker {
-	return &FileTracker{versions: make(map[string]FileVersion)}
+	return &FileTracker{
+		versions: make(map[string]FileVersion),
+		seen:     make(map[string]fileObservation),
+	}
+}
+
+type lineRange struct {
+	start int
+	end   int
+}
+
+type fileObservation struct {
+	whole bool
+	// total is the file's line count as of the last recorded read, so coverage
+	// can be judged from the ranges alone. Without it a file read in pieces
+	// could never be known to have been seen in full.
+	total      int
+	ranges     []lineRange
+	totalBytes int
+	byteRanges []lineRange // zero-based, half-open byte intervals
+}
+
+type pendingFileObservation struct {
+	path     string
+	output   string
+	hash     string
+	start    int
+	end      int
+	total    int
+	byteMode bool
 }
 
 // Record stores the version of absPath given its content and optional stat info.
@@ -63,10 +94,200 @@ func (tracker *FileTracker) RecordHash(absPath string, hash string, info os.File
 		version.MTime = info.ModTime()
 	}
 	tracker.mu.Lock()
+	if previous, ok := tracker.versions[absPath]; !ok || previous.Hash != hash {
+		delete(tracker.seen, absPath)
+	}
 	tracker.versions[absPath] = version
 	tracker.mu.Unlock()
 }
 
+// RecordSeenRange records exact, non-elided source lines returned to the model.
+// Ranges accumulate while the content hash remains unchanged.
+func (tracker *FileTracker) RecordSeenRange(absPath string, start, end, total int) {
+	if tracker == nil || start < 1 {
+		return
+	}
+	tracker.mu.Lock()
+	defer tracker.mu.Unlock()
+	observation := tracker.seen[absPath]
+	if total == 0 {
+		observation.whole = true
+		observation.ranges = nil
+		tracker.seen[absPath] = observation
+		return
+	}
+	if end < start {
+		return
+	}
+	// A new line count means the file changed shape since the last read, so
+	// previously recorded ranges no longer describe it.
+	if observation.total != 0 && observation.total != total {
+		observation = fileObservation{}
+	}
+	observation.total = total
+	if start == 1 && end >= total {
+		observation.whole = true
+		observation.ranges = nil
+		tracker.seen[absPath] = observation
+		return
+	}
+	observation.ranges = append(observation.ranges, lineRange{start: start, end: end})
+	tracker.seen[absPath] = observation
+}
+
+// RecordSeenBytes records an exact, non-elided byte interval returned to the
+// model. Byte intervals make oversized single-line files recoverable without
+// crediting the model for the omitted middle of a truncated line read.
+func (tracker *FileTracker) RecordSeenBytes(absPath string, start, end, total int) {
+	if tracker == nil || start < 0 || end < start || total < 0 || end > total {
+		return
+	}
+	tracker.mu.Lock()
+	defer tracker.mu.Unlock()
+	observation := tracker.seen[absPath]
+	if total == 0 {
+		observation.whole = true
+		observation.byteRanges = nil
+		tracker.seen[absPath] = observation
+		return
+	}
+	if observation.totalBytes != 0 && observation.totalBytes != total {
+		observation = fileObservation{}
+	}
+	observation.totalBytes = total
+	if start == 0 && end >= total {
+		observation.whole = true
+		observation.byteRanges = nil
+		tracker.seen[absPath] = observation
+		return
+	}
+	observation.byteRanges = append(observation.byteRanges, lineRange{start: start, end: end})
+	tracker.seen[absPath] = observation
+}
+
+// coversFully reports whether ranges together cover every line in [start, end].
+//
+// Ranges are merged rather than scanned line by line: a caller asking about a
+// large file would otherwise walk every line against every recorded range, and
+// the answer is the same.
+func coversFully(ranges []lineRange, start int, end int) bool {
+	if start > end {
+		return true
+	}
+	if len(ranges) == 0 {
+		return false
+	}
+	sorted := make([]lineRange, len(ranges))
+	copy(sorted, ranges)
+	sort.Slice(sorted, func(left int, right int) bool {
+		if sorted[left].start != sorted[right].start {
+			return sorted[left].start < sorted[right].start
+		}
+		return sorted[left].end < sorted[right].end
+	})
+	next := start
+	for _, seen := range sorted {
+		if seen.start > next {
+			return false
+		}
+		if seen.end >= next {
+			next = seen.end + 1
+		}
+		if next > end {
+			return true
+		}
+	}
+	return next > end
+}
+
+// coversBytes reports whether half-open byte ranges cover [start, end).
+func coversBytes(ranges []lineRange, start, end int) bool {
+	if start >= end {
+		return true
+	}
+	if len(ranges) == 0 {
+		return false
+	}
+	sorted := make([]lineRange, len(ranges))
+	copy(sorted, ranges)
+	sort.Slice(sorted, func(left, right int) bool {
+		if sorted[left].start != sorted[right].start {
+			return sorted[left].start < sorted[right].start
+		}
+		return sorted[left].end < sorted[right].end
+	})
+	next := start
+	for _, seen := range sorted {
+		if seen.start > next {
+			return false
+		}
+		if seen.end > next {
+			next = seen.end
+		}
+		if next >= end {
+			return true
+		}
+	}
+	return false
+}
+
+// SeenRange reports whether every line in the requested range was returned
+// exactly to the model for the currently tracked version.
+func (tracker *FileTracker) SeenRange(absPath string, start, end int) bool {
+	if tracker == nil {
+		return true
+	}
+	tracker.mu.Lock()
+	defer tracker.mu.Unlock()
+	observation, ok := tracker.seen[absPath]
+	if !ok {
+		return false
+	}
+	if observation.whole {
+		return true
+	}
+	return coversFully(observation.ranges, start, end)
+}
+
+// SeenBytes reports whether every byte in [start, end) was returned exactly to
+// the model for the currently tracked version.
+func (tracker *FileTracker) SeenBytes(absPath string, start, end int) bool {
+	if tracker == nil {
+		return true
+	}
+	tracker.mu.Lock()
+	defer tracker.mu.Unlock()
+	observation, ok := tracker.seen[absPath]
+	if !ok {
+		return false
+	}
+	return observation.whole || coversBytes(observation.byteRanges, start, end)
+}
+
+func (tracker *FileTracker) SeenWhole(absPath string) bool {
+	if tracker == nil {
+		return true
+	}
+	tracker.mu.Lock()
+	defer tracker.mu.Unlock()
+	observation, ok := tracker.seen[absPath]
+	if !ok {
+		return false
+	}
+	if observation.whole {
+		return true
+	}
+	// Derived from the ranges rather than tracked as its own flag. The flag was
+	// only ever set by a SINGLE read covering the file, so a file read in two
+	// halves stayed "not seen whole" forever even though SeenRange agreed every
+	// line had been seen — and write_file, which gates on this, then refused the
+	// overwrite with advice to read the file that could not change the answer.
+	if observation.total > 0 && coversFully(observation.ranges, 1, observation.total) {
+		return true
+	}
+	return observation.totalBytes > 0 && coversBytes(observation.byteRanges, 0, observation.totalBytes)
+}
+
 // Version returns the recorded version for absPath and whether one exists.
 func (tracker *FileTracker) Version(absPath string) (FileVersion, bool) {
 	if tracker == nil {
@@ -119,6 +340,7 @@ func (tracker *FileTracker) Forget(absPath string) {
 	}
 	tracker.mu.Lock()
 	delete(tracker.versions, absPath)
+	delete(tracker.seen, absPath)
 	tracker.mu.Unlock()
 }
 
@@ -153,3 +375,7 @@ func fileConflictMessage(relativePath string) string {
 	return "Error writing " + relativePath + ": " + ErrFileChangedOnDisk.Error() +
 		" (it may have been edited outside Zero). Re-read it with read_file, then re-apply your change so you do not overwrite the newer content."
 }
+
+func fileUnseenMessage(relativePath string) string {
+	return "Error writing " + relativePath + ": the intended change depends on content that has not been read exactly in this session. Read the affected lines with read_file using offset/limit (or byte_offset/byte_limit for a very long line), then retry the edit."
+}

internal/tools/file_tracker_coverage_test.go

@@ -0,0 +1,96 @@
+package tools
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// SeenWhole used to be a flag set only by a SINGLE read that covered the file,
+// while SeenRange judged coverage from the accumulated ranges. The two then
+// disagreed about the same reads, and write_file — which gates on SeenWhole —
+// refused overwrites it should have allowed.
+func TestSeenWholeIsDerivedFromAccumulatedRanges(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "f.go")
+
+	for name, testCase := range map[string]struct {
+		reads [][3]int // start, end, total
+		want  bool
+	}{
+		"one read covering the file": {
+			reads: [][3]int{{1, 100, 100}},
+			want:  true,
+		},
+		"two adjacent reads covering it together": {
+			reads: [][3]int{{1, 50, 100}, {51, 100, 100}},
+			want:  true,
+		},
+		"overlapping reads covering it together": {
+			reads: [][3]int{{1, 60, 100}, {40, 100, 100}},
+			want:  true,
+		},
+		"out-of-order reads covering it together": {
+			reads: [][3]int{{51, 100, 100}, {1, 50, 100}},
+			want:  true,
+		},
+		"a gap in the middle": {
+			reads: [][3]int{{1, 40, 100}, {60, 100, 100}},
+			want:  false,
+		},
+		"missing the first line": {
+			reads: [][3]int{{2, 100, 100}},
+			want:  false,
+		},
+		"missing the last line": {
+			reads: [][3]int{{1, 99, 100}},
+			want:  false,
+		},
+		"nothing read at all": {
+			reads: nil,
+			want:  false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			tracker := NewFileTracker()
+			for _, read := range testCase.reads {
+				tracker.RecordSeenRange(path, read[0], read[1], read[2])
+			}
+			if got := tracker.SeenWhole(path); got != testCase.want {
+				t.Errorf("SeenWhole = %v, want %v after reads %v", got, testCase.want, testCase.reads)
+			}
+		})
+	}
+}
+
+// SeenWhole and SeenRange must not disagree about the same reads.
+func TestSeenWholeAgreesWithSeenRange(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "f.go")
+	tracker := NewFileTracker()
+	tracker.RecordSeenRange(path, 1, 50, 100)
+	tracker.RecordSeenRange(path, 51, 100, 100)
+
+	if !tracker.SeenRange(path, 1, 100) {
+		t.Fatal("SeenRange says the whole file was not seen")
+	}
+	if !tracker.SeenWhole(path) {
+		t.Error("SeenRange covers every line but SeenWhole disagrees")
+	}
+}
+
+// A file that changed length since the recorded reads must not stay "seen":
+// the old ranges describe a shape the file no longer has.
+func TestSeenWholeResetsWhenTheFileChangesLength(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "f.go")
+	tracker := NewFileTracker()
+	tracker.RecordSeenRange(path, 1, 100, 100)
+	if !tracker.SeenWhole(path) {
+		t.Fatal("precondition: the whole file was read")
+	}
+	// The file grew; only the first 100 lines of 200 have been seen.
+	tracker.RecordSeenRange(path, 1, 100, 200)
+	if tracker.SeenWhole(path) {
+		t.Error("file grew to 200 lines but is still reported as seen whole")
+	}
+	if !tracker.SeenRange(path, 1, 100) {
+		t.Error("the lines that were read should still count as seen")
+	}
+}

internal/tools/file_tracker_largefile_test.go

@@ -0,0 +1,263 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"unicode/utf8"
+)
+
+// A file past the read byte budget cannot be read whole in one call: the read is
+// truncated and RecordSeenRange is skipped, which is correct — the model did not
+// see those lines. But SeenWhole was a flag only a single whole-file read could
+// set, so no sequence of scoped reads could ever clear it either, and write_file
+// refused the overwrite forever while telling the model to read the file again.
+func TestLargeFileBecomesWritableAfterScopedReadsCoverIt(t *testing.T) {
+	dir := t.TempDir()
+	// read_file resolves the workspace root through EvalSymlinks before it
+	// records anything, so the tracker is keyed on the resolved path. On macOS
+	// t.TempDir() sits under /var, a symlink to /private/var, and asserting
+	// against the raw path would look up a key that never existed — passing on
+	// Windows and failing there.
+	resolvedDir, err := filepath.EvalSymlinks(dir)
+	if err != nil {
+		t.Fatalf("resolve temp dir: %v", err)
+	}
+	path := filepath.Join(resolvedDir, "big.go")
+
+	const lines = 2400
+	var builder strings.Builder
+	for index := 0; index < lines; index++ {
+		fmt.Fprintf(&builder, "line %06d %s\n", index, strings.Repeat("x", 60))
+	}
+	if writeErr := os.WriteFile(path, []byte(builder.String()), 0o600); writeErr != nil {
+		t.Fatalf("seed file: %v", writeErr)
+	}
+
+	tracker := NewFileTracker()
+	options := RunOptions{FileTracker: tracker}
+	ctx := context.Background()
+	read := NewReadFileTool(dir).(interface {
+		RunWithOptions(context.Context, map[string]any, RunOptions) Result
+	})
+	write := NewScopedWriteFileTool(dir, nil).(interface {
+		RunWithOptions(context.Context, map[string]any, RunOptions) Result
+	})
+
+	// One unbounded read is byte-truncated, so nothing is recorded.
+	full := read.RunWithOptions(ctx, map[string]any{"path": "big.go"}, options)
+	if full.Meta["truncation_reason"] != "byte_budget" {
+		t.Fatalf("precondition: expected the file to exceed the read byte budget, got reason %q", full.Meta["truncation_reason"])
+	}
+	if tracker.SeenWhole(path) {
+		t.Fatal("a truncated read must not credit the model with the whole file")
+	}
+
+	// Scoped reads that together cover it must.
+	for _, span := range [][2]int{{1, 1200}, {1201, 2400}} {
+		result := read.RunWithOptions(ctx, map[string]any{
+			"path": "big.go", "start_line": span[0], "end_line": span[1],
+		}, options)
+		if result.Status != StatusOK {
+			t.Fatalf("scoped read %v: %s", span, result.Output)
+		}
+		if result.Meta["truncation_reason"] == "byte_budget" {
+			t.Fatalf("scoped read %v was itself truncated; pick smaller spans", span)
+		}
+	}
+	if !tracker.SeenWhole(path) {
+		t.Fatal("scoped reads covered every line but the file is still not seen whole")
+	}
+
+	overwrite := write.RunWithOptions(ctx, map[string]any{
+		"path": "big.go", "content": "replaced\n", "overwrite": true,
+	}, options)
+	if overwrite.Status != StatusOK {
+		t.Fatalf("overwrite refused after the file was fully read in scoped reads: %s", overwrite.Output)
+	}
+}
+
+func TestSingleLongLineBecomesWritableAfterExactByteReads(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "bundle.min.js")
+	content := strings.Repeat("x", readOutputBudgetBytes*3)
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatalf("seed file: %v", err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatalf("resolve file: %v", err)
+	}
+
+	tracker := NewFileTracker()
+	options := RunOptions{FileTracker: tracker}
+	ctx := context.Background()
+	read := NewReadFileTool(dir).(interface {
+		RunWithOptions(context.Context, map[string]any, RunOptions) Result
+	})
+	write := NewScopedWriteFileTool(dir, nil).(interface {
+		RunWithOptions(context.Context, map[string]any, RunOptions) Result
+	})
+
+	full := read.RunWithOptions(ctx, map[string]any{"path": "bundle.min.js"}, options)
+	if full.Meta["truncation_reason"] != "byte_budget" {
+		t.Fatalf("precondition: expected byte truncation, got %#v", full.Meta)
+	}
+	if tracker.SeenWhole(resolvedPath) {
+		t.Fatal("a truncated line read must not credit the whole file")
+	}
+
+	const chunkSize = 64 * 1024
+	for offset := 0; offset < len(content); offset += chunkSize {
+		result := read.RunWithOptions(ctx, map[string]any{
+			"path":        "bundle.min.js",
+			"byte_offset": offset,
+			"byte_limit":  chunkSize,
+		}, options)
+		if result.Status != StatusOK || result.Truncated {
+			t.Fatalf("byte read at %d was not exact: status=%s truncated=%v output=%q", offset, result.Status, result.Truncated, result.Output)
+		}
+	}
+	if !tracker.SeenWhole(resolvedPath) {
+		t.Fatal("exact byte reads covered the file but it is not seen whole")
+	}
+
+	overwrite := write.RunWithOptions(ctx, map[string]any{
+		"path": "bundle.min.js", "content": "replaced\n", "overwrite": true,
+	}, options)
+	if overwrite.Status != StatusOK {
+		t.Fatalf("overwrite refused after exact byte reads: %s", overwrite.Output)
+	}
+}
+
+func TestExactByteReadsAdvanceAlongUTF8Boundaries(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "unicode.min.js")
+	content := strings.Repeat("😀", 40_000)
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tracker := NewFileTracker()
+	options := RunOptions{FileTracker: tracker}
+	read := NewReadFileTool(dir).(interface {
+		RunWithOptions(context.Context, map[string]any, RunOptions) Result
+	})
+	offset := 0
+	for offset < len(content) {
+		result := read.RunWithOptions(context.Background(), map[string]any{
+			"path": "unicode.min.js", "byte_offset": offset, "byte_limit": 65_535,
+		}, options)
+		if result.Status != StatusOK || result.Truncated || !utf8.ValidString(result.Output) {
+			t.Fatalf("invalid exact UTF-8 read at %d: %#v", offset, result)
+		}
+		next, parseErr := strconv.Atoi(result.Meta["next_byte_offset"])
+		if parseErr != nil || next <= offset {
+			t.Fatalf("invalid continuation offset %q after %d", result.Meta["next_byte_offset"], offset)
+		}
+		offset = next
+	}
+	if !tracker.SeenWhole(resolvedPath) {
+		t.Fatal("UTF-8-safe byte reads covered the file but it is not seen whole")
+	}
+}
+
+func TestRegistryTruncationDoesNotCreditUndeliveredByteRanges(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "unicode.min.js")
+	content := strings.Repeat("界", 84_000)
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	result := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "unicode.min.js", "byte_offset": 0, "byte_limit": readFileByteChunkMax,
+	}, grantedOpts(tracker))
+	if !result.Truncated {
+		t.Fatalf("precondition: multibyte chunk was not truncated at the registry boundary: %#v", result.Meta)
+	}
+	next, err := strconv.Atoi(result.Meta["next_byte_offset"])
+	if err != nil || next <= 0 {
+		t.Fatalf("invalid continuation offset %q", result.Meta["next_byte_offset"])
+	}
+	if tracker.SeenBytes(resolvedPath, 0, next) || tracker.SeenWhole(resolvedPath) {
+		t.Fatal("registry-truncated bytes were credited as delivered to the model")
+	}
+}
+
+func TestRegistryTruncationDoesNotCreditWholeLineRead(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "unicode.go")
+	content := strings.Repeat("界界界界界界界界\n", 4_000)
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	result := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "unicode.go",
+	}, grantedOpts(tracker))
+	if !result.Truncated {
+		t.Fatalf("precondition: multibyte line read was not truncated at the registry boundary: %#v", result.Meta)
+	}
+	if tracker.SeenWhole(resolvedPath) {
+		t.Fatal("registry-truncated line output credited the whole file")
+	}
+}
+
+func TestPartialByteEditDoesNotCreditAnEntireLongLine(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "bundle.min.js")
+	content := "UNIQUE_TARGET" + strings.Repeat("x", readOutputBudgetBytes*2)
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	resolvedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	registry := safetyRegistry(t, dir)
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+	read := registry.RunWithOptions(context.Background(), "read_file", map[string]any{
+		"path": "bundle.min.js", "byte_offset": 0, "byte_limit": 64,
+	}, opts)
+	if read.Status != StatusOK || read.Truncated {
+		t.Fatalf("exact byte read failed: %#v", read)
+	}
+	edit := registry.RunWithOptions(context.Background(), "edit_file", map[string]any{
+		"path": "bundle.min.js", "old_string": "UNIQUE_TARGET", "new_string": "UPDATED_TARGET",
+	}, opts)
+	if edit.Status != StatusOK {
+		t.Fatalf("edit of exactly observed bytes failed: %s", edit.Output)
+	}
+	if tracker.SeenWhole(resolvedPath) {
+		t.Fatal("editing observed bytes credited the unread remainder of the long line")
+	}
+	overwrite := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+		"path": "bundle.min.js", "content": "replacement", "overwrite": true,
+	}, opts)
+	if overwrite.Status != StatusError {
+		t.Fatalf("whole overwrite should remain blocked after a partial byte read, got %#v", overwrite)
+	}
+}

internal/tools/format_on_write_test.go

@@ -61,15 +61,37 @@ func TestFormatOnWriteFormatsAndKeepsTrackerConsistent(t *testing.T) {
 		t.Fatalf("expected gofmt-formatted content, got %q", onDisk)
 	}
 
-	// The tracker must have been re-baselined to the POST-format content: a
-	// follow-up edit must not trip the external-modification conflict guard.
+	// The tracker is re-baselined to the post-format bytes, but those bytes were
+	// not returned exactly to the model, so an edit must require an exact read.
 	edit := NewScopedEditFileTool(dir, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
 		"path":       "a.go",
 		"old_string": "func A() {",
 		"new_string": "func B() {",
 	}, RunOptions{FileTracker: tracker})
+	if edit.Status != StatusError || !strings.Contains(edit.Output, "has not been read exactly") {
+		t.Fatalf("formatter-modified content must require an exact read: %q", edit.Output)
+	}
+	read := NewScopedReadFileTool(dir, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go",
+	}, RunOptions{FileTracker: tracker})
+	if read.Status != StatusOK {
+		t.Fatalf("exact read failed: %q", read.Output)
+	}
+	edit = NewScopedEditFileTool(dir, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path":       "a.go",
+		"old_string": "func A() {",
+		"new_string": "func B( ) {",
+	}, RunOptions{FileTracker: tracker})
 	if edit.Status != StatusOK {
-		t.Fatalf("follow-up edit must not conflict after formatting: %q", edit.Output)
+		t.Fatalf("follow-up edit after exact read failed: %q", edit.Output)
+	}
+	edit = NewScopedEditFileTool(dir, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path":       "a.go",
+		"old_string": "func B() {",
+		"new_string": "func C() {",
+	}, RunOptions{FileTracker: tracker})
+	if edit.Status != StatusError || !strings.Contains(edit.Output, "has not been read exactly") {
+		t.Fatalf("formatter-modified edit must require an exact read: %q", edit.Output)
 	}
 }
 

internal/tools/goal.go

@@ -0,0 +1,187 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/sessions"
+)
+
+type goalTool struct {
+	baseTool
+	store     *sessions.Store
+	sessionID string
+	action    string
+}
+
+// NewGoalTools returns goal lifecycle tools bound to one captured session. The
+// binding prevents a late tool call from mutating a different session after a
+// resume or session switch.
+func NewGoalTools(store *sessions.Store, sessionID string) []Tool {
+	return []Tool{
+		newGetGoalTool(store, sessionID),
+		newCreateGoalTool(store, sessionID),
+		newUpdateGoalTool(store, sessionID),
+	}
+}
+
+func newGetGoalTool(store *sessions.Store, sessionID string) Tool {
+	return &goalTool{
+		baseTool: baseTool{
+			name:        "get_goal",
+			description: "Get the current persistent goal and its status, token budget, and usage for this session.",
+			parameters: Schema{
+				Type:                 "object",
+				AdditionalProperties: false,
+			},
+			safety:       readOnlySafety("Reads goal state for the current session."),
+			capabilities: ToolCapabilities{Effect: EffectReadOnly, ThreadSafe: true},
+		},
+		store:     store,
+		sessionID: sessionID,
+		action:    "get",
+	}
+}
+
+func newCreateGoalTool(store *sessions.Store, sessionID string) Tool {
+	minimum := 0
+	maximum := 1_000_000_000
+	maxObjectiveLength := sessions.GoalObjectiveMaxLength
+	return &goalTool{
+		baseTool: baseTool{
+			name: "create_goal",
+			description: "Create one persistent goal for this session when the user explicitly asks to pursue an ongoing objective. " +
+				"Do not infer a goal from an ordinary one-turn task. This fails while any goal is still stored.",
+			parameters: Schema{
+				Type: "object",
+				Properties: map[string]PropertySchema{
+					"objective": {
+						Type:        "string",
+						Description: "The concrete objective to keep pursuing.",
+						MaxLength:   &maxObjectiveLength,
+					},
+					"token_budget": {
+						Type:        "integer",
+						Description: "Optional maximum total tokens. Zero means no goal-specific limit.",
+						Minimum:     &minimum,
+						Maximum:     &maximum,
+					},
+				},
+				Required:             []string{"objective"},
+				AdditionalProperties: false,
+			},
+			safety: Safety{
+				SideEffect:      SideEffectWrite,
+				Permission:      PermissionPrompt,
+				Reason:          "Creates persistent goal state and enables automatic follow-up runs for the current session.",
+				AdvertiseInAuto: true,
+			},
+			capabilities: ToolCapabilities{Effect: EffectInteractive, ThreadSafe: false, ResourceKeys: sessionResourceKeys},
+		},
+		store:     store,
+		sessionID: sessionID,
+		action:    "create",
+	}
+}
+
+func newUpdateGoalTool(store *sessions.Store, sessionID string) Tool {
+	return &goalTool{
+		baseTool: baseTool{
+			name: "update_goal",
+			description: "Finish the current goal or mark it blocked. Use complete only when the objective is achieved and no required work remains. " +
+				"Use blocked only when progress cannot continue without user input or an external state change.",
+			parameters: Schema{
+				Type: "object",
+				Properties: map[string]PropertySchema{
+					"status": {
+						Type:        "string",
+						Description: "The terminal state to apply.",
+						Enum:        []string{string(sessions.GoalStatusComplete), string(sessions.GoalStatusBlocked)},
+					},
+					"reason": {
+						Type:        "string",
+						Description: "Why the goal is blocked. Optional for completed goals.",
+					},
+				},
+				Required:             []string{"status"},
+				AdditionalProperties: false,
+			},
+			safety: Safety{
+				SideEffect: SideEffectNone,
+				Permission: PermissionAllow,
+				Reason:     "Updates persistent goal state for the current session.",
+			},
+			capabilities: ToolCapabilities{Effect: EffectInteractive, ThreadSafe: false, ResourceKeys: sessionResourceKeys},
+		},
+		store:     store,
+		sessionID: sessionID,
+		action:    "update",
+	}
+}
+
+func (tool *goalTool) Run(_ context.Context, args map[string]any) Result {
+	if tool.store == nil || !sessions.ValidSessionID(tool.sessionID) {
+		return errorResult("Error: Goal state is unavailable for this run.")
+	}
+	switch tool.action {
+	case "get":
+		session, err := tool.store.Get(tool.sessionID)
+		if err != nil {
+			return errorResult("Error: Read goal: " + err.Error())
+		}
+		if session == nil || session.Goal == nil {
+			return okResult("No goal is set for this session.")
+		}
+		return goalResult(session.Goal)
+	case "create":
+		objective, err := stringArg(args, "objective", "", true)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for create_goal: " + err.Error())
+		}
+		tokenBudget, err := intArg(args, "token_budget", 0, 0, 1_000_000_000)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for create_goal: " + err.Error())
+		}
+		session, _, err := tool.store.CreateGoal(tool.sessionID, objective, tokenBudget)
+		if err != nil {
+			return errorResult("Error: Create goal: " + err.Error())
+		}
+		return goalResult(session.Goal)
+	case "update":
+		statusText, err := stringArg(args, "status", "", true)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for update_goal: " + err.Error())
+		}
+		status := sessions.GoalStatus(strings.ToLower(statusText))
+		if status != sessions.GoalStatusComplete && status != sessions.GoalStatusBlocked {
+			return errorResult(`Error: Invalid arguments for update_goal: status must be "complete" or "blocked"`)
+		}
+		reason, err := stringArgWithEmpty(args, "reason", "", false, true)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for update_goal: " + err.Error())
+		}
+		if status == sessions.GoalStatusBlocked && strings.TrimSpace(reason) == "" {
+			return errorResult("Error: Invalid arguments for update_goal: blocked goals require a reason")
+		}
+		session, _, err := tool.store.UpdateGoal(tool.sessionID, status, reason)
+		if err != nil {
+			return errorResult("Error: Update goal: " + err.Error())
+		}
+		return goalResult(session.Goal)
+	default:
+		return errorResult("Error: Unknown goal action.")
+	}
+}
+
+func goalResult(goal *sessions.Goal) Result {
+	if goal == nil {
+		return okResult("No goal is set for this session.")
+	}
+	data, err := json.MarshalIndent(goal, "", "  ")
+	if err != nil {
+		return errorResult(fmt.Sprintf("Error: Encode goal: %v", err))
+	}
+	return okResult(string(data))
+}

internal/tools/goal_test.go

@@ -0,0 +1,76 @@
+package tools
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/sessions"
+)
+
+func TestGoalToolsAreBoundToTheirSession(t *testing.T) {
+	store := sessions.NewStore(sessions.StoreOptions{RootDir: t.TempDir()})
+	first, err := store.Create(sessions.CreateInput{SessionID: "first"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := store.Create(sessions.CreateInput{SessionID: "second"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	goalTools := NewGoalTools(store, first.SessionID)
+
+	result := goalTools[1].Run(context.Background(), map[string]any{"objective": "Finish first"})
+	if result.Status != StatusOK {
+		t.Fatalf("create result = %#v", result)
+	}
+	loadedFirst, _ := store.Get(first.SessionID)
+	loadedSecond, _ := store.Get(second.SessionID)
+	if loadedFirst.Goal == nil || loadedFirst.Goal.Objective != "Finish first" {
+		t.Fatalf("first goal = %#v", loadedFirst.Goal)
+	}
+	if loadedSecond.Goal != nil {
+		t.Fatalf("second goal unexpectedly changed = %#v", loadedSecond.Goal)
+	}
+}
+
+func TestCreateGoalToolDeclaresTokenBudgetMaximum(t *testing.T) {
+	create := NewGoalTools(nil, "goal")[1]
+	maximum := create.Parameters().Properties["token_budget"].Maximum
+	if maximum == nil || *maximum != 1_000_000_000 {
+		t.Fatalf("token_budget maximum = %v, want 1000000000", maximum)
+	}
+	maxLength := create.Parameters().Properties["objective"].MaxLength
+	if maxLength == nil || *maxLength != sessions.GoalObjectiveMaxLength {
+		t.Fatalf("objective maxLength = %v, want %d", maxLength, sessions.GoalObjectiveMaxLength)
+	}
+	safety := create.Safety()
+	if safety.SideEffect != SideEffectWrite || safety.Permission != PermissionPrompt || !safety.AdvertiseInAuto {
+		t.Fatalf("create_goal safety = %#v, want prompted persistent write advertised in auto mode", safety)
+	}
+}
+
+func TestUpdateGoalToolRestrictsAgentTransitions(t *testing.T) {
+	store := sessions.NewStore(sessions.StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(sessions.CreateInput{SessionID: "goal"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := store.CreateGoal(session.SessionID, "Finish it", 0); err != nil {
+		t.Fatal(err)
+	}
+	update := NewGoalTools(store, session.SessionID)[2]
+
+	result := update.Run(context.Background(), map[string]any{"status": "paused"})
+	if result.Status != StatusError || !strings.Contains(result.Output, "complete") {
+		t.Fatalf("paused result = %#v", result)
+	}
+	result = update.Run(context.Background(), map[string]any{"status": "blocked"})
+	if result.Status != StatusError || !strings.Contains(result.Output, "require a reason") {
+		t.Fatalf("reasonless blocked result = %#v", result)
+	}
+	result = update.Run(context.Background(), map[string]any{"status": "complete"})
+	if result.Status != StatusOK {
+		t.Fatalf("complete result = %#v", result)
+	}
+}

internal/tools/grep.go

@@ -48,7 +48,6 @@ func NewScopedGrepTool(workspaceRoot string, scope PathScope) Tool {
 					"path":             {Type: "string", Description: "Directory or file to search. Relative paths stay in the workspace; use an absolute path to search a granted extra root. Defaults to workspace root.", Default: "."},
 					"glob":             {Type: "string", Description: `Optional glob filter, for example "**/*.go".`},
 					"output_mode":      {Type: "string", Description: "Output mode.", Enum: []string{"content", "files_with_matches", "count"}, Default: "content"},
-					"-i":               {Type: "boolean", Description: "Case insensitive search.", Default: false},
 					"case_insensitive": {Type: "boolean", Description: "Case insensitive search.", Default: false},
 					"head_limit":       {Type: "integer", Description: "Maximum content results to return.", Default: 50, Minimum: intPtr(1)},
 				},

internal/tools/local_browser.go

@@ -45,6 +45,7 @@ func newBrowserInstallTool(options localcontrol.BrowserOptions) Tool {
 	return browserInstallTool{
 		baseTool: baseTool{
 			name:        "browser_install",
+			deferred:    true,
 			description: "Install the local browser runtime used by browser automation.",
 			parameters: Schema{
 				Type: "object",
@@ -86,6 +87,7 @@ func newBrowserLaunchToolWithLauncher(options localcontrol.BrowserOptions, launc
 	return browserLaunchTool{
 		baseTool: baseTool{
 			name:        "browser_launch",
+			deferred:    true,
 			description: "Launch a supported local Chromium/Electron app with Chrome DevTools enabled and attach browser automation to it. Use this for installed Electron apps such as Discord instead of launching GUI apps through shell commands.",
 			parameters: Schema{
 				Type: "object",
@@ -165,6 +167,7 @@ func newBrowserConnectTool(options localcontrol.BrowserOptions) Tool {
 	return browserConnectTool{
 		baseTool: baseTool{
 			name:        "browser_connect",
+			deferred:    true,
 			description: "Attach local browser automation to an existing Chrome/Electron DevTools endpoint. For Electron apps, first launch the app with --remote-debugging-port=<port>, then connect to that port instead of using desktop control.",
 			parameters: Schema{
 				Type: "object",
@@ -205,6 +208,7 @@ func newBrowserOpenTool(options localcontrol.BrowserOptions) Tool {
 	return browserOpenTool{
 		baseTool: baseTool{
 			name:        "browser_open",
+			deferred:    true,
 			description: "Open a URL in the local browser automation session.",
 			parameters: Schema{
 				Type: "object",
@@ -245,6 +249,7 @@ func newBrowserSnapshotTool(options localcontrol.BrowserOptions) Tool {
 	return browserSnapshotTool{
 		baseTool: baseTool{
 			name:        "browser_snapshot",
+			deferred:    true,
 			description: "Return an accessibility snapshot from the current local browser automation session.",
 			parameters: Schema{
 				Type: "object",
@@ -288,6 +293,7 @@ func newBrowserClickTool(options localcontrol.BrowserOptions) Tool {
 	return browserClickTool{
 		baseTool: baseTool{
 			name:        "browser_click",
+			deferred:    true,
 			description: "Click a ref from browser_snapshot in the current local browser automation session.",
 			parameters: Schema{
 				Type: "object",
@@ -328,6 +334,7 @@ func newBrowserTypeTool(options localcontrol.BrowserOptions) Tool {
 	return browserTypeTool{
 		baseTool: baseTool{
 			name:        "browser_type",
+			deferred:    true,
 			description: "Type text into a ref from browser_snapshot in the current local browser automation session.",
 			parameters: Schema{
 				Type: "object",
@@ -369,6 +376,7 @@ func newBrowserPressTool(options localcontrol.BrowserOptions) Tool {
 	return browserPressTool{
 		baseTool: baseTool{
 			name:        "browser_press",
+			deferred:    true,
 			description: "Press a keyboard key in the current local browser automation session.",
 			parameters: Schema{
 				Type: "object",
@@ -454,6 +462,7 @@ func newBrowserActionTool(options localcontrol.BrowserOptions) Tool {
 	return browserActionTool{
 		baseTool: baseTool{
 			name:        "browser_action",
+			deferred:    true,
 			description: "Run an allowed action against the current local browser automation session.",
 			parameters: Schema{
 				Type: "object",

internal/tools/local_capture.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"github.com/Gitlawb/zero/internal/imageinput"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -40,6 +42,7 @@ func newCaptureArtifactTool(options LocalControlArtifactOptions) Tool {
 	return captureArtifactTool{
 		baseTool: baseTool{
 			name:        "capture_artifact",
+			deferred:    true,
 			description: "Capture local browser, desktop, or terminal state into the configured artifact directory.",
 			parameters: Schema{
 				Type: "object",
@@ -344,9 +347,18 @@ func captureOKResult(driver string, request captureArtifactRequest, path string,
 	if helperOutput != "" {
 		output += "\n\n" + helperOutput
 	}
+	// Attach the artifact itself. Without this the model is told a screenshot
+	// exists and cannot look at it, which is the whole point of asking for one.
+	// A PDF or an unreadable file simply yields no image and the text stands on
+	// its own, so a capture is never failed over the attachment.
+	var images []zeroruntime.ImageBlock
+	if image, err := imageinput.LoadFile(path, ""); err == nil {
+		images = []zeroruntime.ImageBlock{image}
+	}
 	return Result{
 		Status: StatusOK,
 		Output: output,
+		Images: images,
 		Meta: map[string]string{
 			"artifact_path": path,
 			"action":        request.action,