fix(tools): reject mixed-root freeform patches

Merge main into feat/runtime-performance
fix(tools): make apply_patch tolerant and re-expose edit_file (#956 )
2026-11-08 09:49:34 -10:00 · 2026-08-26 01:18:34 +05:30 · 2026-08-25 21:04:28 +05:30 · 2026-08-25 20:23:48 +08:00 · 2026-08-25 11:43:40 +05:30 · 2026-08-25 11:43:40 +05:30
199 changed files with 12089 additions and 2829 deletions
@@ -1 +1 @@
-{".":"0.7.0"}
+{".":"0.8.0"}
@@ -111,3 +111,42 @@ These classes drive multi-round reviews. Fix them before requesting review:
  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.
+- **Host tool version floors:** Zero shells out to `git` and other host tools,
+  and the project does not declare a minimum version for any of them. A flag,
+  subcommand, or config key that is not long-established therefore raises that
+  floor silently, and the failure on an older host is an unhelpful usage error
+  rather than a clear message. Before adding one, check when it landed and say
+  so where a caller would look. Record the floor for the exact subcommand you
+  call, not for the flag in general: `--end-of-options` reached Git's shared
+  parser in 2.24, but `git rev-parse` only accepted it from 2.30, and
+  `git checkout` and `git reset` later still. Likewise `--show-current` is
+  `git branch` 2.22, and `branch.autoSetupMerge=inherit` is 2.35. Then either
+  keep a fallback for older versions or gate the call. A test that depends on a
+  newer feature must skip below its floor instead of failing, and say which
+  version it needs.
+- **Prove the test fails without the change:** A regression test earns its
+  place only if it fails on the unfixed code, for the reason it claims. Run it
+  both ways and quote the failure in the PR. The recurring miss is not a
+  missing test but a test that never reaches the behavior it names, because an
+  earlier guard rejects the input first, so it passes with and without the fix.
+  When a test targets a specific layer, call that layer directly rather than
+  relying on a public entry point that may refuse earlier.
+- **Hermetic tests:** Tests must not read or write the developer's real config,
+  cache, or state directories. Redirect every root the code under test
+  resolves, not just config. `os.UserConfigDir` and `os.UserCacheDir` read
+  `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` only on Linux and the BSDs. On macOS
+  they derive from `HOME`, and on Windows from `%AppData%` and `%LocalAppData%`.
+  Setting the XDG variables alone still leaves a macOS run writing to the real
+  home, so set `HOME` as well, or take the directory as a parameter. Apply it to
+  every test that reaches the same storage, not only the one where it was first
+  needed; a test that passes on a clean machine and pollutes a real one is a
+  blocker.
+- **Error codes vary by platform and by flag combination:** A check written
+  against the code one target returns can be silently inert on another while
+  still looking correct. `openat(O_DIRECTORY|O_NOFOLLOW)` on a symlink may
+  report `ENOTDIR` or `ELOOP` depending on the platform, because the kernel can
+  reject the directory mismatch before it ever resolves the link; accept both
+  rather than assuming the one POSIX names. On Windows, `\\?\` and `\\.\`
+  prefixes are not UNC paths, and an `NtCreateFile` information class must match
+  the struct actually passed. Confirm the code each supported target returns
+  instead of reasoning from the man page.
@@ -6,6 +6,27 @@ 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.8.0](https://github.com/Gitlawb/zero/compare/v0.7.0...v0.8.0) (2026-08-21)
+
+
+### Features
+
+* **security:** path-jail primitive, credential-store locking, worktree git hardening ([#891](https://github.com/Gitlawb/zero/issues/891)) ([060d38c](https://github.com/Gitlawb/zero/commit/060d38ce716feb7c5b6657b082cd35cb8dda3d75))
+* **update:** recognise Homebrew installs and add mise, go install docs ([#910](https://github.com/Gitlawb/zero/issues/910)) ([01c3498](https://github.com/Gitlawb/zero/commit/01c3498205e69d26e5f929225f9455b276444f39))
+* use Exa as default search provider ([#926](https://github.com/Gitlawb/zero/issues/926)) ([1ec7219](https://github.com/Gitlawb/zero/commit/1ec7219aee7b2840481ab0905f131644e27d2a4e))
+* **zerogit:** auto-create a conventional branch before push/pr on default branch ([#671](https://github.com/Gitlawb/zero/issues/671)) ([d065467](https://github.com/Gitlawb/zero/commit/d065467cd3ec3ed91c5dc60554c36fc4b4d6de4c))
+
+
+### Bug Fixes
+
+* **acp:** three defects a desktop ACP client hits ([#915](https://github.com/Gitlawb/zero/issues/915)) ([a78c6c3](https://github.com/Gitlawb/zero/commit/a78c6c357e1d21146d7cd2e8030a754e06f7f1f5))
+* bump Go to 1.26.6 for stdlib vulnerability fixes ([#903](https://github.com/Gitlawb/zero/issues/903)) ([dc15e82](https://github.com/Gitlawb/zero/commit/dc15e822987d8d7de467c62c375518f435b74d8c))
+* **daemon:** clean up child after startup timeout ([#774](https://github.com/Gitlawb/zero/issues/774)) ([9c29209](https://github.com/Gitlawb/zero/commit/9c292092a26c9092fd873d072b0af1b0d9d39ef0))
+* **dictation:** redact API keys from streaming transcriber errors ([#852](https://github.com/Gitlawb/zero/issues/852)) ([64a783b](https://github.com/Gitlawb/zero/commit/64a783b08caa2c7b21f188033b9ed84a14e00e84))
+* **modelregistry:** expose reasoning effort for DeepSeek V4 models ([#931](https://github.com/Gitlawb/zero/issues/931)) ([90dcfd1](https://github.com/Gitlawb/zero/commit/90dcfd127e8a6d9902ec9f4e72f6d03fef1a0fc6))
+* **providers:** discover ChatGPT capabilities ([#890](https://github.com/Gitlawb/zero/issues/890)) ([2d2450e](https://github.com/Gitlawb/zero/commit/2d2450e9a744349f0d01b1d4e9ba29c24ba5650d))
+* **sandbox:** normalize launcher names before the command-prefix denylist ([#934](https://github.com/Gitlawb/zero/issues/934)) ([6edf9a8](https://github.com/Gitlawb/zero/commit/6edf9a8b78dc030dc44598919db1c7fa9d4f809a))
+
 ## [0.7.0](https://github.com/Gitlawb/zero/compare/v0.6.0...v0.7.0) (2026-08-10)


@@ -371,9 +371,13 @@ go run ./cmd/zero-perf-bench

 Experimental: `ZERO_OPENAI_TURN_SESSION=1` enables the optimized OpenAI turn
 session (background connection prewarm + request-prefix telemetry) for headless
-`zero exec` runs against official OpenAI profiles. Off by default; `0`/`false`
-disable. A/B-benchmark it by running the same `zero-perf-bench` suite with the
-variable unset and set.
+`zero exec` runs against official OpenAI profiles. Off by default; `0`, `false`,
+or `off` disable it. A/B-benchmark it by running the same `zero-perf-bench` suite
+with the variable unset and set.
+
+Native ChatGPT Responses sessions are enabled by default. Set
+`ZERO_CHATGPT_TURN_SESSION=0`, `false`, or `off` to restore stateless HTTP/SSE
+transport.

 ### Code Quality and Security Checks

@@ -33,4 +33,4 @@ Please include, where possible:
  depend on a user explicitly disabling the sandbox (`--skip-permissions-unsafe`), are generally
  out of scope — but please report anything you are unsure about.
 - Zero sends no telemetry. Network calls go to the model/tool providers you configure (and, for
-  keyless web search, to the documented Firecrawl endpoint — see the README).
+  keyless web search, to Exa's hosted MCP endpoint at `https://mcp.exa.ai/mcp`).
@@ -4,7 +4,7 @@ go 1.26.6

 require (
 	charm.land/bubbles/v2 v2.1.1
-	charm.land/bubbletea/v2 v2.0.8
+	charm.land/bubbletea/v2 v2.0.9
 	charm.land/lipgloss/v2 v2.0.5
 	github.com/Microsoft/go-winio v0.6.2
 	github.com/alecthomas/chroma/v2 v2.27.0
@@ -1,7 +1,7 @@
 charm.land/bubbles/v2 v2.1.1 h1:7r55WzBxpo/R3z98hGmY7KKPd3ET6vsf0Fb9sDHOV60=
 charm.land/bubbles/v2 v2.1.1/go.mod h1:GE6M31gaWZVXzGw73OeuTTgy4lX+OtkH0E5ymnNsHxo=
-charm.land/bubbletea/v2 v2.0.8 h1:SxTJMhCAI3lbPmy4SgX5LWZ24AdINr4I6UEqzZvYJuY=
-charm.land/bubbletea/v2 v2.0.8/go.mod h1:2SkdgoTXluXJHOUwAoRlRXF/28vklb1rFl6GcgV1/ss=
+charm.land/bubbletea/v2 v2.0.9 h1:DpJCMWKgzQK8SJv4zbKKFHAI10ymWy/evClPFk0k0f8=
+charm.land/bubbletea/v2 v2.0.9/go.mod h1:2SkdgoTXluXJHOUwAoRlRXF/28vklb1rFl6GcgV1/ss=
 charm.land/lipgloss/v2 v2.0.5 h1:kbNxgeeUOYv5J0YdpxFjfvf3dFvqH8Aci4zB6xqFtrY=
 charm.land/lipgloss/v2 v2.0.5/go.mod h1:9oqhxt4yxIMe6q5A4kHr44DremZk7J9UNh74GlWa5nc=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
@@ -64,8 +64,6 @@ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavM
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 golang.org/x/exp v0.0.0-20260611194520-c48552f49976 h1:X8Hz2ImujgbmetVuW+w2YkyZChE3cBpZi2P158rTG9M=
 golang.org/x/exp v0.0.0-20260611194520-c48552f49976/go.mod h1:vnf4pv9iKZXY58sQE1L86zmNWJ4159e1RkcWiLCkeEY=
-golang.org/x/image v0.44.0 h1:+tDekMZED9+LrtB3G5xzRggpVh9CARjZqROla3R3R+I=
-golang.org/x/image v0.44.0/go.mod h1:V8K3KE9KKKE+pLpQDOeN18w9oacNSvy1tDOirTu4xtY=
 golang.org/x/image v0.45.0 h1:FMb1nTbH5H9vF55SriQHgFw5GnNL9Jg6L25BwXKzhB0=
 golang.org/x/image v0.45.0/go.mod h1:n62x/7RqlwXDvGsSU4u6IUTUf6KghUZ9Bt7cG/T9Fx4=
 golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
@@ -296,6 +296,16 @@ func stopReasonFor(result agent.Result, err error) (string, error) {
 		if errors.Is(err, context.Canceled) {
 			return StopCancelled, nil
 		}
+		// A CLIENT THAT CANCELLED A PERMISSION PROMPT DID NOT FAIL. Only
+		// context.Canceled was matched here, so dismissing a permission dialog —
+		// a deliberate action, and for apply_patch the only refusal a client is
+		// offered — came back as JSON-RPC -32603 carrying the internal sentinel
+		// text. Editors and the desktop app both render that as a crashed turn,
+		// so declining a tool looked like ZERO falling over. It is a
+		// cancellation, and StopCancelled is what ACP has for saying so.
+		if errors.Is(err, agent.ErrPermissionApprovalCanceled) {
+			return StopCancelled, nil
+		}
 		return "", err
 	}
 	if result.FinishReason == "length" {
@@ -311,10 +321,14 @@ func stopReasonFor(result agent.Result, err error) (string, error) {
 // session/request_permission request and maps the outcome back. Failure to reach
 // the client fails closed to deny.
 func (a *Agent) requestPermission(ctx context.Context, sessionID string, req agent.PermissionRequest) (agent.PermissionDecision, error) {
+	// Built ONCE and used for both halves. Sending one list and validating the
+	// reply against another is the defect this whole path had; see
+	// decisionFromOutcome.
+	options := buildPermissionOptions(req)
 	params := RequestPermissionParams{
 		SessionID: sessionID,
 		ToolCall:  permissionToolCall(req),
-		Options:   buildPermissionOptions(req),
+		Options:   options,
 	}
 	var result RequestPermissionResult
 	if err := a.conn.Call(ctx, MethodSessionRequestPerm, params, &result); err != nil {
@@ -323,7 +337,7 @@ func (a *Agent) requestPermission(ctx context.Context, sessionID string, req age
 		}
 		return agent.PermissionDecision{Action: agent.PermissionDecisionDeny, Reason: "permission request failed: " + err.Error()}, nil
 	}
-	return decisionFromOutcome(result.Outcome, req.AvailableDecisions), nil
+	return decisionFromOutcome(result.Outcome, options), nil
 }

 func (a *Agent) emitPlan(registry *tools.Registry, note *notifier) {
@@ -0,0 +1,217 @@
+package acp
+
+// desktopinterop_test.go covers three defects found by driving the real `zero
+// acp` binary from a desktop ACP client. Each is a case where ZERO and a
+// conforming client disagreed about the wire, and none of them failed loudly —
+// they produced a silent denial, a spurious crash, or two buttons the user
+// could not tell apart.
+//
+// A fourth, session/load restoring history without replaying it, is fixed by
+// #914 rather than here: that one also gives the replayed messages stable ids
+// and keeps session/resume replay-free, which this did not.
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/agent"
+)
+
+// ---- an offered option is an acceptable answer ----
+
+// The list the options were BUILT from and the list the answer was CHECKED
+// against were different whenever ZERO did not enumerate: the client was sent
+// Allow and Reject, and its reply was validated against an empty slice, so
+// every button it could possibly show failed closed to deny. The user clicked
+// Allow and ZERO recorded a denial, with nothing on screen to say so.
+func TestAnOfferedOptionIsAccepted(t *testing.T) {
+	// No AvailableDecisions: the fallback path, which is every permission event
+	// that is not a prompt.
+	req := agent.PermissionRequest{ToolName: "bash"}
+
+	options := buildPermissionOptions(req)
+	if len(options) == 0 {
+		t.Fatal("no options were offered")
+	}
+
+	for _, option := range options {
+		decision := decisionFromOutcome(
+			RequestPermissionOutcome{Outcome: OutcomeSelected, OptionID: option.OptionID},
+			buildPermissionOptions(req),
+		)
+		if string(decision.Action) != option.OptionID {
+			t.Fatalf("option %q was answered with %q (%s) — an offered option must be accepted",
+				option.OptionID, decision.Action, decision.Reason)
+		}
+	}
+}
+
+// The narrowing this validation exists for still holds: a client must not be
+// able to return a broader grant than it was shown.
+func TestAnOptionThatWasNotOfferedIsStillRefused(t *testing.T) {
+	req := agent.PermissionRequest{ToolName: "bash"}
+
+	decision := decisionFromOutcome(
+		RequestPermissionOutcome{Outcome: OutcomeSelected, OptionID: string(agent.PermissionDecisionAlwaysAllow)},
+		buildPermissionOptions(req),
+	)
+	if decision.Action != agent.PermissionDecisionDeny {
+		t.Fatalf("an unoffered broader grant was accepted as %q", decision.Action)
+	}
+}
+
+// The resolver is the single source of truth for both sides, which is what
+// makes the two agree by construction rather than by being kept in step.
+func TestOfferedDecisionsMatchWhatWasSent(t *testing.T) {
+	for _, req := range []agent.PermissionRequest{
+		{ToolName: "bash"},
+		{ToolName: "bash", AvailableDecisions: []agent.PermissionDecisionAction{
+			agent.PermissionDecisionAllow,
+			agent.PermissionDecisionAllowForSession,
+			agent.PermissionDecisionDeny,
+		}},
+	} {
+		offered := buildPermissionOptions(req)
+		for _, option := range buildPermissionOptions(req) {
+			if !actionOffered(option.OptionID, offered) {
+				t.Fatalf("option %q was sent but is not in the offered set %v", option.OptionID, offered)
+			}
+		}
+	}
+}
+
+// ---- two options the user can tell apart ----
+
+// request_permissions offers plain allow and strict-review allow together, and
+// both were labelled "Allow". The label is the only thing an ACP client shows,
+// so the panel presented two identical buttons where one silently enabled
+// strict auto-review of what was granted.
+func TestEveryOfferedOptionHasADistinctLabel(t *testing.T) {
+	req := agent.PermissionRequest{
+		ToolName: "request_permissions",
+		AvailableDecisions: []agent.PermissionDecisionAction{
+			agent.PermissionDecisionAllow,
+			agent.PermissionDecisionAllowStrict,
+			agent.PermissionDecisionAllowForSession,
+			agent.PermissionDecisionDeny,
+		},
+	}
+
+	seen := map[string]string{}
+	for _, option := range buildPermissionOptions(req) {
+		if previous, clash := seen[option.Name]; clash {
+			t.Fatalf("options %q and %q share the label %q — a user cannot tell them apart",
+				previous, option.OptionID, option.Name)
+		}
+		seen[option.Name] = option.OptionID
+	}
+}
+
+// The two remain distinct decisions: the label changed, the round trip did not.
+func TestStrictAllowStillRoundTrips(t *testing.T) {
+	req := agent.PermissionRequest{
+		ToolName: "request_permissions",
+		AvailableDecisions: []agent.PermissionDecisionAction{
+			agent.PermissionDecisionAllow,
+			agent.PermissionDecisionAllowStrict,
+		},
+	}
+	decision := decisionFromOutcome(
+		RequestPermissionOutcome{Outcome: OutcomeSelected, OptionID: string(agent.PermissionDecisionAllowStrict)},
+		buildPermissionOptions(req),
+	)
+	if decision.Action != agent.PermissionDecisionAllowStrict {
+		t.Fatalf("strict allow round-tripped as %q", decision.Action)
+	}
+}
+
+// ---- cancelling a permission is a cancellation, not a crash ----
+
+// Only context.Canceled was recognised, so dismissing a permission dialog came
+// back as JSON-RPC -32603 carrying the internal sentinel text. Clients render
+// that as a failed turn, so declining a tool looked like ZERO falling over —
+// and for apply_patch, dismissing is the ONLY refusal a client is offered.
+func TestCancellingAPermissionEndsTheTurnAsCancelled(t *testing.T) {
+	canceled := fmt.Errorf("%w for apply_patch", agent.ErrPermissionApprovalCanceled)
+
+	reason, err := stopReasonFor(agent.Result{}, canceled)
+	if err != nil {
+		t.Fatalf("stopReasonFor returned an error for a cancellation: %v", err)
+	}
+	if reason != StopCancelled {
+		t.Fatalf("stop reason = %q, want %q", reason, StopCancelled)
+	}
+}
+
+// A genuine failure must still be an error. Mapping too much to cancelled would
+// hide real faults behind a clean ending, which is the opposite mistake.
+func TestARealFailureIsStillAnError(t *testing.T) {
+	failure := errors.New("provider exploded")
+
+	if _, err := stopReasonFor(agent.Result{}, failure); !errors.Is(err, failure) {
+		t.Fatalf("stopReasonFor(%v) = %v, want the failure preserved", failure, err)
+	}
+}
+
+// The sentinel is matched through errors.Is, so it survives the wrapping every
+// return site applies — each one adds the tool name.
+func TestPermissionCancellationSurvivesWrapping(t *testing.T) {
+	if !errors.Is(fmt.Errorf("%w for bash", agent.ErrPermissionApprovalCanceled), agent.ErrPermissionApprovalCanceled) {
+		t.Fatal("a wrapped permission cancellation was not recognised")
+	}
+	if errors.Is(errors.New("something else"), agent.ErrPermissionApprovalCanceled) {
+		t.Fatal("an unrelated error was reported as a permission cancellation")
+	}
+}
+
+// A decision that never became an option cannot be selected.
+//
+// PermissionDecisionCancel is the case that exists today: optionKindFor drops
+// it because ACP expresses cancellation through the outcome, yet ZERO
+// enumerates it in AvailableDecisions for shell commands and apply_patch. While
+// the reply was validated against the DECISIONS rather than the sent options, a
+// client could return {"outcome":"selected","optionId":"cancel"} — an id it was
+// never shown — and abort the whole turn.
+//
+// Written over every option-less decision rather than over "cancel", so a
+// future action that optionKindFor declines to render is covered the day it is
+// added rather than the day someone remembers this test.
+func TestADecisionThatIsNotAnOptionCannotBeSelected(t *testing.T) {
+	for _, toolName := range []string{"bash", "apply_patch"} {
+		req := agent.PermissionRequest{
+			ToolName: toolName,
+			AvailableDecisions: []agent.PermissionDecisionAction{
+				agent.PermissionDecisionAllow,
+				agent.PermissionDecisionDeny,
+				agent.PermissionDecisionCancel,
+			},
+		}
+		options := buildPermissionOptions(req)
+
+		for _, action := range req.AvailableDecisions {
+			if actionOffered(string(action), options) {
+				continue // it was sent; selecting it is legitimate
+			}
+			decision := decisionFromOutcome(
+				RequestPermissionOutcome{Outcome: OutcomeSelected, OptionID: string(action)},
+				options,
+			)
+			if decision.Action != agent.PermissionDecisionDeny {
+				t.Fatalf("%s: %q was never sent as an option but was accepted as %q",
+					toolName, action, decision.Action)
+			}
+		}
+	}
+}
+
+// Cancelling is still reachable — through the outcome, which is where ACP puts
+// it. Closing the selected-id route must not close the real one.
+func TestCancellingThroughTheOutcomeStillWorks(t *testing.T) {
+	options := buildPermissionOptions(agent.PermissionRequest{ToolName: "apply_patch"})
+
+	decision := decisionFromOutcome(RequestPermissionOutcome{Outcome: OutcomeCancelled}, options)
+	if decision.Action != agent.PermissionDecisionCancel {
+		t.Fatalf("outcome=cancelled gave %q, want cancel", decision.Action)
+	}
+}
@@ -15,14 +15,7 @@ import (
 // PermissionOptions. Only the actions ZERO actually presented (AvailableDecisions)
 // are surfaced; the optionId is the ZERO action string for a clean round-trip.
 func buildPermissionOptions(req agent.PermissionRequest) []PermissionOption {
-	actions := req.AvailableDecisions
-	if len(actions) == 0 {
-		// Sensible default if ZERO didn't enumerate: allow once / reject.
-		actions = []agent.PermissionDecisionAction{
-			agent.PermissionDecisionAllow,
-			agent.PermissionDecisionDeny,
-		}
-	}
+	actions := offeredDecisions(req)
 	options := make([]PermissionOption, 0, len(actions))
 	for _, action := range actions {
 		kind, name := optionKindFor(action, req.PrefixApprovalEscalates)
@@ -38,6 +31,32 @@ func buildPermissionOptions(req agent.PermissionRequest) []PermissionOption {
 	return options
 }

+// offeredDecisions resolves what this request actually offers the client.
+//
+// ONE RESOLVER, USED BY BOTH SIDES, and that is the entire point of it existing.
+// The fallback below used to live inside buildPermissionOptions while
+// requestPermission validated the client's answer against the raw
+// req.AvailableDecisions. When ZERO did not enumerate — which is every
+// permission event that is not a prompt, and includes a shell call whose sandbox
+// decision came back deny — the two disagreed completely: the client was sent
+// "Allow" and "Reject", and validation was performed against an EMPTY list, so
+// every option the client could possibly click failed closed to deny with
+// "permission option was not offered".
+//
+// The user clicked Allow and ZERO recorded a denial. Nothing surfaced it,
+// because a denial is a legitimate answer — the tool was simply refused and the
+// turn carried on as though the user had rejected it.
+func offeredDecisions(req agent.PermissionRequest) []agent.PermissionDecisionAction {
+	if len(req.AvailableDecisions) > 0 {
+		return req.AvailableDecisions
+	}
+	// Sensible default if ZERO didn't enumerate: allow once / reject.
+	return []agent.PermissionDecisionAction{
+		agent.PermissionDecisionAllow,
+		agent.PermissionDecisionDeny,
+	}
+}
+
 // optionKindFor maps a ZERO decision action to an ACP PermissionOptionKind and a
 // human label. Returns an empty kind for actions that ACP expresses through the
 // outcome rather than an option (cancel).
@@ -49,8 +68,16 @@ func buildPermissionOptions(req agent.PermissionRequest) []PermissionOption {
 // disclosure cannot be TUI-only.
 func optionKindFor(action agent.PermissionDecisionAction, escalates bool) (kind, name string) {
 	switch action {
-	case agent.PermissionDecisionAllow, agent.PermissionDecisionAllowStrict:
+	case agent.PermissionDecisionAllow:
 		return PermAllowOnce, "Allow"
+	case agent.PermissionDecisionAllowStrict:
+		// SPLIT FROM PLAIN ALLOW because the label is the only thing an ACP
+		// client shows. Both were labelled "Allow", and request_permissions
+		// offers them together — so the panel presented two identical buttons,
+		// and whichever the user picked looked the same while one of them
+		// silently turned on strict auto-review of what was granted. The option
+		// id carries no room for the distinction, so it has to be in the name.
+		return PermAllowOnce, "Allow with strict review"
 	case agent.PermissionDecisionAllowForSession:
 		return PermAllowAlways, "Allow for this session"
 	case agent.PermissionDecisionAllowPrefix:
@@ -70,19 +97,31 @@ func optionKindFor(action agent.PermissionDecisionAction, escalates bool) (kind,

 // decisionFromOutcome maps the client's permission outcome back to a ZERO
 // decision. A cancelled outcome cancels the run; a selected option id is the ZERO
-// action verbatim (validated against what was offered); anything unrecognized
-// fails closed to deny.
-func decisionFromOutcome(outcome RequestPermissionOutcome, offered []agent.PermissionDecisionAction) agent.PermissionDecision {
+// action verbatim (validated against what was actually sent); anything
+// unrecognized fails closed to deny.
+//
+// IT TAKES THE OPTIONS THAT WERE SENT, not the decisions the request offered,
+// and the two are not the same list. Some actions never become options —
+// PermissionDecisionCancel is dropped by optionKindFor because ACP expresses
+// cancellation through the outcome instead — yet it IS enumerated in
+// AvailableDecisions for shell commands and apply_patch, the two commonest
+// prompts. Validating against the decisions therefore accepted
+// {"outcome":"selected","optionId":"cancel"}: an identifier no client was ever
+// shown, aborting the whole turn.
+//
+// Passing the sent options makes "what we offered" and "what we accept" the
+// same slice rather than two things kept in step, so anything optionKindFor
+// declines to render is excluded structurally instead of by name.
+func decisionFromOutcome(outcome RequestPermissionOutcome, offered []PermissionOption) agent.PermissionDecision {
 	switch outcome.Outcome {
 	case OutcomeCancelled:
 		return agent.PermissionDecision{Action: agent.PermissionDecisionCancel, Reason: "client cancelled"}
 	case OutcomeSelected:
-		action := agent.PermissionDecisionAction(outcome.OptionID)
 		// Bind to what was actually offered for THIS call: a client must not be able
 		// to return a broader grant (always_allow / allow_for_session) that wasn't
 		// presented. Anything not offered fails closed to deny.
-		if actionOffered(action, offered) {
-			return agent.PermissionDecision{Action: action}
+		if actionOffered(outcome.OptionID, offered) {
+			return agent.PermissionDecision{Action: agent.PermissionDecisionAction(outcome.OptionID)}
 		}
 		return agent.PermissionDecision{Action: agent.PermissionDecisionDeny, Reason: "permission option was not offered"}
 	default:
@@ -90,9 +129,9 @@ func decisionFromOutcome(outcome RequestPermissionOutcome, offered []agent.Permi
 	}
 }

-func actionOffered(action agent.PermissionDecisionAction, offered []agent.PermissionDecisionAction) bool {
-	for _, a := range offered {
-		if a == action {
+func actionOffered(optionID string, offered []PermissionOption) bool {
+	for _, option := range offered {
+		if option.OptionID == optionID {
 			return true
 		}
 	}
@@ -56,10 +56,11 @@ func TestACPPrefixOptionsStaySilentWithoutEscalation(t *testing.T) {
 // what was offered, so decorating it would fail every prefix approval closed.
 func TestACPDisclosureDoesNotDisturbTheOptionIDRoundTrip(t *testing.T) {
 	request := escalationRequest(true)
-	for _, option := range buildPermissionOptions(request) {
+	options := buildPermissionOptions(request)
+	for _, option := range options {
 		decision := decisionFromOutcome(
 			RequestPermissionOutcome{Outcome: OutcomeSelected, OptionID: option.OptionID},
-			request.AvailableDecisions,
+			options,
 		)
 		if string(decision.Action) != option.OptionID {
 			t.Errorf("option id %q round-tripped to %q (%s)", option.OptionID, decision.Action, decision.Reason)
@@ -39,11 +39,14 @@ func TestBuildPermissionOptionsDefault(t *testing.T) {
 }

 func TestDecisionFromOutcome(t *testing.T) {
-	offered := []agent.PermissionDecisionAction{
-		agent.PermissionDecisionAllow,
-		agent.PermissionDecisionAlwaysAllow,
-		agent.PermissionDecisionDeny,
-	}
+	offered := buildPermissionOptions(agent.PermissionRequest{
+		ToolName: "bash",
+		AvailableDecisions: []agent.PermissionDecisionAction{
+			agent.PermissionDecisionAllow,
+			agent.PermissionDecisionAlwaysAllow,
+			agent.PermissionDecisionDeny,
+		},
+	})
 	if d := decisionFromOutcome(RequestPermissionOutcome{Outcome: OutcomeCancelled}, offered); d.Action != agent.PermissionDecisionCancel {
 		t.Errorf("cancelled -> %q, want cancel", d.Action)
 	}
@@ -99,6 +99,43 @@ func TestProposedCommandPrefixRejectsUnsafeRequestedPrefix(t *testing.T) {
 	}
 }

+// The launcher denylist is only worth anything if it holds on the path a user
+// actually sees. A model naming its own prefix_rule is that path: before
+// launcher names were normalized, "python3.11" was offered as a one-token
+// grant, and hasStringPrefix then matched every later python3.11 invocation.
+func TestProposedCommandPrefixRejectsLauncherSpellingsInRequestedPrefix(t *testing.T) {
+	for _, testCase := range []struct {
+		command string
+		rule    []any
+	}{
+		{"python3.11 script.py", []any{"python3.11"}},
+		{"python.exe script.py", []any{"python.exe"}},
+		{"node.exe app.js", []any{"node.exe"}},
+		{"cmd /c whoami", []any{"cmd"}},
+		{"busybox sh -c id", []any{"busybox"}},
+		{"uv run main.py", []any{"uv", "run"}},
+		{"python3.11 -c import_os", []any{"python3.11", "-c"}},
+	} {
+		got := proposedCommandPrefix("bash", map[string]any{
+			"command":     testCase.command,
+			"prefix_rule": testCase.rule,
+		})
+		if got != nil {
+			t.Errorf("prefix_rule %v for %q was offered as %#v, want rejected", testCase.rule, testCase.command, got)
+		}
+	}
+}
+
+func TestProposedCommandPrefixStillOffersOrdinaryCommands(t *testing.T) {
+	got := proposedCommandPrefix("bash", map[string]any{
+		"command":     "cargo build --release",
+		"prefix_rule": []any{"cargo", "build"},
+	})
+	if len(got) != 2 || got[0] != "cargo" || got[1] != "build" {
+		t.Fatalf("ordinary prefix rule = %#v, want [cargo build]", got)
+	}
+}
+
 func TestProposedCommandPrefixRejectsUnsafeShellForms(t *testing.T) {
 	cases := []string{
 		"cat < in > out",
@@ -144,11 +144,17 @@ func estimateToolDefTokens(tools []zeroruntime.ToolDefinition) int {
 	for _, tool := range tools {
 		total += ApproxTextTokens(tool.Name)
 		total += ApproxTextTokens(tool.Description)
+		total += ApproxTextTokens(string(tool.Type))
 		if len(tool.Parameters) > 0 {
 			if encoded, err := json.Marshal(tool.Parameters); err == nil {
 				total += ApproxTextTokens(string(encoded))
 			}
 		}
+		if tool.Format != nil {
+			total += ApproxTextTokens(tool.Format.Type)
+			total += ApproxTextTokens(tool.Format.Syntax)
+			total += ApproxTextTokens(tool.Format.Definition)
+		}
 		total += 4 // per-tool overhead
 	}
 	return total
@@ -126,8 +126,11 @@ func capCompactionBrief(brief string) (string, bool) {

 func compactionToolCallLine(call zeroruntime.ToolCall) string {
 	detail := ""
+	if call.Freeform && call.Name == "apply_patch" {
+		detail = strings.Join(patchPaths(call.Arguments), ", ")
+	}
 	var arguments map[string]any
-	if json.Unmarshal([]byte(strings.TrimSpace(call.Arguments)), &arguments) == nil {
+	if detail == "" && json.Unmarshal([]byte(strings.TrimSpace(call.Arguments)), &arguments) == nil {
 		for _, key := range []string{"file_path", "path", "url", "query", "pattern", "prompt", "description", "question"} {
 			if value, ok := arguments[key].(string); ok && strings.TrimSpace(value) != "" {
 				detail = value
@@ -73,6 +73,7 @@ func TestProjectCompactionInputRetainsAskUserExchangeAndSemanticArguments(t *tes
 		{Role: zeroruntime.MessageRoleTool, ToolCallID: "ask", Content: "Which database should remain?: Postgres only; do not touch MySQL."},
 		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
 			{ID: "patch", Name: "apply_patch", Arguments: `{"patch":"*** Begin Patch\n*** Update File: internal/db.go\n*** End Patch"}`},
+			{ID: "raw-patch", Name: "apply_patch", Freeform: true, Arguments: "*** Begin Patch\n*** Update File: internal/api.go\n*** Add File: internal/config.go\n*** End Patch\n"},
 			{ID: "fetch", Name: "web_fetch", Arguments: `{"url":"https://example.com/spec"}`},
 			{ID: "task", Name: "task", Arguments: `{"prompt":"Inspect the Windows implementation"}`},
 		}},
@@ -80,7 +81,7 @@ func TestProjectCompactionInputRetainsAskUserExchangeAndSemanticArguments(t *tes
 	}

 	content := projectCompactionInput(messages).messages[0].Content
-	for _, want := range []string{"Which database should remain?", "Postgres only; do not touch MySQL", "internal/db.go", "https://example.com/spec", "Inspect the Windows implementation"} {
+	for _, want := range []string{"Which database should remain?", "Postgres only; do not touch MySQL", "internal/db.go", "internal/api.go", "internal/config.go", "https://example.com/spec", "Inspect the Windows implementation"} {
 		if !strings.Contains(content, want) {
 			t.Fatalf("projection missing %q: %q", want, content)
 		}
@@ -275,6 +275,27 @@ func TestEstimateToolDefTokensCountsDefinitions(t *testing.T) {
 	if estimateToolDefTokens(one) <= 0 {
 		t.Fatal("a tool definition (name + description + schema) should estimate > 0 tokens")
 	}
+	typed := append([]zeroruntime.ToolDefinition(nil), one...)
+	typed[0].Type = zeroruntime.ToolDefinitionFreeform
+	if estimateToolDefTokens(typed) <= estimateToolDefTokens(one) {
+		t.Fatal("a non-empty tool type must increase the estimated request cost")
+	}
+	for _, test := range []struct {
+		name   string
+		format zeroruntime.ToolDefinitionFormat
+	}{
+		{name: "type", format: zeroruntime.ToolDefinitionFormat{Type: "grammar"}},
+		{name: "syntax", format: zeroruntime.ToolDefinitionFormat{Syntax: "lark"}},
+		{name: "definition", format: zeroruntime.ToolDefinitionFormat{Definition: "start: WORD"}},
+	} {
+		t.Run("format "+test.name, func(t *testing.T) {
+			formatted := append([]zeroruntime.ToolDefinition(nil), one...)
+			formatted[0].Format = &test.format
+			if estimateToolDefTokens(formatted) <= estimateToolDefTokens(one) {
+				t.Fatalf("a non-empty format %s must increase the estimated request cost", test.name)
+			}
+		})
+	}
 	two := append(append([]zeroruntime.ToolDefinition{}, one...), zeroruntime.ToolDefinition{
 		Name:        "write_file",
 		Description: "Write contents to a file in the workspace.",
@@ -102,6 +102,10 @@ func copyToolDefinitions(toolDefs []zeroruntime.ToolDefinition) []zeroruntime.To
 	for index, definition := range toolDefs {
 		copied[index] = definition
 		copied[index].Parameters = copySchemaMap(definition.Parameters)
+		if definition.Format != nil {
+			format := *definition.Format
+			copied[index].Format = &format
+		}
 	}
 	return copied
 }
@@ -15,6 +15,7 @@ func TestContextPlannerPreservesProviderRequest(t *testing.T) {
 	}
 	toolDefs := []zeroruntime.ToolDefinition{{
 		Name: "read_file", Description: "Read a file",
+		Format: &zeroruntime.ToolDefinitionFormat{Type: "grammar", Syntax: "lark", Definition: "start: PATH"},
 		Parameters: map[string]any{
 			"type":       "object",
 			"required":   []string{"path"},
@@ -53,10 +54,12 @@ func TestContextPlannerPreservesProviderRequest(t *testing.T) {
 	toolDefs[0].Parameters["required"].([]string)[0] = "other"
 	toolDefs[0].Parameters["properties"].(map[string]any)["path"].(map[string]any)["type"] = "integer"
 	toolDefs[0].Parameters["anyOf"].([]any)[0].(map[string]any)["type"] = "array"
+	toolDefs[0].Format.Definition = "changed"
 	if plan.Request.Messages[1].Content != "inspect this" || plan.Request.Messages[1].Images[0].Data[0] != 1 {
 		t.Fatalf("planned messages alias caller state: %#v", plan.Request.Messages[1])
 	}
 	if plan.Request.Tools[0].Name != "read_file" ||
+		plan.Request.Tools[0].Format == nil || plan.Request.Tools[0].Format.Definition != "start: PATH" ||
 		plan.Request.Tools[0].Parameters["required"].([]string)[0] != "path" ||
 		plan.Request.Tools[0].Parameters["properties"].(map[string]any)["path"].(map[string]any)["type"] != "string" ||
 		plan.Request.Tools[0].Parameters["anyOf"].([]any)[0].(map[string]any)["type"] != "object" {
@@ -0,0 +1,378 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/sandbox"
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+type customApplyPatchTool struct {
+	calls int
+}
+
+type fixedPathScope struct {
+	roots []string
+}
+
+func (scope fixedPathScope) Roots() []string {
+	return append([]string(nil), scope.roots...)
+}
+
+func newFixedPathScope(t *testing.T, roots ...string) fixedPathScope {
+	t.Helper()
+	resolved := make([]string, 0, len(roots))
+	for _, root := range roots {
+		absolute, err := filepath.Abs(root)
+		if err != nil {
+			t.Fatalf("Abs(%q): %v", root, err)
+		}
+		if physical, err := filepath.EvalSymlinks(absolute); err == nil {
+			absolute = physical
+		}
+		resolved = append(resolved, absolute)
+	}
+	return fixedPathScope{roots: resolved}
+}
+
+func (*customApplyPatchTool) Name() string        { return "apply_patch" }
+func (*customApplyPatchTool) Description() string { return "custom JSON tool" }
+func (*customApplyPatchTool) Parameters() tools.Schema {
+	return tools.Schema{Type: "object", Properties: map[string]tools.PropertySchema{"value": {Type: "string"}}}
+}
+func (*customApplyPatchTool) Safety() tools.Safety {
+	return tools.Safety{Permission: tools.PermissionAllow, SideEffect: tools.SideEffectRead}
+}
+func (tool *customApplyPatchTool) Run(context.Context, map[string]any) tools.Result {
+	tool.calls++
+	return tools.Result{Status: tools.StatusOK}
+}
+
+func TestFreeformApplyPatchUsesExistingToolExecutionPath(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedApplyPatchTool(root, nil))
+	patch := "*** Begin Patch\n*** Add File: hello.txt\n+hello\n*** End Patch\n"
+
+	result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+		ID:        "call-1",
+		Name:      "apply_patch",
+		Arguments: patch,
+		Freeform:  true,
+	}, PermissionModeUnsafe, Options{Cwd: root, FileTracker: tools.NewFileTracker()})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusOK {
+		t.Fatalf("freeform apply_patch status = %s: %s", result.Status, result.Output)
+	}
+	content, err := os.ReadFile(filepath.Join(root, "hello.txt"))
+	if err != nil {
+		t.Fatalf("read patched file: %v", err)
+	}
+	if string(content) != "hello\n" {
+		t.Fatalf("patched content = %q, want hello newline", content)
+	}
+}
+
+func TestFreeformApplyPatchSupportsGrantedExtraRoot(t *testing.T) {
+	root := t.TempDir()
+	extra := t.TempDir()
+	scope, err := sandbox.NewScope(root, []string{extra})
+	if err != nil {
+		t.Fatalf("NewScope: %v", err)
+	}
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedApplyPatchTool(root, scope))
+	target := filepath.Join(extra, "hello.txt")
+	patch := "*** Begin Patch\n*** Add File: " + target + "\n+hello\n*** End Patch\n"
+
+	result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+		ID: "call-1", Name: "apply_patch", Arguments: patch, Freeform: true,
+	}, PermissionModeUnsafe, Options{Cwd: root, FileTracker: tools.NewFileTracker()})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusOK {
+		t.Fatalf("freeform extra-root apply_patch status = %s: %s", result.Status, result.Output)
+	}
+	content, err := os.ReadFile(target)
+	if err != nil {
+		t.Fatalf("read extra-root patched file: %v", err)
+	}
+	if string(content) != "hello\n" {
+		t.Fatalf("patched content = %q, want hello newline", content)
+	}
+}
+
+func TestFreeformApplyPatchRejectsMixedWorkspaceAndExtraRoots(t *testing.T) {
+	for _, extraHasMatchingPath := range []bool{false, true} {
+		name := "extra target missing"
+		if extraHasMatchingPath {
+			name = "extra target exists"
+		}
+		t.Run(name, func(t *testing.T) {
+			workspace := t.TempDir()
+			extra := t.TempDir()
+			if err := os.MkdirAll(filepath.Join(workspace, "src"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			workspaceTarget := filepath.Join(workspace, "src", "a.go")
+			if err := os.WriteFile(workspaceTarget, []byte("old\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			extraTarget := filepath.Join(extra, "src", "a.go")
+			if extraHasMatchingPath {
+				if err := os.MkdirAll(filepath.Dir(extraTarget), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(extraTarget, []byte("old\n"), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			scope, err := sandbox.NewScope(workspace, []string{extra})
+			if err != nil {
+				t.Fatal(err)
+			}
+			registry := tools.NewRegistry()
+			registry.Register(tools.NewScopedApplyPatchTool(workspace, scope))
+			extraCreated := filepath.Join(extra, "b.go")
+			patch := strings.Join([]string{
+				"*** Begin Patch",
+				"*** Update File: src/a.go",
+				"@@",
+				"-old",
+				"+new",
+				"*** Add File: " + extraCreated,
+				"+extra",
+				"*** End Patch",
+			}, "\n")
+
+			result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+				ID: "call-1", Name: "apply_patch", Arguments: patch, Freeform: true,
+			}, PermissionModeUnsafe, Options{Cwd: workspace, FileTracker: tools.NewFileTracker()})
+			if err != nil {
+				t.Fatalf("executeToolCall: %v", err)
+			}
+			if result.Status != tools.StatusError || !strings.Contains(result.Output, "mixes workspace-relative paths with an extra write root") {
+				t.Fatalf("mixed-root patch result = %s: %s", result.Status, result.Output)
+			}
+			if content, err := os.ReadFile(workspaceTarget); err != nil || string(content) != "old\n" {
+				t.Fatalf("workspace target changed: content=%q err=%v", content, err)
+			}
+			if extraHasMatchingPath {
+				if content, err := os.ReadFile(extraTarget); err != nil || string(content) != "old\n" {
+					t.Fatalf("extra-root target changed: content=%q err=%v", content, err)
+				}
+			}
+			if _, err := os.Stat(extraCreated); !os.IsNotExist(err) {
+				t.Fatalf("mixed-root patch created extra file: %v", err)
+			}
+		})
+	}
+}
+
+func TestFreeformApplyPatchAcceptsOneSemanticRoot(t *testing.T) {
+	for _, test := range []struct {
+		name         string
+		useExtraRoot bool
+	}{
+		{name: "workspace"},
+		{name: "extra root", useExtraRoot: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			workspace := t.TempDir()
+			extra := t.TempDir()
+			scope, err := sandbox.NewScope(workspace, []string{extra})
+			if err != nil {
+				t.Fatal(err)
+			}
+			root := workspace
+			if test.useExtraRoot {
+				root = extra
+			}
+			if err := os.MkdirAll(filepath.Join(root, "src"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			target := filepath.Join(root, "src", "a.go")
+			if err := os.WriteFile(target, []byte("old\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			updatePath := target
+			if !test.useExtraRoot {
+				updatePath = filepath.Join("src", "a.go")
+			}
+			created := filepath.Join(root, "b.go")
+			patch := strings.Join([]string{
+				"*** Begin Patch",
+				"*** Update File: " + updatePath,
+				"@@",
+				"-old",
+				"+new",
+				"*** Add File: " + created,
+				"+created",
+				"*** End Patch",
+			}, "\n")
+			registry := tools.NewRegistry()
+			registry.Register(tools.NewScopedApplyPatchTool(workspace, scope))
+			result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+				ID: "call-1", Name: "apply_patch", Arguments: patch, Freeform: true,
+			}, PermissionModeUnsafe, Options{Cwd: workspace, FileTracker: tools.NewFileTracker()})
+			if err != nil {
+				t.Fatalf("executeToolCall: %v", err)
+			}
+			if result.Status != tools.StatusOK {
+				t.Fatalf("single-root patch status = %s: %s", result.Status, result.Output)
+			}
+			if content, err := os.ReadFile(target); err != nil || string(content) != "new\n" {
+				t.Fatalf("updated content=%q err=%v", content, err)
+			}
+			if content, err := os.ReadFile(created); err != nil || string(content) != "created\n" {
+				t.Fatalf("created content=%q err=%v", content, err)
+			}
+		})
+	}
+}
+
+func TestFreeformApplyPatchRejectsAbsolutePathOutsideGrantedRoots(t *testing.T) {
+	root := t.TempDir()
+	granted := t.TempDir()
+	outside := t.TempDir()
+	scope := newFixedPathScope(t, root, granted)
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedApplyPatchTool(root, scope))
+	target := filepath.Join(outside, "blocked.txt")
+	patch := "*** Begin Patch\n*** Add File: " + target + "\n+blocked\n*** End Patch\n"
+
+	result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+		ID: "call-1", Name: "apply_patch", Arguments: patch, Freeform: true,
+	}, PermissionModeUnsafe, Options{Cwd: root})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusError {
+		t.Fatalf("ungranted absolute patch status = %s, want error: %s", result.Status, result.Output)
+	}
+	if _, err := os.Stat(target); !os.IsNotExist(err) {
+		t.Fatalf("ungranted absolute patch created target: %v", err)
+	}
+}
+
+func TestPreparedFreeformPatchRejectsIntermediateSymlinkSwap(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("creating directory symlinks requires privileges on Windows")
+	}
+	root := t.TempDir()
+	extra := t.TempDir()
+	outside := t.TempDir()
+	intermediate := filepath.Join(extra, "nested")
+	if err := os.Mkdir(intermediate, 0o755); err != nil {
+		t.Fatalf("Mkdir: %v", err)
+	}
+	scope := newFixedPathScope(t, root, extra)
+	tool := tools.NewScopedApplyPatchTool(root, scope)
+	target := filepath.Join(intermediate, "blocked.txt")
+	patch := "*** Begin Patch\n*** Add File: " + target + "\n+blocked\n*** End Patch\n"
+	args, err := tools.PrepareFreeformApplyPatchArguments(tool, patch)
+	if err != nil {
+		t.Fatalf("PrepareFreeformApplyPatchArguments: %v", err)
+	}
+
+	if err := os.Remove(intermediate); err != nil {
+		t.Fatalf("Remove intermediate: %v", err)
+	}
+	if err := os.Symlink(outside, intermediate); err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+	result := tool.Run(context.Background(), args)
+	if result.Status != tools.StatusError {
+		t.Fatalf("symlink-swapped patch status = %s, want error: %s", result.Status, result.Output)
+	}
+	if _, err := os.Stat(filepath.Join(outside, "blocked.txt")); !os.IsNotExist(err) {
+		t.Fatalf("symlink-swapped patch wrote outside root: %v", err)
+	}
+}
+
+func TestUnknownFreeformToolFailsClosed(t *testing.T) {
+	result, err := executeToolCall(context.Background(), tools.NewRegistry(), zeroruntime.ToolCall{
+		ID: "call-1", Name: "unknown", Arguments: "raw", Freeform: true,
+	}, PermissionModeUnsafe, Options{})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusError {
+		t.Fatalf("unknown freeform status = %s, want error", result.Status)
+	}
+}
+
+func TestCustomApplyPatchCannotUseFreeformContract(t *testing.T) {
+	custom := &customApplyPatchTool{}
+	registry := tools.NewRegistry()
+	registry.Register(custom)
+
+	result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+		ID: "call-1", Name: "apply_patch", Arguments: "raw patch", Freeform: true,
+	}, PermissionModeUnsafe, Options{})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusError || !strings.Contains(result.Output, "Unsupported freeform tool call") {
+		t.Fatalf("custom freeform apply_patch result = %#v, want unsupported error", result)
+	}
+	if custom.calls != 0 {
+		t.Fatalf("custom apply_patch executed %d times", custom.calls)
+	}
+}
+
+func TestDeniedFreeformApplyPatchDoesNotWrite(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedApplyPatchTool(root, nil))
+	patch := "*** Begin Patch\n*** Add File: denied.txt\n+must not exist\n*** End Patch\n"
+
+	result, err := executeToolCall(context.Background(), registry, zeroruntime.ToolCall{
+		ID:        "call-1",
+		Name:      "apply_patch",
+		Arguments: patch,
+		Freeform:  true,
+	}, PermissionModeAsk, Options{
+		Cwd: root,
+		OnPermissionRequest: func(context.Context, PermissionRequest) (PermissionDecision, error) {
+			return PermissionDecision{Action: PermissionDecisionDeny, Reason: "test denial"}, nil
+		},
+	})
+	if err != nil {
+		t.Fatalf("executeToolCall: %v", err)
+	}
+	if result.Status != tools.StatusError {
+		t.Fatalf("denied freeform status = %s, want error", result.Status)
+	}
+	if _, err := os.Stat(filepath.Join(root, "denied.txt")); !os.IsNotExist(err) {
+		t.Fatalf("denied freeform patch changed the workspace: %v", err)
+	}
+}
+
+func TestHistorySafeToolCallsPreservesRawFreeformArguments(t *testing.T) {
+	raw := "*** Begin Patch\n*** Update File: internal/main.go\n@@\n-old\n+new\n*** End Patch\n"
+	safe := historySafeToolCalls([]ToolCall{{
+		ID: "call-1", ProviderCallID: "provider-1", Name: "apply_patch", Arguments: raw, Freeform: true,
+	}})
+	if len(safe) != 1 || safe[0].Arguments != raw || safe[0].ProviderCallID != "provider-1" || !safe[0].Freeform {
+		t.Fatalf("freeform history changed raw call: %#v", safe)
+	}
+}
+
+func TestAbortedToolResultPreservesProviderCallID(t *testing.T) {
+	messages := appendAbortedToolResults(nil, []ToolCall{{
+		ID: "call-1", ProviderCallID: "provider-1", Name: "read_file",
+	}})
+	if len(messages) != 1 || messages[0].ToolCallID != "call-1" || messages[0].ToolCallProviderID != "provider-1" || !messages[0].IsError {
+		t.Fatalf("aborted tool result lost provider identity: %#v", messages)
+	}
+}
@@ -33,11 +33,11 @@ const (
 	// knows before spending more tool turns.
 	toolOnlyProgressReminderAt = 6

-	// planReminderTurn is the turn (1-based) by the end of which a multi-step
-	// task should have called update_plan; if it hasn't, a one-time reminder is
-	// injected. Set to 3 (not 2) so short, legitimate two-step tasks finish
-	// without a spurious planning nag.
-	planReminderTurn = 3
+	// planReminderTurn and planReminderToolThreshold keep bounded implementation
+	// work plan-free while still nudging a genuinely sustained run that has not
+	// established any structured progress. Both thresholds must be met.
+	planReminderTurn          = 7
+	planReminderToolThreshold = 7

 	// planToolName is the planning tool the loop watches for by name.
 	planToolName = "update_plan"
@@ -591,13 +591,12 @@ func (state *guardState) planReminder(turn int) string {
 		return planStaleReminder(state.toolCallsSincePlanUpdate)
 	}

-	// NOT-CALLED reminder: by the end of planReminderTurn the model should have
-	// called update_plan if it's doing a multi-step task (>=1 other tool call).
-	// One-shot for the whole run.
+	// NOT-CALLED reminder: once both the turn and tool-call thresholds are met,
+	// sustained work should have called update_plan. One-shot for the whole run.
 	if !state.notCalledReminderSent &&
 		!state.planEverCalled &&
 		turn >= planReminderTurn &&
-		state.totalToolCalls >= 1 {
+		state.totalToolCalls >= planReminderToolThreshold {
 		state.notCalledReminderSent = true
 		return planNotCalledReminder()
 	}
@@ -257,19 +257,16 @@ func TestRunDoesNotCountDroppedToolCallTurnsAsEmpty(t *testing.T) {
 }

 func TestRunInjectsPlanNotCalledReminderForMultiStepTask(t *testing.T) {
+	const expectedThreshold = 7
+	if planReminderToolThreshold != expectedThreshold {
+		t.Fatalf("plan reminder tool threshold = %d, want %d", planReminderToolThreshold, expectedThreshold)
+	}
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
 	registry.Register(tools.NewScopedReadFileTool(root, nil))

-	provider := &mockProvider{
-		turns: [][]zeroruntime.StreamEvent{
-			toolTurn("call-1", "read_file", `{"path":"notes.txt"}`), // turn 1: other tool call
-			toolTurn("call-2", "read_file", `{"path":"notes.txt"}`), // turn 2: still no update_plan
-			toolTurn("call-3", "read_file", `{"path":"notes.txt"}`), // turn 3: reminder fires here
-			textTurn("done"),
-		},
-	}
+	provider := &mockProvider{turns: append(repeatedReadTurns(expectedThreshold), textTurn("done"))}

 	result, err := Run(context.Background(), "go", provider, Options{
 		Registry: registry,
@@ -287,6 +284,44 @@ func TestRunInjectsPlanNotCalledReminderForMultiStepTask(t *testing.T) {
 	}
 }

+func TestRunDoesNotInjectPlanReminderForBoundedToolSequence(t *testing.T) {
+	const expectedThreshold = 7
+	root := t.TempDir()
+	writeAgentTestFile(t, root+"/notes.txt", "alpha")
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
+
+	provider := &mockProvider{turns: append(repeatedReadTurns(expectedThreshold-1), textTurn("done"))}
+	result, err := Run(context.Background(), "go", provider, Options{Registry: registry, MaxTurns: 12})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("expected final answer, got %q", result.FinalAnswer)
+	}
+	if count := countUserMessagesContaining(result.Messages, planNotCalledReminderMarker); count != 0 {
+		t.Fatalf("bounded tool sequence must not draw a plan reminder, got %d", count)
+	}
+}
+
+func TestPlanReminderWaitsForTurnThresholdAfterEnoughToolCalls(t *testing.T) {
+	state := guardState{totalToolCalls: 7}
+	if got := state.planReminder(6); got != "" {
+		t.Fatalf("planReminder(6) = %q, want no reminder before turn threshold", got)
+	}
+	if state.notCalledReminderSent {
+		t.Fatal("early turn marked the not-called reminder as sent")
+	}
+}
+
+func repeatedReadTurns(count int) [][]zeroruntime.StreamEvent {
+	turns := make([][]zeroruntime.StreamEvent, 0, count)
+	for range count {
+		turns = append(turns, toolTurn("call", "read_file", `{"path":"notes.txt"}`))
+	}
+	return turns
+}
+
 func TestRunDoesNotInjectPlanReminderForTrivialTask(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
@@ -40,7 +40,15 @@ const (
 	toolResultControlSpecReview = "spec_review_required"
 )

-var errPermissionApprovalCanceled = errors.New("permission approval cancelled")
+// ErrPermissionApprovalCanceled ends a run because the caller cancelled a
+// permission prompt, rather than because anything failed.
+//
+// EXPORTED FOR THE SURFACES. A cancel is a normal ending and each surface says
+// so its own way — the TUI unwinds, and ACP has a "cancelled" stop reason for
+// exactly this. While it was unexported ACP could not distinguish it from a
+// fault and reported it as an internal error, so declining a tool looked like
+// the agent crashing.
+var ErrPermissionApprovalCanceled = errors.New("permission approval cancelled")

 // isImageRejectionError reports whether err is a provider 400 that rejects
 // image/multimodal content. This is checked BEFORE the compaction-retry path
@@ -133,6 +141,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 			options.Trace.Counter(trace.CounterInputTokens, int64(usage.InputTokens))
 			options.Trace.Counter(trace.CounterCachedInputTokens, int64(usage.CachedInputTokens))
+			options.Trace.Counter(trace.CounterCacheWriteTokens, int64(usage.CacheWriteTokens))
 			options.Trace.Counter(trace.CounterOutputTokens, int64(usage.OutputTokens))
 		}
 	}
@@ -689,11 +698,12 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				turnRequestedModel = toolResult.RequestedModel
 			}
 			messages = append(messages, zeroruntime.Message{
-				Role:         zeroruntime.MessageRoleTool,
-				Content:      toolResult.ModelOutput(),
-				ToolCallID:   toolResult.ToolCallID,
-				IsError:      toolResult.Status == tools.StatusError,
-				ChangedFiles: append([]string(nil), toolResult.ChangedFiles...),
+				Role:               zeroruntime.MessageRoleTool,
+				Content:            toolResult.ModelOutput(),
+				ToolCallID:         toolResult.ToolCallID,
+				ToolCallProviderID: call.ProviderCallID,
+				IsError:            toolResult.Status == tools.StatusError,
+				ChangedFiles:       append([]string(nil), toolResult.ChangedFiles...),
 			})
 			// Images ride a following USER message rather than the tool result
 			// above. Every provider drops images on a tool-role message —
@@ -1027,6 +1037,9 @@ func historySafeToolCalls(calls []ToolCall) []ToolCall {
 	safe := make([]ToolCall, len(calls))
 	for i, call := range calls {
 		safe[i] = call
+		if call.Freeform {
+			continue
+		}
 		args := strings.TrimSpace(call.Arguments)
 		switch {
 		case args == "":
@@ -1110,8 +1123,28 @@ func decodeToolArguments(arguments string, v any) error {
 }

 func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCall, permissionMode PermissionMode, options Options) (ToolResult, error) {
+	tool, toolFound := registry.Get(call.Name)
 	args := map[string]any{}
-	if call.Arguments != "" {
+	if call.Freeform {
+		if !toolFound || !tools.IsBuiltInApplyPatch(tool) {
+			return ToolResult{
+				ToolCallID: call.ID,
+				Name:       call.Name,
+				Status:     tools.StatusError,
+				Output:     "Error: Unsupported freeform tool call for " + call.Name + ".",
+			}, nil
+		}
+		prepared, err := tools.PrepareFreeformApplyPatchArguments(tool, call.Arguments)
+		if err != nil {
+			return ToolResult{
+				ToolCallID: call.ID,
+				Name:       call.Name,
+				Status:     tools.StatusError,
+				Output:     "Error: Invalid freeform apply_patch input: " + err.Error(),
+			}, nil
+		}
+		args = prepared
+	} else if call.Arguments != "" {
 		if err := decodeToolArguments(call.Arguments, &args); err != nil {
 			return ToolResult{
 				ToolCallID: call.ID,
@@ -1139,7 +1172,6 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			DenialReason: DenialFiltered,
 		}, nil
 	}
-	tool, toolFound := registry.Get(call.Name)
 	if (permissionMode == PermissionModeSpecDraft || permissionMode == PermissionModePlan) && toolFound && !ToolAdvertised(tool, permissionMode) {
 		modeName := string(permissionMode)
 		return ToolResult{
@@ -1364,7 +1396,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			}
 		case PermissionDecisionCancel:
 			emitCanceledPermission(options, call, requestEvent, decisionReason)
-			return canceledPermissionResult(call, decisionReason, requestEvent), fmt.Errorf("%w for %s", errPermissionApprovalCanceled, call.Name)
+			return canceledPermissionResult(call, decisionReason, requestEvent), fmt.Errorf("%w for %s", ErrPermissionApprovalCanceled, call.Name)
 		default:
 			emitDeniedPermission(options, call, requestEvent, decisionReason)
 			return deniedPermissionResult(call, decisionReason, requestEvent), nil
@@ -1548,7 +1580,7 @@ func maybeRetryUnsandboxedAfterSandboxRestriction(ctx context.Context, registry
 	case PermissionDecisionCancel:
 		emitCanceledPermission(options, call, requestEvent, reason)
 		canceled := canceledPermissionResult(call, reason, requestEvent)
-		return result, &canceled, true, decision.Action, reason, nil, fmt.Errorf("%w for %s", errPermissionApprovalCanceled, call.Name)
+		return result, &canceled, true, decision.Action, reason, nil, fmt.Errorf("%w for %s", ErrPermissionApprovalCanceled, call.Name)
 	default:
 		emitDeniedPermission(options, call, requestEvent, reason)
 		denied := deniedPermissionResult(call, reason, requestEvent)
@@ -1596,7 +1628,7 @@ func maybeRetryWithNetworkAfterSandboxDenial(ctx context.Context, registry *tool
 	case PermissionDecisionCancel:
 		emitCanceledPermission(options, call, requestEvent, reason)
 		canceled := canceledPermissionResult(call, reason, requestEvent)
-		return result, &canceled, true, decision.Action, reason, fmt.Errorf("%w for %s", errPermissionApprovalCanceled, call.Name)
+		return result, &canceled, true, decision.Action, reason, fmt.Errorf("%w for %s", ErrPermissionApprovalCanceled, call.Name)
 	default:
 		emitDeniedPermission(options, call, requestEvent, reason)
 		denied := deniedPermissionResult(call, reason, requestEvent)
@@ -3087,13 +3119,15 @@ func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMod
 	// Deferral may activate only when tool_search is actually runnable; otherwise
 	// the loop would hide deferred tools behind a loader the dispatch gate rejects
 	// — an inescapable dead-end. "Runnable" mirrors executeToolCall's gate:
-	// registered, not in DisabledTools, and advertised in the current permission
-	// mode (e.g. not spec-draft, where tool_search is not advertised). The
+	// registered, model-visible, not in DisabledTools, and advertised in the
+	// current permission mode (e.g. not spec-draft, where tool_search is not
+	// advertised). The
 	// EnabledTools allowlist is intentionally NOT checked here — tool_search is
 	// exempt from the allowlist at dispatch, so an allowlist that omits it must
 	// not disable deferral.
 	loader, loaderFound := registry.Get(tools.ToolSearchToolName)
 	loaderUsable := loaderFound &&
+		tools.ModelVisible(loader) &&
 		!containsToolName(options.DisabledTools, tools.ToolSearchToolName) &&
 		ToolAdvertised(loader, permissionMode)

@@ -3200,15 +3234,21 @@ func cachedRuntimeToolDefinition(defCache map[string]zeroruntime.ToolDefinition,
 // runtimeToolDefinition renders a tool's advertised definition (name, description,
 // JSON-schema parameters) as sent to the provider.
 func runtimeToolDefinition(tool tools.Tool) zeroruntime.ToolDefinition {
-	return zeroruntime.ToolDefinition{
+	definition := zeroruntime.ToolDefinition{
 		Name:        tool.Name(),
 		Description: tool.Description(),
 		Parameters:  schemaToRuntimeMap(tool.Parameters()),
 	}
+	if tools.IsBuiltInApplyPatch(tool) {
+		definition.Type = zeroruntime.ToolDefinitionFreeform
+	}
+	return definition
 }

 func ToolVisible(tool tools.Tool, permissionMode PermissionMode, enabledTools []string, disabledTools []string) bool {
-	return ToolAllowedByFilters(tool.Name(), enabledTools, disabledTools) && ToolAdvertised(tool, permissionMode)
+	return tools.ModelVisible(tool) &&
+		ToolAllowedByFilters(tool.Name(), enabledTools, disabledTools) &&
+		ToolAdvertised(tool, permissionMode)
 }

 func ToolAllowedByFilters(name string, enabledTools []string, disabledTools []string) bool {
@@ -3357,10 +3397,11 @@ func loadedToolsFromResult(meta map[string]string) []string {
 func appendAbortedToolResults(messages []Message, remaining []ToolCall) []Message {
 	for _, call := range remaining {
 		messages = append(messages, zeroruntime.Message{
-			Role:       zeroruntime.MessageRoleTool,
-			Content:    abortedToolResultNotice,
-			ToolCallID: call.ID,
-			IsError:    true,
+			Role:               zeroruntime.MessageRoleTool,
+			Content:            abortedToolResultNotice,
+			ToolCallID:         call.ID,
+			ToolCallProviderID: call.ProviderCallID,
+			IsError:            true,
 		})
 	}
 	return messages
@@ -1853,7 +1853,7 @@ func TestRunAbortsWhenPermissionRequestCanceled(t *testing.T) {
 		},
 	})

-	if !errors.Is(err, errPermissionApprovalCanceled) {
+	if !errors.Is(err, ErrPermissionApprovalCanceled) {
 		t.Fatalf("expected permission approval cancel error, got %v", err)
 	}
 	if result.FinalAnswer != "" {
@@ -4096,7 +4096,7 @@ func TestRunDoesNotFlagCleanToolOutput(t *testing.T) {
 // caller's callback AND stamps token counters, and the run completes.
 func TestRunTracingWrapperStampsUsage(t *testing.T) {
 	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{{
-		{Type: zeroruntime.StreamEventUsage, Usage: zeroruntime.Usage{InputTokens: 100, CachedInputTokens: 20, OutputTokens: 40}},
+		{Type: zeroruntime.StreamEventUsage, Usage: zeroruntime.Usage{PromptTokens: 100, CachedInputTokens: 20, CacheWriteTokens: 10, CompletionTokens: 40}},
 		{Type: zeroruntime.StreamEventText, Content: "done"},
 		{Type: zeroruntime.StreamEventDone},
 	}}}
@@ -4135,6 +4135,9 @@ func TestRunTracingWrapperStampsUsage(t *testing.T) {
 	if got := tr.Counter(trace.CounterCachedInputTokens); got != 20 {
 		t.Fatalf("cached input token counter = %d, want 20", got)
 	}
+	if got := tr.Counter(trace.CounterCacheWriteTokens); got != 10 {
+		t.Fatalf("cache-write token counter = %d, want 10", got)
+	}
 	if got := tr.Counter(trace.CounterOutputTokens); got != 40 {
 		t.Fatalf("output token counter = %d, want 40", got)
 	}
@@ -4340,3 +4343,95 @@ func TestPlanModeHonorsBeforeToolVeto(t *testing.T) {
 		t.Fatalf("expected tool result to mention the beforeTool veto, got %q", combined)
 	}
 }
+
+// A cancelled permission on either sandbox-retry path must abort the run with a
+// recognisable cancellation, and must not run the escalated retry.
+//
+// BOTH PATHS, because both wrap ErrPermissionApprovalCanceled and each is
+// reached by a different kind of denial: one by an unrestricted platform denial
+// asking for approval, the other by an external-network denial. Surfaces map
+// this sentinel onto their own idea of a cancel — ACP returns stopReason
+// "cancelled" for it — so a path that produced a bare error instead would show
+// the user a crash where they had simply declined.
+func TestCancellingASandboxRetryAbortsWithoutRetrying(t *testing.T) {
+	denial := func(capability execution.CapabilityKind, scope string) tools.Result {
+		return tools.Result{
+			Status: tools.StatusError,
+			ExecutionOutcome: &execution.Outcome{
+				State: execution.StateDenied,
+				Kind:  execution.OutcomeEnforcementDenied,
+				Denial: &execution.Denial{
+					Capability:  execution.Capability{Kind: capability, Scope: scope},
+					Source:      execution.DenialSourcePlatformSandbox,
+					Reason:      "denied by the sandbox",
+					Recoverable: true,
+					NextAction:  execution.DenialNextActionRequestApproval,
+				},
+			},
+		}
+	}
+
+	for _, testCase := range []struct {
+		name   string
+		result tools.Result
+		run    func(context.Context, *tools.Registry, ToolCall, tools.Tool, map[string]any, tools.Result, Options) error
+	}{
+		{
+			name:   "unsandboxed retry",
+			result: denial(execution.CapabilityUnrestricted, "host"),
+			run: func(ctx context.Context, registry *tools.Registry, call ToolCall, tool tools.Tool, args map[string]any, result tools.Result, options Options) error {
+				_, _, _, _, _, _, abortErr := maybeRetryUnsandboxedAfterSandboxRestriction(
+					ctx, registry, call, tool, args, result, PermissionModeAsk, options, nil)
+				return abortErr
+			},
+		},
+		{
+			name:   "network retry",
+			result: denial(execution.CapabilityExternalNetwork, ""),
+			run: func(ctx context.Context, registry *tools.Registry, call ToolCall, tool tools.Tool, args map[string]any, result tools.Result, options Options) error {
+				_, _, _, _, _, abortErr := maybeRetryWithNetworkAfterSandboxDenial(
+					ctx, registry, call, tool, args, result, PermissionModeAsk, options, nil)
+				return abortErr
+			},
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			retryTool := &sandboxNamespaceLimitedRetryTool{}
+			registry := tools.NewRegistry()
+			registry.Register(retryTool)
+
+			asked := 0
+			options := Options{
+				Registry:       registry,
+				PermissionMode: PermissionModeAsk,
+				Autonomy:       "medium",
+				Sandbox: sandbox.NewEngine(sandbox.EngineOptions{
+					WorkspaceRoot: t.TempDir(),
+					Policy:        sandbox.DefaultPolicy(),
+				}),
+				OnPermissionRequest: func(context.Context, PermissionRequest) (PermissionDecision, error) {
+					asked++
+					return PermissionDecision{Action: PermissionDecisionCancel, Reason: "client cancelled"}, nil
+				},
+			}
+
+			call := ToolCall{ID: "call-1", Name: "bash", Arguments: `{"command":"curl example.com"}`}
+			args := map[string]any{"command": "curl example.com"}
+
+			abortErr := testCase.run(context.Background(), registry, call, retryTool, args, testCase.result, options)
+
+			if asked != 1 {
+				t.Fatalf("permission was requested %d times, want exactly 1", asked)
+			}
+			if !errors.Is(abortErr, ErrPermissionApprovalCanceled) {
+				t.Fatalf("abort error = %v, want it to match ErrPermissionApprovalCanceled", abortErr)
+			}
+			// The escalated retry is the thing the permission was gating. A
+			// cancelled prompt that still ran it would have run the command the
+			// user just declined.
+			if len(retryTool.calls) != 0 {
+				t.Fatalf("the escalated retry ran %d times after a cancel: %+v", len(retryTool.calls), retryTool.calls)
+			}
+		})
+	}
+}
@@ -31,6 +31,19 @@ func (t countingSchemaTool) Run(_ context.Context, _ map[string]any) tools.Resul
 	return tools.Result{Status: tools.StatusOK}
 }

+func TestRuntimeToolDefinitionMarksOnlyBuiltInApplyPatchFreeform(t *testing.T) {
+	builtIn := runtimeToolDefinition(tools.NewScopedApplyPatchTool(t.TempDir(), nil))
+	if builtIn.Type != zeroruntime.ToolDefinitionFreeform {
+		t.Fatalf("built-in apply_patch type = %q, want freeform", builtIn.Type)
+	}
+
+	calls := 0
+	custom := runtimeToolDefinition(countingSchemaTool{name: "apply_patch", calls: &calls})
+	if custom.Type != "" {
+		t.Fatalf("custom apply_patch type = %q, want legacy function shape", custom.Type)
+	}
+}
+
 // The cache renders a tool's schema once and reuses it across calls, and its
 // output is identical to the uncached path.
 func TestPartitionToolsCacheRendersOnceAndMatchesUncached(t *testing.T) {
@@ -67,3 +67,21 @@ func TestEagerToolSchemaTokenBudget(t *testing.T) {
 		t.Fatalf("eager tool schemas are %d tokens, over the %d ceiling — trim a schema, drop a core tool, or raise the ceiling deliberately (deferring will NOT help: this test disables deferral)", got, maxEagerToolSchemaTokens)
 	}
 }
+
+func TestAgentAdvertisesBothEditTools(t *testing.T) {
+	registry := tools.NewRegistry()
+	for _, tool := range tools.CoreToolsScoped(t.TempDir(), nil) {
+		registry.Register(tool)
+	}
+	exposed, _ := partitionTools(registry, PermissionModeAsk, Options{}, map[string]bool{})
+	names := make(map[string]bool, len(exposed))
+	for _, definition := range exposed {
+		names[definition.Name] = true
+	}
+	if !names["apply_patch"] {
+		t.Fatal("agent must retain apply_patch for multi-hunk changes")
+	}
+	if !names["edit_file"] {
+		t.Fatal("agent must receive edit_file for targeted exact replacements")
+	}
+}
@@ -58,12 +58,18 @@ func toolSubstrings(exposed []zeroruntime.ToolDefinition) (toolsSubstr, schemaSu
 	for _, def := range exposed {
 		writeLengthPrefixed(&toolsSB, def.Name)
 		writeLengthPrefixed(&toolsSB, def.Description)
+		writeLengthPrefixed(&toolsSB, string(def.Type))
 		// Parameters is rendered to a canonical JSON string per tool. The
 		// schema-render cache in internal/agent (used by partitionToolsCached)
 		// guarantees the same render is byte-identical across turns for the
 		// same tool, so this substring is a stable hash input.
 		writeLengthPrefixed(&schemaSB, def.Name)
 		writeLengthPrefixed(&schemaSB, canonicalSchemaString(def.Parameters))
+		if def.Format != nil {
+			writeLengthPrefixed(&schemaSB, def.Format.Type)
+			writeLengthPrefixed(&schemaSB, def.Format.Syntax)
+			writeLengthPrefixed(&schemaSB, def.Format.Definition)
+		}
 	}
 	return toolsSB.String(), schemaSB.String()
 }
@@ -73,6 +73,38 @@ func TestComputePrefixFingerprintSchemaChangeChangesSchemaHash(t *testing.T) {
 	}
 }

+func TestComputePrefixFingerprintIncludesToolTypeAndFormat(t *testing.T) {
+	opts := Options{Cwd: t.TempDir(), SystemPrompt: "core"}
+	base := zeroruntime.ToolDefinition{Name: "apply_patch", Description: "Patch files"}
+	baseFingerprint := ComputePrefixFingerprint(opts, []zeroruntime.ToolDefinition{base})
+
+	typed := base
+	typed.Type = zeroruntime.ToolDefinitionFreeform
+	if got := ComputePrefixFingerprint(opts, []zeroruntime.ToolDefinition{typed}); got.ToolsHash == baseFingerprint.ToolsHash {
+		t.Fatal("ToolsHash must change when tool Type changes")
+	}
+
+	formatCases := []struct {
+		name   string
+		format zeroruntime.ToolDefinitionFormat
+	}{
+		{name: "type", format: zeroruntime.ToolDefinitionFormat{Type: "grammar"}},
+		{name: "syntax", format: zeroruntime.ToolDefinitionFormat{Syntax: "lark"}},
+		{name: "definition", format: zeroruntime.ToolDefinitionFormat{Definition: "start: PATCH"}},
+		{name: "empty", format: zeroruntime.ToolDefinitionFormat{}},
+	}
+	for _, test := range formatCases {
+		t.Run(test.name, func(t *testing.T) {
+			withFormat := base
+			withFormat.Format = &test.format
+			got := ComputePrefixFingerprint(opts, []zeroruntime.ToolDefinition{withFormat})
+			if got.SchemaHash == baseFingerprint.SchemaHash {
+				t.Fatalf("SchemaHash must change for %s format input", test.name)
+			}
+		})
+	}
+}
+
 // TestComputePrefixFingerprintSystemPromptChangeChangesBaseHash asserts the
 // most common drift path: a system-prompt edit (e.g. an agent.md update, a
 // model addendum change) must move the base-instructions hash, which moves
@@ -30,13 +30,10 @@ 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.** 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.
+2. **Plan.** Use update_plan for multi-component, sequencing-uncertain, or long
+   work. Skip it for bounded changes in one component. Update only when the
+   overall phase changes, keep at most one item in_progress, and never create a
+   plan after the work is complete.
 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
@@ -52,37 +49,48 @@ work.

 - Choose the narrowest tool that safely accomplishes the step. Prefer native
  file tools - read_file, read_minified_file, list_directory, glob, grep,
-  write_file, edit_file, apply_patch - over shelling out to
+  edit_file, apply_patch, write_file - over shelling out to
  cat/sed/awk/python for file operations.
  They are safer, reviewable, and produce clean diffs.
- 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.
+- Use read_minified_file only to explore large or unfamiliar source. Use
+  read_file for small or likely edit targets and exact text, comments, or line
+  numbers. Do not read both unless a new need for exact content appears.
 - 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
-  the code is already comment-dense.
+- For edits to existing files, use edit_file for a targeted change (old_string
+  must match the file exactly and be unique, so include a few surrounding
+  lines) and apply_patch when one coherent change spans several hunks or
+  files. Use write_file only to create a file or when most of it changes; do
+  not rewrite a whole file to change a few lines. Match the existing
+  indentation, imports, and idioms. Match the file's comment density: do not
+  add explanatory comments unless the user asks or the code is already
+  comment-dense.
+- A successful edit result already confirms the change; do not re-read a file
+  just to verify an edit that succeeded. If an edit fails, read the error, fix
+  the old_string or hunk, and retry the same tool rather than switching to a
+  full rewrite.
 - Solve the problem as posed, not a more general version of it. Add no
  speculative abstraction, configurability, or handling for cases that cannot
  occur, and nothing the user did not ask for. A small diff can still be
-  over-built; if a 200-line solution could be 50, rewrite it.
+  over-built; if a 200-line solution could be 50, rewrite it. Once the required
+  behavior passes validation, stop instead of adding optional cleanup.
 - Preserve behavior you were not asked to change. Do not delete or rewrite code
  you did not author unless the task requires it; if you must, say so.

 ## Testing gate (mandatory)

- After any change to code, verify after edits by running the project's
-  validators before you summarize or commit: tests, type-checks, linters, and/or
-  the build, as appropriate. Scope them to the change while iterating; reserve
-  full-suite runs for milestones.
- If you are unsure which validators apply, search the repo (Makefile, package
-  manifests, CI config) to find them.
+- After code changes, run the project's documented appropriate validators.
+  Scope iteration checks, combine compatible commands when diagnostics stay
+  useful, and run the final set once after the last edit. Rerun only after a
+  change or failure.
+- If unsure which entry points apply, inspect the Makefile, manifests, or CI;
+  do not invent a parallel flow.
 - Never claim a task is done, and never commit, while validators are failing. If
  they fail, fix the cause and rerun; do not paper over it. If you could not run
  a validator, say so explicitly rather than implying success.
+- A successful native patch confirms the edit. Reread only when the next change
+  needs exact content or the result was ambiguous.

 ## Tool use

@@ -104,7 +112,7 @@ work.
  you need to clean up a running foreground command yourself, use write_stdin.
 - write_stdin's session_id is only ever an id returned by a still-running
  exec_command; never guess or probe ids. If you have no such session, start one
-  with exec_command, or use write_file/edit_file/apply_patch for file changes.
+  with exec_command, or use edit_file/apply_patch/write_file for file changes.
 - write_stdin with empty input polls an existing exec_command session, and
  `\u0003` interrupts it. Sending other stdin bytes may require approval because
  it can drive the running process beyond the original command. Non-tty sessions
@@ -140,6 +148,7 @@ work.
 - Default to concise, skimmable output. Lead with the answer or the result.
 - Use GitHub-flavored Markdown: headings to structure longer replies, fenced
  code blocks for code, and `inline code` for file paths, commands, symbols, and
-  short snippets. Reference code as `file:line` so it is clickable.
+  short snippets. Reference code with file paths and include line numbers when
+  already known; do not look them up solely for the final summary.
 - Report outcomes faithfully: if tests failed, show it; if a step was skipped,
  say so; when something is done and verified, state it plainly without hedging.
@@ -60,8 +60,11 @@ const openAIPromptAddendum = `<model_guidance>
  longer answers, fenced code blocks for code, and ` + "`inline code`" + ` for paths,
  commands, and symbols.
 - Strongly prefer the native file tools (read_file, list_directory, grep, glob,
-  write_file, edit_file, apply_patch) over shelling out to cat/sed/awk/python for
-  file work. Make one tool call per file; do not batch file writes into a script.
+  edit_file, apply_patch, write_file) over shelling out to cat/sed/awk/python for
+  file work. Use them directly; never run apply_patch through exec_command.
+  read_file, edit_file and write_file take one file per call, while one coherent
+  apply_patch may span several files. Keep independent native calls in the same
+  turn, and do not batch file writes into a script.
 - Persist until the task is fully handled this turn: gather context, implement,
  run the validators, and report — do not stop at a partial result.
 </model_guidance>`
@@ -29,6 +29,9 @@ func TestBuildSystemPromptAppendsModelAddendum(t *testing.T) {
 	if got := buildSystemPrompt(Options{Model: "gpt-5"}); !strings.Contains(got, openAIPromptAddendum) {
 		t.Fatalf("expected the OpenAI addendum in the gpt-5 prompt")
 	}
+	if got := strings.Join(strings.Fields(strings.ToLower(buildSystemPrompt(Options{Model: "gpt-5"}))), " "); !strings.Contains(got, "never run apply_patch through exec_command") {
+		t.Fatalf("OpenAI prompt must route edits through the native patch tool:\n%s", got)
+	}
 	// Claude is aligned with the core prompt and gets no family addendum now that
 	// comment discipline is universal; it must not pick up another family's block.
 	claude := buildSystemPrompt(Options{Model: "claude-opus-4-6"})
@@ -29,14 +29,17 @@ func TestMain(m *testing.M) {
 }

 func TestCoreSystemPromptIncludesCodingQualityRules(t *testing.T) {
-	prompt := strings.ToLower(buildSystemPrompt(Options{}))
+	prompt := strings.Join(strings.Fields(strings.ToLower(buildSystemPrompt(Options{}))), " ")
+	if strings.Contains(prompt, "clickable file paths") {
+		t.Fatalf("system prompt must not claim inline-code file paths are clickable: %s", prompt)
+	}

 	for _, want := range []string{
 		"read-before-edit",
 		"inspect the target file",
 		"plan then act",
 		"choose the narrowest tool",
-		"prefer edit_file or apply_patch",
+		"for edits to existing files, use edit_file",
 		"verify after edits",
 		"honor the active permission mode",
 		"avoid broad refactors",
@@ -44,6 +47,13 @@ func TestCoreSystemPromptIncludesCodingQualityRules(t *testing.T) {
 		"do not recognize",
 		"scaled to the work",
 		"comment density",
+		"skip it for bounded changes in one component",
+		"do not read both unless a new need for exact content appears",
+		"combine compatible commands when diagnostics stay useful",
+		"do not invent a parallel flow",
+		"a successful native patch confirms the edit",
+		"once the required behavior passes validation, stop",
+		"do not look them up solely for the final summary",
 	} {
 		if !strings.Contains(prompt, want) {
 			t.Fatalf("expected core system prompt to include %q, got:\n%s", want, buildSystemPrompt(Options{}))
@@ -453,7 +453,12 @@ func (manager *Manager) normalizeLoadedTask(fileTaskID string, task Task) (Task,
 	}
 	outputFile, err := manager.outputFile(task.ID, task.OutputFile)
 	if err != nil {
-		return Task{}, false, err
+		var migrated bool
+		outputFile, migrated = manager.migrateLegacyOutputFile(task.ID, task.OutputFile)
+		if !migrated {
+			return Task{}, false, err
+		}
+		changed = true
 	}
 	if outputFile != task.OutputFile {
 		changed = true
@@ -562,6 +567,32 @@ func (manager *Manager) outputFile(taskID string, requested string) (string, err
 	return path, nil
 }

+// migrateLegacyOutputFile recovers task metadata written under a previous home
+// or XDG data root. It accepts only the canonical per-task output
+// name in the historic zero/background layout, and only when the corresponding
+// regular file already exists inside the active manager root.
+func (manager *Manager) migrateLegacyOutputFile(taskID string, requested string) (string, bool) {
+	requested = strings.TrimSpace(requested)
+	if !filepath.IsAbs(requested) {
+		return "", false
+	}
+	requested = filepath.Clean(requested)
+	expectedName := taskID + ".ndjson"
+	if filepath.Base(requested) != expectedName {
+		return "", false
+	}
+	legacyRoot := filepath.Dir(requested)
+	if filepath.Base(legacyRoot) != "background" || filepath.Base(filepath.Dir(legacyRoot)) != "zero" {
+		return "", false
+	}
+	canonical := filepath.Join(manager.rootDir, expectedName)
+	info, err := os.Lstat(canonical)
+	if err != nil || !info.Mode().IsRegular() {
+		return "", false
+	}
+	return canonical, true
+}
+
 func validTaskID(taskID string) bool {
 	return taskIDPattern.MatchString(strings.TrimSpace(taskID))
 }
@@ -1,6 +1,7 @@
 package background

 import (
+	"encoding/json"
 	"errors"
 	"os"
 	"path/filepath"
@@ -191,6 +192,88 @@ func TestManagerSkipsInvalidPersistedMetadata(t *testing.T) {
 	}
 }

+func TestManagerMigratesLegacyOutputPathWhenCanonicalOutputExists(t *testing.T) {
+	root := t.TempDir()
+	const taskID = "legacy_task"
+	canonicalOutput := filepath.Join(root, taskID+".ndjson")
+	if err := os.WriteFile(canonicalOutput, []byte("legacy output\n"), 0o600); err != nil {
+		t.Fatalf("write canonical output: %v", err)
+	}
+	legacyOutput := filepath.Join(t.TempDir(), "zero", "background", taskID+".ndjson")
+	metadata, err := json.Marshal(Task{
+		ID:         taskID,
+		Type:       "specialist",
+		Status:     StatusCompleted,
+		OutputFile: legacyOutput,
+		StartedAt:  time.Date(2026, 8, 1, 10, 0, 0, 0, time.UTC),
+	})
+	if err != nil {
+		t.Fatalf("marshal legacy metadata: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, taskID+".json"), append(metadata, '\n'), 0o600); err != nil {
+		t.Fatalf("write legacy metadata: %v", err)
+	}
+
+	manager, err := NewManager(root)
+	if err != nil {
+		t.Fatalf("NewManager returned error: %v", err)
+	}
+	task, ok := manager.Get(taskID)
+	if !ok {
+		t.Fatal("manager did not load migrated task")
+	}
+	if task.OutputFile != canonicalOutput {
+		t.Fatalf("migrated output file = %q, want %q", task.OutputFile, canonicalOutput)
+	}
+	if warnings := manager.LoadWarnings(); len(warnings) != 0 {
+		t.Fatalf("migration produced load warnings: %#v", warnings)
+	}
+
+	persisted, err := os.ReadFile(filepath.Join(root, taskID+".json"))
+	if err != nil {
+		t.Fatalf("read migrated metadata: %v", err)
+	}
+	var saved Task
+	if err := json.Unmarshal(persisted, &saved); err != nil {
+		t.Fatalf("decode migrated metadata: %v", err)
+	}
+	if saved.OutputFile != canonicalOutput {
+		t.Fatalf("persisted output file = %q, want %q", saved.OutputFile, canonicalOutput)
+	}
+}
+
+func TestManagerRejectsUnrelatedAbsoluteOutputPathDuringMigration(t *testing.T) {
+	root := t.TempDir()
+	const taskID = "legacy_task"
+	if err := os.WriteFile(filepath.Join(root, taskID+".ndjson"), []byte("output\n"), 0o600); err != nil {
+		t.Fatalf("write canonical output: %v", err)
+	}
+	metadata, err := json.Marshal(Task{
+		ID:         taskID,
+		Type:       "specialist",
+		Status:     StatusCompleted,
+		OutputFile: filepath.Join(t.TempDir(), taskID+".ndjson"),
+		StartedAt:  time.Date(2026, 8, 1, 10, 0, 0, 0, time.UTC),
+	})
+	if err != nil {
+		t.Fatalf("marshal metadata: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, taskID+".json"), append(metadata, '\n'), 0o600); err != nil {
+		t.Fatalf("write metadata: %v", err)
+	}
+
+	manager, err := NewManager(root)
+	if err != nil {
+		t.Fatalf("NewManager returned error: %v", err)
+	}
+	if _, ok := manager.Get(taskID); ok {
+		t.Fatal("manager loaded task with an unrelated absolute output path")
+	}
+	if warnings := strings.Join(manager.LoadWarnings(), "\n"); !strings.Contains(warnings, "output file must be inside") {
+		t.Fatalf("load warnings = %q, want containment rejection", warnings)
+	}
+}
+
 func TestManagerMarksReloadedRunningTaskNonKillable(t *testing.T) {
 	root := t.TempDir()
 	manager, err := NewManager(root)
@@ -839,24 +839,26 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 		mcpTokenStore = nil
 		err = nil
 	}
+	criticalMCPConfig, optionalMCPConfig := splitMCPStartupConfig(mcpConfig)
 	mcpRuntime := mcpToolRuntime(noopMCPRuntime{})
-	if len(mcpConfig.Servers) > 0 {
-		mcpRuntime, err = deps.registerMCPTools(context.Background(), registry, mcpConfig, mcp.RegisterOptions{
+	if len(criticalMCPConfig.Servers) > 0 {
+		runtime, registerErr := deps.registerMCPTools(context.Background(), registry, criticalMCPConfig, mcp.RegisterOptions{
 			PermissionStore: mcpPermissionStore,
 			Autonomy:        mcp.AutonomyLow,
 			Execution:       executionRunner,
 			WorkspaceRoot:   workspaceRoot,
 		})
-	}
-	if err != nil {
-		closeMCPRuntime(stderr, mcpRuntime)
-		return writeAppError(stderr, err.Error(), 1)
+		if registerErr != nil {
+			closeMCPRuntime(stderr, runtime)
+			return writeAppError(stderr, redaction.ErrorMessage(registerErr, redaction.Options{}), 1)
+		}
+		mcpRuntime = runtime
 	}
 	defer closeMCPRuntime(stderr, mcpRuntime)
 	// A server that could not be reached or validated is skipped, not fatal (one
 	// bad MCP server must not abort startup) — surface each so a missing tool set is
 	// explained rather than silently absent. A built-in default the user never
-	// configured (e.g. keyless Firecrawl with no credentials) is the exception: it
+	// configured (e.g. keyless Exa with no credentials) is the exception: it
 	// was never asked for, so its failure is not worth a startup warning — only
 	// servers the user actually configured warn on failure (issue #552).
 	for _, skipped := range mcpRuntime.Skipped() {
@@ -909,11 +911,35 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 	}
 	// Activate deferred MCP-tool loading for the interactive run only when the
 	// VISIBLE deferred-eligible count meets the resolved threshold, matching exec.
-	// The registry is complete (core + specialist + MCP + plugins) here, so the
-	// count is accurate; below threshold this is a no-op and the surface is
-	// unchanged. The interactive surface applies no operator tool filters, so
-	// enabled/disabled are nil — matching the AgentOptions below.
+	// This first pass covers every prompt-critical tool. Optional built-in MCP
+	// defaults re-run the same gate after publishing their atomic batch, so a
+	// later catalog generation cannot miss its loader. The interactive surface
+	// applies no operator tool filters, so enabled/disabled are nil — matching the
+	// AgentOptions below.
 	registerToolSearchIfEligible(registry, resolved.Tools.DeferThreshold, permissionMode, nil, nil)
+	var optionalMCPRuntime *optionalMCPStartup
+	var awaitToolReadiness func(context.Context)
+	if len(optionalMCPConfig.Servers) > 0 {
+		optionalMCPRuntime = startOptionalMCP(
+			context.Background(),
+			registry,
+			optionalMCPConfig,
+			mcp.RegisterOptions{
+				PermissionStore: mcpPermissionStore,
+				Autonomy:        mcp.AutonomyLow,
+				Execution:       executionRunner,
+				WorkspaceRoot:   workspaceRoot,
+			},
+			deps.registerMCPTools,
+			func() {
+				registerToolSearchIfEligible(registry, resolved.Tools.DeferThreshold, permissionMode, nil, nil)
+			},
+		)
+		defer closeMCPRuntime(stderr, optionalMCPRuntime)
+		awaitToolReadiness = func(ctx context.Context) {
+			optionalMCPRuntime.Await(ctx, optionalMCPPromptGrace)
+		}
+	}
 	lastKnownMCPConfig := mcpConfig
 	fileTracker := tools.NewFileTracker()
 	var scratchBaseline scratchFileBaseline
@@ -950,8 +976,17 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 		RecapsEnabled:        resolved.Preferences.RecapsEnabled(),
 		Provider:             provider,
 		NewProvider:          deps.newProvider,
-		ProbeProviderHealth:  deps.probeProviderHealth,
-		UserAgent:            userAgent(),
+		NewTurnSessionProvider: func(profile config.ProviderProfile, provider zeroruntime.Provider) zeroruntime.TurnSessionProvider {
+			if provider == nil {
+				return nil
+			}
+			if optimized, ok := providers.OptimizedTurnSessions(profile, provider, providers.Options{}); ok {
+				return optimized
+			}
+			return providers.DefaultTurnSessions(profile, provider, providers.Options{})
+		},
+		ProbeProviderHealth: deps.probeProviderHealth,
+		UserAgent:           userAgent(),
 		PrepareRunCompletionWarning: func() {
 			scratchBaseline = scratchFileSnapshot(workspaceRoot)
 		},
@@ -959,6 +994,7 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 			return scratchFileWarning(workspaceRoot, scratchBaseline)
 		},
 		Registry:           registry,
+		AwaitToolReadiness: awaitToolReadiness,
 		SessionStore:       sessionStore,
 		PeerService:        peerService,
 		SandboxStore:       sandboxStore,
@@ -17,6 +17,7 @@ import (
 	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/mcp"
+	"github.com/Gitlawb/zero/internal/redaction"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/tui"
 	"github.com/Gitlawb/zero/internal/update"
@@ -211,12 +212,12 @@ func TestTUIStartupSuppressesWarningForUnconfiguredDefaultServer(t *testing.T) {
 		},
 		resolveMCPConfig: func(workspaceRoot string, excludeProject bool) (config.MCPConfig, error) {
 			return config.MCPConfig{Servers: map[string]config.MCPServerConfig{
-				"firecrawl": config.DefaultMCPServers()["firecrawl"],
+				"exa": config.DefaultMCPServers()["exa"],
 			}}, nil
 		},
 		registerMCPTools: func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error) {
 			return fakeMCPRuntimeWithSkips{skipped: []mcp.SkippedServer{
-				{Name: "firecrawl", Err: errors.New("returned HTTP 401"), UnconfiguredDefault: true},
+				{Name: "exa", Err: errors.New("returned HTTP 401"), UnconfiguredDefault: true},
 			}}, nil
 		},
 		runTUI: func(ctx context.Context, options tui.Options) int {
@@ -227,7 +228,7 @@ func TestTUIStartupSuppressesWarningForUnconfiguredDefaultServer(t *testing.T) {
 	if exitCode != 0 {
 		t.Fatalf("exitCode = %d stderr=%s", exitCode, stderr.String())
 	}
-	if strings.Contains(stderr.String(), "firecrawl") {
+	if strings.Contains(stderr.String(), "exa") {
 		t.Fatalf("stderr = %q, want no warning for an unconfigured default server", stderr.String())
 	}
 }
@@ -486,6 +487,74 @@ func TestRunNoArgsLaunchesTUIWithMCPState(t *testing.T) {
 	}
 }

+func TestRunNoArgsPaintsBeforeOptionalDefaultMCPIsReady(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cwd := t.TempDir()
+	userConfigPath := filepath.Join(t.TempDir(), "zero", "config.json")
+	permissionStore, err := mcp.NewPermissionStore(mcp.StoreOptions{FilePath: filepath.Join(t.TempDir(), "mcp-permissions.json")})
+	if err != nil {
+		t.Fatalf("NewPermissionStore() error = %v", err)
+	}
+	tokenStore, err := mcp.NewTokenStore(mcp.TokenStoreOptions{FilePath: filepath.Join(t.TempDir(), "mcp-oauth.json")})
+	if err != nil {
+		t.Fatalf("NewTokenStore() error = %v", err)
+	}
+	started := make(chan struct{})
+	release := make(chan struct{})
+	configResult := make(chan error, 1)
+
+	exitCode := runWithDeps([]string{}, &stdout, &stderr, appDeps{
+		getwd:          func() (string, error) { return cwd, nil },
+		userConfigPath: func() (string, error) { return userConfigPath, nil },
+		resolveConfig: func(string, config.Overrides) (config.ResolvedConfig, error) {
+			return config.ResolvedConfig{MaxTurns: 8}, nil
+		},
+		resolveMCPConfig: func(string, bool) (config.MCPConfig, error) {
+			return config.MCPConfig{Servers: config.DefaultMCPServers()}, nil
+		},
+		newMCPStore:      func() (*mcp.PermissionStore, error) { return permissionStore, nil },
+		newMCPTokenStore: func() (*mcp.TokenStore, error) { return tokenStore, nil },
+		registerMCPTools: func(_ context.Context, registry *tools.Registry, cfg config.MCPConfig, _ mcp.RegisterOptions) (mcpToolRuntime, error) {
+			var configErr error
+			if _, ok := cfg.Servers["exa"]; !ok || len(cfg.Servers) != 1 {
+				configErr = fmt.Errorf("optional MCP config = %#v, want only exa", cfg.Servers)
+			}
+			configResult <- configErr
+			close(started)
+			<-release
+			registry.Register(cliFakeMCPRegistryTool{})
+			return noopMCPRuntime{}, nil
+		},
+		runTUI: func(ctx context.Context, options tui.Options) int {
+			select {
+			case <-started:
+			case <-time.After(time.Second):
+				t.Fatal("optional MCP initialization did not start")
+			}
+			if options.AwaitToolReadiness == nil {
+				t.Fatal("TUI did not receive optional tool readiness barrier")
+			}
+			if _, ok := options.Registry.Get("mcp_docs_lookup"); ok {
+				t.Fatal("optional MCP tool was published before registration completed")
+			}
+			close(release)
+			options.AwaitToolReadiness(ctx)
+			if _, ok := options.Registry.Get("mcp_docs_lookup"); !ok {
+				t.Fatal("optional MCP tool was not visible after readiness completed")
+			}
+			return 0
+		},
+	})
+
+	if exitCode != 0 {
+		t.Fatalf("exitCode = %d stderr=%s", exitCode, stderr.String())
+	}
+	if configErr := <-configResult; configErr != nil {
+		t.Fatal(configErr)
+	}
+}
+
 func TestTUIMCPCommandUsesLastGoodConfigOnRefreshError(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
@@ -565,6 +634,7 @@ func TestRunNoArgsClosesPartialMCPRuntimeWhenRegistrationFails(t *testing.T) {
 		t.Fatalf("NewTokenStore() error = %v", err)
 	}
 	runtimeClosed := false
+	secret := "sk-proj-" + strings.Repeat("a", 23) + "0"

 	exitCode := runWithDeps([]string{}, &stdout, &stderr, appDeps{
 		getwd: func() (string, error) {
@@ -591,7 +661,7 @@ func TestRunNoArgsClosesPartialMCPRuntimeWhenRegistrationFails(t *testing.T) {
 			return closeFunc(func() error {
 				runtimeClosed = true
 				return nil
-			}), errors.New("register mcp tools failed")
+			}), fmt.Errorf("register mcp tools failed: %s", secret)
 		},
 		runTUI: func(ctx context.Context, options tui.Options) int {
 			t.Fatal("TUI should not launch after MCP registration fails")
@@ -605,6 +675,12 @@ func TestRunNoArgsClosesPartialMCPRuntimeWhenRegistrationFails(t *testing.T) {
 	if !strings.Contains(stderr.String(), "register mcp tools failed") {
 		t.Fatalf("stderr missing registration error: %s", stderr.String())
 	}
+	if strings.Contains(stderr.String(), secret) {
+		t.Fatalf("stderr leaked MCP registration secret: %s", stderr.String())
+	}
+	if !strings.Contains(stderr.String(), redaction.RedactedSecret) {
+		t.Fatalf("stderr missing redaction marker: %s", stderr.String())
+	}
 	if !runtimeClosed {
 		t.Fatal("partial MCP runtime was not closed after registration error")
 	}
@@ -939,6 +939,9 @@ func registerToolSearchIfEligible(registry *tools.Registry, deferThreshold int,
 	if deferThreshold <= 0 {
 		return
 	}
+	if _, registered := registry.Get(tools.ToolSearchToolName); registered {
+		return
+	}
 	if deferredEligibleCount(registry, permissionMode, enabledTools, disabledTools) < deferThreshold {
 		return
 	}
@@ -267,23 +267,29 @@ func streamJSONPermissionEventType(event agent.PermissionEvent) streamjson.Event
 func (writer *execEventWriter) usage(usage agent.Usage) {
 	if writer.format == execOutputJSON {
 		writer.writeJSON(map[string]any{
-			"type":              "usage",
-			"prompt_tokens":     usage.PromptTokens,
-			"completion_tokens": usage.CompletionTokens,
-			"total_tokens":      usage.TotalTokens(),
+			"type":                "usage",
+			"prompt_tokens":       usage.PromptTokens,
+			"completion_tokens":   usage.CompletionTokens,
+			"cached_input_tokens": usage.CachedInputTokens,
+			"cache_write_tokens":  usage.CacheWriteTokens,
+			"total_tokens":        usage.TotalTokens(),
 		})
 		return
 	}
 	if writer.format == execOutputStreamJSON {
 		promptTokens := usage.EffectiveInputTokens()
 		completionTokens := usage.EffectiveOutputTokens()
+		cachedInputTokens := usage.CachedInputTokens
+		cacheWriteTokens := usage.CacheWriteTokens
 		totalTokens := usage.TotalTokens()
 		writer.writeStreamJSON(streamjson.Event{
-			Type:             streamjson.EventUsage,
-			RunID:            writer.runID,
-			PromptTokens:     &promptTokens,
-			CompletionTokens: &completionTokens,
-			TotalTokens:      &totalTokens,
+			Type:              streamjson.EventUsage,
+			RunID:             writer.runID,
+			PromptTokens:      &promptTokens,
+			CompletionTokens:  &completionTokens,
+			CachedInputTokens: &cachedInputTokens,
+			CacheWriteTokens:  &cacheWriteTokens,
+			TotalTokens:       &totalTokens,
 		})
 	}
 }
@@ -52,3 +52,39 @@ func TestExecWriterPropagatesToolResultTruncation(t *testing.T) {
 		})
 	}
 }
+
+func TestExecWriterPropagatesCacheUsage(t *testing.T) {
+	for _, format := range []execOutputFormat{execOutputJSON, execOutputStreamJSON} {
+		t.Run(string(format), func(t *testing.T) {
+			var stdout bytes.Buffer
+			writer := execEventWriter{
+				stdout:       &stdout,
+				format:       format,
+				runID:        "run_usage",
+				streamedText: &strings.Builder{},
+			}
+			writer.usage(agent.Usage{
+				InputTokens:       100,
+				OutputTokens:      20,
+				PromptTokens:      100,
+				CompletionTokens:  20,
+				CachedInputTokens: 60,
+				CacheWriteTokens:  10,
+			})
+			if writer.err != nil {
+				t.Fatalf("usage: %v", writer.err)
+			}
+			var payload map[string]any
+			if err := json.Unmarshal(bytes.TrimSpace(stdout.Bytes()), &payload); err != nil {
+				t.Fatalf("decode output %q: %v", stdout.String(), err)
+			}
+			cachedKey, writeKey := "cached_input_tokens", "cache_write_tokens"
+			if format == execOutputStreamJSON {
+				cachedKey, writeKey = "cachedInputTokens", "cacheWriteTokens"
+			}
+			if payload[cachedKey] != float64(60) || payload[writeKey] != float64(10) {
+				t.Fatalf("cache usage missing from payload: %#v", payload)
+			}
+		})
+	}
+}
@@ -9,15 +9,15 @@ import (
 	"github.com/Gitlawb/zero/internal/config"
 )

-// `zero mcp disable firecrawl` must work even though firecrawl is a built-in
+// `zero mcp disable exa` must work even though exa is a built-in
 // default that is not written to the user's config file until overridden.
-func TestRunMCPDisableSeededFirecrawlDefault(t *testing.T) {
+func TestRunMCPDisableSeededExaDefault(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "zero", "config.json")
-	// A config with no firecrawl entry — the default lives in code, not the file.
+	// A config with no Exa entry — the default lives in code, not the file.
 	writeMCPCommandRawConfig(t, configPath, `{"activeProvider":"fast"}`)

 	var out, errBuf bytes.Buffer
-	code := runWithDeps([]string{"mcp", "disable", "firecrawl", "--json"}, &out, &errBuf, appDeps{
+	code := runWithDeps([]string{"mcp", "disable", "exa", "--json"}, &out, &errBuf, appDeps{
 		userConfigPath: func() (string, error) { return configPath, nil },
 	})
 	if code != exitSuccess {
@@ -31,8 +31,8 @@ func TestRunMCPDisableSeededFirecrawlDefault(t *testing.T) {
 	if err := json.Unmarshal(out.Bytes(), &payload); err != nil {
 		t.Fatalf("decode disable JSON: %v\n%s", err, out.String())
 	}
-	if payload.ServerName != "firecrawl" || !payload.Disabled || !payload.Changed {
-		t.Fatalf("disable payload = %#v, want firecrawl disabled+changed", payload)
+	if payload.ServerName != "exa" || !payload.Disabled || !payload.Changed {
+		t.Fatalf("disable payload = %#v, want exa disabled+changed", payload)
 	}

 	// End-to-end: resolving that config now turns the default off.
@@ -40,7 +40,7 @@ func TestRunMCPDisableSeededFirecrawlDefault(t *testing.T) {
 	if err != nil {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
-	if !cfg.Servers["firecrawl"].Disabled {
-		t.Fatal("expected `mcp disable firecrawl` to turn the seeded default off in the resolved config")
+	if !cfg.Servers["exa"].Disabled {
+		t.Fatal("expected `mcp disable exa` to turn the seeded default off in the resolved config")
 	}
 }
@@ -0,0 +1,147 @@
+package cli
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/Gitlawb/zero/internal/config"
+	"github.com/Gitlawb/zero/internal/mcp"
+	"github.com/Gitlawb/zero/internal/tools"
+)
+
+const (
+	optionalMCPPromptGrace = time.Second
+	optionalMCPCloseGrace  = 250 * time.Millisecond
+)
+
+// splitMCPStartupConfig keeps explicitly configured servers on the
+// prompt-critical path. Only unchanged built-in defaults may initialize after
+// first paint; their failure was already intentionally silent.
+func splitMCPStartupConfig(cfg config.MCPConfig) (critical config.MCPConfig, optional config.MCPConfig) {
+	critical.Servers = map[string]config.MCPServerConfig{}
+	optional.Servers = map[string]config.MCPServerConfig{}
+	for name, server := range cfg.Servers {
+		if server.Disabled {
+			continue
+		}
+		if config.IsUnconfiguredDefault(name, server) {
+			optional.Servers[name] = server
+			continue
+		}
+		critical.Servers[name] = server
+	}
+	return critical, optional
+}
+
+type optionalMCPStartup struct {
+	cancel context.CancelFunc
+	done   chan struct{}
+
+	mu      sync.Mutex
+	runtime mcpToolRuntime
+
+	closeOnce        sync.Once
+	runtimeCloseOnce sync.Once
+	closeErr         error
+}
+
+func startOptionalMCP(
+	parent context.Context,
+	registry *tools.Registry,
+	cfg config.MCPConfig,
+	options mcp.RegisterOptions,
+	register func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error),
+	onReady func(),
+) *optionalMCPStartup {
+	ctx, cancel := context.WithCancel(parent)
+	startup := &optionalMCPStartup{cancel: cancel, done: make(chan struct{})}
+	go func() {
+		runtime, err := register(ctx, registry, cfg, options)
+		if err == nil && onReady != nil {
+			onReady()
+		}
+		startup.mu.Lock()
+		startup.runtime = runtime
+		startup.mu.Unlock()
+		close(startup.done)
+	}()
+	return startup
+}
+
+// Await gives optional tools one bounded opportunity to join the next turn's
+// immutable registry snapshot. A timeout leaves this turn on the existing core
+// tool set; a later turn observes the completed generation.
+func (startup *optionalMCPStartup) Await(ctx context.Context, timeout time.Duration) bool {
+	if startup == nil {
+		return true
+	}
+	select {
+	case <-startup.done:
+		return true
+	default:
+	}
+	if timeout <= 0 {
+		select {
+		case <-startup.done:
+			return true
+		case <-ctx.Done():
+			return false
+		}
+	}
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	select {
+	case <-startup.done:
+		return true
+	case <-timer.C:
+		return false
+	case <-ctx.Done():
+		return false
+	}
+}
+
+func (startup *optionalMCPStartup) Close() error {
+	if startup == nil {
+		return nil
+	}
+	startup.closeOnce.Do(func() {
+		startup.cancel()
+		reaped := make(chan struct{})
+		go func() {
+			defer close(reaped)
+			<-startup.done
+			startup.closeRuntime()
+		}()
+		timer := time.NewTimer(optionalMCPCloseGrace)
+		defer timer.Stop()
+		select {
+		case <-reaped:
+		case <-timer.C:
+		}
+	})
+	startup.mu.Lock()
+	defer startup.mu.Unlock()
+	return startup.closeErr
+}
+
+func (startup *optionalMCPStartup) closeRuntime() {
+	startup.runtimeCloseOnce.Do(func() {
+		startup.mu.Lock()
+		runtime := startup.runtime
+		startup.mu.Unlock()
+		if runtime == nil {
+			return
+		}
+		err := runtime.Close()
+		startup.mu.Lock()
+		if err != nil && startup.closeErr == nil {
+			startup.closeErr = err
+		}
+		startup.mu.Unlock()
+	})
+}
+
+func (startup *optionalMCPStartup) Skipped() []mcp.SkippedServer {
+	return nil
+}
@@ -0,0 +1,187 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/Gitlawb/zero/internal/config"
+	"github.com/Gitlawb/zero/internal/mcp"
+	"github.com/Gitlawb/zero/internal/tools"
+)
+
+type closeTrackingMCPRuntime struct {
+	closed chan struct{}
+	err    error
+}
+
+func (runtime *closeTrackingMCPRuntime) Close() error {
+	close(runtime.closed)
+	return runtime.err
+}
+
+func (*closeTrackingMCPRuntime) Skipped() []mcp.SkippedServer { return nil }
+
+func TestSplitMCPStartupConfigDefersOnlyUnconfiguredDefaults(t *testing.T) {
+	defaults := config.DefaultMCPServers()
+	cfg := config.MCPConfig{Servers: map[string]config.MCPServerConfig{
+		"exa":      defaults["exa"],
+		"docs":     {Type: "http", URL: "https://docs.example.test/mcp"},
+		"disabled": {Type: "http", URL: "https://disabled.example.test/mcp", Disabled: true},
+	}}
+
+	critical, optional := splitMCPStartupConfig(cfg)
+	if _, ok := critical.Servers["docs"]; !ok || len(critical.Servers) != 1 {
+		t.Fatalf("critical servers = %#v, want only docs", critical.Servers)
+	}
+	if _, ok := optional.Servers["exa"]; !ok || len(optional.Servers) != 1 {
+		t.Fatalf("optional servers = %#v, want only exa", optional.Servers)
+	}
+}
+
+func TestOptionalMCPAwaitTimesOutThenObservesPublishedTools(t *testing.T) {
+	registry := tools.NewRegistry()
+	release := make(chan struct{})
+	started := make(chan struct{})
+	startup := startOptionalMCP(
+		context.Background(),
+		registry,
+		config.MCPConfig{Servers: config.DefaultMCPServers()},
+		mcp.RegisterOptions{},
+		func(ctx context.Context, registry *tools.Registry, _ config.MCPConfig, _ mcp.RegisterOptions) (mcpToolRuntime, error) {
+			close(started)
+			select {
+			case <-release:
+				registry.RegisterBatch([]tools.Tool{tools.NewScopedReadFileTool(t.TempDir(), nil)})
+				return noopMCPRuntime{}, nil
+			case <-ctx.Done():
+				return noopMCPRuntime{}, ctx.Err()
+			}
+		},
+		nil,
+	)
+	defer func() { _ = startup.Close() }()
+	<-started
+
+	if startup.Await(t.Context(), time.Millisecond) {
+		t.Fatal("optional startup unexpectedly completed before release")
+	}
+	if got := len(registry.All()); got != 0 {
+		t.Fatalf("registry published tools before readiness: %d", got)
+	}
+	close(release)
+	if !startup.Await(t.Context(), time.Second) {
+		t.Fatal("optional startup did not complete after release")
+	}
+	if _, ok := registry.Get("read_file"); !ok {
+		t.Fatal("completed optional startup did not publish its tool batch")
+	}
+}
+
+func TestOptionalMCPFailedRegistrationSkipsReadinessCallback(t *testing.T) {
+	readyCalls := 0
+	startup := startOptionalMCP(
+		context.Background(),
+		tools.NewRegistry(),
+		config.MCPConfig{Servers: config.DefaultMCPServers()},
+		mcp.RegisterOptions{},
+		func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error) {
+			return noopMCPRuntime{}, errors.New("connect failed")
+		},
+		func() { readyCalls++ },
+	)
+	defer func() { _ = startup.Close() }()
+
+	if !startup.Await(t.Context(), time.Second) {
+		t.Fatal("failed optional startup did not settle")
+	}
+	if readyCalls != 0 {
+		t.Fatalf("readiness callback ran after failed registration: %d", readyCalls)
+	}
+}
+
+func TestOptionalMCPCloseCancelsBlockedStartup(t *testing.T) {
+	started := make(chan struct{})
+	startup := startOptionalMCP(
+		context.Background(),
+		tools.NewRegistry(),
+		config.MCPConfig{Servers: config.DefaultMCPServers()},
+		mcp.RegisterOptions{},
+		func(ctx context.Context, _ *tools.Registry, _ config.MCPConfig, _ mcp.RegisterOptions) (mcpToolRuntime, error) {
+			close(started)
+			<-ctx.Done()
+			return noopMCPRuntime{}, nil
+		},
+		nil,
+	)
+	<-started
+	if err := startup.Close(); err != nil {
+		t.Fatalf("Close() error = %v", err)
+	}
+}
+
+func TestOptionalMCPCloseReturnsRuntimeErrorWithinGrace(t *testing.T) {
+	closeErr := errors.New("close failed")
+	runtime := &closeTrackingMCPRuntime{closed: make(chan struct{}), err: closeErr}
+	startup := startOptionalMCP(
+		context.Background(),
+		tools.NewRegistry(),
+		config.MCPConfig{Servers: config.DefaultMCPServers()},
+		mcp.RegisterOptions{},
+		func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error) {
+			return runtime, nil
+		},
+		nil,
+	)
+	if !startup.Await(t.Context(), time.Second) {
+		t.Fatal("optional startup did not settle")
+	}
+	if err := startup.Close(); !errors.Is(err, closeErr) {
+		t.Fatalf("Close() error = %v, want %v", err, closeErr)
+	}
+}
+
+func TestOptionalMCPCloseBoundsRegistrationThatIgnoresCancellation(t *testing.T) {
+	started := make(chan struct{})
+	release := make(chan struct{})
+	released := false
+	defer func() {
+		if !released {
+			close(release)
+		}
+	}()
+	runtime := &closeTrackingMCPRuntime{closed: make(chan struct{})}
+	startup := startOptionalMCP(
+		context.Background(),
+		tools.NewRegistry(),
+		config.MCPConfig{Servers: config.DefaultMCPServers()},
+		mcp.RegisterOptions{},
+		func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error) {
+			close(started)
+			<-release
+			return runtime, nil
+		},
+		nil,
+	)
+	<-started
+
+	closeResult := make(chan error, 1)
+	go func() { closeResult <- startup.Close() }()
+	select {
+	case err := <-closeResult:
+		if err != nil {
+			t.Fatalf("Close() error = %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Close blocked on registration after cancellation")
+	}
+
+	close(release)
+	released = true
+	select {
+	case <-runtime.closed:
+	case <-time.After(time.Second):
+		t.Fatal("late optional MCP runtime was not closed")
+	}
+}
@@ -105,7 +105,17 @@ func TestLoadProviderCommandTimeout(t *testing.T) {
 //
 // This is a hang-breaker, not a tuned margin. Nothing in a healthy run waits on
 // it, since both tests return about one WaitDelay after the fixture exits.
-const providerCommandTestBudget = 60 * time.Second
+const (
+	providerCommandTestBudget        = 90 * time.Second
+	providerCommandReadyWaitAttempts = 45
+)
+
+func TestProviderCommandBudgetLeavesCleanupMargin(t *testing.T) {
+	readyWaitCeiling := time.Duration(providerCommandReadyWaitAttempts) * time.Second
+	if providerCommandTestBudget < 2*readyWaitCeiling {
+		t.Fatalf("provider command test budget %s leaves less than one readiness window for cleanup after %s", providerCommandTestBudget, readyWaitCeiling)
+	}
+}

 // backgroundChildLifetime must exceed providerCommandTestBudget so that a child
 // dying of old age is unobservable: any run where runProviderCommand has not
@@ -341,15 +351,15 @@ func writeCommand(t *testing.T, script commandScript) string {
 			// assertion fail is far more diagnosable than blocking until the
 			// timeout fires and reporting an unrelated error. Each iteration is
 			// about a second, since `ping -n 2` sleeps between its two echoes,
-			// so the ceiling is roughly 15s: far longer than any cold PowerShell
-			// start seen on a runner, and far shorter than
-			// providerCommandTestBudget, so giving up surfaces a legible
+			// so the ceiling is roughly 45s: enough for a heavily loaded Windows
+			// runner while leaving the other half of providerCommandTestBudget for
+			// process exit, PID-file verification, and cleanup. Giving up surfaces a legible
 			// PID-file failure rather than a timeout that hides the real cause.
 			lines = append(lines,
 				":zeroWaitReady",
 				"if exist \""+readyFile+"\" goto zeroReady",
 				"set /a ZERO_READY_TRIES+=1",
-				"if %ZERO_READY_TRIES% GEQ 15 goto zeroReady",
+				"if %ZERO_READY_TRIES% GEQ "+itoa(providerCommandReadyWaitAttempts)+" goto zeroReady",
 				"ping -n 2 127.0.0.1 >nul",
 				"goto zeroWaitReady",
 				":zeroReady",
@@ -5,22 +5,20 @@ import (
 	"strings"
 )

-// DefaultMCPServers returns the MCP servers Zero ships ENABLED by default so web
-// search and scraping work out of the box with no setup and no API key. They are
-// seeded before user/project config is merged (see ResolveMCP), so a user can
-// override any field — for example point firecrawl at a self-hosted instance, or
-// add an API-key header to lift the free-tier limit — or disable it entirely with
+// DefaultMCPServers returns the MCP servers Zero ships ENABLED by default so
+// web search and page fetching work out of the box with no setup and no API
+// key. They are seeded before user/project config is merged (see ResolveMCP),
+// so a user can override any field — for example add an API-key header to lift
+// Exa's anonymous rate limit — or disable it entirely with
 // `zero mcp disable <name>` (which writes `"disabled": true`).
 //
-// Keyless Firecrawl routes requests through firecrawl.dev (1,000 free credits per
-// month, no account). Self-host Firecrawl (AGPL-3.0) for unlimited and private
-// use. Zero only calls it over the network, so Firecrawl's license never reaches
-// into Zero's own code.
+// Exa's hosted MCP server works anonymously with rate limits. Users can add an
+// Exa API key for higher limits.
 func DefaultMCPServers() map[string]MCPServerConfig {
 	return map[string]MCPServerConfig{
-		"firecrawl": {
+		"exa": {
 			Type: "http",
-			URL:  "https://mcp.firecrawl.dev/v2/mcp",
+			URL:  "https://mcp.exa.ai/mcp",
 		},
 	}
 }
@@ -35,13 +33,13 @@ func IsDefaultMCPServer(name string) bool {

 // IsUnconfiguredDefault reports whether server is one of Zero's built-in
 // defaults that the user never wrote an entry for in their config — i.e. it is
-// running with whatever Zero ships (e.g. keyless Firecrawl, no credentials).
+// running with whatever Zero ships (e.g. keyless Exa, no credentials).
 //
 // Both conditions below must hold:
 //   - !server.configured: the user's JSON never declared an object for this
 //     server key at all (set by MCPServerConfig.UnmarshalJSON only when it
 //     actually ran for this key). Any explicit action — including a
-//     disable/enable toggle like `zero mcp enable firecrawl` that leaves the
+//     disable/enable toggle like `zero mcp enable exa` that leaves the
 //     resolved value unchanged — sets configured, so it always counts as
 //     user-configured, even though the value comparison below could not tell
 //     the difference on its own.
@@ -58,3 +56,90 @@ func IsUnconfiguredDefault(name string, server MCPServerConfig) bool {
 	def, ok := DefaultMCPServers()[strings.TrimSpace(name)]
 	return ok && !server.configured && reflect.DeepEqual(def, server)
 }
+
+// retiredDefaultMCPServer describes a built-in default Zero no longer ships.
+type retiredDefaultMCPServer struct {
+	// successor is the default that replaced it.
+	successor string
+	// shipped is the value Zero used to seed for this name. A user entry
+	// written while the default was still shipped may name only an override
+	// (a header, say) and rely on these fields for the rest, so they have to
+	// outlive the default itself.
+	shipped MCPServerConfig
+}
+
+// retiredDefaultMCPServers maps a retired built-in default to what replaced it
+// and to the value Zero used to ship for it.
+var retiredDefaultMCPServers = map[string]retiredDefaultMCPServer{
+	"firecrawl": {
+		successor: "exa",
+		shipped: MCPServerConfig{
+			Type: "http",
+			URL:  "https://mcp.firecrawl.dev/v2/mcp",
+		},
+	},
+}
+
+// migrateRetiredDefaultMCPServers keeps an upgrade across a default-provider
+// swap from changing what the user's config means. It handles the two ways a
+// rename can break a config written against the old default:
+//
+//   - A user who ran `zero mcp disable <old default>` made an explicit choice
+//     not to open that outbound connection. Without carrying that decision to
+//     the successor, the upgrade re-opens it under the new name — and because
+//     the replacement looks like an untouched default, even the startup
+//     warning stays quiet (see IsUnconfiguredDefault and issue #552).
+//   - A user who customized the old default could name only the field they
+//     were changing, because the seeded default supplied the transport. Once
+//     the default stops being seeded that entry resolves to a server with no
+//     type, url, or command, which fails NormalizeConfig and takes the whole
+//     startup down rather than just that one server.
+//
+// It runs immediately after the user layer merges (see ResolveMCP), which
+// scopes it to user-level decisions — the only scope whose disable is sticky.
+// The carried-over disable applies only when the user never declared the
+// successor themselves: an explicit `exa` entry wins whether it enables or
+// disables. Because the disable is recorded as a user-level decision, the
+// lower-trust project layer cannot lift it, while `zero mcp enable exa` still
+// can (the CLI override scope merges with canReenable=true).
+func migrateRetiredDefaultMCPServers(cfg *MCPConfig) {
+	for name, retired := range retiredDefaultMCPServers {
+		entry, ok := cfg.Servers[name]
+		if !ok {
+			continue
+		}
+		if inheritsRetiredTransport(entry) {
+			// Re-seed what Zero used to ship underneath the user's fields, so a
+			// partial entry still resolves to the complete server it named when
+			// it was written. Their own values still win — this only fills the
+			// gap the retired default used to cover.
+			entry = mergeMCPServer(retired.shipped, entry, true)
+			cfg.Servers[name] = entry
+		}
+		if !entry.disabledSet || !entry.Disabled {
+			continue
+		}
+		replacement, ok := cfg.Servers[retired.successor]
+		if !ok || replacement.configured {
+			continue
+		}
+		replacement.Disabled = true
+		replacement.disabledSet = true
+		cfg.Servers[retired.successor] = replacement
+	}
+}
+
+// inheritsRetiredTransport reports whether entry named no transport of its own
+// — no type, url, command, or args — and so relied entirely on the retired
+// default to supply one.
+//
+// Anything else is a complete definition the user owns (a self-hosted url, a
+// stdio command) and must be left alone: grafting the retired default's http
+// type onto an entry that names a command produces a server that is rejected
+// outright, turning a working config into a startup failure.
+func inheritsRetiredTransport(entry MCPServerConfig) bool {
+	return strings.TrimSpace(entry.Type) == "" &&
+		strings.TrimSpace(entry.URL) == "" &&
+		strings.TrimSpace(entry.Command) == "" &&
+		len(entry.Args) == 0
+}
@@ -7,10 +7,10 @@ import (
 )

 func TestIsDefaultMCPServer(t *testing.T) {
-	if !IsDefaultMCPServer("firecrawl") {
-		t.Fatal("firecrawl should be a built-in default")
+	if !IsDefaultMCPServer("exa") {
+		t.Fatal("exa should be a built-in default")
 	}
-	if IsDefaultMCPServer("  firecrawl  ") == false {
+	if IsDefaultMCPServer("  exa  ") == false {
 		t.Fatal("IsDefaultMCPServer should trim whitespace")
 	}
 	if IsDefaultMCPServer("not-a-default") {
@@ -18,45 +18,45 @@ func TestIsDefaultMCPServer(t *testing.T) {
 	}
 }

-func TestResolveMCPSeedsEnabledFirecrawlDefault(t *testing.T) {
+func TestResolveMCPSeedsEnabledExaDefault(t *testing.T) {
 	cfg, err := ResolveMCP(ResolveOptions{})
 	if err != nil {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
-	firecrawl, ok := cfg.Servers["firecrawl"]
+	exa, ok := cfg.Servers["exa"]
 	if !ok {
-		t.Fatal("expected the firecrawl default to be seeded with no user config")
+		t.Fatal("expected the exa default to be seeded with no user config")
 	}
-	if firecrawl.Type != "http" || firecrawl.URL != "https://mcp.firecrawl.dev/v2/mcp" {
-		t.Fatalf("unexpected firecrawl default: %#v", firecrawl)
+	if exa.Type != "http" || exa.URL != "https://mcp.exa.ai/mcp" {
+		t.Fatalf("unexpected exa default: %#v", exa)
 	}
-	if firecrawl.Disabled {
-		t.Fatal("the firecrawl default must be enabled out of the box")
+	if exa.Disabled {
+		t.Fatal("the exa default must be enabled out of the box")
 	}
 }

 func TestResolveMCPUserCanDisableDefault(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "config.json")
-	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"exa":{"disabled":true}}}}`), 0o600); err != nil {
 		t.Fatal(err)
 	}
 	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
 	if err != nil {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
-	if !cfg.Servers["firecrawl"].Disabled {
+	if !cfg.Servers["exa"].Disabled {
 		t.Fatal("a user must be able to disable the default by writing over it")
 	}
 }

 func TestIsUnconfiguredDefault(t *testing.T) {
-	if !IsUnconfiguredDefault("firecrawl", DefaultMCPServers()["firecrawl"]) {
-		t.Fatal("an untouched firecrawl default should be reported as unconfigured")
+	if !IsUnconfiguredDefault("exa", DefaultMCPServers()["exa"]) {
+		t.Fatal("an untouched exa default should be reported as unconfigured")
 	}
-	if IsUnconfiguredDefault("firecrawl", MCPServerConfig{Type: "http", URL: "http://localhost:3002/mcp"}) {
+	if IsUnconfiguredDefault("exa", MCPServerConfig{Type: "http", URL: "https://example.com/mcp"}) {
 		t.Fatal("a server overriding the default URL is no longer unconfigured")
 	}
-	if IsUnconfiguredDefault("firecrawl", MCPServerConfig{Type: "http", URL: "https://mcp.firecrawl.dev/v2/mcp", Auth: "bearer"}) {
+	if IsUnconfiguredDefault("exa", MCPServerConfig{Type: "http", URL: "https://mcp.exa.ai/mcp", Auth: "bearer"}) {
 		t.Fatal("a server with credentials added is no longer unconfigured")
 	}
 	if IsUnconfiguredDefault("not-a-default", MCPServerConfig{}) {
@@ -65,57 +65,173 @@ func TestIsUnconfiguredDefault(t *testing.T) {
 }

 func TestResolveMCPExplicitReenableIsNotUnconfiguredDefault(t *testing.T) {
-	// `zero mcp enable firecrawl` after a prior disable writes {"disabled":false}
+	// `zero mcp enable exa` after a prior disable writes {"disabled":false}
 	// explicitly. The resolved value is identical to the untouched default (both
 	// enabled, no credentials), but the user DID take an explicit action here, so
 	// IsUnconfiguredDefault must not treat it as untouched (issue #563 review).
 	path := filepath.Join(t.TempDir(), "config.json")
-	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":false}}}}`), 0o600); err != nil {
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"exa":{"disabled":false}}}}`), 0o600); err != nil {
 		t.Fatal(err)
 	}
 	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
 	if err != nil {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
-	firecrawl := cfg.Servers["firecrawl"]
-	if firecrawl.Disabled {
-		t.Fatalf("explicit re-enable should leave the server enabled: %#v", firecrawl)
+	exa := cfg.Servers["exa"]
+	if exa.Disabled {
+		t.Fatalf("explicit re-enable should leave the server enabled: %#v", exa)
 	}
-	if IsUnconfiguredDefault("firecrawl", firecrawl) {
+	if IsUnconfiguredDefault("exa", exa) {
 		t.Fatal("an explicit enable/disable toggle must count as user-configured, even though the resolved value matches the default")
 	}
 }

 func TestResolveMCPExplicitRedeclareOfDefaultValuesIsNotUnconfiguredDefault(t *testing.T) {
-	// A user who copies firecrawl's exact default type/url into their config
+	// A user who copies Exa's exact default type/url into their config
 	// (e.g. from an example file, planning to add credentials later) produces a
-	// resolved value byte-identical to DefaultMCPServers()["firecrawl"] — the
+	// resolved value byte-identical to DefaultMCPServers()["exa"] — the
 	// same trap TestResolveMCPExplicitReenableIsNotUnconfiguredDefault covers for
 	// the disabled toggle. IsUnconfiguredDefault must still treat this as
 	// user-configured because the user's JSON declared an entry for it, even
 	// though a plain resolved-value comparison could not tell the difference.
 	path := filepath.Join(t.TempDir(), "config.json")
-	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"type":"http","url":"https://mcp.firecrawl.dev/v2/mcp"}}}}`), 0o600); err != nil {
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"exa":{"type":"http","url":"https://mcp.exa.ai/mcp"}}}}`), 0o600); err != nil {
 		t.Fatal(err)
 	}
 	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
 	if err != nil {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
-	firecrawl := cfg.Servers["firecrawl"]
-	want := DefaultMCPServers()["firecrawl"]
-	if firecrawl.Type != want.Type || firecrawl.URL != want.URL || firecrawl.Disabled != want.Disabled {
-		t.Fatalf("expected the resolved value to match the default's fields exactly: %#v", firecrawl)
+	exa := cfg.Servers["exa"]
+	want := DefaultMCPServers()["exa"]
+	if exa.Type != want.Type || exa.URL != want.URL || exa.Disabled != want.Disabled {
+		t.Fatalf("expected the resolved value to match the default's fields exactly: %#v", exa)
 	}
-	if IsUnconfiguredDefault("firecrawl", firecrawl) {
+	if IsUnconfiguredDefault("exa", exa) {
 		t.Fatal("redeclaring the default's exact values is still an explicit user configuration, not an untouched default")
 	}
 }

 func TestResolveMCPUserCanOverrideDefaultURLKeepingOtherFields(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "config.json")
-	// Point firecrawl at a self-hosted instance; the default's Type must survive.
-	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"url":"http://localhost:3002/mcp"}}}}`), 0o600); err != nil {
+	// Point Exa at a proxy; the default's Type must survive.
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"exa":{"url":"https://example.com/mcp"}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	exa := cfg.Servers["exa"]
+	if exa.URL != "https://example.com/mcp" {
+		t.Fatalf("user override of the default URL did not apply: %#v", exa)
+	}
+	if exa.Type != "http" {
+		t.Fatalf("override should keep the default's other fields (type), got %#v", exa)
+	}
+}
+
+func TestResolveMCPCarriesLegacyDefaultDisableToSuccessor(t *testing.T) {
+	// Upgrade path: the user disabled the firecrawl default Zero used to ship.
+	// Swapping the default to exa must not re-open an outbound connection they
+	// explicitly switched off.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	if !cfg.Servers["exa"].Disabled {
+		t.Fatalf("a prior disable of the retired default must carry to its replacement: %#v", cfg.Servers["exa"])
+	}
+}
+
+func TestResolveMCPExplicitSuccessorBeatsLegacyDefaultDisable(t *testing.T) {
+	// The user disabled the old default but has since explicitly configured exa.
+	// Their newer, explicit choice wins — the migration must not override it.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true},"exa":{"disabled":false}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	exa := cfg.Servers["exa"]
+	if exa.Disabled {
+		t.Fatalf("an explicit exa entry must survive the legacy-disable migration: %#v", exa)
+	}
+	if IsUnconfiguredDefault("exa", exa) {
+		t.Fatal("an explicitly configured exa is not an untouched default")
+	}
+}
+
+func TestResolveMCPLegacyDefaultLeftEnabledDoesNotDisableSuccessor(t *testing.T) {
+	// A user who configured firecrawl without disabling it (e.g. added a header)
+	// never opted out of the default search server, so exa stays enabled.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"headers":{"Authorization":"Bearer k"}}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	if cfg.Servers["exa"].Disabled {
+		t.Fatal("only an explicit disable of the retired default should carry over")
+	}
+}
+
+func TestResolveMCPLegacyDefaultDisableIsLiftableByOverride(t *testing.T) {
+	// The carried-over disable is a user-level decision, not a permanent one:
+	// `zero mcp enable exa` merges through the CLI override scope, which is the
+	// one layer allowed to re-enable.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	enabled := MCPServerConfig{Disabled: false, disabledSet: true}
+	cfg, err := ResolveMCP(ResolveOptions{
+		UserConfigPath: path,
+		Overrides:      Overrides{MCP: MCPConfig{Servers: map[string]MCPServerConfig{"exa": enabled}}},
+	})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	if cfg.Servers["exa"].Disabled {
+		t.Fatalf("an explicit enable must lift the carried-over disable: %#v", cfg.Servers["exa"])
+	}
+}
+
+func TestResolveMCPLegacyDisableSurvivesProjectReenable(t *testing.T) {
+	// The project layer is lower-trust and must not lift the carried-over
+	// user-level disable — the same guard a direct `zero mcp disable exa` gets.
+	dir := t.TempDir()
+	userPath := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(userPath, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	projectPath := filepath.Join(dir, "project.json")
+	if err := os.WriteFile(projectPath, []byte(`{"mcp":{"servers":{"exa":{"disabled":false}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: userPath, ProjectConfigPath: projectPath})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	if !cfg.Servers["exa"].Disabled {
+		t.Fatal("project config must not re-enable a server the user disabled")
+	}
+}
+
+func TestResolveMCPKeepsRetiredDefaultTransportForPartialEntry(t *testing.T) {
+	// A user who added an API key to the firecrawl default wrote only the header
+	// — the seeded default supplied the http type and URL. Retiring the default
+	// must not strip those out from under them and leave an unusable server.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"headers":{"Authorization":"Bearer k"}}}}}`), 0o600); err != nil {
 		t.Fatal(err)
 	}
 	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
@@ -123,10 +239,55 @@ func TestResolveMCPUserCanOverrideDefaultURLKeepingOtherFields(t *testing.T) {
 		t.Fatalf("ResolveMCP: %v", err)
 	}
 	firecrawl := cfg.Servers["firecrawl"]
-	if firecrawl.URL != "http://localhost:3002/mcp" {
-		t.Fatalf("user override of the default URL did not apply: %#v", firecrawl)
+	if firecrawl.Type != "http" || firecrawl.URL != "https://mcp.firecrawl.dev/v2/mcp" {
+		t.Fatalf("a partial entry must keep the retired default's transport: %#v", firecrawl)
 	}
-	if firecrawl.Type != "http" {
-		t.Fatalf("override should keep the default's other fields (type), got %#v", firecrawl)
+	if firecrawl.Headers["Authorization"] != "Bearer k" {
+		t.Fatalf("the user's own field must still win: %#v", firecrawl)
+	}
+}
+
+func TestResolveMCPDoesNotGraftRetiredDefaultOntoOwnTransport(t *testing.T) {
+	// A self-hosted firecrawl over stdio is a complete definition the user owns.
+	// Re-seeding the retired http default under it would produce an http server
+	// carrying a command, which NormalizeConfig rejects outright.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"command":"firecrawl-mcp"}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	firecrawl := cfg.Servers["firecrawl"]
+	if firecrawl.Type != "" || firecrawl.URL != "" {
+		t.Fatalf("an entry naming its own transport must be left alone: %#v", firecrawl)
+	}
+	if firecrawl.Command != "firecrawl-mcp" {
+		t.Fatalf("the user's command must survive: %#v", firecrawl)
+	}
+}
+
+func TestResolveMCPDisabledRetiredEntryStaysReEnableable(t *testing.T) {
+	// The disable carries to exa, and the retired entry itself keeps a usable
+	// transport so a later `zero mcp enable firecrawl` does not resolve to a
+	// server with no type, url, or command.
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := ResolveMCP(ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	firecrawl := cfg.Servers["firecrawl"]
+	if !firecrawl.Disabled {
+		t.Fatalf("the retired entry must stay disabled: %#v", firecrawl)
+	}
+	if firecrawl.Type != "http" || firecrawl.URL != "https://mcp.firecrawl.dev/v2/mcp" {
+		t.Fatalf("a disabled retired entry should still carry a usable transport: %#v", firecrawl)
+	}
+	if !cfg.Servers["exa"].Disabled {
+		t.Fatal("the disable must still carry to the successor")
 	}
 }
@@ -34,7 +34,7 @@ func TestResolveMCPExcludeProjectDropsProjectServers(t *testing.T) {
 		if _, ok := cfg.Servers["user-srv"]; !ok {
 			t.Fatal("the user server must always be present")
 		}
-		if _, ok := cfg.Servers["firecrawl"]; !ok {
+		if _, ok := cfg.Servers["exa"]; !ok {
 			t.Fatal("the built-in default must always be present")
 		}
 	})
@@ -54,7 +54,7 @@ func TestResolveMCPExcludeProjectDropsProjectServers(t *testing.T) {
 		if _, ok := cfg.Servers["user-srv"]; !ok {
 			t.Fatal("the user server must survive when the project layer is dropped")
 		}
-		if _, ok := cfg.Servers["firecrawl"]; !ok {
+		if _, ok := cfg.Servers["exa"]; !ok {
 			t.Fatal("the built-in default must survive when the project layer is dropped")
 		}
 	})
@@ -180,7 +180,7 @@ func Resolve(options ResolveOptions) (ResolvedConfig, error) {
 }

 func ResolveMCP(options ResolveOptions) (MCPConfig, error) {
-	// Seed Zero's built-in default MCP servers (e.g. keyless Firecrawl for free,
+	// Seed Zero's built-in default MCP servers (e.g. keyless Exa for free,
 	// no-setup web search/scrape) BEFORE merging user/project config, so the user
 	// can override any field or disable a default by writing over it.
 	cfg := FileConfig{MCP: MCPConfig{Servers: DefaultMCPServers()}}
@@ -194,6 +194,10 @@ func ResolveMCP(options ResolveOptions) (MCPConfig, error) {
 		// server the user disabled (a user-level disable is sticky, but the user
 		// scope itself may lift it).
 		mergeMCPConfig(&cfg.MCP, fileConfig.MCP, true)
+		// Reconcile config written against a default Zero has since retired,
+		// here while the user layer is the only one merged — so a carried-over
+		// disable counts as a user-level decision the project layer cannot lift.
+		migrateRetiredDefaultMCPServers(&cfg.MCP)
 	}
 	// Drop the project layer when the workspace is untrusted, so a cloned repo's
 	// ./.zero/config.json cannot register (and spawn) MCP servers. Fail-closed:
@@ -151,7 +151,8 @@ type KeyBindingsConfig struct {
 	ToggleMouse KeyBindingDef `json:"toggleMouse,omitempty"`
 	// CycleReasoning cycles through reasoning effort levels (default: ctrl+t).
 	CycleReasoning KeyBindingDef `json:"cycleReasoning,omitempty"`
-	// TogglePlan toggles the plan panel expansion (default: ctrl+p).
+	// TogglePlan is retained for configuration compatibility. Plan updates render
+	// in the transcript and no longer have a persistent panel to toggle.
 	TogglePlan KeyBindingDef `json:"togglePlan,omitempty"`
 	// ToggleSidebar toggles the right context sidebar (default: ctrl+b).
 	ToggleSidebar KeyBindingDef `json:"toggleSidebar,omitempty"`
@@ -464,7 +465,7 @@ type MCPServerConfig struct {
 	// fields it set or what values they hold. A built-in default seeded by
 	// DefaultMCPServers() is never unmarshaled from JSON, so it starts false;
 	// any explicit entry in the user/project file — even one that happens to
-	// repeat a default's exact field values (e.g. re-declaring firecrawl's
+	// repeat a default's exact field values (e.g. re-declaring Exa's
 	// default URL) — sets it true. IsUnconfiguredDefault checks this alongside
 	// a resolved-value comparison, so redeclaring default values verbatim still
 	// counts as user-configured.
@@ -9,7 +9,16 @@ import (
 	"strings"
 )

-const PolicyVersion = 1
+// PolicyVersion is the version of the approval policy that recorded grants were
+// evaluated under. Bump it whenever a change narrows what may be approved: the
+// grant store then backs the file up, keeps deny grants, invalidates prior
+// approvals, and tells the user once, instead of silently honoring approvals
+// that the current rules would have refused.
+//
+// v2 tightened command-prefix validation so a launcher spelled with a version
+// or an executable extension ("python3.11", "python.exe") can no longer be
+// approved as an ordinary command.
+const PolicyVersion = 2

 type Origin string

@@ -35,7 +35,7 @@ type Server struct {
 	// credential lookup uses it to avoid reusing legacy user tokens by name.
 	ProjectConfigured bool
 	// UnconfiguredDefault is true when this server is one of Zero's built-in
-	// defaults (e.g. keyless Firecrawl) that the user never touched in their
+	// defaults (e.g. keyless Exa) that the user never touched in their
 	// config — no credentials, no overrides. Callers use it to avoid warning
 	// loudly when a server nobody configured fails to connect.
 	UnconfiguredDefault bool
@@ -1,6 +1,8 @@
 package mcp

 import (
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"

@@ -90,7 +92,7 @@ func TestNormalizeConfigValidatesTransportBoundaries(t *testing.T) {

 func TestNormalizeConfigFlagsUnconfiguredDefault(t *testing.T) {
 	cfg := config.MCPConfig{Servers: map[string]config.MCPServerConfig{
-		"firecrawl": config.DefaultMCPServers()["firecrawl"],
+		"exa": config.DefaultMCPServers()["exa"],
 		"web": {
 			Type: "http",
 			URL:  "https://example.com/mcp",
@@ -107,8 +109,8 @@ func TestNormalizeConfigFlagsUnconfiguredDefault(t *testing.T) {
 		byName[server.Name] = server
 	}

-	if !byName["firecrawl"].UnconfiguredDefault {
-		t.Fatal("an untouched firecrawl default should be flagged UnconfiguredDefault")
+	if !byName["exa"].UnconfiguredDefault {
+		t.Fatal("an untouched exa default should be flagged UnconfiguredDefault")
 	}
 	if byName["web"].UnconfiguredDefault {
 		t.Fatal("a server the user configured must not be flagged UnconfiguredDefault")
@@ -240,3 +242,116 @@ func TestCopyStringMapTrimsKeysAndPreservesValues(t *testing.T) {
 		t.Fatalf("copied[TOKEN] = %q, want value preserved verbatim", copied["TOKEN"])
 	}
 }
+
+// Startup behavior for the firecrawl -> exa default migration: a user who
+// disabled the retired default must end up with no Exa server to connect to,
+// not merely a disabled entry in the resolved config.
+func TestNormalizeConfigSkipsExaAfterLegacyFirecrawlDisable(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"disabled":true}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.ResolveMCP(config.ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	servers, err := NormalizeConfig(cfg)
+	if err != nil {
+		t.Fatalf("NormalizeConfig: %v", err)
+	}
+	for _, server := range servers {
+		if server.Name == "exa" {
+			t.Fatalf("exa must not be started after the user disabled the default it replaced: %#v", server)
+		}
+	}
+}
+
+// The same path with no legacy disable still starts Exa, so the migration
+// cannot quietly switch off the default for everyone else.
+func TestNormalizeConfigStartsExaWithoutLegacyDisable(t *testing.T) {
+	cfg, err := config.ResolveMCP(config.ResolveOptions{})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	servers, err := NormalizeConfig(cfg)
+	if err != nil {
+		t.Fatalf("NormalizeConfig: %v", err)
+	}
+	for _, server := range servers {
+		if server.Name == "exa" {
+			if !server.UnconfiguredDefault {
+				t.Fatalf("an untouched exa default should be flagged unconfigured: %#v", server)
+			}
+			return
+		}
+	}
+	t.Fatal("expected the exa default to be started out of the box")
+}
+
+// The failure path CodeRabbit flagged: a firecrawl entry that named only a
+// header relied on the retired default for its transport. Resolving it must
+// still produce a complete server — an incomplete one fails NormalizeConfig,
+// which takes down every other server's startup with it, not just this one.
+func TestNormalizeConfigResolvesPartialRetiredDefaultEntry(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"headers":{"Authorization":"Bearer k"}}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.ResolveMCP(config.ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	servers, err := NormalizeConfig(cfg)
+	if err != nil {
+		t.Fatalf("a header-only legacy entry must not break startup: %v", err)
+	}
+	var firecrawl *Server
+	var sawExa bool
+	for i := range servers {
+		switch servers[i].Name {
+		case "firecrawl":
+			firecrawl = &servers[i]
+		case "exa":
+			sawExa = true
+		}
+	}
+	if firecrawl == nil {
+		t.Fatalf("expected the customized firecrawl server to survive: %#v", servers)
+	}
+	if firecrawl.Type != ServerTypeHTTP || firecrawl.URL != "https://mcp.firecrawl.dev/v2/mcp" {
+		t.Fatalf("firecrawl lost the transport its entry relied on: %#v", *firecrawl)
+	}
+	if firecrawl.Headers["Authorization"] != "Bearer k" {
+		t.Fatalf("firecrawl lost the user's header: %#v", *firecrawl)
+	}
+	if !sawExa {
+		t.Fatal("the new exa default should still start alongside it")
+	}
+}
+
+// The mirror case: an entry that names its own stdio transport must not have
+// the retired http default grafted onto it, which would be rejected outright.
+func TestNormalizeConfigLeavesRetiredEntryWithOwnTransportAlone(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(path, []byte(`{"mcp":{"servers":{"firecrawl":{"command":"firecrawl-mcp"}}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.ResolveMCP(config.ResolveOptions{UserConfigPath: path})
+	if err != nil {
+		t.Fatalf("ResolveMCP: %v", err)
+	}
+	servers, err := NormalizeConfig(cfg)
+	if err != nil {
+		t.Fatalf("a self-hosted stdio entry must keep working: %v", err)
+	}
+	for _, server := range servers {
+		if server.Name != "firecrawl" {
+			continue
+		}
+		if server.Type != ServerTypeStdio || server.Command != "firecrawl-mcp" {
+			t.Fatalf("the user's own stdio transport was corrupted: %#v", server)
+		}
+		return
+	}
+	t.Fatalf("expected the self-hosted firecrawl server to survive: %#v", servers)
+}
@@ -176,9 +176,11 @@ func RegisterTools(ctx context.Context, registry *tools.Registry, cfg config.MCP
 			staged = append(staged, tool)
 		}
 	}
-	for _, tool := range staged {
-		registry.Register(tool)
+	registered := make([]tools.Tool, 0, len(staged))
+	for index := range staged {
+		registered = append(registered, staged[index])
 	}
+	registry.RegisterBatch(registered)
 	return runtime, nil
 }

@@ -70,6 +70,62 @@ func TestRegisterToolsAddsPromptGatedMCPTools(t *testing.T) {
 	}
 }

+func TestRegisterToolsPublishesServerToolsInOneGeneration(t *testing.T) {
+	registry := tools.NewRegistry()
+	before := registry.Snapshot().Generation
+	client := &fakeToolClient{listed: []RemoteTool{
+		{Name: "lookup", Description: "Lookup documentation"},
+		{Name: "search", Description: "Search documentation"},
+	}}
+	runtime, err := RegisterTools(context.Background(), registry, config.MCPConfig{Servers: map[string]config.MCPServerConfig{
+		"docs": {Type: "stdio", Command: "docs-mcp"},
+	}}, RegisterOptions{ClientFactory: func(context.Context, Server) (ToolClient, error) {
+		return client, nil
+	}})
+	if err != nil {
+		t.Fatalf("RegisterTools() error = %v", err)
+	}
+	defer runtime.Close()
+
+	after := registry.Snapshot()
+	if after.Generation != before+1 {
+		t.Fatalf("registry generation = %d, want %d", after.Generation, before+1)
+	}
+	for _, name := range []string{"mcp_docs_lookup", "mcp_docs_search"} {
+		if _, ok := registry.Get(name); !ok {
+			t.Fatalf("expected %s to be published in the batch", name)
+		}
+	}
+}
+
+func TestRegisterToolsPublishesNoneWhenServerToolValidationFails(t *testing.T) {
+	registry := tools.NewRegistry()
+	before := registry.Snapshot().Generation
+	client := &fakeToolClient{listed: []RemoteTool{
+		{Name: "lookup", Description: "Lookup documentation"},
+		{Name: "", Description: "Invalid nameless tool"},
+	}}
+	runtime, err := RegisterTools(context.Background(), registry, config.MCPConfig{Servers: map[string]config.MCPServerConfig{
+		"docs": {Type: "stdio", Command: "docs-mcp"},
+	}}, RegisterOptions{ClientFactory: func(context.Context, Server) (ToolClient, error) {
+		return client, nil
+	}})
+	if err != nil {
+		t.Fatalf("RegisterTools() error = %v", err)
+	}
+	defer runtime.Close()
+
+	if got := registry.Snapshot().Generation; got != before {
+		t.Fatalf("registry generation = %d, want unchanged %d", got, before)
+	}
+	if _, ok := registry.Get("mcp_docs_lookup"); ok {
+		t.Fatal("valid prefix of rejected server batch was published")
+	}
+	if skipped := runtime.Skipped(); len(skipped) != 1 || skipped[0].Name != "docs" || skipped[0].Err == nil {
+		t.Fatalf("Skipped() = %#v, want one validation failure for docs", skipped)
+	}
+}
+
 func TestRegisterToolsMarksPersistentlyApprovedToolsAllow(t *testing.T) {
 	store, err := NewPermissionStore(StoreOptions{
 		FilePath: filepath.Join(t.TempDir(), "permissions.json"),
@@ -153,16 +209,16 @@ func TestRegisterToolsSkipsUnreachableServerAndKeepsOthers(t *testing.T) {
 }

 func TestRegisterToolsFlagsUnconfiguredDefaultOnSkip(t *testing.T) {
-	// firecrawl is seeded by config.DefaultMCPServers with no credentials; when a
-	// user never configures it, a connect failure (e.g. the real HTTP 401 from
-	// issue #552) must be recorded as UnconfiguredDefault so callers can avoid
+	// Exa is seeded by config.DefaultMCPServers with no credentials; when a
+	// user never configures it, a connect failure must be recorded as
+	// UnconfiguredDefault so callers can avoid
 	// warning about a server the user never asked for. "custom" is configured by
 	// the user and must NOT be flagged even though it also fails to connect.
 	registry := tools.NewRegistry()

 	runtime, err := RegisterTools(context.Background(), registry, config.MCPConfig{Servers: map[string]config.MCPServerConfig{
-		"firecrawl": config.DefaultMCPServers()["firecrawl"],
-		"custom":    {Type: "stdio", Command: "custom-mcp"},
+		"exa":    config.DefaultMCPServers()["exa"],
+		"custom": {Type: "stdio", Command: "custom-mcp"},
 	}}, RegisterOptions{
 		ClientFactory: func(_ context.Context, server Server) (ToolClient, error) {
 			return nil, errors.New(server.Name + " connect failed")
@@ -177,12 +233,12 @@ func TestRegisterToolsFlagsUnconfiguredDefaultOnSkip(t *testing.T) {
 	for _, skipped := range runtime.Skipped() {
 		byName[skipped.Name] = skipped
 	}
-	firecrawl, ok := byName["firecrawl"]
+	exa, ok := byName["exa"]
 	if !ok {
-		t.Fatalf("Skipped() = %#v, want an entry for firecrawl", runtime.Skipped())
+		t.Fatalf("Skipped() = %#v, want an entry for exa", runtime.Skipped())
 	}
-	if !firecrawl.UnconfiguredDefault {
-		t.Fatalf("Skipped()[firecrawl] = %#v, want UnconfiguredDefault", firecrawl)
+	if !exa.UnconfiguredDefault {
+		t.Fatalf("Skipped()[exa] = %#v, want UnconfiguredDefault", exa)
 	}
 	custom, ok := byName["custom"]
 	if !ok {
@@ -231,6 +231,12 @@ func reasoningEffortsForModelName(name string) []ReasoningEffort {
 		// the gateway's translation concern — unknown fields are ignored, so the
 		// worst case is a silent no-op rather than a 400.
 		return []ReasoningEffort{ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh}
+	case strings.Contains(n, "deepseek"):
+		// DeepSeek V4 (deepseek-v4-flash / deepseek-v4-pro) exposes thinking-mode
+		// effort control through the OpenAI-compatible reasoning_effort parameter.
+		// The API accepts low/high/max and maps medium/xhigh onto high, so only
+		// the three distinct tiers are advertised.
+		return []ReasoningEffort{ReasoningEffortLow, ReasoningEffortHigh, ReasoningEffortMax}
 	default:
 		return nil
 	}
@@ -20,6 +20,10 @@ func TestReasoningEffortsFallbackForGPT5AndOSeries(t *testing.T) {
 		{"hy3", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh}},
 		{"hunyuan-t1", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh}},
 		{"openai/o3-mini", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh}}, // github-style vendor/ id
+		{"deepseek-v4-flash", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortHigh, ReasoningEffortMax}},
+		{"deepseek-v4-pro", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortHigh, ReasoningEffortMax}},
+		{"deepseek-reasoner", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortHigh, ReasoningEffortMax}},
+		{"deepseek-chat", []ReasoningEffort{ReasoningEffortLow, ReasoningEffortHigh, ReasoningEffortMax}},
 		{"gpt-4.1", nil}, // non-reasoning, registered: stays empty
 		{"gpt-4o-mini", nil},
 		{"ollama/llama3.1", nil},
@@ -104,7 +104,7 @@ func windowsTokenOwner(token windows.Token) (*windows.SID, error) {
 	}
 	owner := (*windowsTokenOwnerInfo)(unsafe.Pointer(&buffer[0])).owner
 	if owner == nil {
-		return nil, errors.New("Windows access token has no default owner")
+		return nil, errors.New("windows access token has no default owner")
 	}
 	return owner.Copy()
 }
@@ -191,6 +191,7 @@ type TurnBenchResult struct {
 type TurnBenchTotals struct {
 	InputTokens       int64 `json:"inputTokens"`
 	CachedInputTokens int64 `json:"cachedInputTokens"`
+	CacheWriteTokens  int64 `json:"cacheWriteTokens"`
 	OutputTokens      int64 `json:"outputTokens"`
 	ModelRequests     int64 `json:"modelRequests"`
 	ToolCalls         int64 `json:"toolCalls"`
@@ -479,6 +480,7 @@ func topLatencySources(perSpan map[string]SpanStats, top int) []LatencySource {
 func aggregateTotals(totals *TurnBenchTotals, tr *trace.TurnTrace) {
 	totals.InputTokens += tr.Counter(trace.CounterInputTokens)
 	totals.CachedInputTokens += tr.Counter(trace.CounterCachedInputTokens)
+	totals.CacheWriteTokens += tr.Counter(trace.CounterCacheWriteTokens)
 	totals.OutputTokens += tr.Counter(trace.CounterOutputTokens)
 	totals.ModelRequests += tr.Counter(trace.CounterModelRequests)
 	totals.ToolCalls += tr.Counter(trace.CounterToolCalls)
@@ -531,8 +533,9 @@ func FormatTurnBenchSummary(result TurnBenchResult) string {
 			lines = append(lines, fmt.Sprintf("  %-18s %10s  %5.1f%%", src.Span, FormatMetric(src.TotalMs, "ms"), src.Share*100))
 		}
 	}
-	lines = append(lines, fmt.Sprintf("totals: in=%d (cached %d) out=%d | requests=%d tools=%d retries=%d reconnects=%d compactions=%d",
-		result.Totals.InputTokens, result.Totals.CachedInputTokens, result.Totals.OutputTokens,
+	lines = append(lines, fmt.Sprintf("totals: in=%d (cache-read %d, cache-write %d, uncached %d) out=%d | requests=%d tools=%d retries=%d reconnects=%d compactions=%d",
+		result.Totals.InputTokens, result.Totals.CachedInputTokens, result.Totals.CacheWriteTokens,
+		uncachedInputTokens(result.Totals), result.Totals.OutputTokens,
 		result.Totals.ModelRequests, result.Totals.ToolCalls, result.Totals.Retries,
 		result.Totals.Reconnects, result.Totals.Compactions))
 	for _, class := range sortedClasses(result.PerClass) {
@@ -545,6 +548,23 @@ func FormatTurnBenchSummary(result TurnBenchResult) string {
 	return strings.Join(lines, "\n")
 }

+func uncachedInputTokens(totals TurnBenchTotals) int64 {
+	remaining := totals.InputTokens
+	if remaining <= 0 {
+		return 0
+	}
+	for _, cached := range []int64{totals.CachedInputTokens, totals.CacheWriteTokens} {
+		if cached <= 0 {
+			continue
+		}
+		if cached >= remaining {
+			return 0
+		}
+		remaining -= cached
+	}
+	return remaining
+}
+
 // classTier returns the oracle tier label a class was classified into, so the
 // per-class roll-up states explicitly which oracle (if any) its "passed" count
 // is measured against.
@@ -74,6 +74,7 @@ func TestRunTurnBenchAggregation(t *testing.T) {
 		"t3": cannedTrace(150, 20, 1500),
 		"t4": cannedTrace(300, 10, 1000),
 	}
+	canned["t1"].Counters = append(canned["t1"].Counters, trace.Counter{Name: trace.CounterCacheWriteTokens, Value: 125})
 	cfg := TurnBenchConfig{
 		Model:      "fake-model",
 		Iterations: 1,
@@ -155,6 +156,9 @@ func TestRunTurnBenchAggregation(t *testing.T) {
 	if result.Totals.InputTokens != 5500 {
 		t.Fatalf("inputTokens = %d, want 5500", result.Totals.InputTokens)
 	}
+	if result.Totals.CacheWriteTokens != 125 {
+		t.Fatalf("cacheWriteTokens = %d, want 125", result.Totals.CacheWriteTokens)
+	}
 	if result.Totals.OutputTokens != 2750 {
 		t.Fatalf("outputTokens = %d, want 2750", result.Totals.OutputTokens)
 	}
@@ -334,6 +338,35 @@ func TestFormatTurnBenchSummaryNamesTopSources(t *testing.T) {
 	}
 }

+func TestUncachedInputTokensClampsInconsistentTotals(t *testing.T) {
+	tests := []struct {
+		name   string
+		totals TurnBenchTotals
+		want   int64
+	}{
+		{name: "normal", totals: TurnBenchTotals{InputTokens: 100, CachedInputTokens: 30, CacheWriteTokens: 20}, want: 50},
+		{name: "cached exceeds input", totals: TurnBenchTotals{InputTokens: 100, CachedInputTokens: 120}, want: 0},
+		{name: "write exceeds remainder", totals: TurnBenchTotals{InputTokens: 100, CachedInputTokens: 20, CacheWriteTokens: 90}, want: 0},
+		{name: "overflowing inconsistent counters", totals: TurnBenchTotals{CachedInputTokens: 1<<63 - 1, CacheWriteTokens: 1<<63 - 1}, want: 0},
+		{name: "overflowing counters with input", totals: TurnBenchTotals{InputTokens: 100, CachedInputTokens: 1<<63 - 1, CacheWriteTokens: 1<<63 - 1}, want: 0},
+		{name: "negative cache counters ignored", totals: TurnBenchTotals{InputTokens: 100, CachedInputTokens: -20, CacheWriteTokens: -10}, want: 100},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := uncachedInputTokens(test.totals); got != test.want {
+				t.Fatalf("uncachedInputTokens(%+v) = %d, want %d", test.totals, got, test.want)
+			}
+		})
+	}
+	summary := FormatTurnBenchSummary(TurnBenchResult{Totals: TurnBenchTotals{
+		CachedInputTokens: 1<<63 - 1,
+		CacheWriteTokens:  1<<63 - 1,
+	}})
+	if !strings.Contains(summary, "uncached 0") {
+		t.Fatalf("summary did not clamp inconsistent cache totals:\n%s", summary)
+	}
+}
+
 func TestLoadBaselineManifest(t *testing.T) {
 	path := filepath.Join("manifests", "baseline.json")
 	set, err := LoadTaskSet(path)
@@ -184,6 +184,10 @@ func parseOpenAIStyleModelList(body []byte) ([]remoteModel, error) {

 func ModelsDevProviderID(provider providercatalog.Descriptor) string {
 	switch strings.TrimSpace(provider.ID) {
+	case "chatgpt":
+		// ChatGPT authenticates against the Codex backend, while its public
+		// model metadata is published under the OpenAI provider on models.dev.
+		return "openai"
 	case "dashscope":
 		return "alibaba"
 	case "github":
@@ -241,6 +241,7 @@ func TestPublicLiveCatalog(t *testing.T) {

 func TestModelsDevProviderIDMapsZeroAliases(t *testing.T) {
 	tests := map[string]string{
+		"chatgpt":      "openai",
 		"github":       "github-models",
 		"moonshot":     "moonshotai",
 		"nvidia-nim":   "nvidia",
@@ -539,7 +539,8 @@ func mergeLiveModels(provider providercatalog.Descriptor, liveModels []Model, ca
 	hasCatalog := len(byID) > 0
 	// Aggregators publish the live list as the source of truth. Keep live-only
 	// ids even when a remote catalog also loaded, instead of intersecting.
-	preferLive := providermodelcatalog.PublicLiveCatalog(provider.ID) ||
+	preferLive := provider.Local ||
+		providermodelcatalog.PublicLiveCatalog(provider.ID) ||
 		providercatalog.NormalizeID(provider.ID) == "chatgpt"
 	result := make([]Model, 0, len(liveModels))
 	for _, live := range liveModels {
@@ -139,6 +139,68 @@ func TestMergeChatGPTModelsKeepsLiveOnlyEntries(t *testing.T) {
 	}
 }

+func TestDiscoverCatalogChatGPTMergesOpenAIModelsDevMetadata(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api.json":
+			_, _ = w.Write([]byte(`{
+				"openai": {"models": {
+					"gpt-5.6-sol": {
+						"id": "gpt-5.6-sol",
+						"name": "GPT-5.6 Sol",
+						"description": "Frontier coding model",
+						"tool_call": true,
+						"reasoning": true,
+						"reasoning_efforts": ["low", "high", "max"],
+						"limit": {"context": 1050000},
+						"modalities": {"input": ["text", "image", "pdf"], "output": ["text"]}
+					}
+				}}
+			}`))
+		case "/backend-api/codex/models":
+			_, _ = w.Write([]byte(`{"data":[{"id":"gpt-5.6-sol"}]}`))
+		default:
+			t.Errorf("unexpected request path %q", r.URL.Path)
+			http.NotFound(w, r)
+			return
+		}
+	}))
+	defer server.Close()
+
+	provider, ok := providercatalog.Get("chatgpt")
+	if !ok {
+		t.Fatal("ChatGPT provider missing from catalog")
+	}
+	models, err := DiscoverCatalog(context.Background(), provider, config.ProviderProfile{
+		Name:         "chatgpt",
+		CatalogID:    "chatgpt",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		BaseURL:      server.URL + "/backend-api/codex",
+	}, Options{
+		HTTPClient:   server.Client(),
+		ModelsDevURL: server.URL + "/api.json",
+		OAuthResolver: func(context.Context, bool) (string, string, bool, error) {
+			return "Authorization", "Bearer test", true, nil
+		},
+	})
+	if err != nil {
+		t.Fatalf("DiscoverCatalog returned error: %v", err)
+	}
+	if len(models) != 1 {
+		t.Fatalf("models = %#v, want one ChatGPT live model", models)
+	}
+	model := models[0]
+	if model.ID != "gpt-5.6-sol" || model.ContextWindow != 1050000 || !model.ToolCall || !model.Reasoning {
+		t.Fatalf("merged ChatGPT model = %#v, want models.dev metadata", model)
+	}
+	if got := strings.Join(model.InputModalities, ","); got != "text,image,pdf" {
+		t.Fatalf("input modalities = %q, want text,image,pdf", got)
+	}
+	if got := strings.Join(model.ReasoningEfforts, ","); got != "low,high,max" {
+		t.Fatalf("reasoning efforts = %q, want low,high,max", got)
+	}
+}
+
 func TestMergeLiveModelsUsesLiveDefaultsAndReasoningCapability(t *testing.T) {
 	models := mergeLiveModels(
 		providercatalog.Descriptor{ID: "chatgpt"},
@@ -164,6 +226,29 @@ func TestMergeLiveModelsUsesLiveDefaultsAndReasoningCapability(t *testing.T) {
 	}
 }

+func TestMergeLocalModelsKeepsLiveOnlyEntries(t *testing.T) {
+	models := mergeLiveModels(
+		providercatalog.Descriptor{ID: "lmstudio", Local: true},
+		[]Model{
+			{ID: "qwen3-coder-30b", ContextWindow: 32768},
+			{ID: "text-embedding-local"},
+			{ID: "qwen2.5-coder-32b-instruct", Description: "live description"},
+		},
+		[]Model{{ID: "qwen2.5-coder-32b-instruct", Description: "catalog description", ToolCall: true}},
+	)
+
+	if got, want := strings.Join(modelIDs(models), ","), "qwen3-coder-30b,qwen2.5-coder-32b-instruct"; got != want {
+		t.Fatalf("models = %q, want %q", got, want)
+	}
+	for _, model := range models {
+		if model.ID == "qwen2.5-coder-32b-instruct" {
+			if model.Description != "catalog description" || !model.ToolCall {
+				t.Fatalf("merged catalog metadata = %#v", model)
+			}
+		}
+	}
+}
+
 func TestDiscoverCatalogOpenGatewayUsesLiveListWithoutKey(t *testing.T) {
 	// Catalog and live endpoints return distinct payloads so the merge must keep
 	// live-only ids that are absent from the remote catalog response.
@@ -62,6 +62,7 @@ const (
 	responsesEventReasoningDelta    = "response.reasoning_summary_text.delta"
 	responsesEventOutputTextDone    = "response.output_text.done"
 	responsesEventFunctionArgsDelta = "response.function_call_arguments.delta"
+	responsesEventCustomInputDelta  = "response.custom_tool_call_input.delta"
 	responsesEventContentPartDone   = "response.content_part.done"
 	responsesEventOutputItemDone    = "response.output_item.done"
 	responsesEventCompleted         = "response.completed"
@@ -70,17 +71,37 @@ const (
 	responsesEventIncomplete        = "response.incomplete"
 )

+const applyPatchLarkGrammar = `start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+%import common.LF`
+
 // responsesRequest is the wire shape POSTed to {baseURL}/responses.
 type responsesRequest struct {
-	Model           string              `json:"model"`
-	Instructions    string              `json:"instructions"`
-	Input           []inputItem         `json:"input"`
-	Stream          bool                `json:"stream"`
-	Store           bool                `json:"store"`
-	MaxOutputTokens int                 `json:"max_output_tokens,omitempty"`
-	Tools           []responsesTool     `json:"tools,omitempty"`
-	Reasoning       *responsesReasoning `json:"reasoning,omitempty"`
-	ServiceTier     string              `json:"service_tier,omitempty"`
+	Type               string              `json:"type,omitempty"`
+	Model              string              `json:"model"`
+	Instructions       string              `json:"instructions"`
+	PreviousResponseID string              `json:"previous_response_id,omitempty"`
+	Input              []inputItem         `json:"input"`
+	Stream             bool                `json:"stream"`
+	Store              bool                `json:"store"`
+	ParallelToolCalls  bool                `json:"parallel_tool_calls"`
+	MaxOutputTokens    int                 `json:"max_output_tokens,omitempty"`
+	Tools              []responsesTool     `json:"tools,omitempty"`
+	Reasoning          *responsesReasoning `json:"reasoning,omitempty"`
+	ServiceTier        string              `json:"service_tier,omitempty"`
+	PromptCacheKey     string              `json:"prompt_cache_key,omitempty"`
 }

 // responsesReasoning carries the reasoning controls for the Responses API. The
@@ -105,6 +126,7 @@ type inputItem struct {
 	CallID    string `json:"call_id,omitempty"`
 	Name      string `json:"name,omitempty"`
 	Arguments string `json:"arguments,omitempty"`
+	Input     string `json:"input,omitempty"`
 	// function_call_output fields
 	Output any `json:"output,omitempty"`
 }
@@ -118,10 +140,11 @@ type contentItem struct {
 }

 type responsesTool struct {
-	Type        string         `json:"type"`
-	Name        string         `json:"name"`
-	Description string         `json:"description,omitempty"`
-	Parameters  map[string]any `json:"parameters,omitempty"`
+	Type        string                            `json:"type"`
+	Name        string                            `json:"name"`
+	Description string                            `json:"description,omitempty"`
+	Parameters  map[string]any                    `json:"parameters,omitempty"`
+	Format      *zeroruntime.ToolDefinitionFormat `json:"format,omitempty"`
 }

 // responsesEvent is the decoded form of one Responses SSE data payload.
@@ -132,6 +155,7 @@ type responsesEvent struct {
 	Delta string `json:"delta,omitempty"`
 	// item payloads (response.output_item.added / done)
 	ItemID string `json:"item_id,omitempty"`
+	CallID string `json:"call_id,omitempty"`
 	// OutputIndex is a *int so a real 0 (the first output) is distinguishable from
 	// "absent" — a plain int defaulting to 0 dropped a no-item_id call's args (M1).
 	OutputIndex *int         `json:"output_index,omitempty"`
@@ -150,6 +174,7 @@ type itemPayload struct {
 	CallID    string `json:"call_id,omitempty"`
 	Name      string `json:"name,omitempty"`
 	Arguments string `json:"arguments,omitempty"`
+	Input     string `json:"input,omitempty"`
 	Status    string `json:"status,omitempty"`
 }

@@ -173,7 +198,8 @@ type outputDetails struct {
 }

 type inputDetails struct {
-	CachedTokens int `json:"cached_tokens"`
+	CachedTokens     int `json:"cached_tokens"`
+	CacheWriteTokens int `json:"cache_write_tokens"`
 }

 type errorPayload struct {
@@ -187,8 +213,10 @@ type errorPayload struct {
 // response.output_item.done.
 type toolCallBuilder struct {
 	ID        string
+	CallID    string
 	Name      string
 	Arguments strings.Builder
+	Freeform  bool
 	started   bool
 	ended     bool
 }
@@ -197,15 +225,57 @@ type toolCallBuilder struct {
 // event has been emitted. It is the Responses-API equivalent of the
 // chat-completions toolState in provider.go.
 type responsesState struct {
-	toolCalls map[string]*toolCallBuilder
-	usage     *usagePayload
-	done      bool
+	toolCalls  map[string]*toolCallBuilder
+	toolOrder  []string
+	text       strings.Builder
+	responseID string
+	usage      *usagePayload
+	emitted    bool
+	done       bool
 }

 func newResponsesState() *responsesState {
 	return &responsesState{toolCalls: map[string]*toolCallBuilder{}}
 }

+func (state *responsesState) outputInputItems() []inputItem {
+	items := make([]inputItem, 0, len(state.toolOrder)+1)
+	if state.text.Len() > 0 {
+		items = append(items, inputItem{
+			Type:    "message",
+			Role:    "assistant",
+			Content: []contentItem{{Type: "output_text", Text: state.text.String()}},
+		})
+	}
+	for _, key := range state.toolOrder {
+		builder := state.toolCalls[key]
+		if builder == nil || builder.ID == "" || builder.Name == "" {
+			continue
+		}
+		callID := builder.CallID
+		if callID == "" {
+			callID = builder.ID
+		}
+		itemType := "function_call"
+		if builder.Freeform {
+			itemType = "custom_tool_call"
+		}
+		item := inputItem{
+			Type:   itemType,
+			ID:     builder.ID,
+			CallID: callID,
+			Name:   builder.Name,
+		}
+		if builder.Freeform {
+			item.Input = builder.Arguments.String()
+		} else {
+			item.Arguments = builder.Arguments.String()
+		}
+		items = append(items, item)
+	}
+	return items
+}
+
 // buildResponsesRequest converts a runtime CompletionRequest into the
 // Responses API wire format. System messages fold into a top-level
 // `instructions` field; everything else (user/assistant turns, tool
@@ -215,11 +285,14 @@ func (p *CodexProvider) buildResponsesRequest(request zeroruntime.CompletionRequ
 		return nil, errors.New("codex provider: model is required")
 	}
 	req := &responsesRequest{
-		Model:           p.inner.model,
-		Stream:          true,
-		MaxOutputTokens: p.inner.maxTokens,
+		Model:             p.inner.model,
+		Stream:            true,
+		ParallelToolCalls: true,
+		MaxOutputTokens:   p.inner.maxTokens,
+		PromptCacheKey:    request.PromptCacheKey,
 	}
 	instructions := []string{}
+	customCallIDs := map[string]string{}
 	for _, msg := range request.Messages {
 		switch msg.Role {
 		case zeroruntime.MessageRoleSystem:
@@ -234,13 +307,31 @@ func (p *CodexProvider) buildResponsesRequest(request zeroruntime.CompletionRequ
 				return nil, err
 			}
 			req.Input = append(req.Input, items...)
+			for _, call := range msg.ToolCalls {
+				if call.Freeform && call.ID != "" {
+					callID := call.ProviderCallID
+					if callID == "" {
+						callID = call.ID
+					}
+					customCallIDs[call.ID] = callID
+				}
+			}
 		case zeroruntime.MessageRoleTool:
 			if msg.ToolCallID == "" {
 				return nil, fmt.Errorf("codex provider: tool message missing tool call id")
 			}
+			outputType := "function_call_output"
+			callID := msg.ToolCallProviderID
+			if callID == "" {
+				callID = msg.ToolCallID
+			}
+			if customID, custom := customCallIDs[msg.ToolCallID]; custom {
+				outputType = "custom_tool_call_output"
+				callID = customID
+			}
 			req.Input = append(req.Input, inputItem{
-				Type:   "function_call_output",
-				CallID: msg.ToolCallID,
+				Type:   outputType,
+				CallID: callID,
 				Output: msg.Content,
 			})
 		default:
@@ -249,12 +340,25 @@ func (p *CodexProvider) buildResponsesRequest(request zeroruntime.CompletionRequ
 	}
 	req.Instructions = strings.Join(instructions, "\n\n")
 	for _, tool := range request.Tools {
-		req.Tools = append(req.Tools, responsesTool{
-			Type:        "function",
-			Name:        tool.Name,
-			Description: tool.Description,
-			Parameters:  tool.Parameters,
-		})
+		definition := tool
+		if definition.Name == "apply_patch" && definition.Type == zeroruntime.ToolDefinitionFreeform {
+			definition.Description = "The apply_patch tool edits files from a raw structured patch. Use absolute file paths in patch headers to target a granted extra write root. Do not wrap the patch in JSON."
+			definition.Format = &zeroruntime.ToolDefinitionFormat{Type: "grammar", Syntax: "lark", Definition: applyPatchLarkGrammar}
+		}
+		wireTool := responsesTool{
+			Type:        string(definition.Type),
+			Name:        definition.Name,
+			Description: definition.Description,
+			Parameters:  definition.Parameters,
+			Format:      definition.Format,
+		}
+		if wireTool.Type == "" {
+			wireTool.Type = string(zeroruntime.ToolDefinitionFunction)
+		}
+		if wireTool.Type == string(zeroruntime.ToolDefinitionFreeform) {
+			wireTool.Parameters = nil
+		}
+		req.Tools = append(req.Tools, wireTool)
 	}
 	// Codex / o-series reasoning models take the effort tier nested under
 	// `reasoning` on the Responses API (the chat-completions `reasoning_effort`
@@ -312,13 +416,26 @@ func (p *CodexProvider) assistantInputItems(msg zeroruntime.Message) ([]inputIte
 		if tc.Name == "" {
 			return nil, errors.New("codex provider: assistant tool call missing name")
 		}
-		items = append(items, inputItem{
-			Type:      "function_call",
-			ID:        tc.ID,
-			CallID:    tc.ID,
-			Name:      tc.Name,
-			Arguments: tc.Arguments,
-		})
+		callID := tc.ProviderCallID
+		if callID == "" {
+			callID = tc.ID
+		}
+		itemType := "function_call"
+		if tc.Freeform {
+			itemType = "custom_tool_call"
+		}
+		item := inputItem{
+			Type:   itemType,
+			ID:     tc.ID,
+			CallID: callID,
+			Name:   tc.Name,
+		}
+		if tc.Freeform {
+			item.Input = tc.Arguments
+		} else {
+			item.Arguments = tc.Arguments
+		}
+		items = append(items, item)
 	}
 	return items, nil
 }
@@ -479,6 +596,18 @@ func (p *CodexProvider) emitResponsesEvent(
 		state.done = true
 		return false
 	}
+	return p.emitParsedResponsesEvent(ctx, &event, state, events)
+}
+
+// emitParsedResponsesEvent converts one already-decoded Responses event into
+// zero or more runtime events. WebSocket sessions use this path to avoid
+// decoding each frame twice; the SSE path retains emitResponsesEvent above.
+func (p *CodexProvider) emitParsedResponsesEvent(
+	ctx context.Context,
+	event *responsesEvent,
+	state *responsesState,
+	events chan<- zeroruntime.StreamEvent,
+) bool {
 	if event.Type == "" {
 		// A payload that parses as JSON but carries no `type` field is a
 		// malformed Responses event — the type is the discriminator that
@@ -500,12 +629,17 @@ func (p *CodexProvider) emitResponsesEvent(
 		// the runtime. response.incomplete is folded into a length finish at
 		// scan-end (state.done stays false so the wrapper emits the
 		// StreamEventDone with FinishReasonLength).
+		if event.Response != nil && event.Response.ID != "" {
+			state.responseID = event.Response.ID
+		}
 		return true
 	case responsesEventOutputItemAdded:
-		p.handleOutputItemAdded(ctx, &event, state, events)
+		p.handleOutputItemAdded(ctx, event, state, events)
 		return true
 	case responsesEventOutputTextDelta:
 		if event.Delta != "" {
+			state.emitted = true
+			state.text.WriteString(event.Delta)
 			providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 				Type:    zeroruntime.StreamEventText,
 				Content: event.Delta,
@@ -517,6 +651,7 @@ func (p *CodexProvider) emitResponsesEvent(
 		// phase shows progress (and keeps the activity clock fresh) instead of
 		// looking like a hang. Requested via reasoning.summary="auto".
 		if event.Delta != "" {
+			state.emitted = true
 			providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 				Type:    zeroruntime.StreamEventReasoning,
 				Content: event.Delta,
@@ -524,13 +659,16 @@ func (p *CodexProvider) emitResponsesEvent(
 		}
 		return true
 	case responsesEventFunctionArgsDelta:
-		p.handleFunctionArgsDelta(ctx, &event, state, events)
+		p.handleToolInputDelta(ctx, event, state, events, false)
+		return true
+	case responsesEventCustomInputDelta:
+		p.handleToolInputDelta(ctx, event, state, events, true)
 		return true
 	case responsesEventOutputItemDone:
-		p.handleOutputItemDone(ctx, &event, state, events)
+		p.handleOutputItemDone(ctx, event, state, events)
 		return true
 	case responsesEventCompleted, responsesEventFailed:
-		return p.handleTerminalResponse(ctx, &event, state, events)
+		return p.handleTerminalResponse(ctx, event, state, events)
 	case responsesEventError:
 		message := event.Message
 		if event.Code != "" {
@@ -570,22 +708,38 @@ func (p *CodexProvider) handleOutputItemAdded(
 		return
 	}
 	switch event.Item.Type {
-	case "function_call":
+	case "function_call", "custom_tool_call":
 		key := p.toolCallKey(event)
 		if key == "" {
 			return
 		}
-		builder := &toolCallBuilder{
-			ID:   key,
-			Name: event.Item.Name,
+		builder, exists := state.toolCalls[key]
+		if !exists {
+			builder = &toolCallBuilder{ID: key, Freeform: event.Item.Type == "custom_tool_call"}
+			state.toolCalls[key] = builder
+			state.toolOrder = append(state.toolOrder, key)
+		}
+		if event.Item.CallID != "" {
+			builder.CallID = event.Item.CallID
+		}
+		if event.Item.Name != "" {
+			builder.Name = event.Item.Name
+		}
+		builder.Freeform = builder.Freeform || event.Item.Type == "custom_tool_call"
+		if builder.Freeform && event.Item.Input != "" && builder.Arguments.Len() == 0 {
+			builder.Arguments.WriteString(event.Item.Input)
+		}
+		state.emitted = true
+		if !builder.started {
+			providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
+				Type:               zeroruntime.StreamEventToolCallStart,
+				ToolCallID:         key,
+				ToolCallProviderID: builder.CallID,
+				ToolName:           builder.Name,
+				ToolCallFreeform:   builder.Freeform,
+			})
+			builder.started = true
 		}
-		state.toolCalls[key] = builder
-		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
-			Type:       zeroruntime.StreamEventToolCallStart,
-			ToolCallID: key,
-			ToolName:   event.Item.Name,
-		})
-		builder.started = true
 	}
 }

@@ -593,11 +747,12 @@ func (p *CodexProvider) handleOutputItemAdded(
 // to the in-flight builder and emits StreamEventToolCallDelta. The
 // Codex backend uses either `item_id` or `output_index` to attribute
 // the delta; we honor both.
-func (p *CodexProvider) handleFunctionArgsDelta(
+func (p *CodexProvider) handleToolInputDelta(
 	ctx context.Context,
 	event *responsesEvent,
 	state *responsesState,
 	events chan<- zeroruntime.StreamEvent,
+	freeform bool,
 ) {
 	key := p.toolCallKey(event)
 	if key == "" {
@@ -610,10 +765,16 @@ func (p *CodexProvider) handleFunctionArgsDelta(
 		// an intermediate proxy). Treat the delta as the start of a new
 		// tool call with no known name yet — the eventual
 		// response.output_item.done carries the final name.
-		builder = &toolCallBuilder{ID: key}
+		builder = &toolCallBuilder{ID: key, Freeform: freeform}
 		state.toolCalls[key] = builder
+		state.toolOrder = append(state.toolOrder, key)
+	}
+	builder.Freeform = builder.Freeform || freeform
+	if event.CallID != "" && builder.CallID == "" {
+		builder.CallID = event.CallID
 	}
 	builder.Arguments.WriteString(event.Delta)
+	state.emitted = true
 	providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 		Type:              zeroruntime.StreamEventToolCallDelta,
 		ToolCallID:        key,
@@ -632,7 +793,7 @@ func (p *CodexProvider) handleOutputItemDone(
 	state *responsesState,
 	events chan<- zeroruntime.StreamEvent,
 ) {
-	if event.Item == nil || event.Item.Type != "function_call" {
+	if event.Item == nil || (event.Item.Type != "function_call" && event.Item.Type != "custom_tool_call") {
 		return
 	}
 	key := p.toolCallKey(event)
@@ -641,20 +802,31 @@ func (p *CodexProvider) handleOutputItemDone(
 	}
 	builder, ok := state.toolCalls[key]
 	if !ok {
-		builder = &toolCallBuilder{ID: key}
+		builder = &toolCallBuilder{ID: key, Freeform: event.Item.Type == "custom_tool_call"}
 		state.toolCalls[key] = builder
+		state.toolOrder = append(state.toolOrder, key)
 	}
 	if event.Item.Name != "" {
 		builder.Name = event.Item.Name
 	}
-	if event.Item.Arguments != "" && builder.Arguments.Len() == 0 {
-		builder.Arguments.WriteString(event.Item.Arguments)
+	if event.Item.CallID != "" {
+		builder.CallID = event.Item.CallID
+	}
+	builder.Freeform = builder.Freeform || event.Item.Type == "custom_tool_call"
+	finalInput := event.Item.Arguments
+	if builder.Freeform {
+		finalInput = event.Item.Input
+	}
+	if finalInput != "" && builder.Arguments.Len() == 0 {
+		builder.Arguments.WriteString(finalInput)
 	}
 	if !builder.started {
 		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
-			Type:       zeroruntime.StreamEventToolCallStart,
-			ToolCallID: key,
-			ToolName:   builder.Name,
+			Type:               zeroruntime.StreamEventToolCallStart,
+			ToolCallID:         key,
+			ToolCallProviderID: builder.CallID,
+			ToolName:           builder.Name,
+			ToolCallFreeform:   builder.Freeform,
 		})
 		builder.started = true
 	}
@@ -664,6 +836,7 @@ func (p *CodexProvider) handleOutputItemDone(
 		ToolName:   builder.Name,
 	})
 	builder.ended = true
+	state.emitted = true
 }

 // handleTerminalResponse emits the final usage + done event for a
@@ -693,6 +866,7 @@ func (p *CodexProvider) handleTerminalResponse(
 		return false
 	}
 	state.usage = event.Response.Usage
+	state.responseID = event.Response.ID
 	if event.Response.Usage != nil {
 		usage := zeroruntime.Usage{
 			InputTokens:  event.Response.Usage.InputTokens,
@@ -700,6 +874,7 @@ func (p *CodexProvider) handleTerminalResponse(
 		}
 		if event.Response.Usage.InputTokensDetails != nil {
 			usage.CachedInputTokens = event.Response.Usage.InputTokensDetails.CachedTokens
+			usage.CacheWriteTokens = event.Response.Usage.InputTokensDetails.CacheWriteTokens
 		}
 		if event.Response.Usage.OutputTokensDetails != nil {
 			usage.ReasoningTokens = event.Response.Usage.OutputTokensDetails.ReasoningTokens
@@ -735,7 +910,7 @@ func (p *CodexProvider) handleTerminalResponse(
 		state.done = true
 		return false
 	}
-	providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{Type: zeroruntime.StreamEventDone})
+	providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{Type: zeroruntime.StreamEventDone, ResponseID: event.Response.ID})
 	state.done = true
 	return false
 }
@@ -754,6 +929,9 @@ func (p *CodexProvider) toolCallKey(event *responsesEvent) string {
 	if event.Item != nil && event.Item.CallID != "" {
 		return event.Item.CallID
 	}
+	if event.CallID != "" {
+		return event.CallID
+	}
 	if event.OutputIndex != nil {
 		// output_index is present (a *int distinguishes a real 0 — the first output
 		// in the response — from "absent"), so key on it even when 0 instead of
@@ -0,0 +1,421 @@
+package openai
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"reflect"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/coder/websocket"
+
+	"github.com/Gitlawb/zero/internal/providers/providerio"
+	"github.com/Gitlawb/zero/internal/trace"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+const (
+	responsesWebSocketBetaHeader = "OpenAI-Beta"
+	responsesWebSocketBetaValue  = "responses_websockets=2026-02-06"
+	responsesWebSocketRequest    = "response.create"
+	previousResponseNotFoundCode = "previous_response_not_found"
+	webSocketConnectionLimitCode = "websocket_connection_limit_reached"
+	responsesWebSocketReadLimit  = 16 << 20
+)
+
+var errCodexTurnSessionBusy = errors.New("codex turn session already has an active stream")
+
+// NewCodexTurnSessionProvider enables one Responses WebSocket connection for
+// each agent run. The session falls back to the existing HTTP/SSE provider when
+// the endpoint cannot upgrade or loses its response chain.
+func NewCodexTurnSessionProvider(provider *CodexProvider, caps zeroruntime.ProviderCapabilities) zeroruntime.TurnSessionProvider {
+	return &codexTurnSessionProvider{provider: provider, caps: caps}
+}
+
+type codexTurnSessionProvider struct {
+	provider *CodexProvider
+	caps     zeroruntime.ProviderCapabilities
+}
+
+func (provider *codexTurnSessionProvider) OpenTurnSession(ctx context.Context) (zeroruntime.TurnSession, error) {
+	if provider == nil || provider.provider == nil || provider.provider.inner == nil {
+		return nil, errors.New("codex turn session requires a provider")
+	}
+	sessionCtx, cancel := context.WithCancel(ctx)
+	return &codexTurnSession{
+		ctx:         sessionCtx,
+		cancel:      cancel,
+		provider:    provider.provider,
+		prewarmDone: make(chan struct{}),
+	}, nil
+}
+
+func (provider *codexTurnSessionProvider) Capabilities() zeroruntime.ProviderCapabilities {
+	return provider.caps
+}
+
+type codexTurnSession struct {
+	ctx      context.Context
+	cancel   context.CancelFunc
+	provider *CodexProvider
+
+	mu             sync.Mutex
+	connection     *websocket.Conn
+	webSocketOff   bool
+	lastRequest    *responsesRequest
+	lastResponseID string
+	lastOutput     []inputItem
+	streamActive   bool
+
+	prewarmOnce sync.Once
+	prewarmDone chan struct{}
+	closeOnce   sync.Once
+}
+
+// Prewarm starts the WebSocket handshake without blocking prompt assembly. The
+// first Stream waits for this bounded attempt; failure simply selects HTTP/SSE.
+func (session *codexTurnSession) Prewarm(ctx context.Context) error {
+	session.prewarmOnce.Do(func() {
+		go func() {
+			defer close(session.prewarmDone)
+			prewarmCtx, cancel := context.WithTimeout(session.ctx, prewarmTimeout)
+			defer cancel()
+			recorder := trace.FromContext(ctx)
+			span := recorder.Span(trace.SpanProviderPrewarm)
+			defer span.End()
+			recorder.Counter(trace.CounterPrewarmAttempts, 1)
+			connection, err := session.provider.dialResponsesWebSocket(prewarmCtx)
+			session.mu.Lock()
+			defer session.mu.Unlock()
+			if err != nil {
+				session.webSocketOff = true
+				return
+			}
+			session.connection = connection
+		}()
+	})
+	return nil
+}
+
+func (session *codexTurnSession) Stream(ctx context.Context, request zeroruntime.CompletionRequest) (<-chan zeroruntime.StreamEvent, error) {
+	_ = session.Prewarm(ctx)
+	select {
+	case <-session.prewarmDone:
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+
+	fullRequest, err := session.provider.buildResponsesRequest(request)
+	if err != nil {
+		return nil, err
+	}
+
+	session.mu.Lock()
+	if session.streamActive {
+		session.mu.Unlock()
+		return nil, errCodexTurnSessionBusy
+	}
+	if session.webSocketOff || session.connection == nil {
+		session.mu.Unlock()
+		trace.FromContext(ctx).Counter(trace.CounterResponsesHTTPFallback, 1)
+		return session.provider.StreamCompletion(ctx, request)
+	}
+	session.streamActive = true
+	connection := session.connection
+	wireRequest := *fullRequest
+	wireRequest.Type = responsesWebSocketRequest
+	if delta, ok := responseInputDelta(session.lastRequest, session.lastOutput, fullRequest); ok && session.lastResponseID != "" {
+		wireRequest.PreviousResponseID = session.lastResponseID
+		wireRequest.Input = delta
+		trace.FromContext(ctx).Counter(trace.CounterResponseChainReused, 1)
+	} else if session.lastRequest != nil {
+		trace.FromContext(ctx).Counter(trace.CounterResponseChainReset, 1)
+		session.lastRequest = nil
+		session.lastResponseID = ""
+		session.lastOutput = nil
+	}
+	session.mu.Unlock()
+
+	body, err := json.Marshal(wireRequest)
+	if err != nil {
+		session.releaseStream()
+		return nil, fmt.Errorf("encode codex websocket request: %w", err)
+	}
+	events := make(chan zeroruntime.StreamEvent, 16)
+	go func() {
+		defer close(events)
+		defer session.releaseStream()
+		session.streamWebSocket(ctx, connection, body, fullRequest, request, events)
+	}()
+	return events, nil
+}
+
+func (session *codexTurnSession) releaseStream() {
+	session.mu.Lock()
+	session.streamActive = false
+	session.mu.Unlock()
+}
+
+func (session *codexTurnSession) Compact(context.Context, zeroruntime.CompletionRequest) ([]zeroruntime.Message, error) {
+	return nil, zeroruntime.ErrCompactionUnsupported
+}
+
+func (session *codexTurnSession) Close() error {
+	session.closeOnce.Do(func() {
+		session.cancel()
+		session.prewarmOnce.Do(func() { close(session.prewarmDone) })
+		select {
+		case <-session.prewarmDone:
+		case <-time.After(prewarmTimeout):
+		}
+		session.mu.Lock()
+		connection := session.connection
+		session.connection = nil
+		session.webSocketOff = true
+		session.mu.Unlock()
+		if connection != nil {
+			_ = connection.CloseNow()
+		}
+	})
+	return nil
+}
+
+func responseInputDelta(previous *responsesRequest, output []inputItem, current *responsesRequest) ([]inputItem, bool) {
+	if previous == nil || current == nil || !responsesRequestPropertiesEqual(previous, current) {
+		return nil, false
+	}
+	prefix := make([]inputItem, 0, len(previous.Input)+len(output))
+	prefix = append(prefix, previous.Input...)
+	prefix = append(prefix, output...)
+	if len(current.Input) <= len(prefix) || !reflect.DeepEqual(current.Input[:len(prefix)], prefix) {
+		return nil, false
+	}
+	return append([]inputItem(nil), current.Input[len(prefix):]...), true
+}
+
+func responsesRequestPropertiesEqual(left, right *responsesRequest) bool {
+	return left.Model == right.Model &&
+		left.Instructions == right.Instructions &&
+		left.Stream == right.Stream &&
+		left.Store == right.Store &&
+		left.ParallelToolCalls == right.ParallelToolCalls &&
+		left.MaxOutputTokens == right.MaxOutputTokens &&
+		reflect.DeepEqual(left.Tools, right.Tools) &&
+		reflect.DeepEqual(left.Reasoning, right.Reasoning) &&
+		left.ServiceTier == right.ServiceTier &&
+		left.PromptCacheKey == right.PromptCacheKey
+}
+
+func (session *codexTurnSession) streamWebSocket(
+	ctx context.Context,
+	connection *websocket.Conn,
+	body []byte,
+	fullRequest *responsesRequest,
+	runtimeRequest zeroruntime.CompletionRequest,
+	events chan<- zeroruntime.StreamEvent,
+) {
+	if err := connection.Write(ctx, websocket.MessageText, body); err != nil {
+		session.disableWebSocket(connection)
+		session.forwardHTTP(ctx, runtimeRequest, events)
+		return
+	}
+
+	state := newResponsesState()
+	for {
+		readCtx := ctx
+		cancel := func() {}
+		idleTimeout := session.provider.inner.streamIdleTimeout
+		if idleTimeout > 0 {
+			readCtx, cancel = context.WithTimeout(ctx, idleTimeout)
+		}
+		messageType, data, err := connection.Read(readCtx)
+		readTimedOut := errors.Is(readCtx.Err(), context.DeadlineExceeded) && ctx.Err() == nil
+		cancel()
+		if err != nil {
+			session.disableWebSocket(connection)
+			if ctx.Err() != nil {
+				return
+			}
+			if !state.emitted {
+				session.forwardHTTP(ctx, runtimeRequest, events)
+				return
+			}
+			errorMessage := err.Error()
+			if readTimedOut {
+				errorMessage = providerio.StreamTimeoutMessage(providerio.ErrStreamIdle, idleTimeout)
+			}
+			providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
+				Type:  zeroruntime.StreamEventError,
+				Error: session.provider.redact("provider stream error: " + errorMessage),
+			})
+			return
+		}
+		if messageType != websocket.MessageText {
+			continue
+		}
+
+		var responseEvent responsesEvent
+		decodeErr := json.Unmarshal(data, &responseEvent)
+		if decodeErr == nil {
+			if (responseEvent.Code == previousResponseNotFoundCode || responseEvent.Code == webSocketConnectionLimitCode) &&
+				!state.emitted {
+				session.disableWebSocket(connection)
+				session.forwardHTTP(ctx, runtimeRequest, events)
+				return
+			}
+			if responseEvent.Type == responsesEventIncomplete {
+				session.resetResponseChain(connection)
+				providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
+					Type:         zeroruntime.StreamEventDone,
+					FinishReason: zeroruntime.FinishReasonLength,
+				})
+				return
+			}
+		}
+
+		keepReading := false
+		if decodeErr == nil {
+			keepReading = session.provider.emitParsedResponsesEvent(ctx, &responseEvent, state, events)
+		} else {
+			keepReading = session.provider.emitResponsesEvent(ctx, string(data), state, events)
+		}
+		if keepReading {
+			continue
+		}
+		if responseEvent.Type == responsesEventCompleted && responseEvent.Response != nil &&
+			responseEvent.Response.Error == nil && responseEvent.Response.Status != "failed" && state.responseID != "" {
+			session.mu.Lock()
+			if session.connection == connection && !session.webSocketOff {
+				requestCopy := *fullRequest
+				requestCopy.Input = append([]inputItem(nil), fullRequest.Input...)
+				session.lastRequest = &requestCopy
+				session.lastResponseID = state.responseID
+				session.lastOutput = state.outputInputItems()
+			}
+			session.mu.Unlock()
+		}
+		return
+	}
+}
+
+func (session *codexTurnSession) resetResponseChain(connection *websocket.Conn) {
+	session.mu.Lock()
+	defer session.mu.Unlock()
+	if session.connection != connection {
+		return
+	}
+	session.lastRequest = nil
+	session.lastResponseID = ""
+	session.lastOutput = nil
+}
+
+func (session *codexTurnSession) forwardHTTP(ctx context.Context, request zeroruntime.CompletionRequest, events chan<- zeroruntime.StreamEvent) {
+	trace.FromContext(ctx).Counter(trace.CounterResponsesHTTPFallback, 1)
+	stream, err := session.provider.StreamCompletion(ctx, request)
+	if err != nil {
+		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
+			Type:  zeroruntime.StreamEventError,
+			Error: session.provider.redact(err.Error()),
+		})
+		return
+	}
+	for event := range stream {
+		providerio.SendEvent(ctx, events, event)
+	}
+}
+
+func (session *codexTurnSession) disableWebSocket(connection *websocket.Conn) {
+	session.mu.Lock()
+	if session.connection == connection {
+		session.connection = nil
+		session.webSocketOff = true
+		session.lastRequest = nil
+		session.lastResponseID = ""
+		session.lastOutput = nil
+	}
+	session.mu.Unlock()
+	_ = connection.CloseNow()
+}
+
+func (provider *CodexProvider) dialResponsesWebSocket(ctx context.Context) (*websocket.Conn, error) {
+	endpoint, err := responsesWebSocketURL(provider.inner.endpoint)
+	if err != nil {
+		return nil, err
+	}
+	for authTry := 0; authTry < 2; authTry++ {
+		headers, err := provider.responsesWebSocketHeaders(ctx, authTry == 1)
+		if err != nil {
+			return nil, err
+		}
+		connection, response, err := websocket.Dial(ctx, endpoint, &websocket.DialOptions{
+			HTTPClient:      provider.inner.httpClient,
+			HTTPHeader:      headers,
+			CompressionMode: websocket.CompressionNoContextTakeover,
+		})
+		if err == nil {
+			connection.SetReadLimit(responsesWebSocketReadLimit)
+			return connection, nil
+		}
+		if response == nil || response.StatusCode != http.StatusUnauthorized || provider.inner.oauthResolver == nil || authTry == 1 {
+			return nil, err
+		}
+	}
+	return nil, errors.New("codex websocket authentication failed")
+}
+
+func (provider *CodexProvider) responsesWebSocketHeaders(ctx context.Context, forceRefresh bool) (http.Header, error) {
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, provider.inner.endpoint, nil)
+	if err != nil {
+		return nil, err
+	}
+	base := providerio.AuthHeaders{
+		APIKey:            provider.inner.apiKey,
+		DefaultAuthHeader: "Authorization",
+		DefaultAuthScheme: "Bearer",
+		AuthHeader:        provider.inner.authHeader,
+		AuthScheme:        provider.inner.authScheme,
+		AuthHeaderValue:   provider.inner.authHeaderValue,
+		CustomHeaders:     provider.inner.customHeaders,
+	}
+	if resolver := provider.inner.oauthResolver; resolver != nil {
+		header, value, ok, err := resolver(ctx, forceRefresh)
+		if err != nil {
+			return nil, err
+		}
+		if ok {
+			providerio.ApplyAuthHeaders(request, providerio.AuthHeaders{CustomHeaders: provider.inner.customHeaders})
+			if strings.TrimSpace(header) == "" {
+				header = "Authorization"
+			}
+			request.Header.Set(header, value)
+		} else {
+			providerio.ApplyAuthHeaders(request, base)
+		}
+	} else {
+		providerio.ApplyAuthHeaders(request, base)
+	}
+	provider.injectCodexHeaders(request)
+	request.Header.Set(responsesWebSocketBetaHeader, responsesWebSocketBetaValue)
+	return request.Header.Clone(), nil
+}
+
+func responsesWebSocketURL(endpoint string) (string, error) {
+	parsed, err := url.Parse(strings.TrimSpace(endpoint))
+	if err != nil {
+		return "", err
+	}
+	switch parsed.Scheme {
+	case "http":
+		parsed.Scheme = "ws"
+	case "https":
+		parsed.Scheme = "wss"
+	default:
+		return "", fmt.Errorf("unsupported Responses websocket URL scheme %q", parsed.Scheme)
+	}
+	return parsed.String(), nil
+}
@@ -0,0 +1,590 @@
+package openai
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/coder/websocket"
+
+	"github.com/Gitlawb/zero/internal/trace"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func TestCodexTurnSessionChainsOnlyAppendOnlyRequests(t *testing.T) {
+	var mu sync.Mutex
+	requests := []map[string]any{}
+	betaHeader := ""
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if !strings.EqualFold(request.Header.Get("Upgrade"), "websocket") {
+			http.Error(writer, "websocket required", http.StatusUpgradeRequired)
+			return
+		}
+		mu.Lock()
+		betaHeader = request.Header.Get(responsesWebSocketBetaHeader)
+		mu.Unlock()
+		connection, err := websocket.Accept(writer, request, nil)
+		if err != nil {
+			return
+		}
+		defer connection.CloseNow()
+		for index := 0; index < 3; index++ {
+			_, body, err := connection.Read(request.Context())
+			if err != nil {
+				return
+			}
+			var payload map[string]any
+			if err := json.Unmarshal(body, &payload); err != nil {
+				return
+			}
+			mu.Lock()
+			requests = append(requests, payload)
+			mu.Unlock()
+			switch index {
+			case 0:
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.created","response":{"id":"resp-1","status":"in_progress"}}`,
+					`{"type":"response.output_item.added","item_id":"call-1","item":{"type":"function_call","id":"call-1","call_id":"call-1","name":"read_file"}}`,
+					`{"type":"response.function_call_arguments.delta","item_id":"call-1","delta":"{}"}`,
+					`{"type":"response.output_item.done","item_id":"call-1","item":{"type":"function_call","id":"call-1","call_id":"call-1","name":"read_file","arguments":"{}"}}`,
+					`{"type":"response.completed","response":{"id":"resp-1","status":"completed"}}`,
+				)
+			case 1:
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.output_text.delta","delta":"done"}`,
+					`{"type":"response.completed","response":{"id":"resp-2","status":"completed"}}`,
+				)
+			case 2:
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.completed","response":{"id":"resp-3","status":"completed"}}`,
+				)
+			}
+		}
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	// A disabled stream watchdog must use the parent context rather than creating
+	// an immediately-expired read deadline.
+	provider.inner.streamIdleTimeout = 0
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	recorder := trace.NewRecorder("session-1", "run-1", "test")
+	recorder.Start()
+	streamContext := trace.WithContext(t.Context(), recorder)
+
+	base := zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{
+			{Role: zeroruntime.MessageRoleSystem, Content: "Use tools carefully."},
+			{Role: zeroruntime.MessageRoleUser, Content: "Read the file."},
+		},
+		Tools:          []zeroruntime.ToolDefinition{{Name: "read_file", Parameters: map[string]any{"type": "object"}}},
+		PromptCacheKey: "session-1",
+	}
+	first := collectCodexSessionEvents(t, session, base)
+	if !hasToolCallEnd(first, "call-1") {
+		t.Fatalf("first stream did not produce the tool call: %#v", first)
+	}
+
+	second := base
+	second.Messages = append(append([]zeroruntime.Message(nil), base.Messages...),
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{ID: "call-1", Name: "read_file", Arguments: "{}"}}},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleTool, ToolCallID: "call-1", Content: "contents"},
+	)
+	secondEvents := collectCodexSessionEventsContext(t, streamContext, session, second)
+	if got := joinedText(secondEvents); got != "done" {
+		t.Fatalf("second stream text = %q, want done", got)
+	}
+
+	third := second
+	third.ReasoningEffort = "high"
+	third.Messages = append(append([]zeroruntime.Message(nil), second.Messages...),
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "done"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "Continue."},
+	)
+	collectCodexSessionEventsContext(t, streamContext, session, third)
+	finishedTrace := recorder.Finish()
+	if got := finishedTrace.Counter(trace.CounterResponseChainReused); got != 1 {
+		t.Fatalf("response-chain reuse count = %d, want 1", got)
+	}
+	if got := finishedTrace.Counter(trace.CounterResponseChainReset); got != 1 {
+		t.Fatalf("response-chain reset count = %d, want 1", got)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if len(requests) != 3 {
+		t.Fatalf("websocket requests = %d, want 3", len(requests))
+	}
+	if betaHeader != responsesWebSocketBetaValue {
+		t.Fatalf("OpenAI-Beta = %q, want %q", betaHeader, responsesWebSocketBetaValue)
+	}
+	if requests[0]["type"] != responsesWebSocketRequest || requests[0]["previous_response_id"] != nil {
+		t.Fatalf("first request chaining fields = %#v", requests[0])
+	}
+	if requests[0]["parallel_tool_calls"] != true || requests[0]["prompt_cache_key"] != "session-1" {
+		t.Fatalf("first request stable fields = %#v", requests[0])
+	}
+	if requests[1]["previous_response_id"] != "resp-1" {
+		t.Fatalf("second previous_response_id = %#v", requests[1]["previous_response_id"])
+	}
+	secondInput, _ := requests[1]["input"].([]any)
+	if len(secondInput) != 1 || secondInput[0].(map[string]any)["type"] != "function_call_output" {
+		t.Fatalf("second incremental input = %#v", requests[1]["input"])
+	}
+	if requests[2]["previous_response_id"] != nil {
+		t.Fatalf("incompatible request reused response chain: %#v", requests[2])
+	}
+	thirdInput, _ := requests[2]["input"].([]any)
+	if len(thirdInput) <= 1 {
+		t.Fatalf("incompatible request did not send full input: %#v", thirdInput)
+	}
+}
+
+func TestCodexTurnSessionFallsBackWhenPreviousResponseIsMissing(t *testing.T) {
+	var mu sync.Mutex
+	webSocketRequests := 0
+	httpRequests := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if strings.EqualFold(request.Header.Get("Upgrade"), "websocket") {
+			connection, err := websocket.Accept(writer, request, nil)
+			if err != nil {
+				return
+			}
+			defer connection.CloseNow()
+			for index := 0; index < 2; index++ {
+				if _, _, err := connection.Read(request.Context()); err != nil {
+					return
+				}
+				mu.Lock()
+				webSocketRequests++
+				mu.Unlock()
+				if index == 0 {
+					writeWebSocketEvents(request.Context(), connection,
+						`{"type":"response.output_item.added","item_id":"call-1","item":{"type":"function_call","id":"call-1","call_id":"call-1","name":"read_file"}}`,
+						`{"type":"response.output_item.done","item_id":"call-1","item":{"type":"function_call","id":"call-1","call_id":"call-1","name":"read_file","arguments":"{}"}}`,
+						`{"type":"response.completed","response":{"id":"resp-1","status":"completed"}}`,
+					)
+					continue
+				}
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.error","code":"previous_response_not_found","message":"missing"}`,
+				)
+			}
+			return
+		}
+
+		mu.Lock()
+		httpRequests++
+		mu.Unlock()
+		writer.Header().Set("Content-Type", "text/event-stream")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.output_text.delta\",\"delta\":\"fallback\"}\n\n")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp-http\",\"status\":\"completed\"}}\n\n")
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	base := zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Read it."}},
+		Tools:    []zeroruntime.ToolDefinition{{Name: "read_file", Parameters: map[string]any{"type": "object"}}},
+	}
+	collectCodexSessionEvents(t, session, base)
+	second := base
+	second.Messages = append(append([]zeroruntime.Message(nil), base.Messages...),
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{ID: "call-1", Name: "read_file", Arguments: "{}"}}},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleTool, ToolCallID: "call-1", Content: "contents"},
+	)
+	events := collectCodexSessionEvents(t, session, second)
+	if got := joinedText(events); got != "fallback" {
+		t.Fatalf("fallback stream text = %q, want fallback; events=%#v", got, events)
+	}
+	for _, event := range events {
+		if event.Type == zeroruntime.StreamEventError {
+			t.Fatalf("response-chain recovery leaked an error: %#v", event)
+		}
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if webSocketRequests != 2 || httpRequests != 1 {
+		t.Fatalf("requests = websocket:%d http:%d, want 2/1", webSocketRequests, httpRequests)
+	}
+}
+
+func TestCodexTurnSessionFallsBackWhenSocketClosesBeforeOutput(t *testing.T) {
+	var mu sync.Mutex
+	httpRequests := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if strings.EqualFold(request.Header.Get("Upgrade"), "websocket") {
+			connection, err := websocket.Accept(writer, request, nil)
+			if err != nil {
+				return
+			}
+			if _, _, err := connection.Read(request.Context()); err == nil {
+				_ = connection.CloseNow()
+			}
+			return
+		}
+		mu.Lock()
+		httpRequests++
+		mu.Unlock()
+		writer.Header().Set("Content-Type", "text/event-stream")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.output_text.delta\",\"delta\":\"recovered\"}\n\n")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp-http\",\"status\":\"completed\"}}\n\n")
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	recorder := trace.NewRecorder("session-fallback", "run-fallback", "test")
+	recorder.Start()
+	events := collectCodexSessionEventsContext(t, trace.WithContext(t.Context(), recorder), session, zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Hello"}},
+	})
+	if got := joinedText(events); got != "recovered" {
+		t.Fatalf("fallback text = %q, want recovered", got)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if httpRequests != 1 {
+		t.Fatalf("HTTP fallback requests = %d, want 1", httpRequests)
+	}
+	if got := recorder.Finish().Counter(trace.CounterResponsesHTTPFallback); got != 1 {
+		t.Fatalf("responses HTTP fallback counter = %d, want 1", got)
+	}
+}
+
+func TestCodexTurnSessionKeepsWebSocketAfterIncompleteResponse(t *testing.T) {
+	var mu sync.Mutex
+	webSocketRequests := 0
+	httpRequests := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if strings.EqualFold(request.Header.Get("Upgrade"), "websocket") {
+			connection, err := websocket.Accept(writer, request, nil)
+			if err != nil {
+				return
+			}
+			defer connection.CloseNow()
+			for index := 0; index < 2; index++ {
+				if _, _, err := connection.Read(request.Context()); err != nil {
+					return
+				}
+				mu.Lock()
+				webSocketRequests++
+				mu.Unlock()
+				if index == 0 {
+					writeWebSocketEvents(request.Context(), connection,
+						`{"type":"response.incomplete","response":{"id":"resp-1","status":"incomplete"}}`,
+					)
+					continue
+				}
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.output_text.delta","delta":"websocket"}`,
+					`{"type":"response.completed","response":{"id":"resp-2","status":"completed"}}`,
+				)
+			}
+			return
+		}
+
+		mu.Lock()
+		httpRequests++
+		mu.Unlock()
+		writer.Header().Set("Content-Type", "text/event-stream")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.output_text.delta\",\"delta\":\"fallback\"}\n\n")
+		_, _ = fmt.Fprint(writer, "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp-http\",\"status\":\"completed\"}}\n\n")
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	request := zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Continue."}},
+	}
+	first := collectCodexSessionEvents(t, session, request)
+	if len(first) != 1 || first[0].Type != zeroruntime.StreamEventDone || first[0].FinishReason != zeroruntime.FinishReasonLength {
+		t.Fatalf("incomplete response events = %#v, want length completion", first)
+	}
+	second := collectCodexSessionEvents(t, session, request)
+	if got := joinedText(second); got != "websocket" {
+		t.Fatalf("second turn text = %q, want websocket; events=%#v", got, second)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if webSocketRequests != 2 || httpRequests != 0 {
+		t.Fatalf("requests = websocket:%d http:%d, want 2/0", webSocketRequests, httpRequests)
+	}
+}
+
+func TestCodexTurnSessionDoesNotReplayAfterVisibleOutput(t *testing.T) {
+	var mu sync.Mutex
+	httpRequests := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if strings.EqualFold(request.Header.Get("Upgrade"), "websocket") {
+			connection, err := websocket.Accept(writer, request, nil)
+			if err != nil {
+				return
+			}
+			if _, _, err := connection.Read(request.Context()); err == nil {
+				writeWebSocketEvents(request.Context(), connection,
+					`{"type":"response.output_text.delta","delta":"visible"}`,
+				)
+			}
+			_ = connection.Close(websocket.StatusInternalError, "interrupted")
+			return
+		}
+		mu.Lock()
+		httpRequests++
+		mu.Unlock()
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	stream, err := session.Stream(t.Context(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Hello"}},
+	})
+	if err != nil {
+		t.Fatalf("Stream: %v", err)
+	}
+	sawText, sawError := false, false
+	for event := range stream {
+		sawText = sawText || event.Type == zeroruntime.StreamEventText
+		sawError = sawError || event.Type == zeroruntime.StreamEventError
+	}
+	if !sawText || !sawError {
+		t.Fatalf("visible interrupted stream = text:%v error:%v", sawText, sawError)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if httpRequests != 0 {
+		t.Fatalf("visible interrupted stream was replayed over HTTP %d time(s)", httpRequests)
+	}
+}
+
+func TestCodexTurnSessionReportsWebSocketIdleTimeout(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		connection, err := websocket.Accept(writer, request, nil)
+		if err != nil {
+			return
+		}
+		defer connection.CloseNow()
+		if _, _, err := connection.Read(request.Context()); err != nil {
+			return
+		}
+		writeWebSocketEvents(request.Context(), connection,
+			`{"type":"response.output_text.delta","delta":"visible"}`,
+		)
+		<-request.Context().Done()
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	provider.inner.streamIdleTimeout = 200 * time.Millisecond
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	stream, err := session.Stream(t.Context(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Hello"}},
+	})
+	if err != nil {
+		t.Fatalf("Stream: %v", err)
+	}
+
+	var streamError string
+	for event := range stream {
+		if event.Type == zeroruntime.StreamEventError {
+			streamError = event.Error
+			break
+		}
+	}
+	if !strings.Contains(streamError, "idle timeout after 200ms") {
+		t.Fatalf("stream error = %q, want idle-timeout detail", streamError)
+	}
+}
+
+func TestCodexTurnSessionRejectsOverlappingStreams(t *testing.T) {
+	started := make(chan struct{})
+	release := make(chan struct{})
+	var releaseOnce sync.Once
+	releaseStream := func() { releaseOnce.Do(func() { close(release) }) }
+	t.Cleanup(releaseStream)
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		connection, err := websocket.Accept(writer, request, nil)
+		if err != nil {
+			return
+		}
+		defer connection.CloseNow()
+		if _, _, err := connection.Read(request.Context()); err != nil {
+			return
+		}
+		close(started)
+		<-release
+		writeWebSocketEvents(request.Context(), connection,
+			`{"type":"response.completed","response":{"id":"resp-1","status":"completed"}}`,
+		)
+	}))
+	defer server.Close()
+
+	provider := newCodexSessionTestProvider(t, server)
+	session := openCodexSession(t, provider)
+	defer session.Close()
+	request := zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Hello"}},
+	}
+	first, err := session.Stream(t.Context(), request)
+	if err != nil {
+		t.Fatalf("first Stream: %v", err)
+	}
+	select {
+	case <-started:
+	case <-time.After(time.Second):
+		t.Fatal("first WebSocket stream did not start")
+	}
+	if _, err := session.Stream(t.Context(), request); !errors.Is(err, errCodexTurnSessionBusy) {
+		t.Fatalf("overlapping Stream error = %v, want %v", err, errCodexTurnSessionBusy)
+	}
+	releaseStream()
+	for range first {
+	}
+}
+
+func TestCodexTurnSessionHTTPFallbackRedactsSetupError(t *testing.T) {
+	const secret = "sk-secret-fallback"
+	provider, err := NewCodexProvider(CodexOptions{Options: Options{
+		APIKey:  secret,
+		BaseURL: "https://chatgpt.example/backend-api/codex",
+		Model:   "gpt-test",
+	}})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	session := &codexTurnSession{provider: provider}
+	events := make(chan zeroruntime.StreamEvent, 1)
+	session.forwardHTTP(t.Context(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRole(secret), Content: "invalid"}},
+	}, events)
+
+	select {
+	case event := <-events:
+		if event.Type != zeroruntime.StreamEventError {
+			t.Fatalf("fallback event type = %s, want error", event.Type)
+		}
+		if strings.Contains(event.Error, secret) {
+			t.Fatalf("fallback error leaked credential: %q", event.Error)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("fallback did not emit setup error")
+	}
+}
+
+func TestCodexTurnSessionCloseDoesNotStartPrewarm(t *testing.T) {
+	provider, err := NewCodexProvider(CodexOptions{Options: Options{
+		APIKey:  "test-token",
+		BaseURL: "https://chatgpt.example/backend-api/codex",
+		Model:   "gpt-test",
+	}})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	session, err := NewCodexTurnSessionProvider(provider, zeroruntime.ProviderCapabilities{}).OpenTurnSession(t.Context())
+	if err != nil {
+		t.Fatalf("OpenTurnSession: %v", err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- session.Close() }()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Close() error = %v", err)
+		}
+	case <-time.After(200 * time.Millisecond):
+		t.Fatal("Close blocked without a prewarm attempt")
+	}
+}
+
+func newCodexSessionTestProvider(t *testing.T, server *httptest.Server) *CodexProvider {
+	t.Helper()
+	provider, err := NewCodexProvider(CodexOptions{
+		Options: Options{
+			APIKey:     "test-token",
+			BaseURL:    server.URL,
+			Model:      "gpt-test",
+			HTTPClient: server.Client(),
+		},
+		AccountID: "account-test",
+	})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	return provider
+}
+
+func openCodexSession(t *testing.T, provider *CodexProvider) zeroruntime.TurnSession {
+	t.Helper()
+	session, err := NewCodexTurnSessionProvider(provider, zeroruntime.ProviderCapabilities{}).OpenTurnSession(t.Context())
+	if err != nil {
+		t.Fatalf("OpenTurnSession: %v", err)
+	}
+	if err := session.Prewarm(t.Context()); err != nil {
+		t.Fatalf("Prewarm: %v", err)
+	}
+	return session
+}
+
+func collectCodexSessionEvents(t *testing.T, session zeroruntime.TurnSession, request zeroruntime.CompletionRequest) []zeroruntime.StreamEvent {
+	t.Helper()
+	return collectCodexSessionEventsContext(t, t.Context(), session, request)
+}
+
+func collectCodexSessionEventsContext(t *testing.T, ctx context.Context, session zeroruntime.TurnSession, request zeroruntime.CompletionRequest) []zeroruntime.StreamEvent {
+	t.Helper()
+	stream, err := session.Stream(ctx, request)
+	if err != nil {
+		t.Fatalf("Stream: %v", err)
+	}
+	events := []zeroruntime.StreamEvent{}
+	for event := range stream {
+		events = append(events, event)
+		if event.Type == zeroruntime.StreamEventError {
+			t.Fatalf("stream error: %s", event.Error)
+		}
+	}
+	return events
+}
+
+func writeWebSocketEvents(ctx context.Context, connection *websocket.Conn, events ...string) {
+	for _, event := range events {
+		if err := connection.Write(ctx, websocket.MessageText, []byte(event)); err != nil {
+			return
+		}
+	}
+}
+
+func hasToolCallEnd(events []zeroruntime.StreamEvent, id string) bool {
+	for _, event := range events {
+		if event.Type == zeroruntime.StreamEventToolCallEnd && event.ToolCallID == id {
+			return true
+		}
+	}
+	return false
+}
+
+func joinedText(events []zeroruntime.StreamEvent) string {
+	var builder strings.Builder
+	for _, event := range events {
+		if event.Type == zeroruntime.StreamEventText {
+			builder.WriteString(event.Content)
+		}
+	}
+	return builder.String()
+}
@@ -2,6 +2,8 @@ package openai

 import (
 	"context"
+	"reflect"
+	"strings"
 	"testing"

 	"github.com/Gitlawb/zero/internal/zeroruntime"
@@ -25,6 +27,126 @@ func TestToolCallKeyOutputIndexZero(t *testing.T) {
 	}
 }

+func TestResponsesStatePreservesDistinctCallID(t *testing.T) {
+	provider := &CodexProvider{}
+	state := newResponsesState()
+	events := make(chan zeroruntime.StreamEvent, 4)
+	provider.handleOutputItemAdded(context.Background(), &responsesEvent{
+		ItemID: "item-1",
+		Item: &itemPayload{
+			Type:   "function_call",
+			ID:     "item-1",
+			CallID: "call-1",
+			Name:   "read_file",
+		},
+	}, state, events)
+	items := state.outputInputItems()
+	if len(items) != 1 || items[0].ID != "item-1" || items[0].CallID != "call-1" {
+		t.Fatalf("captured function call = %#v, want item id item-1 and call id call-1", items)
+	}
+}
+
+func TestCodexCustomApplyPatchStreamProducesFreeformCall(t *testing.T) {
+	provider := &CodexProvider{}
+	state := newResponsesState()
+	events := make(chan zeroruntime.StreamEvent, 16)
+	patch := "*** Begin Patch\n*** Add File: hello.txt\n+hello\n*** End Patch\n"
+	for _, payload := range []string{
+		`{"type":"response.output_item.added","item_id":"item-1","item":{"type":"custom_tool_call","call_id":"call-1","name":"apply_patch"}}`,
+		`{"type":"response.custom_tool_call_input.delta","item_id":"item-1","call_id":"call-1","delta":"*** Begin Patch\n*** Add File: hello.txt\n"}`,
+		`{"type":"response.custom_tool_call_input.delta","item_id":"item-1","call_id":"call-1","delta":"+hello\n*** End Patch\n"}`,
+		`{"type":"response.output_item.done","item_id":"item-1","item":{"type":"custom_tool_call","call_id":"call-1","name":"apply_patch","input":"*** Begin Patch\n*** Add File: hello.txt\n+hello\n*** End Patch\n"}}`,
+		`{"type":"response.completed","response":{"id":"resp-1","status":"completed"}}`,
+	} {
+		if keepReading := provider.emitResponsesEvent(context.Background(), payload, state, events); !keepReading && !state.done {
+			t.Fatalf("stream stopped before terminal event for %s", payload)
+		}
+	}
+	close(events)
+	collected := zeroruntime.CollectStream(context.Background(), events)
+	if len(collected.ToolCalls) != 1 {
+		t.Fatalf("tool calls = %#v, want one", collected.ToolCalls)
+	}
+	call := collected.ToolCalls[0]
+	if call.ID != "item-1" || call.ProviderCallID != "call-1" || call.Name != "apply_patch" || !call.Freeform || call.Arguments != patch {
+		t.Fatalf("custom apply_patch call = %#v", call)
+	}
+}
+
+func TestCodexApplyPatchUsesFreeformWireContract(t *testing.T) {
+	provider, err := NewCodexProvider(CodexOptions{Options: Options{
+		APIKey:  "test-token",
+		BaseURL: "https://chatgpt.example/backend-api/codex",
+		Model:   "gpt-test",
+	}})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	patch := "*** Begin Patch\n*** Add File: hello.txt\n+hello\n*** End Patch\n"
+	request, err := provider.buildResponsesRequest(zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{
+			{Role: zeroruntime.MessageRoleUser, Content: "Add the file."},
+			{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{
+				ID: "item-1", ProviderCallID: "call-1", Name: "apply_patch", Arguments: patch, Freeform: true,
+			}}},
+			{Role: zeroruntime.MessageRoleTool, ToolCallID: "item-1", ToolCallProviderID: "call-1", Content: "Done!"},
+		},
+		Tools: []zeroruntime.ToolDefinition{{
+			Name: "apply_patch", Description: "Apply a patch.", Type: zeroruntime.ToolDefinitionFreeform,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("buildResponsesRequest: %v", err)
+	}
+	if len(request.Tools) != 1 || request.Tools[0].Type != string(zeroruntime.ToolDefinitionFreeform) ||
+		request.Tools[0].Format == nil || request.Tools[0].Format.Syntax != "lark" || request.Tools[0].Parameters != nil {
+		t.Fatalf("apply_patch tool wire shape = %#v", request.Tools)
+	}
+	if !strings.Contains(request.Tools[0].Format.Definition, "*** Begin Patch") {
+		t.Fatalf("apply_patch grammar = %q", request.Tools[0].Format.Definition)
+	}
+	if !strings.Contains(request.Tools[0].Description, "absolute file paths") || !strings.Contains(request.Tools[0].Description, "granted extra write root") {
+		t.Fatalf("apply_patch description does not explain extra-root paths: %q", request.Tools[0].Description)
+	}
+	if len(request.Input) != 3 || request.Input[1].Type != "custom_tool_call" || request.Input[1].ID != "item-1" ||
+		request.Input[1].CallID != "call-1" || request.Input[1].Input != patch ||
+		request.Input[2].Type != "custom_tool_call_output" || request.Input[2].CallID != "call-1" {
+		t.Fatalf("custom apply_patch replay input = %#v", request.Input)
+	}
+}
+
+func TestCodexPreservesCustomApplyPatchFunction(t *testing.T) {
+	provider, err := NewCodexProvider(CodexOptions{Options: Options{
+		APIKey:  "test-token",
+		BaseURL: "https://chatgpt.example/backend-api/codex",
+		Model:   "gpt-test",
+	}})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	parameters := map[string]any{
+		"type":       "object",
+		"properties": map[string]any{"value": map[string]any{"type": "string"}},
+	}
+	request, err := provider.buildResponsesRequest(zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "Call the custom tool."}},
+		Tools: []zeroruntime.ToolDefinition{{
+			Name: "apply_patch", Description: "Custom integration tool.", Parameters: parameters,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("buildResponsesRequest: %v", err)
+	}
+	if len(request.Tools) != 1 {
+		t.Fatalf("tools = %#v, want one", request.Tools)
+	}
+	tool := request.Tools[0]
+	if tool.Type != string(zeroruntime.ToolDefinitionFunction) || tool.Format != nil ||
+		tool.Description != "Custom integration tool." || !reflect.DeepEqual(tool.Parameters, parameters) {
+		t.Fatalf("custom apply_patch function was rewritten: %#v", tool)
+	}
+}
+
 func TestHandleTerminalResponseNilPayload(t *testing.T) {
 	p := &CodexProvider{}

@@ -90,11 +212,14 @@ func TestHandleTerminalResponseFailedPayloadWithoutError(t *testing.T) {
 	// A response.completed with a payload and no error remains a clean done.
 	ok := make(chan zeroruntime.StreamEvent, 8)
 	p.handleTerminalResponse(context.Background(),
-		&responsesEvent{Type: responsesEventCompleted, Response: &responsePayload{Status: "completed"}}, &responsesState{}, ok)
+		&responsesEvent{Type: responsesEventCompleted, Response: &responsePayload{ID: "resp-1", Status: "completed"}}, &responsesState{}, ok)
 	close(ok)
 	for ev := range ok {
 		if ev.Type == zeroruntime.StreamEventError {
 			t.Error("response.completed with a non-error payload must NOT emit an error")
 		}
+		if ev.Type == zeroruntime.StreamEventDone && ev.ResponseID != "resp-1" {
+			t.Errorf("done response id = %q, want resp-1", ev.ResponseID)
+		}
 	}
 }
@@ -771,7 +771,7 @@ func TestCodexProviderParsesResponsesTextDeltas(t *testing.T) {
 		`{"type":"response.output_text.delta","delta":"hello "}`,
 		`{"type":"response.output_text.delta","delta":"world"}`,
 		`{"type":"response.output_text.delta","delta":"!"}`,
-		`{"type":"response.completed","response":{"id":"resp-1","status":"completed","usage":{"input_tokens":7,"output_tokens":3,"output_tokens_details":{"reasoning_tokens":1},"input_tokens_details":{"cached_tokens":2}}}}`,
+		`{"type":"response.completed","response":{"id":"resp-1","status":"completed","usage":{"input_tokens":7,"output_tokens":3,"output_tokens_details":{"reasoning_tokens":1},"input_tokens_details":{"cached_tokens":2,"cache_write_tokens":1}}}}`,
 	)
 	defer srv.Close()

@@ -809,8 +809,8 @@ func TestCodexProviderParsesResponsesTextDeltas(t *testing.T) {
 	if usage == nil {
 		t.Fatal("expected a usage event, got none")
 	}
-	if usage.InputTokens != 7 || usage.OutputTokens != 3 || usage.CachedInputTokens != 2 || usage.ReasoningTokens != 1 {
-		t.Fatalf("usage = %+v, want input=7 output=3 cached=2 reasoning=1", *usage)
+	if usage.InputTokens != 7 || usage.OutputTokens != 3 || usage.CachedInputTokens != 2 || usage.CacheWriteTokens != 1 || usage.ReasoningTokens != 1 {
+		t.Fatalf("usage = %+v, want input=7 output=3 cached=2 cache-write=1 reasoning=1", *usage)
 	}
 	if !gotDone {
 		t.Fatal("expected a done event, got none")
@@ -357,6 +357,7 @@ func (provider *Provider) emitChunk(
 				PromptTokens:      chunk.Usage.PromptTokens,
 				CompletionTokens:  chunk.Usage.CompletionTokens,
 				CachedInputTokens: chunk.Usage.PromptTokensDetails.CachedTokens,
+				CacheWriteTokens:  chunk.Usage.PromptTokensDetails.CacheWriteTokens,
 				ReasoningTokens:   chunk.Usage.CompletionTokensDetails.ReasoningTokens,
 			},
 		})
@@ -486,7 +487,7 @@ func (provider *Provider) openAIRequest(request zeroruntime.CompletionRequest) c
 				Function: toolFunction{
 					Name:        tool.Name,
 					Description: tool.Description,
-					Parameters:  tool.Parameters,
+					Parameters:  normalizeToolParameters(tool.Parameters),
 				},
 			})
 		}
@@ -494,6 +495,21 @@ func (provider *Provider) openAIRequest(request zeroruntime.CompletionRequest) c
 	return mapped
 }

+// normalizeToolParameters keeps schemas accepted by strict OpenAI-compatible
+// servers such as LM Studio. No-argument tools still need an object-valued
+// parameters.properties field instead of an omitted field.
+func normalizeToolParameters(parameters map[string]any) map[string]any {
+	normalized := make(map[string]any, len(parameters)+1)
+	for key, value := range parameters {
+		normalized[key] = value
+	}
+	properties, ok := normalized["properties"].(map[string]any)
+	if !ok || properties == nil {
+		normalized["properties"] = map[string]any{}
+	}
+	return normalized
+}
+
 // promptCacheKeyDisabled reports whether the ZERO_DISABLE_PROMPT_CACHE_KEY
 // kill switch is set to a truthy value. "0" and "false" (any case) are
 // no-ops, matching how ZERO_FORMAT_ON_WRITE parses boolean flags, so an
@@ -3,6 +3,7 @@ package openai
 import (
 	"context"
 	"encoding/json"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"reflect"
@@ -105,6 +106,72 @@ func TestStreamCompletionPostsChatCompletionRequest(t *testing.T) {
 	if tool["type"] != "function" {
 		t.Fatalf("unexpected tool wrapper: %#v", tool)
 	}
+	functionDefinition := tool["function"].(map[string]any)
+	parameters := functionDefinition["parameters"].(map[string]any)
+	properties, ok := parameters["properties"].(map[string]any)
+	if !ok || len(properties) != 0 {
+		t.Fatalf("parameters.properties = %#v, want empty object", parameters["properties"])
+	}
+}
+
+// TestStreamCompletionSerializesTypedNilPropertiesAsEmptyObject locks in the
+// normalizeToolParameters fix: a tool whose parameters carry a typed-nil
+// properties map must serialize "properties":{} on the wire, never
+// "properties":null, because strict OpenAI-compatible servers (LM Studio)
+// reject the null form.
+func TestStreamCompletionSerializesTypedNilPropertiesAsEmptyObject(t *testing.T) {
+	var gotBody map[string]any
+	var gotRaw []byte
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, err := io.ReadAll(r.Body)
+		if err != nil {
+			t.Fatalf("read request body: %v", err)
+		}
+		gotRaw = raw
+		if err := json.Unmarshal(raw, &gotBody); err != nil {
+			t.Fatalf("decode request body: %v", err)
+		}
+		writeSSE(w, `{"choices":[]}`)
+		writeSSE(w, `[DONE]`)
+	}))
+	defer server.Close()
+
+	provider, err := New(Options{
+		APIKey:  "sk-secret",
+		BaseURL: server.URL + "/",
+		Model:   "gpt-test",
+	})
+	if err != nil {
+		t.Fatalf("New returned error: %v", err)
+	}
+
+	stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hi"}},
+		Tools: []zeroruntime.ToolDefinition{{
+			Name:        "no_args",
+			Description: "Takes no arguments",
+			Parameters:  map[string]any{"type": "object", "properties": map[string]any(nil)},
+		}},
+	})
+	if err != nil {
+		t.Fatalf("StreamCompletion returned error: %v", err)
+	}
+	drain(stream)
+
+	if !strings.Contains(string(gotRaw), `"properties":{}`) {
+		t.Fatalf("request body must serialize properties as an empty object, got: %s", gotRaw)
+	}
+	if strings.Contains(string(gotRaw), `"properties":null`) {
+		t.Fatalf("request body must not serialize properties as null, got: %s", gotRaw)
+	}
+	tools := gotBody["tools"].([]any)
+	tool := tools[0].(map[string]any)
+	functionDefinition := tool["function"].(map[string]any)
+	parameters := functionDefinition["parameters"].(map[string]any)
+	properties, ok := parameters["properties"].(map[string]any)
+	if !ok || len(properties) != 0 {
+		t.Fatalf("parameters.properties = %#v, want empty object", parameters["properties"])
+	}
 }

 func TestNewRequiresModelButNotAPIKey(t *testing.T) {
@@ -193,14 +260,14 @@ func TestStreamCompletionAppliesCustomAuthAndHeaders(t *testing.T) {
 func TestStreamCompletionEmitsTextUsageAndDone(t *testing.T) {
 	provider := newTestProvider(t, func(w http.ResponseWriter, r *http.Request) {
 		writeSSE(w, `{"choices":[{"delta":{"content":"hello "}}]}`)
-		writeSSE(w, `{"choices":[{"delta":{"content":"zero"}}],"usage":{"prompt_tokens":12,"completion_tokens":5,"prompt_tokens_details":{"cached_tokens":3}}}`)
+		writeSSE(w, `{"choices":[{"delta":{"content":"zero"}}],"usage":{"prompt_tokens":12,"completion_tokens":5,"prompt_tokens_details":{"cached_tokens":3,"cache_write_tokens":2}}}`)
 		writeSSE(w, `[DONE]`)
 	})

 	events := collectProviderEvents(t, provider)
 	assertEvent(t, events[0], zeroruntime.StreamEventText, "hello ")
 	assertEvent(t, events[1], zeroruntime.StreamEventText, "zero")
-	if events[2].Type != zeroruntime.StreamEventUsage || events[2].Usage.PromptTokens != 12 || events[2].Usage.CompletionTokens != 5 || events[2].Usage.CachedInputTokens != 3 {
+	if events[2].Type != zeroruntime.StreamEventUsage || events[2].Usage.PromptTokens != 12 || events[2].Usage.CompletionTokens != 5 || events[2].Usage.CachedInputTokens != 3 || events[2].Usage.CacheWriteTokens != 2 {
 		t.Fatalf("unexpected usage event: %#v", events[2])
 	}
 	if events[3].Type != zeroruntime.StreamEventDone {
@@ -1479,3 +1546,66 @@ func TestOpenAIRequestPreservesCacheablePrefixAcrossTurns(t *testing.T) {
 		t.Fatalf("wire prompt cache key must remain stable: first=%#v second=%#v", first["prompt_cache_key"], second["prompt_cache_key"])
 	}
 }
+
+// TestStreamCompletionSerializesNonMapPropertiesAsEmptyObject locks in the
+// normalizeToolParameters type-assert branch: when a tool's parameters carry a
+// `properties` field whose value is a non-map (e.g., an empty slice), it must
+// be normalized to "properties":{} on the wire, never "properties":[] or
+// "properties":null.
+func TestStreamCompletionSerializesNonMapPropertiesAsEmptyObject(t *testing.T) {
+	var gotBody map[string]any
+	var gotRaw []byte
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, err := io.ReadAll(r.Body)
+		if err != nil {
+			t.Fatalf("read request body: %v", err)
+		}
+		gotRaw = raw
+		if err := json.Unmarshal(raw, &gotBody); err != nil {
+			t.Fatalf("decode request body: %v", err)
+		}
+		writeSSE(w, `{"choices":[]}`)
+		writeSSE(w, `[DONE]`)
+	}))
+	defer server.Close()
+
+	provider, err := New(Options{
+		APIKey:  "sk-secret",
+		BaseURL: server.URL + "/",
+		Model:   "gpt-test",
+	})
+	if err != nil {
+		t.Fatalf("New returned error: %v", err)
+	}
+
+	stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hi"}},
+		Tools: []zeroruntime.ToolDefinition{{
+			Name:        "no_args",
+			Description: "Takes no arguments",
+			Parameters:  map[string]any{"type": "object", "properties": []any{}},
+		}},
+	})
+	if err != nil {
+		t.Fatalf("StreamCompletion returned error: %v", err)
+	}
+	drain(stream)
+
+	if !strings.Contains(string(gotRaw), `"properties":{}`) {
+		t.Fatalf("request body must serialize properties as an empty object, got: %s", gotRaw)
+	}
+	if strings.Contains(string(gotRaw), `"properties":null`) {
+		t.Fatalf("request body must not serialize properties as null, got: %s", gotRaw)
+	}
+	if strings.Contains(string(gotRaw), `"properties":[]`) {
+		t.Fatalf("request body must not serialize properties as an empty array, got: %s", gotRaw)
+	}
+	tools := gotBody["tools"].([]any)
+	tool := tools[0].(map[string]any)
+	functionDefinition := tool["function"].(map[string]any)
+	parameters := functionDefinition["parameters"].(map[string]any)
+	properties, ok := parameters["properties"].(map[string]any)
+	if !ok || len(properties) != 0 {
+		t.Fatalf("parameters.properties = %#v, want empty object", parameters["properties"])
+	}
+}
@@ -195,7 +195,12 @@ func (s *turnSession) computeFingerprint(request zeroruntime.CompletionRequest)
 func wireToolsDigest(tools []zeroruntime.ToolDefinition) string {
 	rendered := make([]string, 0, len(tools))
 	for _, tool := range tools {
-		schema, err := json.Marshal(tool.Parameters)
+		wireShape := struct {
+			Type       zeroruntime.ToolDefinitionType    `json:"type,omitempty"`
+			Parameters map[string]any                    `json:"parameters,omitempty"`
+			Format     *zeroruntime.ToolDefinitionFormat `json:"format,omitempty"`
+		}{Type: tool.Type, Parameters: tool.Parameters, Format: tool.Format}
+		schema, err := json.Marshal(wireShape)
 		if err != nil {
 			rendered = append(rendered, tool.Name+"\n"+tool.Description+"\n__non_json:"+tool.Name)
 			continue
@@ -109,7 +109,8 @@ type usage struct {
 }

 type promptTokenDetails struct {
-	CachedTokens int `json:"cached_tokens"`
+	CachedTokens     int `json:"cached_tokens"`
+	CacheWriteTokens int `json:"cache_write_tokens"`
 }

 type completionTokenDetails struct {
@@ -15,9 +15,27 @@ import (
 // value (e.g. "1") to enable — the same boolean idiom as ZERO_FORMAT_ON_WRITE.
 const openaiTurnSessionEnv = "ZERO_OPENAI_TURN_SESSION"

+// ChatGPT Responses sessions are enabled by default for their native provider.
+// Setting this to 0/false/off restores the stateless HTTP/SSE transport.
+const chatGPTTurnSessionEnv = "ZERO_CHATGPT_TURN_SESSION"
+
 func openaiTurnSessionEnabled() bool {
 	value := strings.TrimSpace(os.Getenv(openaiTurnSessionEnv))
-	return value != "" && value != "0" && !strings.EqualFold(value, "false")
+	return value != "" && !explicitEnvFalse(value)
+}
+
+func chatGPTTurnSessionEnabled() bool {
+	value := strings.TrimSpace(os.Getenv(chatGPTTurnSessionEnv))
+	return value == "" || !explicitEnvFalse(value)
+}
+
+func explicitEnvFalse(value string) bool {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "0", "false", "off":
+		return true
+	default:
+		return false
+	}
 }

 // OptimizedTurnSessions returns the gated optimized TurnSessionProvider for an
@@ -25,20 +43,33 @@ func openaiTurnSessionEnabled() bool {
 // is ineligible. Callers leave agent Options.TurnSessionProvider nil on false,
 // so the loop's default wrap keeps today's behavior byte-identical.
 //
-// Eligibility is deliberately narrow: the resolved provider kind must be
-// official OpenAI (NOT openai-compatible gateways — the constructor merges the
-// two, so this branches on the resolved kind explicitly), not the ChatGPT
-// Codex catalog, and the provider value must be the concrete *openai.Provider
-// (a fake, a Codex provider, or nil falls back to the default path safely).
-// No base-URL check on top of the kind: prewarm and fingerprint telemetry are
-// harmless against any host, and kind==openai mirrors the existing
-// official-OpenAI precedent used for prompt_cache_key.
+// Eligibility is deliberately narrow: native ChatGPT Responses uses its
+// concrete Codex provider and defaults on with a kill switch; official OpenAI
+// chat-completions keeps its existing opt-in prewarm session. Compatible
+// gateways and foreign provider values always retain the default adapter.
 func OptimizedTurnSessions(profile config.ProviderProfile, provider zeroruntime.Provider, options Options) (zeroruntime.TurnSessionProvider, bool) {
-	if !openaiTurnSessionEnabled() {
+	resolved, err := resolveProfile(profile, options)
+	if err != nil {
 		return nil, false
 	}
-	resolved, err := resolveProfile(profile, options)
-	if err != nil || resolved.providerKind != config.ProviderKindOpenAI || isCodexCatalog(profile, resolved) {
+	if isCodexCatalog(profile, resolved) {
+		if !chatGPTTurnSessionEnabled() {
+			return nil, false
+		}
+		concrete, ok := provider.(*openai.CodexProvider)
+		if !ok {
+			return nil, false
+		}
+		caps, err := resolveCapabilities(profile, options)
+		if err != nil {
+			return nil, false
+		}
+		return openai.NewCodexTurnSessionProvider(concrete, caps), true
+	}
+	if resolved.providerKind != config.ProviderKindOpenAI {
+		return nil, false
+	}
+	if !openaiTurnSessionEnabled() {
 		return nil, false
 	}
 	concrete, ok := provider.(*openai.Provider)
@@ -5,6 +5,7 @@ import (
 	"testing"

 	"github.com/Gitlawb/zero/internal/config"
+	"github.com/Gitlawb/zero/internal/providers/openai"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )

@@ -45,7 +46,7 @@ func TestOptimizedTurnSessionsDefaultOff(t *testing.T) {
 func TestOptimizedTurnSessionsFalseyValues(t *testing.T) {
 	profile := openaiEligibleProfile()
 	provider := buildGateProvider(t, profile)
-	for _, value := range []string{"0", "false", "FALSE", "False", " ", ""} {
+	for _, value := range []string{"0", "false", "FALSE", "False", "off", "OFF", " ", ""} {
 		t.Setenv(openaiTurnSessionEnv, value)
 		if _, ok := OptimizedTurnSessions(profile, provider, Options{}); ok {
 			t.Fatalf("gate enabled for falsey value %q", value)
@@ -59,6 +60,21 @@ func TestOptimizedTurnSessionsFalseyValues(t *testing.T) {
 	}
 }

+func TestChatGPTTurnSessionGateValues(t *testing.T) {
+	for _, value := range []string{"0", "false", "FALSE", "off", "OFF"} {
+		t.Setenv(chatGPTTurnSessionEnv, value)
+		if chatGPTTurnSessionEnabled() {
+			t.Fatalf("ChatGPT gate enabled for falsey value %q", value)
+		}
+	}
+	for _, value := range []string{"", " ", "1", "true", "on"} {
+		t.Setenv(chatGPTTurnSessionEnv, value)
+		if !chatGPTTurnSessionEnabled() {
+			t.Fatalf("ChatGPT gate disabled for default/truthy value %q", value)
+		}
+	}
+}
+
 func TestOptimizedTurnSessionsOpenAIEligible(t *testing.T) {
 	t.Setenv(openaiTurnSessionEnv, "1")
 	profile := openaiEligibleProfile()
@@ -88,13 +104,64 @@ func TestOptimizedTurnSessionsRejectsCompatible(t *testing.T) {
 }

 func TestOptimizedTurnSessionsRejectsCodexCatalog(t *testing.T) {
-	t.Setenv(openaiTurnSessionEnv, "1")
+	t.Setenv(chatGPTTurnSessionEnv, "0")
+	profile := openaiEligibleProfile()
+	profile.Name = "chatgpt"
+	profile.CatalogID = "chatgpt"
+	if _, ok := OptimizedTurnSessions(profile, buildChatGPTGateProvider(t, profile), Options{}); ok {
+		t.Fatal("the ChatGPT Codex catalog must honor the turn-session kill switch")
+	}
+}
+
+func TestOptimizedTurnSessionsEnablesChatGPTResponsesByDefault(t *testing.T) {
+	t.Setenv(chatGPTTurnSessionEnv, "")
+	profile := openaiEligibleProfile()
+	profile.Name = "chatgpt"
+	profile.CatalogID = "chatgpt"
+	provider := buildChatGPTGateProvider(t, profile)
+
+	turnSessions, ok := OptimizedTurnSessions(profile, provider, Options{})
+	if !ok || turnSessions == nil {
+		t.Fatal("ChatGPT Responses provider did not receive its default turn session")
+	}
+	if got := turnSessions.Capabilities().Model; got != profile.Model {
+		t.Fatalf("Capabilities().Model = %q, want %q", got, profile.Model)
+	}
+}
+
+func TestOptimizedTurnSessionsRecognizesCompatibleLabeledChatGPTProfile(t *testing.T) {
+	t.Setenv(chatGPTTurnSessionEnv, "")
+	profile := openaiEligibleProfile()
+	profile.Name = "chatgpt"
+	profile.CatalogID = "chatgpt"
+	profile.ProviderKind = config.ProviderKindOpenAICompatible
+	if turnSessions, ok := OptimizedTurnSessions(profile, buildChatGPTGateProvider(t, profile), Options{}); !ok || turnSessions == nil {
+		t.Fatal("ChatGPT catalog profile must use its native session regardless of the stored compatibility label")
+	}
+}
+
+func buildChatGPTGateProvider(t *testing.T, profile config.ProviderProfile) *openai.CodexProvider {
+	t.Helper()
+	provider, err := openai.NewCodexProvider(openai.CodexOptions{
+		Options: openai.Options{
+			APIKey:  "test-token",
+			BaseURL: "https://chatgpt.example/backend-api/codex",
+			Model:   profile.Model,
+		},
+		AccountID: "account-test",
+	})
+	if err != nil {
+		t.Fatalf("NewCodexProvider: %v", err)
+	}
+	return provider
+}
+
+func TestOptimizedTurnSessionsRejectsNonCodexProviderForChatGPT(t *testing.T) {
+	t.Setenv(chatGPTTurnSessionEnv, "1")
 	profile := openaiEligibleProfile()
 	profile.CatalogID = "chatgpt"
-	// Build the provider from the base profile: the point under test is the
-	// catalog check, not Codex construction (which needs OAuth wiring).
 	if _, ok := OptimizedTurnSessions(profile, buildGateProvider(t, openaiEligibleProfile()), Options{}); ok {
-		t.Fatal("the ChatGPT Codex catalog must not get the optimized session")
+		t.Fatal("a ChatGPT catalog profile with a non-Codex provider must use the default session")
 	}
 }

@@ -0,0 +1,96 @@
+package sandbox
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestApplyPatchPathBlockOnlyRejectsRelativeTraversal(t *testing.T) {
+	root := t.TempDir()
+	inside := filepath.Join(root, "main.js")
+	structured := func(path string) string {
+		return strings.Join([]string{"*** Begin Patch", "*** Update File: " + path, "@@", "-a", "+b", "*** End Patch"}, "\n")
+	}
+	for name, patch := range map[string]string{
+		"absolute inside workspace": structured(inside),
+		"relative":                  structured("main.js"),
+		"decorated markers":         "*** Begin Patch ***\n*** Update File: main.js\n@@\n-a\n+b\n*** End Patch ***",
+		"no-space marker":           "***Begin Patch\n*** Update File: main.js\n@@\n-a\n+b\n***End Patch",
+	} {
+		request := Request{ToolName: "apply_patch", WorkspaceRoot: root, SideEffect: SideEffectWrite, Args: map[string]any{"patch": patch}}
+		if block := applyPatchPathBlock(request); block != nil {
+			t.Fatalf("%s: unexpected block %+v", name, block)
+		}
+	}
+	for _, path := range []string{"../escape.js", ".."} {
+		for name, patch := range map[string]string{"canonical": structured(path), "no-space": "***Begin Patch\n*** Update File: " + path + "\n@@\n-a\n+b\n***End Patch"} {
+			request := Request{ToolName: "apply_patch", WorkspaceRoot: root, SideEffect: SideEffectWrite, Args: map[string]any{"patch": patch}}
+			block := applyPatchPathBlock(request)
+			if block == nil || block.Code != BlockOutsideWorkspace {
+				t.Fatalf("%s %q must be blocked as traversal, got %+v", name, path, block)
+			}
+		}
+	}
+}
+
+// Every marker spelling the tool applies must be classified as structured at
+// the sandbox boundary too; otherwise the boundary scans the patch as a unified
+// diff, extracts no targets, and validates nothing (fail-open).
+func TestStructuredPatchClassifierMatchesToolSpellings(t *testing.T) {
+	for _, header := range []string{"*** Begin Patch", "*** Begin Patch ***", "***Begin Patch", "  *** Begin Patch  ", "\ufeff*** Begin Patch"} {
+		patch := header + "\n*** Update File: main.js\n@@\n-a\n+b\n*** End Patch"
+		if !IsStructuredPatch(patch) {
+			t.Fatalf("%q must classify as a structured patch", header)
+		}
+		if paths := applyPatchPaths(patch); len(paths) != 1 || paths[0] != "main.js" {
+			t.Fatalf("%q: sandbox must extract the structured target, got %v", header, paths)
+		}
+	}
+	for _, header := range []string{"--- a/x", "Begin Patch", "*** Begin Patchwork", "*** Update File: x"} {
+		if IsStructuredPatch(header + "\n-a\n+b") {
+			t.Fatalf("%q must not classify as a structured patch", header)
+		}
+	}
+	if StructuredPatchMarker("*** End Patch ***") != "end" || StructuredPatchMarker("***End Patch") != "end" {
+		t.Fatal("decorated end markers must classify as end")
+	}
+}
+
+func TestApplyPatchRequestPathsCarryAbsolutePathsToScopeValidation(t *testing.T) {
+	root := t.TempDir()
+	// NewScope also grants the system temp dir, so a sibling t.TempDir() is
+	// legitimately in scope; pick a path under the filesystem root instead.
+	outside, err := filepath.Abs(filepath.Join(string(filepath.Separator), "zero-outside-workspace-test", "escape.js"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	scope, err := NewScope(root, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	inside := filepath.Join(root, "main.js")
+	structured := func(header, footer, path string) string {
+		return strings.Join([]string{header, "*** Update File: " + path, "@@", "-a", "+b", footer}, "\n")
+	}
+	for name, spelling := range map[string][2]string{"canonical": {"*** Begin Patch", "*** End Patch"}, "no-space": {"***Begin Patch", "***End Patch"}} {
+		// Failure path: the exact path the boundary parsed must be denied by the
+		// scope. structuredPatchHeaderPaths normalises separators to "/", so the
+		// parsed form is compared in slash form and then validated as-is.
+		paths := applyPatchRequestPaths(map[string]any{"patch": structured(spelling[0], spelling[1], outside)})
+		if len(paths) != 1 || paths[0] != filepath.ToSlash(outside) {
+			t.Fatalf("%s: absolute patch path must reach scope validation unchanged, got %v", name, paths)
+		}
+		if block := scope.validate(paths[0]); block == nil || block.Code != BlockOutsideWorkspace {
+			t.Fatalf("%s: scope must deny the parsed outside path %q, got %+v", name, paths[0], block)
+		}
+		// Success path: the parsed inside path must be accepted by the scope.
+		paths = applyPatchRequestPaths(map[string]any{"patch": structured(spelling[0], spelling[1], inside)})
+		if len(paths) != 1 || paths[0] != filepath.ToSlash(inside) {
+			t.Fatalf("%s: inside patch path must reach scope validation unchanged, got %v", name, paths)
+		}
+		if block := scope.validate(paths[0]); block != nil {
+			t.Fatalf("%s: scope must accept the parsed inside path %q, got %+v", name, paths[0], block)
+		}
+	}
+}
@@ -148,8 +148,10 @@ func unsafeCommandPrefix(prefix []string) bool {
 			return true
 		}
 	}
+	normalized := append([]string(nil), prefix...)
+	normalized[0] = normalizeLauncherName(normalized[0])
 	for _, banned := range bannedCommandPrefixSuggestions {
-		if sameStringSlice(prefix, banned) {
+		if sameStringSlice(prefix, banned) || sameStringSlice(normalized, banned) {
 			return true
 		}
 	}
@@ -165,25 +167,118 @@ func unsafeCommandPrefixPart(part string) bool {
 }

 func unsafeCommandPrefixLauncher(program string) bool {
-	program = strings.ToLower(strings.TrimSpace(program))
-	if strings.ContainsAny(program, `/\`) {
+	// A path is already refused. ":" and "~" are refused for the same reason:
+	// on Windows they introduce names that resolve to a different file than the
+	// one matched here, and no list can keep up with them. "PYTHON~1.EXE" is
+	// python.exe under an 8.3 short name, and 8.3 truncates the stem, so
+	// "POWERS~1.EXE" cannot be recognized by name at all; "python.exe::$DATA"
+	// names the same executable through its default stream. Refusing the shape
+	// costs a permission prompt on names no real command uses.
+	if strings.ContainsAny(program, `/\:~`) {
 		return true
 	}
-	switch program {
-	case "bash", "sh", "zsh", "/bin/bash", "/bin/zsh",
-		"pwsh", "powershell", "powershell.exe",
-		"env", "sudo", "doas", "su", "run0", "osascript",
+	name := normalizeLauncherName(program)
+	return bannedLauncherName(name) || bannedLauncherName(strings.TrimRight(name, "0123456789"))
+}
+
+func bannedLauncherName(name string) bool {
+	switch name {
+	case "bash", "sh", "zsh", "dash", "ash", "ksh", "csh", "tcsh", "fish", "busybox",
+		"pwsh", "powershell", "cmd", "wsl",
+		"env", "sudo", "sudoedit", "doas", "su", "run0", "osascript",
 		"command", "eval", "exec", "time",
 		"find", "xargs", "timeout", "nice", "nohup", "watch", "setsid", "stdbuf", "ionice",
-		"ssh", "make", "npm", "npx",
-		"python", "python3", "py", "pythonw", "pyw", "pypy", "pypy3",
-		"node", "perl", "ruby", "php", "lua", "deno", "bun":
+		"ssh", "make", "npm", "npx", "pnpm", "yarn", "bunx",
+		"python", "py", "pythonw", "pyw", "pypy", "uv", "uvx",
+		"node", "nodejs", "perl", "ruby", "php", "lua", "deno", "bun":
 		return true
 	default:
 		return false
 	}
 }

+// normalizeLauncherName reduces a program name to the launcher it actually runs
+// so the list above cannot be stepped around by spelling the same interpreter
+// differently: "python3.11", "python.exe" and "PYTHON3" all reach it as a name
+// the list matches. internal/agent's commandName already normalizes case and
+// Windows executable extensions on the allow side; this side matched raw, so
+// every versioned or .exe-suffixed launcher validated as an ordinary command
+// and persisted as a prefix grant that auto-allows every later invocation.
+//
+// A name is only ever narrowed toward an existing entry, so the failure
+// direction is an extra permission prompt, never a silent grant.
+func normalizeLauncherName(program string) string {
+	name := strings.ToLower(strings.TrimSpace(program))
+	// Windows discards trailing dots and spaces when resolving a filename, so
+	// "python." starts python.exe. Drop them before anything matches on the
+	// result, on every platform: the deny side must not depend on which OS is
+	// reading the grant, since the grants file travels with a synced home
+	// directory.
+	name = strings.TrimRight(name, ". ")
+	for _, suffix := range []string{".exe", ".cmd", ".bat", ".com", ".ps1"} {
+		if strings.HasSuffix(name, suffix) {
+			name = strings.TrimSuffix(name, suffix)
+			name = strings.TrimRight(name, ". ")
+			break
+		}
+	}
+	return trimLauncherVersion(trimLauncherABISuffix(trimLauncherBuildSuffix(name)))
+}
+
+// trimLauncherBuildSuffix drops the build-channel suffixes distributions and
+// upstreams append to an otherwise unchanged interpreter, so "python3.11-dbg",
+// "bash-static" and "pwsh-preview" are the launchers they say they are. The set
+// is closed on purpose: a general "-word" strip would also swallow
+// "node-gyp", "python3-config" and "ruby-lsp", which are ordinary tools a user
+// should still be able to approve.
+func trimLauncherBuildSuffix(name string) string {
+	for _, suffix := range []string{"-dbg", "-debug", "-static", "-nightly", "-preview", "-beta"} {
+		if strings.HasSuffix(name, suffix) {
+			return strings.TrimSuffix(name, suffix)
+		}
+	}
+	return name
+}
+
+// trimLauncherABISuffix drops CPython's ABI flags from a versioned interpreter
+// name, so "python3.7m" and "python3.6dm" reduce to their version, and the
+// free-threaded builds "python3.13t" and "python3.13td" reduce to theirs. The
+// flags are only removed when a digit sits underneath them, which leaves
+// ordinary names that happen to end in those letters alone: "sha256sum" keeps
+// its "sum", "zstd" its "td", "cat" its "t".
+func trimLauncherABISuffix(name string) string {
+	trimmed := strings.TrimRight(name, "dmut")
+	if trimmed == name || trimmed == "" {
+		return name
+	}
+	if last := trimmed[len(trimmed)-1]; last < '0' || last > '9' {
+		return name
+	}
+	return trimmed
+}
+
+// trimLauncherVersion drops a trailing "<separator><digits>" version from a
+// program name, so "python3.11" becomes "python3" and "python2.7" becomes
+// "python2". Digits without a separator are part of the name, which keeps
+// "base64", "7z" and "sha256sum" intact; the caller handles the "python3" shape
+// by also testing the digit-stripped form.
+func trimLauncherVersion(name string) string {
+	for {
+		trimmed := strings.TrimRight(name, "0123456789")
+		if trimmed == name || trimmed == "" {
+			return name
+		}
+		if !strings.HasSuffix(trimmed, ".") && !strings.HasSuffix(trimmed, "-") {
+			return name
+		}
+		next := trimmed[:len(trimmed)-1]
+		if next == "" {
+			return name
+		}
+		name = next
+	}
+}
+
 func sameStringSlice(left []string, right []string) bool {
 	if len(left) != len(right) {
 		return false
@@ -0,0 +1,115 @@
+package sandbox
+
+import "testing"
+
+func TestUnsafeCommandPrefixLauncherIgnoresVersionAndExtension(t *testing.T) {
+	for _, program := range []string{
+		"python3", "python", "node", "git", "sh", "bash", "sudo",
+		"python3.11", "python3.12", "python2.7", "python3.13.1",
+		"python.exe", "python3.exe", "node.exe", "git.exe", "bash.exe",
+		"PYTHON3.11", "Node.EXE",
+		"cmd", "cmd.exe", "wsl", "wsl.exe",
+		// Windows resolves these to the same executable.
+		"python.", "python3.", "python3.11.", "python.exe.", "PYTHON.",
+		"python.cmd", "python.bat", "python.com", "python.ps1",
+		"PYTHON~1.EXE", "POWERS~1.EXE", "python.exe::$DATA",
+		// Versioned and ABI-suffixed interpreters.
+		"python3.7m", "python3.6dm", "pythonw3.11", "python-3.11",
+		// Free-threaded CPython (PEP 703) ships beside the GIL build.
+		"python3.13t", "python3.13t.exe", "python3.14t", "python3.13td",
+		// Distribution and build-channel spellings of the same interpreter.
+		"nodejs", "nodejs.exe", "node-nightly", "python3-dbg", "python3.11-dbg",
+		"python3.13t-dbg", "python3-debug", "python3.11-debug", "node-beta",
+		"pwsh-preview", "bash-static", "sudoedit",
+		// Twins of npm and npx, which the list already refuses.
+		"pnpm", "yarn", "bunx", "pnpm.cmd", "yarn.exe",
+		"perl5.36", "ruby3.2", "php8", "lua5.4", "node22.exe", "bash5",
+	} {
+		if !unsafeCommandPrefix([]string{program}) {
+			t.Errorf("unsafeCommandPrefix([%q]) = false, want true", program)
+		}
+	}
+}
+
+func TestUnsafeCommandPrefixKeepsOrdinaryCommandsGrantable(t *testing.T) {
+	for _, prefix := range [][]string{
+		{"cargo", "build"},
+		{"go", "test"},
+		{"ls", "-la"},
+		{"rg", "--json"},
+		{"7z", "l"},
+		{"base64", "-d"},
+		{"kubectl", "get", "pods"},
+		{"docker", "ps"},
+		{"sha256sum", "file"},
+		{"gcc-13", "-c"},
+		{"node-gyp", "build"},
+		{"python3-config", "--includes"},
+		{"s3cmd", "ls"},
+		{"cat", "file"},
+		{"zstd", "-d"},
+		{"sqlite3", "db"},
+		{"yt-dlp", "url"},
+		{"perl-doc", "-h"},
+		{"php-fpm", "-t"},
+		{"ruby-lsp", "--version"},
+		{"lua-language-server", "--check"},
+		{"nodemon", "app.js"},
+	} {
+		if unsafeCommandPrefix(prefix) {
+			t.Errorf("unsafeCommandPrefix(%q) = true, want false", prefix)
+		}
+	}
+}
+func TestNormalizeLauncherName(t *testing.T) {
+	for _, testCase := range []struct{ in, want string }{
+		{"python3.11", "python3"},
+		{"python2.7", "python2"},
+		{"pypy3", "pypy3"},
+		{"node.exe", "node"},
+		{"POWERSHELL.EXE", "powershell"},
+		{"7z", "7z"},
+		{"base64", "base64"},
+		{"sha256sum", "sha256sum"},
+		{"python.", "python"},
+		{"python3.11.exe.", "python3"},
+		{"python3.7m", "python3"},
+		{"python3.6dm", "python3"},
+		{"python3.13t", "python3"},
+		{"python3.13td", "python3"},
+		{"python3.11-dbg", "python3"},
+		{"node-nightly", "node"},
+		{"node-gyp", "node-gyp"},
+		{"python3-config", "python3-config"},
+		{"zstd", "zstd"},
+		{"cat", "cat"},
+		{"cargo", "cargo"},
+		{"", ""},
+	} {
+		if got := normalizeLauncherName(testCase.in); got != testCase.want {
+			t.Errorf("normalizeLauncherName(%q) = %q, want %q", testCase.in, got, testCase.want)
+		}
+	}
+}
+
+// Session-scoped grants are the agent's other entry point (loop.go grants them
+// for a single turn without touching the store), so they must refuse the same
+// launcher spellings the persisted path does.
+func TestGrantCommandPrefixForSessionRefusesLauncherVariants(t *testing.T) {
+	engine := &Engine{commandPrefixes: newCommandPrefixGrantSet()}
+	engine.GrantCommandPrefixForSession("bash", []string{"cargo", "build"})
+	if _, ok := engine.LookupCommandPrefixForSession("bash", []string{"cargo", "build", "--release"}); !ok {
+		t.Fatal("CONTROL BROKEN: an ordinary session prefix grant did not match")
+	}
+	for _, prefix := range [][]string{
+		{"python3.11", "-c"},
+		{"python.exe", "-c"},
+		{"cmd", "/c"},
+	} {
+		engine.GrantCommandPrefixForSession("bash", prefix)
+		command := append(append([]string(nil), prefix...), "whatever")
+		if _, ok := engine.LookupCommandPrefixForSession("bash", command); ok {
+			t.Errorf("session grant %q matched %q, want refused", prefix, command)
+		}
+	}
+}
@@ -242,6 +242,7 @@ func TestEngineAutoAllowsWorkspaceFileMutationTools(t *testing.T) {
 		{name: "write_file", args: map[string]any{"path": "notes.txt"}},
 		{name: "edit_file", args: map[string]any{"path": "notes.txt"}},
 		{name: "apply_patch", args: map[string]any{"patch": "diff --git a/notes.txt b/notes.txt\n"}},
+		{name: "apply_patch", args: map[string]any{"patch": "*** Begin Patch\n*** Add File: notes.txt\n+x\n*** End Patch\n"}},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			decision := engine.Evaluate(context.Background(), Request{
@@ -315,6 +316,27 @@ func TestEngineDeniesApplyPatchEscapesFromPatchBody(t *testing.T) {
 	}
 }

+func TestEngineDeniesStructuredApplyPatchEscapesFromPatchBody(t *testing.T) {
+	root := t.TempDir()
+	engine := NewEngine(EngineOptions{WorkspaceRoot: root, Policy: DefaultPolicy()})
+
+	for _, patch := range []string{
+		"*** Begin Patch\n*** Add File: ../escape.txt\n+x\n*** End Patch\n",
+		"*** Begin Patch\n*** Add File: ..\\escape.txt\n+x\n*** End Patch\n",
+	} {
+		decision := engine.Evaluate(context.Background(), Request{
+			ToolName:       "apply_patch",
+			SideEffect:     SideEffectWrite,
+			Permission:     PermissionPrompt,
+			PermissionMode: PermissionModeAsk,
+			Args:           map[string]any{"patch": patch},
+		})
+		if decision.Action != ActionDeny || decision.Block == nil || decision.Block.Code != BlockOutsideWorkspace {
+			t.Fatalf("escaping structured apply_patch decision = %#v, want outside-workspace deny", decision)
+		}
+	}
+}
+
 func TestEngineSessionGrantDoesNotMatchSiblingFile(t *testing.T) {
 	root := t.TempDir()
 	engine := NewEngine(EngineOptions{WorkspaceRoot: root, Policy: promptWorkspaceWritePolicy()})
@@ -2,12 +2,15 @@ package sandbox

 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/execution"
 )

 func TestGrantStorePersistsListsRevokesAndClears(t *testing.T) {
@@ -343,7 +346,8 @@ func TestGrantStoreMigratesExactV1GrantAndReportsOnce(t *testing.T) {
 	if err != nil {
 		t.Fatalf("read rewritten grant file: %v", err)
 	}
-	if !strings.Contains(string(raw), `"schemaVersion": 3`) || !strings.Contains(string(raw), `"policyVersion": 1`) || !strings.Contains(string(raw), `"write_file": [`) {
+	policyLine := fmt.Sprintf(`"policyVersion": %d`, execution.PolicyVersion)
+	if !strings.Contains(string(raw), `"schemaVersion": 3`) || !strings.Contains(string(raw), policyLine) || !strings.Contains(string(raw), `"write_file": [`) {
 		t.Fatalf("grant file was not rewritten as a versioned grant store:\n%s", raw)
 	}
 	backup, err := os.ReadFile(path + ".v1.backup")
@@ -406,6 +410,62 @@ func TestGrantStorePolicyChangePreservesDeniesAndInvalidatesApprovals(t *testing
 	}
 }

+// A prefix grant recorded before launcher-name normalization existed (a
+// versioned or .exe-suffixed interpreter) no longer validates. It must reach
+// the user through the policy migration — backup, denies preserved, one notice
+// — and never make the whole grants file unreadable, which would silently drop
+// their persisted deny grants too.
+func TestGrantStoreMigratesPreNormalizationPrefixInsteadOfRejectingTheFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "sandbox-grants.json")
+	original := `{"schemaVersion":3,"policyVersion":1,"grants":{"bash":[{"toolName":"bash","decision":"deny","approvedAt":"2026-06-05T14:30:00Z"}]},"commandPrefixes":{"bash":[{"toolName":"bash","prefix":["python3.11","-c"],"approvedAt":"2026-06-05T14:30:00Z"},{"toolName":"bash","prefix":["cargo","build"],"approvedAt":"2026-06-05T14:30:00Z"}]}}`
+	if err := writeText(path, original); err != nil {
+		t.Fatal(err)
+	}
+	store, err := NewGrantStore(StoreOptions{FilePath: path})
+	if err != nil {
+		t.Fatal(err)
+	}
+	grants, err := store.List()
+	if err != nil || len(grants) != 1 || grants[0].Decision != GrantDeny {
+		t.Fatalf("grants after migration = %#v err=%v, want the deny preserved", grants, err)
+	}
+	prefixes, err := store.ListCommandPrefixes()
+	if err != nil || len(prefixes) != 0 {
+		t.Fatalf("prefixes after migration = %#v err=%v, want all re-approved", prefixes, err)
+	}
+	if notice, err := store.ConsumeMigrationNotice(); err != nil || !strings.Contains(notice, "invalidated 2") {
+		t.Fatalf("notice = %q err=%v", notice, err)
+	}
+	if backup, err := os.ReadFile(path + ".policy-v1.backup"); err != nil || string(backup) != original {
+		t.Fatalf("backup = %q err=%v", backup, err)
+	}
+}
+
+// The legacy-schema path is a separate migration from the policy bump above and
+// prunes per grant rather than wholesale, so a pre-normalization prefix must be
+// dropped there while the valid prefix beside it survives.
+func TestGrantStoreLegacyMigrationDropsOnlyThePreNormalizationPrefix(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "sandbox-grants.json")
+	original := `{"schemaVersion":2,"grants":{},"commandPrefixes":{"bash":[{"toolName":"bash","prefix":["python3.11","-c"],"approvedAt":"2026-06-05T14:30:00Z"},{"toolName":"bash","prefix":["git","status"],"approvedAt":"2026-06-05T14:30:00Z"}]}}`
+	if err := writeText(path, original); err != nil {
+		t.Fatal(err)
+	}
+	store, err := NewGrantStore(StoreOptions{FilePath: path})
+	if err != nil {
+		t.Fatal(err)
+	}
+	prefixes, err := store.ListCommandPrefixes()
+	if err != nil {
+		t.Fatalf("ListCommandPrefixes after legacy migration returned error: %v", err)
+	}
+	if len(prefixes) != 1 || !sameStringSlice(prefixes[0].Prefix, []string{"git", "status"}) {
+		t.Fatalf("prefixes = %#v, want only [git status]", prefixes)
+	}
+	if notice, err := store.ConsumeMigrationNotice(); err != nil || !strings.Contains(notice, "migrated 1, invalidated 1") {
+		t.Fatalf("notice = %q err=%v", notice, err)
+	}
+}
+
 func TestGrantStorePersistsCommandPrefixes(t *testing.T) {
 	store, err := NewGrantStore(StoreOptions{
 		FilePath: filepath.Join(t.TempDir(), "sandbox-grants.json"),
@@ -481,6 +541,11 @@ func TestGrantStoreRejectsUnsafeCommandPrefixes(t *testing.T) {
 		{"python", "script.py"},
 		{"./script.sh"},
 		{"git"},
+		{"python3.11", "-c"},
+		{"python.exe", "-c"},
+		{"node.exe", "-e"},
+		{"git.exe"},
+		{"cmd", "/c"},
 	} {
 		if _, err := store.GrantCommandPrefix(CommandPrefixInput{ToolName: "bash", Prefix: prefix}); err == nil {
 			t.Fatalf("GrantCommandPrefix(%#v) succeeded, want validation error", prefix)
@@ -261,7 +261,7 @@ func applyPatchRequestPaths(args map[string]any) []string {
 	}
 	cwd := firstArgString(args, "cwd")
 	var paths []string
-	for _, path := range patchHeaderPaths(patch) {
+	for _, path := range applyPatchPaths(patch) {
 		if path == "" || path == "/dev/null" {
 			continue
 		}
@@ -281,11 +281,15 @@ func applyPatchPathBlock(request Request) *pathBlock {
 	if patch == "" {
 		return nil
 	}
-	for _, path := range patchHeaderPaths(patch) {
+	// Only relative traversal is rejected up front. Absolute paths flow through
+	// the regular workspace-scope validation below (requestPaths), which accepts
+	// one inside the workspace and denies one outside — a model that echoes the
+	// absolute path read_file showed it must not be blocked for that alone.
+	for _, path := range applyPatchPaths(patch) {
 		if path == "" || path == "/dev/null" {
 			continue
 		}
-		if filepath.IsAbs(path) || path == ".." || strings.HasPrefix(path, "../") {
+		if path == ".." || strings.HasPrefix(path, "../") {
 			return &pathBlock{
 				Code:   BlockOutsideWorkspace,
 				Path:   path,
@@ -296,6 +300,61 @@ func applyPatchPathBlock(request Request) *pathBlock {
 	return nil
 }

+// structuredPatchMarkerPattern is the single classifier for structured-patch
+// markers, shared by the sandbox boundary and the apply_patch tool (which
+// imports this package). It accepts the canonical "*** Begin Patch" /
+// "*** End Patch" and the decorated spellings models emit ("*** Begin Patch ***",
+// "***Begin Patch", trailing whitespace). Both sides must agree: a spelling the
+// tool would apply but the sandbox did not recognise would make the sandbox
+// scan the patch as a unified diff, extract no targets, and validate nothing.
+var structuredPatchMarkerPattern = regexp.MustCompile(`^\*{3}\s*(Begin|End) Patch\s*\**\s*$`)
+
+// StructuredPatchMarker classifies a line as the "begin" or "end" marker of a
+// structured patch, or "" when it is neither.
+func StructuredPatchMarker(line string) string {
+	match := structuredPatchMarkerPattern.FindStringSubmatch(strings.TrimSpace(line))
+	if match == nil {
+		return ""
+	}
+	return strings.ToLower(match[1])
+}
+
+// IsStructuredPatch reports whether patch opens with a structured begin marker.
+// The tool applies exactly the patches this returns true for, so the sandbox
+// extracts structured header paths for exactly the same set.
+func IsStructuredPatch(patch string) bool {
+	first, _, _ := strings.Cut(strings.TrimSpace(strings.TrimPrefix(patch, "\ufeff")), "\n")
+	return StructuredPatchMarker(first) == "begin"
+}
+
+func applyPatchPaths(patch string) []string {
+	if IsStructuredPatch(patch) {
+		return structuredPatchHeaderPaths(patch)
+	}
+	return patchHeaderPaths(patch)
+}
+
+// structuredPatchHeaderPaths is intentionally a small, conservative scanner for
+// the sandbox boundary. The executor validates the complete hunk grammar before
+// writing; the sandbox only needs every possible target path so it can reject an
+// unsafe request before the tool runs.
+func structuredPatchHeaderPaths(patch string) []string {
+	var paths []string
+	for _, line := range strings.Split(strings.ReplaceAll(patch, "\r\n", "\n"), "\n") {
+		trimmed := strings.TrimSpace(line)
+		for _, prefix := range []string{"*** Add File: ", "*** Delete File: ", "*** Update File: ", "*** Move to: "} {
+			if path, ok := strings.CutPrefix(trimmed, prefix); ok {
+				path = strings.ReplaceAll(filepath.ToSlash(strings.TrimSpace(path)), "\\", "/")
+				if path != "" {
+					paths = append(paths, path)
+				}
+				break
+			}
+		}
+	}
+	return paths
+}
+
 func patchHeaderPaths(patch string) []string {
 	var paths []string
 	oldRemaining, newRemaining := 0, 0
@@ -94,6 +94,8 @@ type Event struct {
 	Meta              map[string]string `json:"meta,omitempty"`
 	PromptTokens      *int              `json:"promptTokens,omitempty"`
 	CompletionTokens  *int              `json:"completionTokens,omitempty"`
+	CachedInputTokens *int              `json:"cachedInputTokens,omitempty"`
+	CacheWriteTokens  *int              `json:"cacheWriteTokens,omitempty"`
 	TotalTokens       *int              `json:"totalTokens,omitempty"`
 	CostUSD           *float64          `json:"costUsd,omitempty"`
 	Text              string            `json:"text,omitempty"`
@@ -3,11 +3,11 @@ package tools
 import (
 	"context"
 	"fmt"
-	"os"
-	"os/exec"
 	"path/filepath"
 	"strconv"
 	"strings"
+
+	"github.com/Gitlawb/zero/internal/sandbox"
 )

 type applyPatchTool struct {
@@ -16,15 +16,110 @@ type applyPatchTool struct {
 	scope         PathScope
 }

+func (applyPatchTool) isBuiltInApplyPatch() {}
+
+// PrepareFreeformApplyPatchArguments converts native structured-patch input
+// into the ordinary apply_patch argument map used by permission checks and tool
+// execution. Absolute patch-header paths select a granted write root and are
+// rewritten relative to that root; relative-only patches keep workspace-root
+// behavior.
+func PrepareFreeformApplyPatchArguments(tool Tool, patch string) (map[string]any, error) {
+	preparer, ok := tool.(interface {
+		prepareFreeformArguments(string) (map[string]any, error)
+	})
+	if !ok {
+		return nil, fmt.Errorf("tool is not Zero's built-in apply_patch")
+	}
+	return preparer.prepareFreeformArguments(patch)
+}
+
+func (tool applyPatchTool) prepareFreeformArguments(patch string) (map[string]any, error) {
+	args := map[string]any{"patch": patch}
+	if !isStructuredPatch(patch) {
+		return args, nil
+	}
+
+	lines := strings.Split(strings.ReplaceAll(patch, "\r\n", "\n"), "\n")
+	selectedRoot := ""
+	hasRelativeHeader := false
+	for index, line := range lines {
+		prefix := ""
+		switch {
+		case strings.HasPrefix(line, structuredAddFile):
+			prefix = structuredAddFile
+		case strings.HasPrefix(line, structuredDeleteFile):
+			prefix = structuredDeleteFile
+		case strings.HasPrefix(line, structuredUpdateFile):
+			prefix = structuredUpdateFile
+		case strings.HasPrefix(line, structuredMoveTo):
+			prefix = structuredMoveTo
+		default:
+			continue
+		}
+		path := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+		if !filepath.IsAbs(path) {
+			hasRelativeHeader = true
+			continue
+		}
+		root, relative, err := tool.freeformPatchRoot(path)
+		if err != nil {
+			return nil, err
+		}
+		if selectedRoot != "" && selectedRoot != root {
+			return nil, fmt.Errorf("freeform patch spans multiple write roots")
+		}
+		selectedRoot = root
+		lines[index] = prefix + filepath.ToSlash(relative)
+	}
+	if selectedRoot != "" {
+		roots, err := scopedRoots(tool.workspaceRoot, tool.scope)
+		if err != nil {
+			return nil, err
+		}
+		if hasRelativeHeader && selectedRoot != roots[0] {
+			return nil, fmt.Errorf("freeform patch mixes workspace-relative paths with an extra write root")
+		}
+		args["cwd"] = selectedRoot
+		args["patch"] = strings.Join(lines, "\n")
+	}
+	return args, nil
+}
+
+func (tool applyPatchTool) freeformPatchRoot(path string) (string, string, error) {
+	roots, err := scopedRoots(tool.workspaceRoot, tool.scope)
+	if err != nil {
+		return "", "", err
+	}
+	var firstErr error
+	for _, root := range roots {
+		candidate := sandbox.NormalizePrefixForRoot(path, root)
+		candidate, err = filepath.Abs(candidate)
+		if err != nil {
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+		relative, err := filepath.Rel(root, candidate)
+		if err == nil && relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator)) && !filepath.IsAbs(relative) {
+			return root, filepath.ToSlash(relative), nil
+		}
+		if firstErr == nil {
+			firstErr = outsideWorkspaceError(path)
+		}
+	}
+	return "", "", firstErr
+}
+
 func NewScopedApplyPatchTool(workspaceRoot string, scope PathScope) Tool {
 	return applyPatchTool{
 		baseTool: baseTool{
 			name:        "apply_patch",
-			description: "Apply a unified diff patch inside the workspace or an explicitly granted extra write root.",
+			description: "Apply a multi-hunk or multi-file patch inside the workspace (or a granted extra write root). Structured format:\n*** Begin Patch\n*** Update File: src/app.js\n@@\n unchanged context line\n-removed line\n+added line\n*** End Patch\nUse \"*** Add File: path\" with \"+\" lines to create a file and \"*** Delete File: path\" to remove one; several sections may follow each other. A unified diff (---/+++ headers with a/ b/ prefixes, @@ hunks) is also accepted and applied in-process. Paths are workspace-relative; absolute paths inside the workspace are fine. For a single targeted change, edit_file is simpler.",
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
-					"patch": {Type: "string", Description: "Unified diff patch to apply."},
+					"patch": {Type: "string", Description: "The structured (*** Begin Patch) or unified-diff patch text."},
 					"cwd":   {Type: "string", Description: "Directory where the patch should be applied. Relative paths stay in the workspace; use an absolute path to target a granted extra write root. Defaults to workspace root.", Default: "."},
 				},
 				Required:             []string{"patch"},
@@ -56,177 +151,17 @@ func (tool applyPatchTool) RunWithOptions(ctx context.Context, args map[string]a
 	if err != nil {
 		return errorResult("Error applying patch: " + err.Error())
 	}
-	if err := validatePatchPaths(applyRoot, patch); err != nil {
-		return errorResult("Error applying patch: " + err.Error())
+	if isStructuredPatch(patch) {
+		return tool.runStructuredPatch(applyRoot, relativeRoot, patch, options)
 	}
-
-	tempFile, err := os.CreateTemp("", "zero-patch-*.patch")
+	// Unified diffs are translated into the same operations and applied by
+	// the same os.Root engine, so neither format opens a target by pathname
+	// after validation (no check-to-use window) and git is not needed.
+	operations, err := parseUnifiedPatch(patch)
 	if err != nil {
 		return errorResult("Error applying patch: " + err.Error())
 	}
-	patchPath := tempFile.Name()
-	defer func() {
-		_ = os.Remove(patchPath)
-	}()
-	if _, err := tempFile.WriteString(patch); err != nil {
-		_ = tempFile.Close()
-		return errorResult("Error applying patch: " + err.Error())
-	}
-	if err := tempFile.Close(); err != nil {
-		return errorResult("Error applying patch: " + err.Error())
-	}
-
-	if err := recheckPatchWriteTargets(applyRoot, patch); err != nil {
-		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)
-	command.Dir = applyRoot
-	output, err := command.CombinedOutput()
-	if err != nil {
-		message := strings.TrimSpace(string(output))
-		if message == "" {
-			message = err.Error()
-		}
-		return errorResult("Error applying patch: " + message)
-	}
-
-	summary := "Patch applied successfully."
-	if relativeRoot != "." {
-		summary = "Patch applied successfully in " + relativeRoot + "."
-	}
-	result := okResult(summary)
-	result.ChangedFiles = changedFilesFromPatch(relativeRoot, patch)
-	result.Display = Display{Summary: summary, Kind: "diff", Preview: capPreviewDiff(patch)}
-	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 {
-			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)
-	return result
-}
-
-func missingPatchTargets(root string, patch string) []string {
-	seen := map[string]bool{}
-	var missing []string
-	for _, path := range patchHeaderPaths(patch) {
-		if path == "" || path == "/dev/null" {
-			continue
-		}
-		absolute, _, err := resolveWorkspaceTargetPath(root, path)
-		if err != nil || seen[absolute] {
-			continue
-		}
-		seen[absolute] = true
-		if _, err := os.Stat(absolute); os.IsNotExist(err) {
-			missing = append(missing, absolute)
-		}
-	}
-	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
-	}
-	for _, absolute := range missingBefore {
-		if _, err := os.Stat(absolute); err != nil {
-			continue
-		}
-		if resolved, err := filepath.EvalSymlinks(absolute); err == nil {
-			absolute = resolved
-		}
-		tracker.RecordCreated(absolute)
-	}
+	return applyPatchOperations(applyRoot, relativeRoot, operations, options)
 }

 // changedFilesFromPatch extracts the unique, WORKSPACE-relative paths a patch
@@ -257,27 +192,35 @@ func changedFilesFromPatch(relativeRoot string, patch string) []string {
 	return paths
 }

+// normalizePatchPathForRoot resolves platform-level symlinks (macOS /var ->
+// /private/var) in the prefix of an absolute patch path that lies outside the
+// apply root, so a path the model copied from read_file compares equal to the
+// symlink-resolved root. Relative paths are returned unchanged.
+func normalizePatchPathForRoot(root string, path string) string {
+	if !filepath.IsAbs(path) {
+		return path
+	}
+	resolvedRoot, err := filepath.Abs(root)
+	if err != nil {
+		return path
+	}
+	if evaluated, err := filepath.EvalSymlinks(resolvedRoot); err == nil {
+		resolvedRoot = evaluated
+	}
+	return sandbox.NormalizePrefixForRoot(path, resolvedRoot)
+}
+
 func validatePatchPaths(root string, patch string) error {
 	for _, path := range patchHeaderPaths(patch) {
 		if path == "" || path == "/dev/null" {
 			continue
 		}
-		if filepath.IsAbs(path) || path == ".." || strings.HasPrefix(path, "../") {
+		// Relative traversal is rejected here; an absolute path is checked by
+		// resolveWorkspaceTargetPath, which only accepts one inside the root.
+		if path == ".." || strings.HasPrefix(path, "../") {
 			return fmt.Errorf("patch path %q must stay inside the workspace", path)
 		}
-		if _, _, err := resolveWorkspaceTargetPath(root, path); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func recheckPatchWriteTargets(root string, patch string) error {
-	for _, path := range patchHeaderPaths(patch) {
-		if path == "" || path == "/dev/null" {
-			continue
-		}
-		if err := recheckWorkspaceWriteTarget(root, path); err != nil {
+		if _, _, err := resolveWorkspaceTargetPath(root, normalizePatchPathForRoot(root, path)); err != nil {
 			return err
 		}
 	}
@@ -348,7 +291,7 @@ func patchFileHeaderPath(line string) string {
 // tokens. Scanning the whole line would let a crafted heading like
 // "@@ -1,1 +1,1 @@ +1,999999" overwrite the real count, keep the parser stuck in
 // hunk mode, and swallow later "--- "/"+++ " file headers so they escape
-// validatePatchPaths / recheckPatchWriteTargets — a workspace-confinement bypass.
+// validatePatchPaths — a workspace-confinement bypass.
 func parseHunkCounts(line string) (int, int) {
 	_, rest, ok := strings.Cut(line, "@@")
 	if !ok {
@@ -0,0 +1,712 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// Models routinely decorate the structured markers ("*** Begin Patch ***") and
+// write unified-diff ranges after "@@"; both used to fail on the first line and
+// pushed the model into whole-file rewrites.
+func TestApplyPatchToleratesDecoratedMarkersAndRangeHeaders(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "hello.txt"), "hello\nold\nbye\n")
+
+	patch := strings.Join([]string{
+		"*** Begin Patch ***",
+		"*** Update File: hello.txt",
+		"@@ -1,3 +1,3 @@",
+		" hello",
+		"-old",
+		"+new",
+		"*** End Patch ***",
+		"",
+	}, "\n")
+
+	if !isStructuredPatch(patch) {
+		t.Fatal("decorated begin marker must still be recognised as a structured patch")
+	}
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("decorated structured patch should apply, got %s: %s", result.Status, result.Output)
+	}
+	content, err := os.ReadFile(filepath.Join(root, "hello.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.ReplaceAll(string(content), "\r\n", "\n"); got != "hello\nnew\nbye\n" {
+		t.Fatalf("patched content = %q", got)
+	}
+}
+
+func TestStructuredHunkAnchorKeepsHeadingAndPlainContext(t *testing.T) {
+	cases := map[string]string{
+		"-12,4 +12,6":                  "",
+		"-12 +12":                      "",
+		"-12,4 +12,6 @@":               "",
+		"-12,4 +12,6 @@ func main() {": "func main() {",
+		"func main() {":                "func main() {",
+		"":                             "",
+	}
+	for input, want := range cases {
+		if got := structuredHunkAnchor(input); got != want {
+			t.Fatalf("structuredHunkAnchor(%q) = %q, want %q", input, got, want)
+		}
+	}
+}
+
+func TestStructuredPatchMarkerSpellings(t *testing.T) {
+	begin := []string{"*** Begin Patch", "*** Begin Patch ***", "***Begin Patch", "  *** Begin Patch  ", "*** Begin Patch **"}
+	for _, line := range begin {
+		if structuredPatchMarker(line) != "begin" {
+			t.Fatalf("%q must read as the begin marker", line)
+		}
+	}
+	if structuredPatchMarker("*** End Patch ***") != "end" {
+		t.Fatal("decorated end marker must read as the end marker")
+	}
+	for _, line := range []string{"*** Update File: x", "Begin Patch", "*** Begin Patchwork"} {
+		if structuredPatchMarker(line) != "" {
+			t.Fatalf("%q must not read as a marker", line)
+		}
+	}
+}
+
+func TestStructuredPatchHeaderErrorCarriesFormatHint(t *testing.T) {
+	_, err := parseStructuredPatch("--- a/x\n+++ b/x\n")
+	if err == nil || !strings.Contains(err.Error(), "*** Update File: path") {
+		t.Fatalf("header error should teach the format, got %v", err)
+	}
+}
+
+func TestApplyPatchAcceptsAbsoluteInWorkspacePaths(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "hello.txt"), "hello\nold\n")
+	absolute := filepath.Join(root, "hello.txt")
+
+	structured := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Update File: " + absolute,
+		"@@",
+		" hello",
+		"-old",
+		"+structured",
+		"*** End Patch",
+		"",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": structured})
+	if result.Status != StatusOK {
+		t.Fatalf("absolute in-workspace structured path should apply, got %s: %s", result.Status, result.Output)
+	}
+	content, _ := os.ReadFile(absolute)
+	if got := strings.ReplaceAll(string(content), "\r\n", "\n"); got != "hello\nstructured\n" {
+		t.Fatalf("structured content = %q", got)
+	}
+	if len(result.ChangedFiles) != 1 || result.ChangedFiles[0] != "hello.txt" {
+		t.Fatalf("changed files should be workspace-relative, got %v", result.ChangedFiles)
+	}
+
+	unified := strings.Join([]string{
+		"--- " + absolute,
+		"+++ " + absolute,
+		"@@ -1,2 +1,2 @@",
+		" hello",
+		"-structured",
+		"+unified",
+		"",
+	}, "\n")
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": unified})
+	if result.Status != StatusOK {
+		t.Fatalf("absolute in-workspace unified path should apply, got %s: %s", result.Status, result.Output)
+	}
+	content, _ = os.ReadFile(absolute)
+	if got := strings.ReplaceAll(string(content), "\r\n", "\n"); got != "hello\nunified\n" {
+		t.Fatalf("unified content = %q", got)
+	}
+}
+
+func TestApplyPatchStillRejectsAbsolutePathsOutsideWorkspace(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "escape.txt")
+	writeTestFile(t, outside, "old\n")
+
+	for name, patch := range map[string]string{
+		"structured": strings.Join([]string{"*** Begin Patch", "*** Update File: " + outside, "@@", "-old", "+new", "*** End Patch", ""}, "\n"),
+		"unified":    strings.Join([]string{"--- " + outside, "+++ " + outside, "@@ -1 +1 @@", "-old", "+new", ""}, "\n"),
+	} {
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+		if result.Status == StatusOK {
+			t.Fatalf("%s patch outside the workspace must be rejected", name)
+		}
+		if content, _ := os.ReadFile(outside); string(content) != "old\n" {
+			t.Fatalf("%s patch must not touch a file outside the workspace", name)
+		}
+	}
+}
+
+// Unified diffs are applied in-process through the same os.Root engine as
+// structured patches: git C-quoted paths with whitespace resolve to one file,
+// and the same header outside the workspace is refused before anything is
+// written.
+func TestUnifiedPatchQuotedWhitespacePaths(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "work tree")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	target := filepath.Join(dir, "file.txt")
+	writeTestFile(t, target, "hello\nold\n")
+
+	quoted := func(path string) string { return strconv.Quote(path) }
+	inside := strings.Join([]string{
+		"diff --git " + quoted("a/"+filepath.ToSlash(target)) + " " + quoted("b/"+filepath.ToSlash(target)),
+		"--- " + quoted(target),
+		"+++ " + quoted(target),
+		"@@ -1,2 +1,2 @@",
+		" hello",
+		"-old",
+		"+new",
+		"",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": inside})
+	if result.Status != StatusOK {
+		t.Fatalf("quoted whitespace path inside the workspace should apply, got %s: %s", result.Status, result.Output)
+	}
+	content, _ := os.ReadFile(target)
+	if got := strings.ReplaceAll(string(content), "\r\n", "\n"); got != "hello\nnew\n" {
+		t.Fatalf("content = %q", got)
+	}
+	if len(result.ChangedFiles) != 1 || result.ChangedFiles[0] != "work tree/file.txt" {
+		t.Fatalf("changed files = %v", result.ChangedFiles)
+	}
+
+	outsideDir := filepath.Join(t.TempDir(), "other tree")
+	if err := os.MkdirAll(outsideDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	outside := filepath.Join(outsideDir, "file.txt")
+	writeTestFile(t, outside, "hello\nold\n")
+	escape := strings.Join([]string{"--- " + quoted(outside), "+++ " + quoted(outside), "@@ -1,2 +1,2 @@", " hello", "-old", "+new", ""}, "\n")
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": escape})
+	if result.Status == StatusOK {
+		t.Fatal("quoted whitespace path outside the workspace must be rejected")
+	}
+	if content, _ := os.ReadFile(outside); string(content) != "hello\nold\n" {
+		t.Fatal("outside file must be untouched")
+	}
+}
+
+// A workspace path that is swapped for a symlink escaping the root — the
+// classic check-to-use attack — is refused by the os.Root engine for both
+// formats, and the outside file is never modified.
+func TestApplyPatchRefusesSymlinkEscapingWorkspace(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "secret.txt")
+	writeTestFile(t, outside, "hello\nold\n")
+	link := filepath.Join(root, "target.txt")
+	if err := os.Symlink(outside, link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	for name, patch := range map[string]string{
+		"unified":    strings.Join([]string{"--- a/target.txt", "+++ b/target.txt", "@@ -1,2 +1,2 @@", " hello", "-old", "+new", ""}, "\n"),
+		"structured": strings.Join([]string{"*** Begin Patch", "*** Update File: target.txt", "@@", " hello", "-old", "+new", "*** End Patch", ""}, "\n"),
+	} {
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+		if result.Status == StatusOK {
+			t.Fatalf("%s patch through an escaping symlink must be refused", name)
+		}
+		if content, _ := os.ReadFile(outside); string(content) != "hello\nold\n" {
+			t.Fatalf("%s patch must not modify the file outside the workspace", name)
+		}
+	}
+}
+
+func TestUnifiedPatchCreatesDeletesAndHonoursNoNewlineMarker(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "gone.txt"), "bye\n")
+	writeTestFile(t, filepath.Join(root, "keep.txt"), "a\nb\n")
+	patch := strings.Join([]string{
+		"diff --git a/new.txt b/new.txt",
+		"new file mode 100644",
+		"--- /dev/null",
+		"+++ b/new.txt",
+		"@@ -0,0 +1,2 @@",
+		"+first",
+		"+second",
+		"\\ No newline at end of file",
+		"diff --git a/gone.txt b/gone.txt",
+		"deleted file mode 100644",
+		"--- a/gone.txt",
+		"+++ /dev/null",
+		"@@ -1 +0,0 @@",
+		"-bye",
+		"--- a/keep.txt",
+		"+++ b/keep.txt",
+		"@@ -1,2 +1,2 @@",
+		" a",
+		"-b",
+		"+c",
+		"\\ No newline at end of file",
+		"",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("multi-file unified patch should apply, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "new.txt")); string(content) != "first\nsecond" {
+		t.Fatalf("created file = %q", string(content))
+	}
+	if _, err := os.Stat(filepath.Join(root, "gone.txt")); !os.IsNotExist(err) {
+		t.Fatal("deleted file must be gone")
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "keep.txt")); string(content) != "a\nc" {
+		t.Fatalf("updated file = %q", string(content))
+	}
+	if len(result.ChangedFiles) != 3 {
+		t.Fatalf("changed files = %v", result.ChangedFiles)
+	}
+}
+
+func TestUnifiedPatchUsesRangeHintThenFallsBackToContext(t *testing.T) {
+	root := t.TempDir()
+	// Two identical blocks: the hunk's range picks the second one, which
+	// content search alone would call ambiguous.
+	writeTestFile(t, filepath.Join(root, "dup.txt"), "x\ny\nx\ny\n")
+	patch := strings.Join([]string{"--- a/dup.txt", "+++ b/dup.txt", "@@ -3,2 +3,2 @@", " x", "-y", "+z", ""}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("range-hinted hunk should apply, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "dup.txt")); string(content) != "x\ny\nx\nz\n" {
+		t.Fatalf("content = %q", string(content))
+	}
+	// A stale range (file grew above the hunk) still applies by unique context.
+	writeTestFile(t, filepath.Join(root, "moved.txt"), "header\nhello\nold\n")
+	patch = strings.Join([]string{"--- a/moved.txt", "+++ b/moved.txt", "@@ -1,2 +1,2 @@", " hello", "-old", "+new", ""}, "\n")
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("offset hunk should apply by context, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "moved.txt")); string(content) != "header\nhello\nnew\n" {
+		t.Fatalf("content = %q", string(content))
+	}
+}
+
+func TestUnifiedPatchRenameWithHunkAndRejectsBinary(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "x.txt"), "hello\nold\n")
+	rename := strings.Join([]string{
+		"diff --git a/x.txt b/y.txt",
+		"similarity index 90%",
+		"rename from x.txt",
+		"rename to y.txt",
+		"--- a/x.txt",
+		"+++ b/y.txt",
+		"@@ -1,2 +1,2 @@",
+		" hello",
+		"-old",
+		"+new",
+		"",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": rename})
+	if result.Status != StatusOK {
+		t.Fatalf("rename with hunk should apply, got %s: %s", result.Status, result.Output)
+	}
+	if _, err := os.Stat(filepath.Join(root, "x.txt")); !os.IsNotExist(err) {
+		t.Fatal("renamed source must be gone")
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "y.txt")); string(content) != "hello\nnew\n" {
+		t.Fatalf("renamed content = %q", string(content))
+	}
+	for name, patch := range map[string]string{
+		"binary": "diff --git a/x b/x\nBinary files a/x and b/x differ\n",
+		"empty":  "diff --git a/x b/x\n",
+	} {
+		if result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch}); result.Status == StatusOK {
+			t.Fatalf("%s patch must be rejected", name)
+		}
+	}
+}
+
+func TestUnifiedPatchCopyOperation(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "src.txt"), "hello\nold\n")
+	copyPatch := func(from, to string, hunk bool) string {
+		lines := []string{"diff --git a/" + from + " b/" + to, "similarity index 90%", "copy from " + from, "copy to " + to}
+		if hunk {
+			lines = append(lines, "--- a/"+from, "+++ b/"+to, "@@ -1,2 +1,2 @@", " hello", "-old", "+new")
+		}
+		return strings.Join(append(lines, ""), "\n")
+	}
+
+	// Success: source kept, destination created with the hunk applied, and the
+	// destination inherits the source's tracker state (read whole -> whole).
+	tracker := NewFileTracker()
+	registry := NewRegistry()
+	registry.Register(NewScopedReadFileTool(root, nil))
+	registry.Register(NewScopedApplyPatchTool(root, nil))
+	opts := RunOptions{PermissionGranted: true, FileTracker: tracker}
+	if r := registry.RunWithOptions(context.Background(), "read_file", map[string]any{"path": "src.txt"}, opts); r.Status != StatusOK {
+		t.Fatalf("read: %s", r.Output)
+	}
+	result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": copyPatch("src.txt", "dst.txt", true)}, opts)
+	if result.Status != StatusOK {
+		t.Fatalf("copy with hunk should apply, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "src.txt")); string(content) != "hello\nold\n" {
+		t.Fatalf("copy must keep the source, got %q", string(content))
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "dst.txt")); string(content) != "hello\nnew\n" {
+		t.Fatalf("copy destination = %q", string(content))
+	}
+	if len(result.ChangedFiles) != 2 || result.ChangedFiles[0] != "src.txt" || result.ChangedFiles[1] != "dst.txt" {
+		t.Fatalf("changed files = %v", result.ChangedFiles)
+	}
+	destination, err := filepath.EvalSymlinks(filepath.Join(root, "dst.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !tracker.SeenWhole(destination) {
+		t.Fatal("destination copied from a fully read source must be tracked as seen whole")
+	}
+	unreadSource, _ := filepath.EvalSymlinks(filepath.Join(root, "src.txt"))
+	if _, tracked := tracker.Version(unreadSource); !tracked {
+		t.Fatal("source must stay tracked after a copy")
+	}
+
+	// Failure: destination already exists — nothing is written.
+	writeTestFile(t, filepath.Join(root, "taken.txt"), "keep\n")
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": copyPatch("src.txt", "taken.txt", false)})
+	if result.Status == StatusOK || !strings.Contains(result.Output, "already exists") {
+		t.Fatalf("copy onto an existing destination must be refused, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "taken.txt")); string(content) != "keep\n" {
+		t.Fatal("existing destination must be untouched")
+	}
+
+	// Failure: copy onto itself.
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": copyPatch("src.txt", "src.txt", false)})
+	if result.Status == StatusOK || !strings.Contains(result.Output, "onto itself") {
+		t.Fatalf("copy onto itself must be refused, got %s: %s", result.Status, result.Output)
+	}
+}
+
+func TestUnifiedPatchRejectsOverDeclaredHunkCounts(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "a.txt"), "hello\nold\n")
+	writeTestFile(t, filepath.Join(root, "b.txt"), "x\n")
+	// "-1,3 +1,3" over-declares a two-line hunk, so without a guard the next
+	// file's ---/+++ headers would be swallowed as "-"/"+" content.
+	patch := strings.Join([]string{
+		"--- a/a.txt", "+++ b/a.txt", "@@ -1,3 +1,3 @@", " hello", "-old", "+new",
+		"--- a/b.txt", "+++ b/b.txt", "@@ -1 +1 @@", "-x", "+y", "",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status == StatusOK || !strings.Contains(result.Output, "declared line counts") {
+		t.Fatalf("over-declared hunk must be reported as malformed, got %s: %s", result.Status, result.Output)
+	}
+	for name, want := range map[string]string{"a.txt": "hello\nold\n", "b.txt": "x\n"} {
+		if content, _ := os.ReadFile(filepath.Join(root, name)); string(content) != want {
+			t.Fatalf("%s must be untouched after a malformed patch, got %q", name, string(content))
+		}
+	}
+	// Truncated at end of input is reported the same way.
+	truncated := "--- a/a.txt\n+++ b/a.txt\n@@ -1,2 +1,2 @@\n hello\n-old\n"
+	if result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": truncated}); result.Status == StatusOK || !strings.Contains(result.Output, "declared line counts") {
+		t.Fatalf("truncated hunk must be reported as malformed, got %s: %s", result.Status, result.Output)
+	}
+}
+
+func TestUnifiedPatchNoNewlineMarkerOnlyAfterFinalHunk(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "two.txt"), "a\nb\nc\nd\ne\nf\n")
+	// A marker after the first of two hunks describes nothing real and must
+	// not leak into the second hunk's result: the patch is rejected untouched.
+	early := strings.Join([]string{
+		"--- a/two.txt", "+++ b/two.txt",
+		"@@ -1,2 +1,2 @@", " a", "-b", "+B", "\\ No newline at end of file",
+		"@@ -5,2 +5,2 @@", " e", "-f", "+F", "",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": early})
+	if result.Status == StatusOK || !strings.Contains(result.Output, "must follow the last hunk") {
+		t.Fatalf("marker before a later hunk must be rejected, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "two.txt")); string(content) != "a\nb\nc\nd\ne\nf\n" {
+		t.Fatal("rejected patch must not modify the file")
+	}
+	// The same marker after the final hunk applies and strips the newline.
+	final := strings.Join([]string{
+		"--- a/two.txt", "+++ b/two.txt",
+		"@@ -1,2 +1,2 @@", " a", "-b", "+B",
+		"@@ -5,2 +5,2 @@", " e", "-f", "+F", "\\ No newline at end of file", "",
+	}, "\n")
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": final})
+	if result.Status != StatusOK {
+		t.Fatalf("two-hunk patch with a final marker should apply, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "two.txt")); string(content) != "a\nB\nc\nd\ne\nF" {
+		t.Fatalf("content = %q", string(content))
+	}
+}
+
+// A removed "-- …" line directly followed by an added "++ …" line looks like a
+// ---/+++ header pair; the boundary check must not mistake it for one.
+func TestUnifiedPatchKeepsAdjacentDashPlusContentLines(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.sql"), "select 1;\n-- old comment\nselect 2;\n")
+	patch := strings.Join([]string{
+		"--- a/notes.sql", "+++ b/notes.sql",
+		"@@ -1,3 +1,3 @@", " select 1;", "--- old comment", "+++ new comment", " select 2;", "",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("adjacent -- / ++ content lines must apply, got %s: %s", result.Status, result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "notes.sql")); string(content) != "select 1;\n++ new comment\nselect 2;\n" {
+		t.Fatalf("content = %q", string(content))
+	}
+}
+
+// A unified deletion states the content it removes; it must be verified
+// against the current file before anything is deleted.
+func TestUnifiedPatchDeletionVerifiesExpectedContent(t *testing.T) {
+	deletion := func(path string, hunks ...string) string {
+		lines := []string{"diff --git a/" + path + " b/" + path, "deleted file mode 100644", "--- a/" + path, "+++ /dev/null"}
+		return strings.Join(append(append(lines, hunks...), ""), "\n")
+	}
+	t.Run("matching deletion succeeds", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "current\n")
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deletion("gone.txt", "@@ -1 +0,0 @@", "-current")})
+		if result.Status != StatusOK {
+			t.Fatalf("matching deletion should apply, got %s: %s", result.Status, result.Output)
+		}
+		if _, err := os.Stat(filepath.Join(root, "gone.txt")); !os.IsNotExist(err) {
+			t.Fatal("file must be deleted")
+		}
+	})
+	t.Run("stale deletion is refused untouched", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "current\n")
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deletion("gone.txt", "@@ -1 +0,0 @@", "-stale")})
+		if result.Status == StatusOK || !strings.Contains(result.Output, "does not match its current content") {
+			t.Fatalf("stale deletion must be refused, got %s: %s", result.Status, result.Output)
+		}
+		if content, _ := os.ReadFile(filepath.Join(root, "gone.txt")); string(content) != "current\n" {
+			t.Fatalf("file must be byte-for-byte unchanged, got %q", string(content))
+		}
+	})
+	t.Run("partial deletion is refused", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "one\ntwo\n")
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deletion("gone.txt", "@@ -1 +0,0 @@", "-one")})
+		if result.Status == StatusOK || !strings.Contains(result.Output, "does not match its current content") {
+			t.Fatalf("deletion that does not cover the file must be refused, got %s: %s", result.Status, result.Output)
+		}
+		if content, _ := os.ReadFile(filepath.Join(root, "gone.txt")); string(content) != "one\ntwo\n" {
+			t.Fatal("file must be unchanged")
+		}
+	})
+	t.Run("header-only deletion is refused", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "current\n")
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deletion("gone.txt")})
+		if result.Status == StatusOK || !strings.Contains(result.Output, "must include the hunk") {
+			t.Fatalf("header-only deletion must be refused, got %s: %s", result.Status, result.Output)
+		}
+		if _, err := os.Stat(filepath.Join(root, "gone.txt")); err != nil {
+			t.Fatal("file must still exist")
+		}
+	})
+	t.Run("multi-hunk deletion verifies everything before removing", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "a\nb\nc\nd\n")
+		good := deletion("gone.txt", "@@ -1,2 +0,0 @@", "-a", "-b", "@@ -3,2 +0,0 @@", "-c", "-d")
+		bad := deletion("gone.txt", "@@ -1,2 +0,0 @@", "-a", "-b", "@@ -3,2 +0,0 @@", "-c", "-stale")
+		result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": bad})
+		if result.Status == StatusOK {
+			t.Fatalf("deletion with one stale hunk must be refused: %s", result.Output)
+		}
+		if content, _ := os.ReadFile(filepath.Join(root, "gone.txt")); string(content) != "a\nb\nc\nd\n" {
+			t.Fatal("no hunk may be applied when any hunk is stale")
+		}
+		result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": good})
+		if result.Status != StatusOK {
+			t.Fatalf("multi-hunk deletion should apply, got %s: %s", result.Status, result.Output)
+		}
+		if _, err := os.Stat(filepath.Join(root, "gone.txt")); !os.IsNotExist(err) {
+			t.Fatal("file must be deleted")
+		}
+	})
+	t.Run("structured delete stays unconditional", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "anything\n")
+		patch := "*** Begin Patch\n*** Delete File: gone.txt\n*** End Patch\n"
+		if result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch}); result.Status != StatusOK {
+			t.Fatalf("structured delete should apply, got %s: %s", result.Status, result.Output)
+		}
+	})
+}
+
+// The source is re-read through the root immediately before commit, so a
+// change made after planning is refused instead of overwritten or removed.
+func TestApplyStructuredPatchChangeRefusesSourceChangedAfterPlanning(t *testing.T) {
+	root := t.TempDir()
+	path := filepath.Join(root, "file.txt")
+	writeTestFile(t, path, "planned\n")
+	workspace, err := os.OpenRoot(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer workspace.Close()
+	target := structuredPatchTarget{requested: "file.txt", absolute: path, relative: "file.txt"}
+	destination := structuredPatchTarget{requested: "copy.txt", absolute: filepath.Join(root, "copy.txt"), relative: "copy.txt"}
+	for name, change := range map[string]structuredPatchChange{
+		"update": {kind: structuredPatchUpdate, from: target, to: target, before: "planned\n", after: "new\n", mode: 0o644},
+		"delete": {kind: structuredPatchDelete, from: target, to: target, before: "planned\n", mode: 0o644},
+		"copy":   {kind: structuredPatchCopy, from: target, to: destination, before: "planned\n", after: "planned\n", mode: 0o644},
+	} {
+		writeTestFile(t, path, "changed after planning\n")
+		committed, err := applyStructuredPatchChange(workspace, change)
+		if err == nil || committed || !strings.Contains(err.Error(), "changed on disk between planning and commit") {
+			t.Fatalf("%s: expected a refusal, got committed=%v err=%v", name, committed, err)
+		}
+		if content, _ := os.ReadFile(path); string(content) != "changed after planning\n" {
+			t.Fatalf("%s: file must be untouched, got %q", name, string(content))
+		}
+		if _, statErr := os.Stat(filepath.Join(root, "copy.txt")); !os.IsNotExist(statErr) {
+			t.Fatalf("%s: refused change must not create copy.txt", name)
+		}
+	}
+}
+
+func TestUnifiedPatchDeletionIsByteExact(t *testing.T) {
+	deletion := func(hunks ...string) string {
+		return strings.Join(append(append([]string{"--- a/gone.txt", "+++ /dev/null"}, hunks...), ""), "\n")
+	}
+	for name, tc := range map[string]struct{ file, patch string }{
+		"trailing whitespace differs": {"current  \n", deletion("@@ -1 +0,0 @@", "-current")},
+		"indentation differs":         {"  current\n", deletion("@@ -1 +0,0 @@", "-current")},
+		"blank line not covered":      {"current\n\n", deletion("@@ -1 +0,0 @@", "-current")},
+		"space-only line not covered": {"current\n   \n", deletion("@@ -1 +0,0 @@", "-current")},
+		"missing final newline":       {"current", deletion("@@ -1 +0,0 @@", "-current")},
+	} {
+		t.Run(name, func(t *testing.T) {
+			root := t.TempDir()
+			writeTestFile(t, filepath.Join(root, "gone.txt"), tc.file)
+			result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": tc.patch})
+			if result.Status == StatusOK {
+				t.Fatalf("deletion must be byte-exact; %q was deleted by a non-matching hunk", tc.file)
+			}
+			if content, _ := os.ReadFile(filepath.Join(root, "gone.txt")); string(content) != tc.file {
+				t.Fatalf("file must be unchanged, got %q", string(content))
+			}
+		})
+	}
+	t.Run("no-newline marker on the removed side matches exactly", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "current")
+		patch := deletion("@@ -1 +0,0 @@", "-current", "\\ No newline at end of file")
+		if result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch}); result.Status != StatusOK {
+			t.Fatalf("deletion with a matching no-newline marker should apply, got %s: %s", result.Status, result.Output)
+		}
+		if _, err := os.Stat(filepath.Join(root, "gone.txt")); !os.IsNotExist(err) {
+			t.Fatal("file must be deleted")
+		}
+	})
+	t.Run("CRLF file matches an LF patch of the same content", func(t *testing.T) {
+		root := t.TempDir()
+		writeTestFile(t, filepath.Join(root, "gone.txt"), "a\r\nb\r\n")
+		if result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deletion("@@ -1,2 +0,0 @@", "-a", "-b")}); result.Status != StatusOK {
+			t.Fatalf("CRLF deletion should apply, got %s: %s", result.Status, result.Output)
+		}
+	})
+}
+
+// git describes an empty file's creation or deletion with header lines only.
+func TestUnifiedPatchHeaderOnlyEmptyFileForms(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "empty.txt"), "")
+	writeTestFile(t, filepath.Join(root, "full.txt"), "content\n")
+	writeTestFile(t, filepath.Join(root, "keep.txt"), "a\n")
+	deleteHeader := func(path string) string {
+		return "diff --git a/" + path + " b/" + path + "\ndeleted file mode 100644\nindex e69de29..0000000\n"
+	}
+	// A non-empty file is not deleted by the header-only form.
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": deleteHeader("full.txt")})
+	if result.Status == StatusOK || !strings.Contains(result.Output, "expects an empty file") {
+		t.Fatalf("header-only deletion of a non-empty file must be refused, got %s: %s", result.Status, result.Output)
+	}
+	if _, err := os.Stat(filepath.Join(root, "full.txt")); err != nil {
+		t.Fatal("non-empty file must still exist")
+	}
+	// In a multi-file patch the empty-file deletion and creation are applied
+	// alongside a normal hunk.
+	patch := deleteHeader("empty.txt") +
+		"diff --git a/blank.txt b/blank.txt\nnew file mode 100644\nindex 0000000..e69de29\n" +
+		"diff --git a/keep.txt b/keep.txt\n--- a/keep.txt\n+++ b/keep.txt\n@@ -1 +1 @@\n-a\n+b\n"
+	result = NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusOK {
+		t.Fatalf("multi-file patch with header-only forms should apply, got %s: %s", result.Status, result.Output)
+	}
+	if _, err := os.Stat(filepath.Join(root, "empty.txt")); !os.IsNotExist(err) {
+		t.Fatal("empty file must be deleted")
+	}
+	if content, err := os.ReadFile(filepath.Join(root, "blank.txt")); err != nil || len(content) != 0 {
+		t.Fatalf("empty file must be created, got err=%v content=%q", err, string(content))
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "keep.txt")); string(content) != "b\n" {
+		t.Fatalf("hunk file = %q", string(content))
+	}
+	if len(result.ChangedFiles) != 3 {
+		t.Fatalf("changed files = %v", result.ChangedFiles)
+	}
+}
+
+// When a later change fails, the error names exactly which files were already
+// committed so the caller knows what changed and what did not.
+func TestApplyPatchOperationsReportsCommittedPrefixOnFailure(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "first.txt"), "one\n")
+	writeTestFile(t, filepath.Join(root, "second.txt"), "two\n")
+	writeTestFile(t, filepath.Join(root, "third.txt"), "three\n")
+	// Make second.txt change after planning so its commit is refused.
+	structuredPatchBeforeCommit = func(change structuredPatchChange) {
+		if change.to.relative == "second.txt" {
+			writeTestFile(t, filepath.Join(root, "second.txt"), "changed\n")
+		}
+	}
+	defer func() { structuredPatchBeforeCommit = nil }()
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Update File: first.txt", "@@", "-one", "+ONE",
+		"*** Update File: second.txt", "@@", "-two", "+TWO",
+		"*** Update File: third.txt", "@@", "-three", "+THREE",
+		"*** End Patch", "",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status == StatusOK {
+		t.Fatal("patch must fail when a later change is refused")
+	}
+	for _, want := range []string{"already committed: first.txt", "remaining files are unchanged"} {
+		if !strings.Contains(result.Output, want) {
+			t.Fatalf("error must report the committed prefix, got: %s", result.Output)
+		}
+	}
+	if strings.Contains(result.Output, "committed: first.txt, second.txt") || strings.Contains(result.Output, "third.txt") {
+		t.Fatalf("error must not list uncommitted files as committed: %s", result.Output)
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "first.txt")); string(content) != "ONE\n" {
+		t.Fatalf("first.txt must hold the committed change, got %q", string(content))
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "second.txt")); string(content) != "changed\n" {
+		t.Fatalf("second.txt must be untouched by the patch, got %q", string(content))
+	}
+	if content, _ := os.ReadFile(filepath.Join(root, "third.txt")); string(content) != "three\n" {
+		t.Fatalf("third.txt must be untouched, got %q", string(content))
+	}
+}
@@ -231,6 +231,25 @@ func TestApplyPatchResourceKeysFromDiffAndCwd(t *testing.T) {
 	}
 }

+func TestApplyPatchResourceKeysFromStructuredPatchAndCwd(t *testing.T) {
+	patch := "*** Begin Patch\n*** Update File: old.go\n*** Move to: new.go\n@@\n-old\n+new\n*** End Patch\n"
+	keys := applyPatchResourceKeys(map[string]any{"patch": patch, "cwd": "pkg"})
+	want := map[string]bool{
+		ResourceKeyDirectory + "pkg":   true,
+		ResourceKeyFile + "pkg/old.go": true,
+		ResourceKeyFile + "pkg/new.go": true,
+	}
+	for _, key := range keys {
+		if !want[key] {
+			t.Fatalf("unexpected key %q in %v", key, keys)
+		}
+		delete(want, key)
+	}
+	if len(want) != 0 {
+		t.Fatalf("missing keys %v from %v", want, keys)
+	}
+}
+
 func TestDeclaredMutatorThreadSafeIsReportedByCatalogValidation(t *testing.T) {
 	// Runtime CapabilitiesOf clears ThreadSafe on mutators; catalog validation
 	// must still see the raw declaration so miswired constructors fail the gate.
@@ -168,7 +168,7 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	options.FileTracker.Record(absolutePath, []byte(updated), newInfo)
 	if updated == modelKnownContent {
 		if previouslySeenWhole {
-			options.FileTracker.RecordSeenRange(absolutePath, 1, lineCount(updated), lineCount(updated))
+			options.FileTracker.RecordSeenRange(absolutePath, 1, trackedLineTotal(updated), trackedLineTotal(updated))
 		} else {
 			for _, span := range editedSpans {
 				options.FileTracker.RecordSeenBytes(absolutePath, span.start, span.end, len(updated))
@@ -221,6 +221,112 @@ func TestApplyPatchCompleteCreationCreditsSuppliedFile(t *testing.T) {
 	}
 }

+func TestStructuredPatchDoesNotCreditUnreadFileForOverwrite(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)
+	registry.Register(NewScopedApplyPatchTool(dir, nil))
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Update File: f.txt",
+		"@@",
+		"-beta",
+		"+updated",
+		"*** End Patch",
+		"",
+	}, "\n")
+
+	if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": patch}, opts); result.Status != StatusOK {
+		t.Fatalf("structured patch failed: %s", result.Output)
+	}
+	trackedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if tracker.SeenWhole(trackedPath) {
+		t.Fatal("a partial structured patch credited the unread file as fully seen")
+	}
+	result := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+		"path": "f.txt", "content": "blind overwrite\n", "overwrite": true,
+	}, opts)
+	if result.Status != StatusError || !strings.Contains(result.Output, "has not been read exactly") {
+		t.Fatalf("blind overwrite after a partial patch was not refused: %#v", result)
+	}
+	if got, want := mustReadTestFile(t, path), "alpha\nupdated\ngamma\n"; got != want {
+		t.Fatalf("file = %q, want %q", got, want)
+	}
+}
+
+func TestStructuredPatchPreservesWholeFileObservation(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{
+		"*** Begin Patch",
+		"*** Update File: f.txt",
+		"@@",
+		"-alpha",
+		"+updated",
+		"*** End Patch",
+		"",
+	}, "\n")
+	if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": patch}, opts); result.Status != StatusOK {
+		t.Fatalf("structured patch failed: %s", result.Output)
+	}
+	trackedPath, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !tracker.SeenWhole(trackedPath) {
+		t.Fatal("structured patch discarded an existing whole-file observation")
+	}
+	result := registry.RunWithOptions(context.Background(), "write_file", map[string]any{
+		"path": "f.txt", "content": "known overwrite\n", "overwrite": true,
+	}, opts)
+	if result.Status != StatusOK {
+		t.Fatalf("overwrite after a whole-file read was refused: %s", result.Output)
+	}
+}
+
+func TestStructuredPatchCreationCreditsSuppliedFile(t *testing.T) {
+	dir := t.TempDir()
+	registry := safetyRegistry(t, dir)
+	registry.Register(NewScopedApplyPatchTool(dir, nil))
+	tracker := NewFileTracker()
+	opts := grantedOpts(tracker)
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Add File: created.txt",
+		"+supplied",
+		"*** End Patch",
+		"",
+	}, "\n")
+	if result := registry.RunWithOptions(context.Background(), "apply_patch", map[string]any{"patch": patch}, opts); result.Status != StatusOK {
+		t.Fatalf("structured patch failed: %s", result.Output)
+	}
+	path, err := filepath.EvalSymlinks(filepath.Join(dir, "created.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !tracker.SeenWhole(path) {
+		t.Fatal("a fully supplied structured add was not credited as fully seen")
+	}
+}
+
 func TestWriteFileOverwriteRefusedWhenChangedOnDisk(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "f.txt")
@@ -26,8 +26,8 @@ func TestReadFileToolReadsLineRanges(t *testing.T) {
 	}
 	for _, want := range []string{
 		"File: notes.txt (lines 2-3 of 4)",
-		"2 | beta",
-		"3 | gamma",
+		"2→beta",
+		"3→gamma",
 	} {
 		if !strings.Contains(result.Output, want) {
 			t.Fatalf("expected output to contain %q, got %q", want, result.Output)
@@ -54,7 +54,7 @@ func TestReadFileToolReadsCanonicalLineRange(t *testing.T) {
 	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") {
+	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") {
@@ -94,7 +94,7 @@ func TestReadFileToolMixedLegacyRangesPreferLines(t *testing.T) {
 	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") {
+	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)
 	}
 }
@@ -110,7 +110,7 @@ func TestReadFileToolCombinesLegacyStartWithCanonicalLimit(t *testing.T) {
 	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") {
+	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") {
@@ -955,7 +955,7 @@ func TestReadFileToolRecoversBackwardsRange(t *testing.T) {
 	for _, want := range []string{
 		"end_line 2 was before start_line 3", // the note
 		"only line 3 was read",
-		"3 | gamma",
+		"3→gamma",
 	} {
 		if !strings.Contains(result.Output, want) {
 			t.Fatalf("expected %q in output, got %q", want, result.Output)
@@ -984,7 +984,7 @@ func TestReadFileToolValidRangeUnchangedByRecovery(t *testing.T) {
 	// Byte-for-byte: header, blank separator, the exact selected lines, and no
 	// recovery note or trailing content. An altered header/separator or a stray
 	// out-of-range line would fail this where a substring check would not.
-	const want = "File: notes.txt (lines 2-4 of 5)\n\n2 | beta\n3 | gamma\n4 | delta"
+	const want = "File: notes.txt (lines 2-4 of 5)\n\n2→beta\n3→gamma\n4→delta"
 	if result.Output != want {
 		t.Fatalf("valid-range output changed by the recovery path:\n got: %q\nwant: %q", result.Output, want)
 	}
@@ -0,0 +1,11 @@
+package tools
+
+// ModelVisible reports whether a registered tool is advertised to an agent.
+// Every registered tool is visible. edit_file (exact search/replace with a
+// uniqueness guard, CRLF and fuzzy fallbacks) was hidden for a while in favour
+// of apply_patch; head-to-head benchmarking showed that when a model misses the
+// patch grammar it degrades to whole-file rewrites, so both edit tools are
+// advertised and the prompt steers between them.
+func ModelVisible(tool Tool) bool {
+	return tool != nil
+}
@@ -0,0 +1,29 @@
+package tools
+
+import "testing"
+
+func TestToolSearchSurfacesBothEditTools(t *testing.T) {
+	registry := NewRegistry()
+	registry.Register(NewScopedEditFileTool(t.TempDir(), nil))
+	registry.Register(NewScopedApplyPatchTool(t.TempDir(), nil))
+	search := NewToolSearchTool(registry).(toolSearchTool)
+
+	eager := search.visibleEagerToolNames(nil, nil, "ask")
+	if !eager["edit_file"] {
+		t.Fatal("tool_search must describe edit_file as available to the model")
+	}
+	if !eager["apply_patch"] {
+		t.Fatal("tool_search must retain apply_patch as an available edit tool")
+	}
+}
+
+func TestModelVisibleAdvertisesEveryRegisteredTool(t *testing.T) {
+	if ModelVisible(nil) {
+		t.Fatal("a nil tool must not be visible")
+	}
+	for _, tool := range []Tool{NewScopedEditFileTool(t.TempDir(), nil), NewScopedApplyPatchTool(t.TempDir(), nil), NewScopedWriteFileTool(t.TempDir(), nil)} {
+		if !ModelVisible(tool) {
+			t.Fatalf("%s must be visible to the model", tool.Name())
+		}
+	}
+}
@@ -1,5 +1,7 @@
 package tools

+import "path/filepath"
+
 // MutationTargets returns the workspace-relative paths a tool call will write to,
 // so the session layer can snapshot their before-state for safe rewind. It is a
 // pure helper (no I/O beyond path resolution) and returns nil for read-only tools
@@ -36,6 +38,19 @@ func MutationTargets(workspaceRoot string, name string, args map[string]any) []s
 		if err != nil {
 			return nil
 		}
+		if isStructuredPatch(patch) {
+			operations, err := parseStructuredPatch(patch)
+			if err != nil {
+				return nil
+			}
+			paths := structuredPatchOperationPaths(operations)
+			for _, path := range paths {
+				if _, _, err := resolveWorkspaceTargetPath(applyRoot, path); err != nil {
+					return nil
+				}
+			}
+			return prefixPatchPaths(relativeRoot, paths)
+		}
 		// Enforce the same workspace confinement apply_patch applies (against the
 		// resolved apply dir), so a patch with a traversal path (../x) never yields
 		// an out-of-workspace target.
@@ -51,3 +66,22 @@ func MutationTargets(workspaceRoot string, name string, args map[string]any) []s
 		return nil
 	}
 }
+
+func prefixPatchPaths(relativeRoot string, paths []string) []string {
+	if len(paths) == 0 {
+		return nil
+	}
+	seen := make(map[string]bool)
+	var out []string
+	for _, path := range paths {
+		workspacePath := path
+		if relativeRoot != "" && relativeRoot != "." {
+			workspacePath = filepath.ToSlash(filepath.Join(relativeRoot, path))
+		}
+		if !seen[workspacePath] {
+			seen[workspacePath] = true
+			out = append(out, workspacePath)
+		}
+	}
+	return out
+}
@@ -17,6 +17,7 @@ func TestMutationTargets(t *testing.T) {
 		{"write_file", map[string]any{"path": "a/b.txt", "content": "x"}, []string{"a/b.txt"}},
 		{"edit_file", map[string]any{"path": "c.txt", "old_string": "x", "new_string": "y"}, []string{"c.txt"}},
 		{"apply_patch", map[string]any{"patch": "--- a/d.txt\n+++ b/d.txt\n@@ -1 +1 @@\n-x\n+y\n"}, []string{"d.txt"}},
+		{"apply_patch", map[string]any{"patch": "*** Begin Patch\n*** Add File: nested/new.txt\n+x\n*** Update File: old.txt\n*** Move to: moved.txt\n@@\n-old\n+new\n*** End Patch\n"}, []string{"nested/new.txt", "old.txt", "moved.txt"}},
 		{"bash", map[string]any{"command": "echo hi"}, nil},
 		{"read_file", map[string]any{"path": "e.txt"}, nil},
 		{"grep", map[string]any{"pattern": "x"}, nil},
@@ -62,6 +63,10 @@ func TestMutationTargetsRejectsEscapingPaths(t *testing.T) {
 	if got := MutationTargets(root, "apply_patch", map[string]any{"patch": escapePatch}); len(got) != 0 {
 		t.Errorf("expected no targets for escaping apply_patch, got %v", got)
 	}
+	structuredEscapePatch := "*** Begin Patch\n*** Add File: ../escape.txt\n+x\n*** End Patch\n"
+	if got := MutationTargets(root, "apply_patch", map[string]any{"patch": structuredEscapePatch}); len(got) != 0 {
+		t.Errorf("expected no targets for escaping structured apply_patch, got %v", got)
+	}
 }

 // Finding 3: with cwd != ".", apply_patch's MutationTargets must return
@@ -82,6 +87,12 @@ func TestMutationTargetsApplyPatchPrefixesCwd(t *testing.T) {
 		t.Fatalf("got %v, want %v", got, want)
 	}

+	structuredPatch := "*** Begin Patch\n*** Update File: d.txt\n@@\n-x\n+y\n*** End Patch\n"
+	got = MutationTargets(root, "apply_patch", map[string]any{"patch": structuredPatch, "cwd": "sub/dir"})
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("structured cwd: got %v, want %v", got, want)
+	}
+
 	// cwd "." (the default) must keep paths unprefixed.
 	got = MutationTargets(root, "apply_patch", map[string]any{"patch": patch, "cwd": "."})
 	if !reflect.DeepEqual(got, []string{"d.txt"}) {
@@ -9,6 +9,9 @@ import (

 func TestUpdatePlanToolStoresAndFormatsPlan(t *testing.T) {
 	tool := NewUpdatePlanTool()
+	if description := strings.ToLower(tool.Description()); !strings.Contains(description, "skip it for bounded changes in one component") {
+		t.Fatalf("update_plan description must preserve the bounded-task fast path: %q", description)
+	}

 	result := tool.Run(context.Background(), map[string]any{
 		"plan": []any{
@@ -9,12 +9,14 @@ import (
 	"io"
 	"os"
 	"strconv"
-	"strings"
 	"unicode/utf8"
 )

 const readFileByteChunkMax = 64 * 1024

+// readFileLinePrefixSeparator follows the line number on every read_file line.
+const readFileLinePrefixSeparator = "→"
+
 type readFileTool struct {
 	baseTool
 	workspaceRoot string
@@ -31,7 +33,7 @@ func NewScopedReadFileTool(workspaceRoot string, scope PathScope) Tool {
 	return readFileTool{
 		baseTool: baseTool{
 			name:        "read_file",
-			description: "Read exact file text with line numbers. Use for comments, formatting, or edits; prefer read_minified_file for initial code understanding. Use offset and limit for a line range.",
+			description: "Read exact file text, each line prefixed with its line number and →. Use directly for small files likely to be edited, or when comments, formatting, or line numbers matter. Prefer read_minified_file only for exploratory understanding of large or unfamiliar code. Use offset and limit for a line range.",
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
@@ -221,7 +223,6 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 	}

 	lastLine := startLine + selectedLines - 1
-	width := len(strconv.Itoa(lastLine))
 	header := fmt.Sprintf("File: %s (%d lines)", relativePath, total)
 	if startLine != 1 || endLine != total || maxLines > 0 {
 		header = fmt.Sprintf("File: %s (lines %d-%d of %d)", relativePath, startLine, lastLine, total)
@@ -244,7 +245,7 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 		budgetedOutput.WriteString("\n")
 	}
 	budgetedOutput.WriteString("\n")
-	if err := appendReadFileRange(budgetedOutput, absolutePath, startLine, selectedLines, width); err != nil {
+	if err := appendReadFileRange(budgetedOutput, absolutePath, startLine, selectedLines); err != nil {
 		return errorResult("Error reading file " + relativePath + ": " + err.Error())
 	}
 	if truncated {
@@ -357,7 +358,7 @@ func renderReadFileBytes(path, relativePath string, total, requestedStart, limit
 	return Result{Status: StatusOK, Output: output, Meta: map[string]string{"next_byte_offset": strconv.Itoa(end)}}, start, end
 }

-func appendReadFileRange(output *outputBudgetBuilder, path string, startLine int, selectedLines int, width int) error {
+func appendReadFileRange(output *outputBudgetBuilder, path string, startLine int, selectedLines int) error {
 	file, err := os.Open(path)
 	if err != nil {
 		return err
@@ -380,10 +381,11 @@ func appendReadFileRange(output *outputBudgetBuilder, path string, startLine int
 			if emitted > 0 {
 				output.WriteString("\n")
 			}
-			number := strconv.Itoa(lineNumber)
-			output.WriteString(strings.Repeat(" ", width-len(number)))
-			output.WriteString(number)
-			output.WriteString(" | ")
+			// Compact "N→" prefix: the padded "  N | " form cost ~19% of every
+			// read (about 1.5k tokens per 800-line file) and was re-sent on each
+			// later call; no consumer parses it, and models read "N→" natively.
+			output.WriteString(strconv.Itoa(lineNumber))
+			output.WriteString(readFileLinePrefixSeparator)
 			output.WriteString(string(trimLineBreak(raw, ended)))
 			emitted++
 		}
@@ -28,7 +28,7 @@ func NewScopedReadMinifiedFileTool(workspaceRoot string, scope PathScope) Tool {
 	return readMinifiedFileTool{
 		baseTool: baseTool{
 			name:        "read_minified_file",
-			description: "Read source code in a token-efficient, language-aware form. Prefer this for initial understanding; use read_file for exact text or line numbers.",
+			description: "Read source code in a token-efficient, language-aware form. Use for exploratory understanding of large or unfamiliar source when no exact edit is planned; use read_file directly for likely edit targets. Do not immediately reread the same file exactly unless a new need for exact text or line numbers appears.",
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
@@ -171,14 +171,9 @@ func selectSourceLines(content []byte, offset, limit int) sourceSelection {
 }

 func sourceLineCount(content []byte) int {
-	if len(content) == 0 {
-		return 1
-	}
-	lines := strings.Count(string(content), "\n")
-	if content[len(content)-1] != '\n' {
-		lines++
-	}
-	return lines
+	// One implementation for reader and writer: the tracker contract lives on
+	// trackedLineTotal, and this must never drift from it.
+	return trackedLineTotal(string(content))
 }

 // lineCount reports the number of newline-separated lines in s (an empty string
@@ -189,3 +184,20 @@ func lineCount(s string) int {
 	}
 	return strings.Count(s, "\n") + 1
 }
+
+// trackedLineTotal reports a file's line count the way read_file reports it
+// to the FileTracker (newline-terminated lines, plus an unterminated last
+// line; an empty file is one line). Writers must record this same number:
+// RecordSeenRange resets every observation when the total changes, so a
+// writer that recorded lineCount (one higher for a trailing newline) made the
+// next partial read_file wipe whole-file knowledge and refuse the next edit.
+func trackedLineTotal(s string) int {
+	if s == "" {
+		return 1
+	}
+	total := strings.Count(s, "\n")
+	if !strings.HasSuffix(s, "\n") {
+		total++
+	}
+	return total
+}
@@ -8,6 +8,29 @@ import (
 	"testing"
 )

+func TestReadToolsDescribeExploratoryAndExactUseWithoutRedundantRereads(t *testing.T) {
+	root := t.TempDir()
+	minified := strings.ToLower(NewScopedReadMinifiedFileTool(root, nil).Description())
+	for _, want := range []string{
+		"exploratory understanding",
+		"use read_file directly for likely edit targets",
+		"unless a new need for exact text or line numbers appears",
+	} {
+		if !strings.Contains(minified, want) {
+			t.Fatalf("read_minified_file description missing %q: %s", want, minified)
+		}
+	}
+	exact := strings.ToLower(NewScopedReadFileTool(root, nil).Description())
+	for _, want := range []string{
+		"use directly for small files likely to be edited",
+		"prefer read_minified_file only for exploratory understanding",
+	} {
+		if !strings.Contains(exact, want) {
+			t.Fatalf("read_file description missing %q: %s", want, exact)
+		}
+	}
+}
+
 func TestReadMinifiedFileStripsCommentsAndLineNumbers(t *testing.T) {
 	dir := t.TempDir()
 	src := "package demo\n\nimport \"fmt\"\n\n// secret doc comment\nfunc F() { fmt.Println(\"x\") }\n"
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+	"sync"

 	"github.com/Gitlawb/zero/internal/redaction"
 	"github.com/Gitlawb/zero/internal/sandbox"
@@ -12,7 +13,17 @@ import (
 )

 type Registry struct {
-	tools map[string]Tool
+	mu         sync.RWMutex
+	tools      map[string]Tool
+	generation uint64
+}
+
+// RegistrySnapshot is one immutable registry generation. Tools is a detached,
+// name-sorted slice: later registrations cannot change the snapshot observed by
+// an in-flight agent turn.
+type RegistrySnapshot struct {
+	Tools      []Tool
+	Generation uint64
 }

 type RunOptions struct {
@@ -107,23 +118,69 @@ func IsDeferralEligible(t Tool) bool {
 }

 func (registry *Registry) Register(tool Tool) {
+	registry.mu.Lock()
+	defer registry.mu.Unlock()
 	registry.tools[tool.Name()] = tool
+	registry.generation++
+}
+
+// RegisterBatch publishes a group of tools as one registry generation. Readers
+// observe either the complete prior generation or the complete new one.
+func (registry *Registry) RegisterBatch(batch []Tool) {
+	if len(batch) == 0 {
+		return
+	}
+	registry.mu.Lock()
+	defer registry.mu.Unlock()
+	for _, tool := range batch {
+		registry.tools[tool.Name()] = tool
+	}
+	registry.generation++
 }

 func (registry *Registry) Get(name string) (Tool, bool) {
+	registry.mu.RLock()
+	defer registry.mu.RUnlock()
 	tool, ok := registry.tools[name]
 	return tool, ok
 }

 func (registry *Registry) All() []Tool {
+	return registry.Snapshot().Tools
+}
+
+// Snapshot returns a stable, sorted view of the registry at one generation.
+func (registry *Registry) Snapshot() RegistrySnapshot {
+	registry.mu.RLock()
 	tools := make([]Tool, 0, len(registry.tools))
 	for _, tool := range registry.tools {
 		tools = append(tools, tool)
 	}
+	generation := registry.generation
+	registry.mu.RUnlock()
 	sort.Slice(tools, func(left, right int) bool {
 		return tools[left].Name() < tools[right].Name()
 	})
-	return tools
+	return RegistrySnapshot{Tools: tools, Generation: generation}
+}
+
+// Clone returns an independent registry containing exactly one source snapshot.
+func (registry *Registry) Clone() *Registry {
+	clone := NewRegistry()
+	if registry == nil {
+		return clone
+	}
+	snapshot := registry.Snapshot()
+	clonedTools := make([]Tool, 0, len(snapshot.Tools))
+	for _, tool := range snapshot.Tools {
+		if cloner, ok := tool.(interface{ cloneForRegistry(*Registry) Tool }); ok {
+			tool = cloner.cloneForRegistry(clone)
+		}
+		clonedTools = append(clonedTools, tool)
+	}
+	clone.RegisterBatch(clonedTools)
+	clone.generation = snapshot.Generation
+	return clone
 }

 func (registry *Registry) Run(ctx context.Context, name string, args map[string]any) Result {
@@ -2,10 +2,12 @@ package tools

 import (
 	"context"
+	"fmt"
 	"os"
 	"path/filepath"
 	"slices"
 	"strings"
+	"sync"
 	"testing"

 	"github.com/Gitlawb/zero/internal/sandbox"
@@ -95,6 +97,81 @@ func TestRegistryAllReturnsToolsSortedByName(t *testing.T) {
 	}
 }

+func TestRegistrySnapshotAndCloneStayOnOneGeneration(t *testing.T) {
+	registry := NewRegistry()
+	registry.Register(fakePlainTool{baseTool: baseTool{name: "alpha", description: "alpha"}})
+	first := registry.Snapshot()
+
+	registry.RegisterBatch([]Tool{
+		fakePlainTool{baseTool: baseTool{name: "charlie", description: "charlie"}},
+		fakePlainTool{baseTool: baseTool{name: "bravo", description: "bravo"}},
+	})
+	second := registry.Snapshot()
+	clone := registry.Clone()
+	registry.Register(fakePlainTool{baseTool: baseTool{name: "delta", description: "delta"}})
+
+	if got := toolNames(first.Tools); !slices.Equal(got, []string{"alpha"}) {
+		t.Fatalf("first snapshot changed after registration: %v", got)
+	}
+	if second.Generation != first.Generation+1 {
+		t.Fatalf("batch generation = %d, want %d", second.Generation, first.Generation+1)
+	}
+	if got := toolNames(second.Tools); !slices.Equal(got, []string{"alpha", "bravo", "charlie"}) {
+		t.Fatalf("second snapshot tools = %v", got)
+	}
+	if got := toolNames(clone.All()); !slices.Equal(got, toolNames(second.Tools)) {
+		t.Fatalf("clone changed with source registry: %v", got)
+	}
+	if clone.Snapshot().Generation != second.Generation {
+		t.Fatalf("clone generation = %d, want %d", clone.Snapshot().Generation, second.Generation)
+	}
+}
+
+func TestRegistryBatchIsAtomicForConcurrentReaders(t *testing.T) {
+	registry := NewRegistry()
+	registry.Register(fakePlainTool{baseTool: baseTool{name: "base", description: "base"}})
+	batch := make([]Tool, 128)
+	for index := range batch {
+		name := fmt.Sprintf("tool_%03d", index)
+		batch[index] = fakePlainTool{baseTool: baseTool{name: name, description: name}}
+	}
+
+	start := make(chan struct{})
+	done := make(chan struct{})
+	var readers sync.WaitGroup
+	for range 4 {
+		readers.Add(1)
+		go func() {
+			defer readers.Done()
+			<-start
+			for {
+				count := len(registry.Snapshot().Tools)
+				if count != 1 && count != len(batch)+1 {
+					t.Errorf("reader observed partial batch with %d tools", count)
+					return
+				}
+				select {
+				case <-done:
+					return
+				default:
+				}
+			}
+		}()
+	}
+	close(start)
+	registry.RegisterBatch(batch)
+	close(done)
+	readers.Wait()
+}
+
+func toolNames(toolset []Tool) []string {
+	names := make([]string, 0, len(toolset))
+	for _, tool := range toolset {
+		names = append(names, tool.Name())
+	}
+	return names
+}
+
 func TestCoreNetworkToolsExposeSafetyMetadata(t *testing.T) {
 	// web_search is only registered when a backend is configured.
 	t.Setenv("ZERO_WEBSEARCH_BASE_URL", "https://search.example/api")
@@ -178,7 +178,7 @@ func applyPatchResourceKeys(args map[string]any) []string {
 	keys = append(keys, multiFileResourceKeys(args)...)
 	cwd := firstStringArg(args, "cwd", "workdir")
 	patch := firstStringArg(args, "patch", "diff")
-	for _, p := range pathsFromUnifiedDiff(patch) {
+	for _, p := range pathsFromApplyPatch(patch) {
 		joined := joinUnderResourceCwd(cwd, p)
 		if n := NormalizeResourcePath(joined); n != "" {
 			keys = append(keys, ResourceKeyFile+n)
@@ -191,6 +191,17 @@ func applyPatchResourceKeys(args map[string]any) []string {
 	return keys
 }

+func pathsFromApplyPatch(patch string) []string {
+	if !isStructuredPatch(patch) {
+		return pathsFromUnifiedDiff(patch)
+	}
+	operations, err := parseStructuredPatch(patch)
+	if err != nil {
+		return nil
+	}
+	return structuredPatchOperationPaths(operations)
+}
+
 // joinUnderResourceCwd joins a relative path under cwd for resource keys only.
 // Absolute paths are left unchanged. Empty cwd or "." leaves rel as-is.
 // Never touches the filesystem.
@@ -0,0 +1,959 @@
+package tools
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/pathjail"
+	"github.com/Gitlawb/zero/internal/sandbox"
+)
+
+const (
+	structuredPatchBegin  = "*** Begin Patch"
+	structuredPatchEnd    = "*** End Patch"
+	structuredAddFile     = "*** Add File: "
+	structuredDeleteFile  = "*** Delete File: "
+	structuredUpdateFile  = "*** Update File: "
+	structuredMoveTo      = "*** Move to: "
+	structuredEndOfFile   = "*** End of File"
+	structuredHunkContext = "@@ "
+)
+
+type structuredPatchKind uint8
+
+const (
+	structuredPatchAdd structuredPatchKind = iota
+	structuredPatchDelete
+	structuredPatchUpdate
+	// structuredPatchCopy creates movePath from path's content (plus any
+	// hunks) and keeps path; produced by a unified diff's "copy from/to".
+	structuredPatchCopy
+)
+
+type structuredPatchOperation struct {
+	kind     structuredPatchKind
+	path     string
+	movePath string
+	contents string
+	chunks   []structuredPatchChunk
+	line     int
+	// eofNewline lets a unified diff's "\ No newline at end of file" marker
+	// force the trailing-newline state of the result; structured patches keep
+	// the file's existing state.
+	eofNewline eofNewlineMode
+	// verifyDelete marks a deletion that carries the expected old content
+	// (a unified diff's "+++ /dev/null" hunks, or git's header-only form for
+	// an empty file): the removed lines must equal the current file byte for
+	// byte, otherwise the deletion is stale and refused. A structured
+	// "*** Delete File" means "delete this path" and has no chunks.
+	verifyDelete bool
+	// oldNoNewline records a unified diff's "\ No newline at end of file"
+	// on the removed side, i.e. the old content did not end with a newline.
+	oldNoNewline bool
+}
+
+type eofNewlineMode uint8
+
+const (
+	eofNewlineKeep eofNewlineMode = iota
+	eofNewlinePresent
+	eofNewlineAbsent
+)
+
+type structuredPatchChunk struct {
+	context          string
+	hasContext       bool
+	old              []string
+	new              []string
+	newSourceOffsets []int
+	endOfFile        bool
+	// hint is the 0-based line the hunk is expected at (from a unified diff's
+	// "@@ -a,b" range). When the expected lines match there it is used as-is;
+	// otherwise the hunk is located by content like a structured hunk.
+	hint    int
+	hasHint bool
+}
+
+type structuredPatchTarget struct {
+	requested string
+	absolute  string
+	relative  string
+}
+
+type structuredPatchChange struct {
+	kind   structuredPatchKind
+	from   structuredPatchTarget
+	to     structuredPatchTarget
+	before string
+	after  string
+	mode   os.FileMode
+}
+
+// unifiedHunkRangePattern recognises a unified-diff range header ("-12,4 +12,6",
+// optionally followed by "@@ heading") written inside a structured hunk marker.
+// The line numbers carry no information for the context-anchored grammar, so
+// the range is dropped and only an explicit heading is kept as the anchor.
+var unifiedHunkRangePattern = regexp.MustCompile(`^-\d+(?:,\d+)?\s+\+\d+(?:,\d+)?\s*(?:@@\s*(.*))?$`)
+
+const structuredPatchFormatHint = ` (format: "*** Begin Patch", then "*** Update File: path" / "*** Add File: path" / "*** Delete File: path" sections whose hunks start with "@@" and use " " context, "-" removed and "+" added lines, then "*** End Patch")`
+
+// structuredPatchMarker classifies a line as the "begin" or "end" marker of a
+// structured patch, or "" when it is neither. The classifier is owned by the
+// sandbox package so the boundary check and the tool accept exactly the same
+// spellings; a strict byte-equal match here once made every patch from some
+// models fail on line 1 and pushed them into whole-file rewrites.
+func structuredPatchMarker(line string) string {
+	return sandbox.StructuredPatchMarker(line)
+}
+
+// structuredHunkAnchor normalises the text after a hunk's "@@ " marker. A
+// unified-diff range is dropped (its optional heading survives as the anchor);
+// anything else is used verbatim.
+func structuredHunkAnchor(context string) string {
+	context = strings.TrimSpace(context)
+	if match := unifiedHunkRangePattern.FindStringSubmatch(context); match != nil {
+		return strings.TrimSpace(match[1])
+	}
+	return context
+}
+
+func isStructuredPatch(patch string) bool {
+	return sandbox.IsStructuredPatch(patch)
+}
+
+func (tool applyPatchTool) runStructuredPatch(applyRoot, relativeRoot, patch string, options RunOptions) Result {
+	operations, err := parseStructuredPatch(patch)
+	if err != nil {
+		return errorResult("Error applying patch: " + err.Error())
+	}
+	return applyPatchOperations(applyRoot, relativeRoot, operations, options)
+}
+
+// applyPatchOperations applies parsed operations (from either patch format)
+// through an opened workspace root: every stat, read, create and write is
+// descriptor-relative and refuses to follow a link out of the root, so there
+// is no pathname check-to-use window between validation and write.
+func applyPatchOperations(applyRoot, relativeRoot string, operations []structuredPatchOperation, options RunOptions) Result {
+	workspace, err := os.OpenRoot(applyRoot)
+	if err != nil {
+		return errorResult("Error applying patch: " + err.Error())
+	}
+	defer workspace.Close()
+	changes, err := planStructuredPatch(workspace, operations, options.FileTracker)
+	if err != nil {
+		return errorResult("Error applying patch: " + err.Error())
+	}
+	wholeBefore := make(map[string]bool, len(changes))
+	if options.FileTracker != nil {
+		for _, change := range changes {
+			if change.kind == structuredPatchUpdate || change.kind == structuredPatchCopy {
+				wholeBefore[change.from.absolute] = options.FileTracker.SeenWhole(change.from.absolute)
+			}
+		}
+	}
+	if err := applyStructuredPatchChanges(workspace, changes, options.FileTracker); err != nil {
+		return errorResult("Error applying patch: " + err.Error())
+	}
+
+	for _, change := range changes {
+		switch change.kind {
+		case structuredPatchDelete:
+			options.FileTracker.Forget(change.from.absolute)
+		case structuredPatchAdd:
+			recordStructuredPatchFile(options.FileTracker, change.to.absolute, true, true)
+		case structuredPatchUpdate:
+			wasWhole := wholeBefore[change.from.absolute]
+			options.FileTracker.Forget(change.from.absolute)
+			recordStructuredPatchFile(options.FileTracker, change.to.absolute, false, wasWhole)
+		case structuredPatchCopy:
+			// The source is untouched; the destination inherits only what the
+			// model had actually seen of the source.
+			recordStructuredPatchFile(options.FileTracker, change.to.absolute, true, wholeBefore[change.from.absolute])
+		}
+	}
+
+	summary := "Patch applied successfully."
+	if relativeRoot != "." {
+		summary = "Patch applied successfully in " + relativeRoot + "."
+	}
+	result := okResult(summary)
+	result.ChangedFiles = changedFilesFromStructuredPatch(relativeRoot, changes)
+	result.Display = Display{Summary: summary, Kind: "diff", Preview: structuredPatchPreview(changes)}
+	return result
+}
+
+func parseStructuredPatch(patch string) ([]structuredPatchOperation, error) {
+	normalized := strings.TrimSpace(strings.TrimPrefix(strings.ReplaceAll(patch, "\r\n", "\n"), "\ufeff"))
+	if normalized == "" {
+		return nil, fmt.Errorf("structured patch is empty")
+	}
+	lines := strings.Split(normalized, "\n")
+	if structuredPatchMarker(lines[0]) != "begin" {
+		return nil, fmt.Errorf("the first line of a structured patch must be %q%s", structuredPatchBegin, structuredPatchFormatHint)
+	}
+	if structuredPatchMarker(lines[len(lines)-1]) != "end" {
+		return nil, fmt.Errorf("the last line of a structured patch must be %q%s", structuredPatchEnd, structuredPatchFormatHint)
+	}
+
+	var operations []structuredPatchOperation
+	for index := 1; index < len(lines)-1; {
+		header := strings.TrimSpace(lines[index])
+		lineNumber := index + 1
+		if header == "" {
+			index++
+			continue
+		}
+		switch {
+		case strings.HasPrefix(header, structuredAddFile):
+			path, err := structuredPatchPath(header, structuredAddFile, lineNumber)
+			if err != nil {
+				return nil, err
+			}
+			op := structuredPatchOperation{kind: structuredPatchAdd, path: path, line: lineNumber}
+			index++
+			var content []string
+			for index < len(lines)-1 && !isStructuredPatchHeader(lines[index]) {
+				if !strings.HasPrefix(lines[index], "+") {
+					return nil, structuredPatchLineError(index+1, "added-file contents must start with '+'")
+				}
+				content = append(content, strings.TrimPrefix(lines[index], "+"))
+				index++
+			}
+			if len(content) > 0 {
+				op.contents = strings.Join(content, "\n") + "\n"
+			}
+			operations = append(operations, op)
+		case strings.HasPrefix(header, structuredDeleteFile):
+			path, err := structuredPatchPath(header, structuredDeleteFile, lineNumber)
+			if err != nil {
+				return nil, err
+			}
+			operations = append(operations, structuredPatchOperation{kind: structuredPatchDelete, path: path, line: lineNumber})
+			index++
+		case strings.HasPrefix(header, structuredUpdateFile):
+			path, err := structuredPatchPath(header, structuredUpdateFile, lineNumber)
+			if err != nil {
+				return nil, err
+			}
+			op := structuredPatchOperation{kind: structuredPatchUpdate, path: path, line: lineNumber}
+			index++
+			if index < len(lines)-1 && strings.HasPrefix(strings.TrimSpace(lines[index]), structuredMoveTo) {
+				op.movePath, err = structuredPatchPath(strings.TrimSpace(lines[index]), structuredMoveTo, index+1)
+				if err != nil {
+					return nil, err
+				}
+				index++
+			}
+			for index < len(lines)-1 && !isStructuredPatchHeader(lines[index]) {
+				line := lines[index]
+				trimmed := strings.TrimSpace(line)
+				if trimmed == structuredEndOfFile {
+					if len(op.chunks) == 0 || (!hasStructuredPatchContent(op.chunks[len(op.chunks)-1])) {
+						return nil, structuredPatchLineError(index+1, "*** End of File must follow an update hunk")
+					}
+					op.chunks[len(op.chunks)-1].endOfFile = true
+					index++
+					continue
+				}
+				if trimmed == "@@" || strings.HasPrefix(trimmed, structuredHunkContext) {
+					chunk := structuredPatchChunk{}
+					rest := ""
+					if trimmed != "@@" {
+						rest = strings.TrimPrefix(trimmed, structuredHunkContext)
+					}
+					if anchor := structuredHunkAnchor(rest); anchor != "" {
+						chunk.context = anchor
+						chunk.hasContext = true
+					}
+					op.chunks = append(op.chunks, chunk)
+					index++
+					continue
+				}
+				if len(op.chunks) == 0 {
+					op.chunks = append(op.chunks, structuredPatchChunk{})
+				}
+				chunk := &op.chunks[len(op.chunks)-1]
+				switch {
+				case line == "":
+					sourceOffset := len(chunk.old)
+					chunk.old = append(chunk.old, "")
+					chunk.new = append(chunk.new, "")
+					chunk.newSourceOffsets = append(chunk.newSourceOffsets, sourceOffset)
+				case strings.HasPrefix(line, " "):
+					content := strings.TrimPrefix(line, " ")
+					sourceOffset := len(chunk.old)
+					chunk.old = append(chunk.old, content)
+					chunk.new = append(chunk.new, content)
+					chunk.newSourceOffsets = append(chunk.newSourceOffsets, sourceOffset)
+				case strings.HasPrefix(line, "+"):
+					chunk.new = append(chunk.new, strings.TrimPrefix(line, "+"))
+					chunk.newSourceOffsets = append(chunk.newSourceOffsets, -1)
+				case strings.HasPrefix(line, "-"):
+					chunk.old = append(chunk.old, strings.TrimPrefix(line, "-"))
+				default:
+					return nil, structuredPatchLineError(index+1, "update lines must start with ' ', '+', or '-'")
+				}
+				index++
+			}
+			if len(op.chunks) == 0 || !allStructuredPatchChunksHaveContent(op.chunks) {
+				return nil, structuredPatchLineError(lineNumber, "update file hunk is empty")
+			}
+			operations = append(operations, op)
+		default:
+			return nil, structuredPatchLineError(lineNumber, "expected an Add File, Delete File, or Update File header")
+		}
+	}
+	if len(operations) == 0 {
+		return nil, fmt.Errorf("structured patch contains no file operations")
+	}
+	return operations, nil
+}
+
+func structuredPatchPath(header, prefix string, line int) (string, error) {
+	path := strings.TrimSpace(strings.TrimPrefix(header, prefix))
+	if path == "" {
+		return "", structuredPatchLineError(line, "file path is required")
+	}
+	return path, nil
+}
+
+func isStructuredPatchHeader(line string) bool {
+	return structuredPatchMarker(line) == "end" || strings.HasPrefix(line, structuredAddFile) || strings.HasPrefix(line, structuredDeleteFile) || strings.HasPrefix(line, structuredUpdateFile)
+}
+
+func structuredPatchLineError(line int, message string) error {
+	return fmt.Errorf("invalid structured patch at line %d: %s", line, message)
+}
+
+func hasStructuredPatchContent(chunk structuredPatchChunk) bool {
+	return len(chunk.old) > 0 || len(chunk.new) > 0
+}
+
+func allStructuredPatchChunksHaveContent(chunks []structuredPatchChunk) bool {
+	for _, chunk := range chunks {
+		if !hasStructuredPatchContent(chunk) {
+			return false
+		}
+	}
+	return true
+}
+
+func structuredPatchOperationPaths(operations []structuredPatchOperation) []string {
+	seen := make(map[string]bool)
+	var paths []string
+	for _, operation := range operations {
+		for _, path := range []string{operation.path, operation.movePath} {
+			if path == "" || seen[path] {
+				continue
+			}
+			seen[path] = true
+			paths = append(paths, path)
+		}
+	}
+	return paths
+}
+
+func planStructuredPatch(root *os.Root, operations []structuredPatchOperation, tracker *FileTracker) ([]structuredPatchChange, error) {
+	seen := make(map[string]struct{})
+	var changes []structuredPatchChange
+	for _, operation := range operations {
+		from, err := resolveStructuredPatchTarget(root.Name(), operation.path)
+		if err != nil {
+			return nil, err
+		}
+		to := from
+		if operation.movePath != "" {
+			to, err = resolveStructuredPatchTarget(root.Name(), operation.movePath)
+			if err != nil {
+				return nil, err
+			}
+		}
+		targets := []structuredPatchTarget{from}
+		if to.absolute != from.absolute {
+			targets = append(targets, to)
+		}
+		for _, target := range targets {
+			if _, exists := seen[target.absolute]; exists {
+				return nil, fmt.Errorf("structured patch changes %q more than once", target.relative)
+			}
+			seen[target.absolute] = struct{}{}
+		}
+
+		change := structuredPatchChange{kind: operation.kind, from: from, to: to, mode: 0o644}
+		switch operation.kind {
+		case structuredPatchAdd:
+			if _, err := root.Lstat(to.relative); err == nil {
+				return nil, fmt.Errorf("cannot add %s because it already exists", to.relative)
+			} else if !os.IsNotExist(err) {
+				return nil, err
+			}
+			change.after = operation.contents
+		case structuredPatchDelete, structuredPatchUpdate, structuredPatchCopy:
+			info, err := root.Stat(from.relative)
+			if err != nil {
+				return nil, fmt.Errorf("stating %s: %w", from.relative, err)
+			}
+			change.mode = info.Mode()
+			content, err := root.ReadFile(from.relative)
+			if err != nil {
+				return nil, fmt.Errorf("reading %s: %w", from.relative, err)
+			}
+			if err := tracker.CheckConflict(from.absolute, content); err != nil {
+				return nil, fmt.Errorf("%s", fileConflictMessage(from.relative))
+			}
+			change.before = string(content)
+			if operation.kind == structuredPatchDelete && operation.verifyDelete {
+				if err := verifyUnifiedDeletion(change.before, from.relative, operation); err != nil {
+					return nil, err
+				}
+			}
+			if operation.kind == structuredPatchUpdate || operation.kind == structuredPatchCopy {
+				updated, err := applyStructuredPatchUpdate(change.before, from.relative, operation.chunks)
+				if err != nil {
+					return nil, err
+				}
+				change.after = applyEOFNewline(updated, operation.eofNewline)
+				if operation.kind == structuredPatchCopy && from.absolute == to.absolute {
+					return nil, fmt.Errorf("cannot copy %s onto itself", from.relative)
+				}
+				if from.absolute != to.absolute {
+					if _, err := root.Lstat(to.relative); err == nil {
+						return nil, fmt.Errorf("cannot move %s to %s because the destination already exists", from.relative, to.relative)
+					} else if !os.IsNotExist(err) {
+						return nil, err
+					}
+				}
+			}
+		}
+		changes = append(changes, change)
+	}
+	return changes, nil
+}
+
+func resolveStructuredPatchTarget(root, path string) (structuredPatchTarget, error) {
+	// Relative traversal is rejected outright. An absolute path is allowed when
+	// it resolves inside the apply root (models routinely echo the absolute path
+	// they were shown by read_file); resolveWorkspaceTargetPath rejects anything
+	// that lands outside.
+	if path == ".." || strings.HasPrefix(filepath.ToSlash(path), "../") {
+		return structuredPatchTarget{}, fmt.Errorf("patch path %q must stay inside the workspace", path)
+	}
+	absolute, relative, err := resolveWorkspaceTargetPath(root, normalizePatchPathForRoot(root, path))
+	if err != nil {
+		return structuredPatchTarget{}, err
+	}
+	return structuredPatchTarget{requested: path, absolute: absolute, relative: relative}, nil
+}
+
+func applyStructuredPatchUpdate(content, path string, chunks []structuredPatchChunk) (string, error) {
+	lineEnding := structuredPatchLineEnding(content)
+	if lineEnding == "\r\n" {
+		content = strings.ReplaceAll(content, "\r\n", "\n")
+	}
+	lines := strings.Split(content, "\n")
+	trailingNewline := content != "" && len(lines) > 0 && lines[len(lines)-1] == ""
+	if len(lines) > 0 && lines[len(lines)-1] == "" {
+		lines = lines[:len(lines)-1]
+	}
+	replacements := make([]structuredReplacement, 0, len(chunks))
+	lineIndex := 0
+	for _, chunk := range chunks {
+		if chunk.hasContext {
+			index, ambiguous := findStructuredPatchSequence(lines, []string{chunk.context}, lineIndex, false)
+			if ambiguous {
+				return "", fmt.Errorf("context %q is ambiguous in %s; provide a more specific hunk header", chunk.context, path)
+			}
+			if index < 0 {
+				return "", fmt.Errorf("could not find context %q in %s", chunk.context, path)
+			}
+			lineIndex = index + 1
+		}
+		if len(chunk.old) == 0 {
+			// A context anchor identifies the line immediately before a pure
+			// insertion. Only an explicit end-of-file hunk (or an unanchored
+			// insertion) belongs at the file end. A unified diff names the
+			// insertion point in its range instead; a zero-context hunk (as
+			// from `git diff -U0`) has nothing to verify the position against,
+			// so it is position-trusting by design — the same semantics git
+			// apply uses without fuzz. Hunks that carry context are verified.
+			start := lineIndex
+			if chunk.hasHint {
+				start = max(chunk.hint, lineIndex)
+			} else if chunk.endOfFile || !chunk.hasContext {
+				start = len(lines)
+			}
+			if start > len(lines) {
+				start = len(lines)
+			}
+			replacement, err := structuredPatchReplacement(chunk, lines, start)
+			if err != nil {
+				return "", fmt.Errorf("building replacement for %s: %w", path, err)
+			}
+			replacements = append(replacements, structuredReplacement{start: start, replacement: replacement})
+			lineIndex = start
+			continue
+		}
+		var index int
+		ambiguous := false
+		if chunk.hasHint && chunk.hint >= lineIndex && sequenceMatchesAt(lines, chunk.old, chunk.hint) {
+			index = chunk.hint
+		} else {
+			index, ambiguous = findStructuredPatchSequence(lines, chunk.old, lineIndex, chunk.endOfFile)
+		}
+		if ambiguous {
+			return "", fmt.Errorf("expected lines are ambiguous in %s; provide more surrounding context:\n%s", path, strings.Join(chunk.old, "\n"))
+		}
+		if index < 0 {
+			return "", fmt.Errorf("could not find expected lines in %s:\n%s", path, strings.Join(chunk.old, "\n"))
+		}
+		replacement, err := structuredPatchReplacement(chunk, lines, index)
+		if err != nil {
+			return "", fmt.Errorf("building replacement for %s: %w", path, err)
+		}
+		replacements = append(replacements, structuredReplacement{start: index, length: len(chunk.old), replacement: replacement})
+		lineIndex = index + len(chunk.old)
+	}
+	for index := 1; index < len(replacements); index++ {
+		previous := replacements[index-1]
+		current := replacements[index]
+		if current.start < previous.start+previous.length {
+			return "", fmt.Errorf("overlapping or out-of-order hunks in %s; provide non-overlapping context", path)
+		}
+	}
+	for index := len(replacements) - 1; index >= 0; index-- {
+		replacement := replacements[index]
+		lines = append(lines[:replacement.start], append(replacement.replacement, lines[replacement.start+replacement.length:]...)...)
+	}
+	if len(lines) == 0 {
+		return "", nil
+	}
+	updated := strings.Join(lines, lineEnding)
+	if trailingNewline {
+		updated += lineEnding
+	}
+	return updated, nil
+}
+
+// verifyUnifiedDeletion checks, byte for byte, that the lines a unified
+// deletion removes are exactly the file's current content. A deletion is not
+// recoverable, so none of the whitespace tolerance used to locate update
+// hunks applies here; only the file's own line-ending style is normalised.
+// With no hunks (git's header-only form) the file must be empty.
+func verifyUnifiedDeletion(current, path string, operation structuredPatchOperation) error {
+	var removed []string
+	for _, chunk := range operation.chunks {
+		if len(chunk.new) > 0 {
+			return fmt.Errorf("deletion of %s must not add lines", path)
+		}
+		removed = append(removed, chunk.old...)
+	}
+	expected := strings.Join(removed, "\n")
+	if len(removed) > 0 && !operation.oldNoNewline {
+		expected += "\n"
+	}
+	actual := current
+	if structuredPatchLineEnding(current) == "\r\n" {
+		actual = strings.ReplaceAll(current, "\r\n", "\n")
+	}
+	if actual != expected {
+		if len(removed) == 0 {
+			return fmt.Errorf("deletion of %s expects an empty file but it has content; include the removed lines in the patch", path)
+		}
+		return fmt.Errorf("deletion of %s does not match its current content; the removed lines must equal the whole file", path)
+	}
+	return nil
+}
+
+// sequenceMatchesAt reports whether wanted appears verbatim at lines[start:].
+func sequenceMatchesAt(lines, wanted []string, start int) bool {
+	if start < 0 || start+len(wanted) > len(lines) {
+		return false
+	}
+	for offset, line := range wanted {
+		if lines[start+offset] != line {
+			return false
+		}
+	}
+	return true
+}
+
+// applyEOFNewline forces or strips a single trailing line ending when a
+// unified diff's end-of-file marker asked for it.
+func applyEOFNewline(content string, mode eofNewlineMode) string {
+	switch mode {
+	case eofNewlinePresent:
+		if content != "" && !strings.HasSuffix(content, "\n") {
+			return content + structuredPatchLineEnding(content)
+		}
+	case eofNewlineAbsent:
+		content = strings.TrimSuffix(content, "\n")
+		content = strings.TrimSuffix(content, "\r")
+	}
+	return content
+}
+
+func structuredPatchReplacement(chunk structuredPatchChunk, source []string, start int) ([]string, error) {
+	if len(chunk.newSourceOffsets) != len(chunk.new) {
+		return nil, fmt.Errorf("context mapping has %d entries for %d output lines", len(chunk.newSourceOffsets), len(chunk.new))
+	}
+	replacement := append([]string(nil), chunk.new...)
+	for outputIndex, sourceOffset := range chunk.newSourceOffsets {
+		if sourceOffset < 0 {
+			continue
+		}
+		sourceIndex := start + sourceOffset
+		if sourceIndex < 0 || sourceIndex >= len(source) {
+			return nil, fmt.Errorf("context source index %d is outside the matched file", sourceIndex)
+		}
+		replacement[outputIndex] = source[sourceIndex]
+	}
+	return replacement, nil
+}
+
+func structuredPatchLineEnding(content string) string {
+	if strings.Contains(content, "\r\n") && !strings.Contains(strings.ReplaceAll(content, "\r\n", ""), "\n") {
+		return "\r\n"
+	}
+	return "\n"
+}
+
+type structuredReplacement struct {
+	start       int
+	length      int
+	replacement []string
+}
+
+func findStructuredPatchSequence(lines, wanted []string, start int, endOfFile bool) (int, bool) {
+	if len(wanted) == 0 {
+		return start, false
+	}
+	if len(wanted) > len(lines) {
+		return -1, false
+	}
+	searchStart := start
+	if endOfFile {
+		searchStart = len(lines) - len(wanted)
+		if searchStart < start {
+			searchStart = start
+		}
+	}
+	for _, equal := range []func(string, string) bool{
+		func(left, right string) bool { return left == right },
+		func(left, right string) bool {
+			return strings.TrimRight(left, " \t") == strings.TrimRight(right, " \t")
+		},
+		func(left, right string) bool { return strings.TrimSpace(left) == strings.TrimSpace(right) },
+	} {
+		match := -1
+		for index := searchStart; index+len(wanted) <= len(lines); index++ {
+			matched := true
+			for offset, line := range wanted {
+				if !equal(lines[index+offset], line) {
+					matched = false
+					break
+				}
+			}
+			if matched {
+				if match >= 0 {
+					return -1, true
+				}
+				match = index
+			}
+		}
+		if match >= 0 {
+			return match, false
+		}
+	}
+	return -1, false
+}
+
+func applyStructuredPatchChanges(root *os.Root, changes []structuredPatchChange, tracker *FileTracker) error {
+	// committed lists, in order, the paths whose change reached disk before a
+	// later change failed, so the caller (and the model) knows exactly which
+	// files now hold the patched content and which were never touched.
+	var committed []string
+	for _, change := range changes {
+		done, err := applyStructuredPatchChange(root, change)
+		if done {
+			committed = append(committed, structuredPatchChangePaths(change)...)
+		}
+		if err != nil {
+			forgetStructuredPatchFiles(tracker, changes)
+			if len(committed) > 0 {
+				return fmt.Errorf("%w; patch was partially applied — already committed: %s; the remaining files are unchanged; re-read the committed files before retrying", err, strings.Join(committed, ", "))
+			}
+			return err
+		}
+	}
+	return nil
+}
+
+// structuredPatchChangePaths names the workspace-relative paths a committed
+// change touched: the destination, plus the source of a move or copy.
+func structuredPatchChangePaths(change structuredPatchChange) []string {
+	if change.kind == structuredPatchDelete {
+		return []string{change.from.relative}
+	}
+	paths := []string{change.to.relative}
+	if change.from.absolute != change.to.absolute && change.from.relative != "" {
+		paths = append([]string{change.from.relative}, paths...)
+	}
+	return paths
+}
+
+func forgetStructuredPatchFiles(tracker *FileTracker, changes []structuredPatchChange) {
+	if tracker == nil {
+		return
+	}
+	for _, change := range changes {
+		tracker.Forget(change.from.absolute)
+		if change.to.absolute != change.from.absolute {
+			tracker.Forget(change.to.absolute)
+		}
+	}
+}
+
+// structuredPatchBeforeCommit, when set, runs before each change's pre-commit
+// recheck. Tests use it to alter the filesystem between planning and commit
+// deterministically; it is nil in production.
+var structuredPatchBeforeCommit func(change structuredPatchChange)
+
+func applyStructuredPatchChange(root *os.Root, change structuredPatchChange) (bool, error) {
+	if structuredPatchBeforeCommit != nil {
+		structuredPatchBeforeCommit(change)
+	}
+	// The planner validated the source against the bytes it read; re-read
+	// through the same root immediately before committing so a change made
+	// by another process in between is refused rather than overwritten or
+	// removed.
+	if change.kind != structuredPatchAdd {
+		current, err := root.ReadFile(change.from.relative)
+		if err != nil {
+			return false, fmt.Errorf("re-reading %s before commit: %w", change.from.relative, err)
+		}
+		if string(current) != change.before {
+			return false, fmt.Errorf("%s changed on disk between planning and commit; re-read it and retry", change.from.relative)
+		}
+	}
+	switch change.kind {
+	case structuredPatchDelete:
+		if err := root.Remove(change.from.relative); err != nil {
+			return false, fmt.Errorf("deleting %s: %w", change.from.relative, err)
+		}
+		return true, nil
+	case structuredPatchAdd, structuredPatchCopy:
+		return writeStructuredPatchFile(root, change.to, change.after, change.mode, true)
+	case structuredPatchUpdate:
+		moving := change.from.absolute != change.to.absolute
+		committed, err := writeStructuredPatchFile(root, change.to, change.after, change.mode, moving)
+		if err != nil {
+			return committed, err
+		}
+		if moving {
+			if err := root.Remove(change.from.relative); err != nil {
+				return true, fmt.Errorf("removing moved source %s: %w", change.from.relative, err)
+			}
+		}
+		return true, nil
+	}
+	return false, fmt.Errorf("unsupported structured patch operation")
+}
+
+func writeStructuredPatchFile(root *os.Root, target structuredPatchTarget, content string, mode os.FileMode, createOnly bool) (bool, error) {
+	parent := filepath.Dir(target.relative)
+	if err := root.MkdirAll(parent, 0o755); err != nil {
+		return false, fmt.Errorf("creating parent directory for %s: %w", target.relative, err)
+	}
+	temp, tempName, err := pathjail.CreateTemp(root, parent, "zero-patch", ".tmp")
+	if err != nil {
+		return false, fmt.Errorf("writing %s: %w", target.relative, err)
+	}
+	defer func() { _ = removeStructuredPatchTemp(root, tempName) }()
+	if _, err := temp.WriteString(content); err != nil {
+		_ = temp.Close()
+		return false, fmt.Errorf("writing %s: %w", target.relative, err)
+	}
+	if err := temp.Chmod(mode.Perm()); err != nil {
+		_ = temp.Close()
+		return false, fmt.Errorf("writing %s: %w", target.relative, err)
+	}
+	if err := temp.Close(); err != nil {
+		return false, fmt.Errorf("writing %s: %w", target.relative, err)
+	}
+	if createOnly {
+		return publishStructuredPatchNoReplace(root, tempName, target.relative, mode)
+	}
+	if err := root.Rename(tempName, target.relative); err != nil {
+		return false, fmt.Errorf("writing %s: %w", target.relative, err)
+	}
+	return true, nil
+}
+
+func publishStructuredPatchNoReplace(root *os.Root, source, target string, mode os.FileMode) (bool, error) {
+	return publishStructuredPatchNoReplaceWith(root, source, target, mode, root.Link)
+}
+
+func publishStructuredPatchNoReplaceWith(root *os.Root, source, target string, mode os.FileMode, link func(string, string) error) (bool, error) {
+	if linkErr := link(source, target); linkErr == nil {
+		cleanupErr := removeStructuredPatchTemp(root, source)
+		chmodErr := root.Chmod(target, mode.Perm())
+		if cleanupErr != nil || chmodErr != nil {
+			return true, fmt.Errorf("publishing %s: %w", target, errors.Join(cleanupErr, chmodErr))
+		}
+		return true, nil
+	} else if errors.Is(linkErr, os.ErrExist) {
+		return false, fmt.Errorf("creating %s: %w", target, linkErr)
+	} else {
+		committed, copyErr := copyStructuredPatchNoReplace(root, source, target, mode)
+		if copyErr != nil {
+			return committed, fmt.Errorf("creating %s without overwrite: hard link failed: %w; exclusive-copy fallback failed: %w", target, linkErr, copyErr)
+		}
+		return committed, nil
+	}
+}
+
+func copyStructuredPatchNoReplace(root *os.Root, source, target string, mode os.FileMode) (bool, error) {
+	return copyStructuredPatchNoReplaceWith(root, source, target, mode, io.Copy, removeStructuredPatchTemp)
+}
+
+func copyStructuredPatchNoReplaceWith(
+	root *os.Root,
+	source, target string,
+	mode os.FileMode,
+	copyFile func(io.Writer, io.Reader) (int64, error),
+	cleanup func(*os.Root, string) error,
+) (bool, error) {
+	sourceFile, err := root.Open(source)
+	if err != nil {
+		return false, err
+	}
+	sourceClosed := false
+	defer func() {
+		if !sourceClosed {
+			_ = sourceFile.Close()
+		}
+	}()
+	targetFile, err := root.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+	if err != nil {
+		return false, err
+	}
+	committed := true
+	cleanupTarget := func(cause error) (bool, error) {
+		_ = targetFile.Close()
+		if cleanupErr := cleanup(root, target); cleanupErr == nil {
+			return false, cause
+		} else {
+			return committed, errors.Join(cause, fmt.Errorf("cleaning partial target: %w", cleanupErr))
+		}
+	}
+	if _, err := copyFile(targetFile, sourceFile); err != nil {
+		return cleanupTarget(err)
+	}
+	if err := sourceFile.Close(); err != nil {
+		sourceClosed = true
+		return cleanupTarget(err)
+	}
+	sourceClosed = true
+	if err := targetFile.Chmod(mode.Perm()); err != nil {
+		return cleanupTarget(err)
+	}
+	if err := targetFile.Close(); err != nil {
+		if cleanupErr := cleanup(root, target); cleanupErr == nil {
+			return false, err
+		} else {
+			return true, errors.Join(err, fmt.Errorf("cleaning target after close failure: %w", cleanupErr))
+		}
+	}
+	if err := cleanup(root, source); err != nil {
+		return true, fmt.Errorf("removing published source: %w", err)
+	}
+	return true, nil
+}
+
+func removeStructuredPatchTemp(root *os.Root, name string) error {
+	chmodErr := root.Chmod(name, 0o600)
+	if os.IsNotExist(chmodErr) {
+		return nil
+	}
+	removeErr := root.Remove(name)
+	if os.IsNotExist(removeErr) {
+		removeErr = nil
+	}
+	if removeErr == nil {
+		return nil
+	}
+	return errors.Join(chmodErr, removeErr)
+}
+
+func recordStructuredPatchFile(tracker *FileTracker, absolute string, created, seenWhole bool) {
+	if tracker == nil {
+		return
+	}
+	content, err := os.ReadFile(absolute)
+	if err != nil {
+		tracker.Forget(absolute)
+		return
+	}
+	info, _ := os.Stat(absolute)
+	tracker.Record(absolute, content, info)
+	if seenWhole {
+		lines := trackedLineTotal(string(content))
+		tracker.RecordSeenRange(absolute, 1, lines, lines)
+	}
+	if created {
+		tracker.RecordCreated(absolute)
+	}
+}
+
+func changedFilesFromStructuredPatch(relativeRoot string, changes []structuredPatchChange) []string {
+	seen := make(map[string]bool)
+	var paths []string
+	for _, change := range changes {
+		targets := []structuredPatchTarget{change.to}
+		if change.from.absolute != change.to.absolute {
+			targets = append([]structuredPatchTarget{change.from}, targets...)
+		}
+		for _, target := range targets {
+			path := target.relative
+			if relativeRoot != "" && relativeRoot != "." {
+				path = filepath.ToSlash(filepath.Join(relativeRoot, path))
+			}
+			if !seen[path] {
+				seen[path] = true
+				paths = append(paths, path)
+			}
+		}
+	}
+	return paths
+}
+
+func structuredPatchPreview(changes []structuredPatchChange) string {
+	var preview strings.Builder
+	for _, change := range changes {
+		path := change.to.relative
+		if change.kind == structuredPatchDelete {
+			path = change.from.relative
+		}
+		before, after := change.before, change.after
+		if change.kind == structuredPatchDelete {
+			after = ""
+		}
+		diff := boundedUnifiedDiff(path, before, after)
+		if diff == "" {
+			continue
+		}
+		if preview.Len()+len(diff)+1 > maxToolPreviewBytes {
+			break
+		}
+		if preview.Len() > 0 {
+			preview.WriteByte('\n')
+		}
+		preview.WriteString(diff)
+	}
+	return capPreviewDiff(preview.String())
+}
@@ -58,6 +58,11 @@ func NewToolSearchTool(registry *Registry) Tool {
 	}
 }

+func (tool toolSearchTool) cloneForRegistry(registry *Registry) Tool {
+	tool.registry = registry
+	return tool
+}
+
 // Run satisfies the Tool interface; actual dispatch goes through RunWithOptions.
 func (tool toolSearchTool) Run(ctx context.Context, args map[string]any) Result {
 	return tool.RunWithOptions(ctx, args, RunOptions{})
@@ -130,6 +135,9 @@ func (tool toolSearchTool) visibleDeferredTools(enabled []string, disabled []str
 	var deferred []Tool
 	if tool.registry != nil {
 		for _, candidate := range tool.registry.All() {
+			if !ModelVisible(candidate) {
+				continue
+			}
 			if !IsDeferred(candidate) {
 				continue
 			}
@@ -158,6 +166,9 @@ func (tool toolSearchTool) visibleEagerToolNames(enabled []string, disabled []st
 		return names
 	}
 	for _, candidate := range tool.registry.All() {
+		if !ModelVisible(candidate) {
+			continue
+		}
 		if IsDeferred(candidate) || candidate.Name() == ToolSearchToolName {
 			continue
 		}
@@ -73,6 +73,37 @@ func newDeferredFixtureRegistry() *Registry {
 	return reg
 }

+func TestRegistryCloneKeepsToolSearchOnFrozenSnapshot(t *testing.T) {
+	live := newDeferredFixtureRegistry()
+	live.Register(NewToolSearchTool(live))
+	runRegistry := live.Clone()
+	live.Register(searchFakeTool{
+		name:        "late_lookup",
+		description: "Registered after the run snapshot.",
+		parameters:  Schema{Type: "object", AdditionalProperties: false},
+	})
+
+	result := runRegistry.Run(context.Background(), ToolSearchToolName, map[string]any{
+		"query": "select:late_lookup",
+	})
+	if result.Status != StatusOK {
+		t.Fatalf("tool_search status = %s: %s", result.Status, result.Output)
+	}
+	if loaded := result.Meta["load_tools"]; loaded != "" {
+		t.Fatalf("snapshot tool_search loaded late tool %q", loaded)
+	}
+	if direct := runRegistry.Run(context.Background(), "late_lookup", map[string]any{}); direct.Status != StatusError {
+		t.Fatalf("late tool unexpectedly executable in run snapshot: %#v", direct)
+	}
+
+	known := runRegistry.Run(context.Background(), ToolSearchToolName, map[string]any{
+		"query": "select:weather_lookup",
+	})
+	if loaded := known.Meta["load_tools"]; loaded != "weather_lookup" {
+		t.Fatalf("snapshot tool_search lost existing tool: load_tools=%q output=%q", loaded, known.Output)
+	}
+}
+
 func TestToolSearchExposesExpectedSafetyAndSchema(t *testing.T) {
 	tool := NewToolSearchTool(NewRegistry())