Test held-message eviction callback

Create the canonicalization fixture beneath a guaranteed short Unix path so it exercises the primary endpoint on macOS, and report temporary-directory cleanup failures.

AGENTS.md

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

go.mod

@@ -6,6 +6,7 @@ require (
 	charm.land/bubbles/v2 v2.1.1
 	charm.land/bubbletea/v2 v2.0.8
 	charm.land/lipgloss/v2 v2.0.5
+	github.com/Microsoft/go-winio v0.6.2
 	github.com/alecthomas/chroma/v2 v2.27.0
 	github.com/atotto/clipboard v0.1.4
 	github.com/aymanbagabas/go-udiff v0.4.1

go.sum

@@ -4,6 +4,8 @@ charm.land/bubbletea/v2 v2.0.8 h1:SxTJMhCAI3lbPmy4SgX5LWZ24AdINr4I6UEqzZvYJuY=
 charm.land/bubbletea/v2 v2.0.8/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=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
 github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
 github.com/alecthomas/chroma/v2 v2.27.0 h1:FodwmyOBgJULFYmDqibcp9pvfDLWdtPRh9v/r5BXYZs=

internal/agent/additional_permissions_validation_test.go

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

internal/agent/compaction.go

@@ -38,8 +38,9 @@ const compactionTriggerRatio = 0.7
 // transcript (and so tests can assert on it).
 const summaryLabel = "[Summary of earlier conversation]"
 
-// summaryInstructions is the system prompt handed to the summarizer model.
-const summaryInstructions = "You are compacting a coding-assistant conversation to save context. " +
+// CompactionSummaryInstructions is the system prompt handed to both automatic
+// and manually requested compaction summarizers.
+const CompactionSummaryInstructions = "You are compacting a coding-assistant conversation to save context. " +
 	"Write a dense, factual summary of the conversation so far. Preserve: the user's goals and explicit constraints; " +
 	"decisions made and why; files created or modified (with paths) and key code changes; commands run and their important " +
 	"results; and anything still in progress or unresolved. Omit pleasantries. Use terse bullet points. Do not invent details. " +
@@ -75,6 +76,12 @@ type CompactionResult struct {
 	// summary message also includes summaryLabel and any preserved structured
 	// state needed by later compactions.
 	SummaryText string
+	// ProjectedChars is the text content sent to the summarizer after semantic
+	// projection, excluding provider protocol framing.
+	ProjectedChars int
+	// Truncated reports whether projection dropped content to satisfy its
+	// bounded brief or previous-summary limits.
+	Truncated bool
 	// Compacted reports whether Messages contains an injected summary.
 	Compacted bool
 }
@@ -216,11 +223,11 @@ func CompactMessages(messages []zeroruntime.Message, opts CompactionOptions) (Co
 		}, nil
 	}
 
-	summary, err := opts.Summarize(middle)
+	summaryResult, err := SummarizeCompactionMessages(middle, opts.Summarize)
 	if err != nil {
 		return CompactionResult{}, err
 	}
-	summary = strings.TrimSpace(summary)
+	summary := summaryResult.SummaryText
 
 	// Preserve structured state (active plan + loaded skills) from the elided
 	// middle verbatim, so it is not lost or paraphrased away by the prose summary.
@@ -238,10 +245,53 @@ func CompactMessages(messages []zeroruntime.Message, opts CompactionOptions) (Co
 		RemovedCount:   len(middle),
 		PreservedCount: len(messages) - len(middle),
 		SummaryText:    summary,
+		ProjectedChars: summaryResult.ProjectedChars,
+		Truncated:      summaryResult.Truncated,
 		Compacted:      true,
 	}, nil
 }
 
+// CompactionSummaryResult describes the shared summarization input and output.
+type CompactionSummaryResult struct {
+	SummaryText    string
+	ProjectedChars int
+	Truncated      bool
+}
+
+// SummarizeCompactionMessages applies the shared semantic projection before
+// invoking a caller-supplied summarizer. Automatic context-pressure compaction
+// and manual session compaction both use this path.
+func SummarizeCompactionMessages(messages []zeroruntime.Message, summarize func([]zeroruntime.Message) (string, error)) (CompactionSummaryResult, error) {
+	if summarize == nil {
+		return CompactionSummaryResult{}, errors.New("compaction requires a Summarize function")
+	}
+	projection := projectCompactionInput(messages)
+	summaryInput := projection.messages
+	if len(summaryInput) == 0 {
+		summaryInput = messages
+	}
+	summary, err := summarize(summaryInput)
+	if err != nil {
+		return CompactionSummaryResult{}, err
+	}
+	return CompactionSummaryResult{
+		SummaryText:    strings.TrimSpace(summary),
+		ProjectedChars: compactionMessageChars(summaryInput),
+		Truncated:      projection.truncated,
+	}, nil
+}
+
+func compactionMessageChars(messages []zeroruntime.Message) int {
+	total := 0
+	for _, message := range messages {
+		total += len(message.Content)
+		for _, call := range message.ToolCalls {
+			total += len(call.Name) + len(call.Arguments)
+		}
+	}
+	return total
+}
+
 // safeSuffixBoundary walks the preserve boundary backward (toward systemEnd) so
 // the preserved suffix begins on a user or assistant message rather than a
 // tool/tool_result message. A tool result with no preceding assistant tool call
@@ -331,6 +381,8 @@ type compactionState struct {
 	// but its token COST must still be counted so usage reports and budgets include it.
 	onUsage func(Usage)
 	task    *taskState
+	planner *contextPlanner
+	trace   *trace.Recorder
 
 	// calibrationRatio scales the raw byte/4 token estimate toward the provider's
 	// real prompt-token count. ApproxTextTokens over-counts code-heavy content by
@@ -377,6 +429,8 @@ func newCompactionState(options Options, task *taskState) *compactionState {
 		preserveLast: options.CompactionPreserveLast,
 		onUsage:      options.OnUsage,
 		task:         task,
+		planner:      newContextPlanner(contextPlannerConfig{contextWindow: options.ContextWindow}),
+		trace:        options.Trace,
 	}
 	return state
 }
@@ -413,6 +467,14 @@ func (state *compactionState) maybeCompact(
 	// the bodies of old, large tool results (the model has already acted on
 	// them). If that brings us back under threshold, skip the paid summarizer
 	// entirely and preserve recent turns verbatim.
+	if pruned, reclaimed := pruneSupersededReadResults(messages); reclaimed > 0 {
+		messages = pruned
+		size = state.calibratedTokens(estimateTokens(messages) + toolTokens)
+		if size <= state.threshold {
+			state.lowWaterMark = size
+			return messages
+		}
+	}
 	if pruned, reclaimed := pruneStaleToolOutput(messages, state.preserveLast); reclaimed > 0 {
 		messages = pruned
 		size = state.calibratedTokens(estimateTokens(messages) + toolTokens)
@@ -424,7 +486,7 @@ func (state *compactionState) maybeCompact(
 
 	compacted, err := Compact(messages, CompactionOptions{
 		PreserveLast: state.preserveLast,
-		Summarize:    summarizeClosure(ctx, provider, state.onUsage),
+		Summarize:    state.summarizeClosure(ctx, provider),
 		taskState:    state.task.snapshotForCompaction(messages),
 	})
 	if err != nil {
@@ -475,7 +537,7 @@ func (state *compactionState) recover(
 
 	result, compactErr := Compact(messages, CompactionOptions{
 		PreserveLast: state.preserveLast,
-		Summarize:    summarizeClosure(ctx, provider, state.onUsage),
+		Summarize:    state.summarizeClosure(ctx, provider),
 		taskState:    state.task.snapshotForCompaction(messages),
 	})
 	if compactErr != nil {
@@ -509,9 +571,12 @@ func (state *compactionState) recover(
 // provider call. The summary stream intentionally does NOT forward OnText (so
 // compaction stays invisible on the user-facing surface), but it DOES forward
 // OnUsage so the summarizer's token cost is still counted by usage/budgeting.
-func summarizeClosure(ctx context.Context, provider Provider, onUsage func(Usage)) func([]zeroruntime.Message) (string, error) {
+func (state *compactionState) summarizeClosure(ctx context.Context, provider Provider) func([]zeroruntime.Message) (string, error) {
+	if state.planner == nil {
+		state.planner = newContextPlanner(contextPlannerConfig{})
+	}
 	return func(toSummarize []zeroruntime.Message) (string, error) {
-		return summarizeWithFallback(ctx, provider, toSummarize, onUsage)
+		return summarizeWithPlanner(ctx, provider, toSummarize, state.onUsage, state.planner, state.trace)
 	}
 }
 
@@ -523,7 +588,11 @@ func summarizeClosure(ctx context.Context, provider Provider, onUsage func(Usage
 // Non-context-limit errors (and a single message that still won't fit) surface
 // to the caller unchanged.
 func summarizeWithFallback(ctx context.Context, provider Provider, messages []zeroruntime.Message, onUsage func(Usage)) (string, error) {
-	summary, err := summarizeMessagesOnce(ctx, provider, messages, onUsage)
+	return summarizeWithPlanner(ctx, provider, messages, onUsage, newContextPlanner(contextPlannerConfig{}), nil)
+}
+
+func summarizeWithPlanner(ctx context.Context, provider Provider, messages []zeroruntime.Message, onUsage func(Usage), planner *contextPlanner, recorder *trace.Recorder) (string, error) {
+	summary, err := summarizeMessagesOnce(ctx, provider, messages, onUsage, planner, recorder)
 	if err == nil {
 		return summary, nil
 	}
@@ -532,11 +601,11 @@ func summarizeWithFallback(ctx context.Context, provider Provider, messages []ze
 	}
 
 	mid := len(messages) / 2
-	left, leftErr := summarizeWithFallback(ctx, provider, messages[:mid], onUsage)
+	left, leftErr := summarizeWithPlanner(ctx, provider, messages[:mid], onUsage, planner, recorder)
 	if leftErr != nil {
 		return "", leftErr
 	}
-	right, rightErr := summarizeWithFallback(ctx, provider, messages[mid:], onUsage)
+	right, rightErr := summarizeWithPlanner(ctx, provider, messages[mid:], onUsage, planner, recorder)
 	if rightErr != nil {
 		return "", rightErr
 	}
@@ -549,7 +618,7 @@ func summarizeWithFallback(ctx context.Context, provider Provider, messages []ze
 	combined := strings.TrimSpace(left + "\n\n" + right)
 	reduced, reduceErr := summarizeMessagesOnce(ctx, provider, []zeroruntime.Message{
 		{Role: zeroruntime.MessageRoleUser, Content: combined},
-	}, onUsage)
+	}, onUsage, planner, recorder)
 	if reduceErr != nil {
 		if isContextLimitError(reduceErr.Error()) {
 			// Even the two combined partials don't fit (extreme): fall back to the
@@ -565,15 +634,15 @@ func summarizeWithFallback(ctx context.Context, provider Provider, messages []ze
 }
 
 // summarizeMessagesOnce performs a single tool-less summarization call.
-func summarizeMessagesOnce(ctx context.Context, provider Provider, messages []zeroruntime.Message, onUsage func(Usage)) (string, error) {
-	request := zeroruntime.CompletionRequest{
-		Messages: []zeroruntime.Message{
-			{Role: zeroruntime.MessageRoleSystem, Content: summaryInstructions},
-			{Role: zeroruntime.MessageRoleUser, Content: "Summarize this conversation:\n\n" + renderTranscript(messages)},
-		},
-		// No tools: this is a plain text summarization call.
+func summarizeMessagesOnce(ctx context.Context, provider Provider, messages []zeroruntime.Message, onUsage func(Usage), planner *contextPlanner, recorder *trace.Recorder) (string, error) {
+	requestMessages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: CompactionSummaryInstructions},
+		{Role: zeroruntime.MessageRoleUser, Content: "Summarize this conversation:\n\n" + renderTranscript(messages)},
 	}
-	stream, err := provider.StreamCompletion(ctx, request)
+	parts := systemPromptParts{prompt: CompactionSummaryInstructions, baseInstructions: CompactionSummaryInstructions}
+	plan := planner.planWithPromptParts(requestMessages, nil, "", parts)
+	recordContextPlanTrace(recorder, plan)
+	stream, err := provider.StreamCompletion(ctx, plan.Request)
 	if err != nil {
 		return "", err
 	}

internal/agent/compaction_metadata_test.go

@@ -43,8 +43,14 @@ func TestCompactMessagesReturnsMetadataForManualCompaction(t *testing.T) {
 	if result.SummaryText != "manual summary" {
 		t.Fatalf("SummaryText = %q, want trimmed summary", result.SummaryText)
 	}
-	if len(captured) != 3 || captured[0].Content != "first question" || captured[2].Content != "second question" {
-		t.Fatalf("summarized middle = %#v, want the three non-preserved non-system messages", captured)
+	if result.ProjectedChars != compactionMessageChars(captured) || result.ProjectedChars == 0 {
+		t.Fatalf("ProjectedChars = %d, want %d", result.ProjectedChars, compactionMessageChars(captured))
+	}
+	if result.Truncated {
+		t.Fatal("Truncated = true for a projection within its limits")
+	}
+	if len(captured) != 1 || !strings.Contains(captured[0].Content, "first question") || !strings.Contains(captured[0].Content, "second question") {
+		t.Fatalf("summarized projection = %#v, want intent from the non-preserved middle", captured)
 	}
 	if len(result.Messages) != 4 {
 		t.Fatalf("compacted message count = %d, want 4", len(result.Messages))
@@ -96,11 +102,46 @@ func TestCompactMessagesNoopReturnsUncompactedMetadata(t *testing.T) {
 	if result.SummaryText != "" {
 		t.Fatalf("SummaryText = %q, want empty", result.SummaryText)
 	}
+	if result.ProjectedChars != 0 || result.Truncated {
+		t.Fatalf("no-op projection metadata = (%d, %t), want zero values", result.ProjectedChars, result.Truncated)
+	}
 	if !reflect.DeepEqual(result.Messages, messages) {
 		t.Fatalf("Messages changed on no-op: %#v", result.Messages)
 	}
 }
 
+func TestCompactMessagesReturnsTruncatedProjectionMetadata(t *testing.T) {
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleSystem, Content: "system"}}
+	for index := range 20 {
+		messages = append(messages, zeroruntime.Message{
+			Role:    zeroruntime.MessageRoleUser,
+			Content: strings.Repeat("contextword ", 256) + string(rune('a'+index)),
+		})
+	}
+	messages = append(messages,
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "recent answer"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "latest question"},
+	)
+
+	var captured []zeroruntime.Message
+	result, err := CompactMessages(messages, CompactionOptions{
+		PreserveLast: 2,
+		Summarize: func(toSummarize []zeroruntime.Message) (string, error) {
+			captured = append([]zeroruntime.Message(nil), toSummarize...)
+			return "bounded summary", nil
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.Compacted || !result.Truncated {
+		t.Fatalf("compaction metadata = compacted %t, truncated %t; want both true", result.Compacted, result.Truncated)
+	}
+	if result.ProjectedChars != compactionMessageChars(captured) || result.ProjectedChars == 0 {
+		t.Fatalf("ProjectedChars = %d, want %d", result.ProjectedChars, compactionMessageChars(captured))
+	}
+}
+
 func TestCompactMessagesPropagatesSummarizeError(t *testing.T) {
 	messages := []zeroruntime.Message{
 		{Role: zeroruntime.MessageRoleSystem, Content: "system"},

internal/agent/compaction_preserve.go

@@ -102,7 +102,7 @@ type skillEntry struct {
 	body string
 }
 
-// recentEdits returns the files mutated by write_file/edit_file calls in messages
+// recentEdits returns files mutated by editing calls in messages
 // — latest note per path, in last-seen order — as skillEntry{name: path, body:
 // note}. After compaction elides the editing turns, this tells the model WHAT it
 // changed in each file (from the tool's result) so it need not re-read to
@@ -113,6 +113,7 @@ type skillEntry struct {
 // rather than an earlier, now-stale entry.
 func recentEdits(messages []zeroruntime.Message) []skillEntry {
 	pathByID := map[string]string{}
+	noteByPath := map[string]string{}
 	sequence := make([]string, 0)
 	for _, message := range messages {
 		for _, call := range message.ToolCalls {
@@ -129,12 +130,24 @@ func recentEdits(messages []zeroruntime.Message) []skillEntry {
 			sequence = append(sequence, path)
 		}
 	}
+	for _, message := range messages {
+		if message.Role != zeroruntime.MessageRoleTool || len(message.ChangedFiles) == 0 {
+			continue
+		}
+		for _, path := range message.ChangedFiles {
+			path = strings.TrimSpace(path)
+			if path == "" {
+				continue
+			}
+			sequence = append(sequence, path)
+			noteByPath[path] = editNote(message.Content)
+		}
+	}
 	order := lastSeenOrder(sequence)
 	if len(order) == 0 {
 		return nil
 	}
 
-	noteByPath := map[string]string{}
 	for _, message := range messages {
 		if message.Role != zeroruntime.MessageRoleTool || message.ToolCallID == "" {
 			continue
@@ -425,15 +438,20 @@ type preservedState struct {
 }
 
 type preservedTaskState struct {
-	Objective           string     `json:"objective"`
-	Status              taskStatus `json:"status,omitempty"`
-	Pending             int        `json:"pending,omitempty"`
-	InProgress          int        `json:"in_progress,omitempty"`
-	Completed           int        `json:"completed,omitempty"`
-	Failed              int        `json:"failed,omitempty"`
-	VerificationPassed  int        `json:"verification_passed,omitempty"`
-	VerificationFailed  int        `json:"verification_failed,omitempty"`
-	VerificationOutcome Outcome    `json:"verification_outcome,omitempty"`
+	Objective           string              `json:"objective"`
+	Status              taskStatus          `json:"status,omitempty"`
+	Pending             int                 `json:"pending,omitempty"`
+	InProgress          int                 `json:"in_progress,omitempty"`
+	Completed           int                 `json:"completed,omitempty"`
+	Failed              int                 `json:"failed,omitempty"`
+	VerificationPassed  int                 `json:"verification_passed,omitempty"`
+	VerificationFailed  int                 `json:"verification_failed,omitempty"`
+	VerificationOutcome Outcome             `json:"verification_outcome,omitempty"`
+	Constraints         []string            `json:"constraints,omitempty"`
+	ChangedFiles        []string            `json:"changed_files,omitempty"`
+	UnresolvedFailures  []taskFailureState  `json:"unresolved_failures,omitempty"`
+	Approvals           []taskApprovalState `json:"approvals,omitempty"`
+	Artifacts           []taskArtifactState `json:"artifacts,omitempty"`
 }
 
 type preservedEdit struct {
@@ -468,7 +486,12 @@ func appendPreservedState(summary string, middle []zeroruntime.Message, taskSnap
 	task := priorState.Task
 	if taskSnapshot != nil {
 		task = &preservedTaskState{
-			Objective: capTaskObjective(taskSnapshot.Objective),
+			Objective:          capTaskObjective(taskSnapshot.Objective),
+			Constraints:        mergeBoundedComparable(priorTaskConstraints(priorState.Task), taskSnapshot.Constraints, maxTaskConstraints),
+			ChangedFiles:       mergeBoundedComparable(priorTaskChangedFiles(priorState.Task), taskSnapshot.ChangedFiles, maxTaskEvidenceEntries),
+			UnresolvedFailures: mergeTaskFailures(priorTaskFailures(priorState.Task), taskSnapshot.UnresolvedFailures, taskSnapshot.ResolvedFailureKeys),
+			Approvals:          mergeBoundedComparable(priorTaskApprovals(priorState.Task), taskSnapshot.Approvals, maxTaskEvidenceEntries),
+			Artifacts:          mergeBoundedComparable(priorTaskArtifacts(priorState.Task), taskSnapshot.Artifacts, maxTaskEvidenceEntries),
 		}
 		// Plan parity corroborates only the mutable task projection. The objective
 		// comes directly from the run prompt and is immutable, so it must survive
@@ -484,6 +507,13 @@ func appendPreservedState(summary string, middle []zeroruntime.Message, taskSnap
 			task.VerificationOutcome = taskSnapshot.Verification.LastOutcome
 		}
 	}
+	freshConstraints := explicitConstraintsFromMessages(middle)
+	if len(freshConstraints) > 0 {
+		if task == nil {
+			task = &preservedTaskState{}
+		}
+		task.Constraints = mergeBoundedComparable(task.Constraints, freshConstraints, maxTaskConstraints)
+	}
 
 	// Plan: a fresh update_plan in middle is authoritative; otherwise carry the
 	// plan preserved by an earlier compaction.
@@ -517,6 +547,95 @@ func appendPreservedState(summary string, middle []zeroruntime.Message, taskSnap
 	return summary
 }
 
+func explicitConstraintsFromMessages(messages []zeroruntime.Message) []string {
+	var constraints []string
+	for _, message := range messages {
+		if message.Role != zeroruntime.MessageRoleUser || strings.Contains(message.Content, preservedStateLabel) {
+			continue
+		}
+		if _, body := projectInstructionBlock(message.Content); body != "" {
+			continue
+		}
+		constraints = mergeBoundedComparable(constraints, extractExplicitConstraints(message.Content), maxTaskConstraints)
+	}
+	return constraints
+}
+
+func priorTaskConstraints(task *preservedTaskState) []string {
+	if task == nil {
+		return nil
+	}
+	return task.Constraints
+}
+
+func priorTaskChangedFiles(task *preservedTaskState) []string {
+	if task == nil {
+		return nil
+	}
+	return task.ChangedFiles
+}
+
+func priorTaskFailures(task *preservedTaskState) []taskFailureState {
+	if task == nil {
+		return nil
+	}
+	return task.UnresolvedFailures
+}
+
+func priorTaskApprovals(task *preservedTaskState) []taskApprovalState {
+	if task == nil {
+		return nil
+	}
+	return task.Approvals
+}
+
+func priorTaskArtifacts(task *preservedTaskState) []taskArtifactState {
+	if task == nil {
+		return nil
+	}
+	return task.Artifacts
+}
+
+func mergeTaskFailures(older, newer []taskFailureState, resolved []string) []taskFailureState {
+	resolvedSet := make(map[string]struct{}, len(resolved))
+	for _, key := range resolved {
+		resolvedSet[key] = struct{}{}
+	}
+	merged := make([]taskFailureState, 0, len(older)+len(newer))
+	for _, failure := range append(append([]taskFailureState(nil), older...), newer...) {
+		if _, ok := resolvedSet[failure.Key]; ok {
+			continue
+		}
+		withoutSameKey := make([]taskFailureState, 0, len(merged))
+		for _, existing := range merged {
+			if existing.Key != failure.Key {
+				withoutSameKey = append(withoutSameKey, existing)
+			}
+		}
+		merged = append(withoutSameKey, failure)
+	}
+	if len(merged) > maxTaskEvidenceEntries {
+		merged = merged[len(merged)-maxTaskEvidenceEntries:]
+	}
+	return merged
+}
+
+func mergeBoundedComparable[T comparable](older, newer []T, limit int) []T {
+	merged := make([]T, 0, len(older)+len(newer))
+	seen := make(map[T]struct{}, len(older)+len(newer))
+	for _, value := range append(append([]T(nil), older...), newer...) {
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		merged = append(merged, value)
+	}
+	if len(merged) > limit {
+		merged = merged[len(merged)-limit:]
+	}
+	return merged
+}
+
 func capTaskObjective(objective string) string {
 	objective = strings.TrimSpace(objective)
 	if len(objective) <= maxTaskObjectiveBytes {

internal/agent/compaction_preserve_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 	"unicode/utf8"
 
+	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
@@ -64,6 +65,9 @@ func TestCompactPreservesBoundedTaskContext(t *testing.T) {
 	objective := strings.Repeat("世", maxTaskObjectiveBytes)
 	task := newTaskState(objective, nil)
 	task.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"write code","status":"in_progress"},{"content":"add tests","status":"pending"}]}`})
+	task.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"patch":"*** Update File: internal/db.go"}`, toolResult: ToolResult{
+		Name: "apply_patch", Status: tools.StatusOK, Output: "Done!", ChangedFiles: []string{"internal/db.go"},
+	}})
 	messages := stateConversation()
 	compacted, err := Compact(messages, CompactionOptions{
 		PreserveLast: 2,
@@ -80,6 +84,69 @@ func TestCompactPreservesBoundedTaskContext(t *testing.T) {
 	if len(state.Task.Objective) > maxTaskObjectiveBytes || !utf8.ValidString(state.Task.Objective) {
 		t.Fatalf("objective was not safely bounded: %d bytes %q", len(state.Task.Objective), state.Task.Objective)
 	}
+	if len(state.Task.ChangedFiles) != 1 || state.Task.ChangedFiles[0] != "internal/db.go" {
+		t.Fatalf("changed files were not preserved: %#v", state.Task.ChangedFiles)
+	}
+}
+
+func TestCompactPreservesRuntimeEvidenceAcrossRepeatedCompaction(t *testing.T) {
+	task := newTaskState("Please keep the change focused.", nil)
+	task.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"cmd":"go test ./..."}`, toolResult: ToolResult{
+		Name: "exec_command", Status: tools.StatusError, Output: "Error: tests failed",
+		Meta: map[string]string{"spill_path": ".zero/artifacts/tests.txt"},
+	}})
+	task.observe(taskStateEvent{kind: taskStateEventPermission, permission: PermissionEvent{
+		ToolName: "exec_command", DecisionAction: PermissionDecisionAllowForSession, Scope: "/tmp",
+	}})
+	messages := stateConversation()
+
+	first, err := Compact(messages, CompactionOptions{
+		PreserveLast: 2,
+		Summarize:    func([]zeroruntime.Message) (string, error) { return "FIRST", nil },
+		taskState:    task.snapshotForCompaction(messages),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	task.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"cmd":"go test ./..."}`, toolResult: ToolResult{
+		Name: "exec_command", Status: tools.StatusError, Output: "Error: tests still fail with newer evidence",
+		Meta: map[string]string{"spill_path": ".zero/artifacts/tests.txt"},
+	}})
+	secondInput := append(append([]zeroruntime.Message{}, first...),
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "Never add background memory models."},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "understood"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "continue"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "working"},
+	)
+	second, err := Compact(secondInput, CompactionOptions{
+		PreserveLast: 2,
+		Summarize:    func([]zeroruntime.Message) (string, error) { return "SECOND", nil },
+		taskState:    task.snapshotForCompaction(secondInput),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	state := parsePreservedStateBlock(second[1].Content)
+	if state.Task == nil || len(state.Task.UnresolvedFailures) != 1 || len(state.Task.Approvals) != 1 || len(state.Task.Artifacts) != 1 {
+		t.Fatalf("runtime evidence did not survive repeated compaction: %#v", state.Task)
+	}
+	if got := state.Task.UnresolvedFailures[0].Summary; got != "Error: tests still fail with newer evidence" {
+		t.Fatalf("newer failure evidence did not replace the older summary: %#v", state.Task.UnresolvedFailures)
+	}
+	for _, want := range []string{"Please keep the change focused.", "Never add background memory models."} {
+		if !containsString(state.Task.Constraints, want) {
+			t.Fatalf("constraint %q missing after repeated compaction: %#v", want, state.Task.Constraints)
+		}
+	}
+}
+
+func containsString(values []string, want string) bool {
+	for _, value := range values {
+		if value == want {
+			return true
+		}
+	}
+	return false
 }
 
 func TestCompactPreservesObjectiveAfterPlanParityMismatch(t *testing.T) {

internal/agent/compaction_projection.go

@@ -0,0 +1,315 @@
+package agent
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+const (
+	compactionUserWordBudget       = 256
+	compactionAssistantWordBudget  = 200
+	compactionToolCallsPerTurn     = 8
+	compactionToolArgumentBytes    = 120
+	compactionErrorBytes           = 150
+	compactionResultBytes          = 1200
+	compactionPreviousSummaryBytes = 16 * 1024
+	compactionBriefMaxBytes        = 24 * 1024
+)
+
+var compactionWordPattern = regexp.MustCompile(`[\p{L}\p{N}]+`)
+
+type compactionProjection struct {
+	messages  []zeroruntime.Message
+	truncated bool
+}
+
+// projectCompactionInput removes reconstructible tool output before the model
+// summary call. It retains a bounded transcript of user intent, assistant
+// decisions, tool actions, and concise errors. Exact durable state is appended
+// separately from the original messages after the summary returns.
+func projectCompactionInput(messages []zeroruntime.Message) compactionProjection {
+	sections := make([]string, 0, len(messages))
+	previousSummary := ""
+	truncated := false
+	for index, message := range messages {
+		switch message.Role {
+		case zeroruntime.MessageRoleUser:
+			content := message.Content
+			if marker := strings.Index(content, preservedStateLabel); marker >= 0 {
+				content = content[:marker]
+			}
+			trimmed := strings.TrimSpace(content)
+			if strings.HasPrefix(trimmed, summaryLabel) {
+				fullSummary := strings.TrimSpace(strings.TrimPrefix(trimmed, summaryLabel))
+				previousSummary = clipHeadTailBytes(fullSummary, compactionPreviousSummaryBytes)
+				truncated = truncated || len(fullSummary) > compactionPreviousSummaryBytes
+				continue
+			}
+			if content = clipInformativeWords(content, compactionUserWordBudget); content != "" {
+				sections = append(sections, fmt.Sprintf("[user #%d]\n%s", index, content))
+			}
+		case zeroruntime.MessageRoleAssistant:
+			lines := make([]string, 0, 1+len(message.ToolCalls))
+			if content := clipInformativeWords(message.Content, compactionAssistantWordBudget); content != "" {
+				lines = append(lines, content)
+			}
+			calls := message.ToolCalls
+			omitted := 0
+			if len(calls) > compactionToolCallsPerTurn {
+				omitted = len(calls) - compactionToolCallsPerTurn
+				calls = calls[omitted:]
+			}
+			if omitted > 0 {
+				lines = append(lines, fmt.Sprintf("* (%d earlier tool calls omitted)", omitted))
+			}
+			for _, call := range calls {
+				lines = append(lines, compactionToolCallLine(call))
+			}
+			if len(lines) > 0 {
+				sections = append(sections, fmt.Sprintf("[assistant #%d]\n%s", index, strings.Join(lines, "\n")))
+			}
+		case zeroruntime.MessageRoleTool:
+			// New tool-result messages carry the execution status directly, as the
+			// source ToolResult does. Keep the text check for older session history
+			// created before Message exposed IsError.
+			name := toolNameForResult(messages, index)
+			mustPreserve := name == "ask_user" || len(message.ChangedFiles) > 0
+			if !mustPreserve && !message.IsError && !isLikelyToolError(message.Content) {
+				continue
+			}
+			if name == "" {
+				name = "tool"
+			}
+			switch {
+			case message.IsError || isLikelyToolError(message.Content):
+				sections = append(sections, fmt.Sprintf("[tool_error #%d] %s\n%s", index, name, clipBytes(firstLine(message.Content), compactionErrorBytes)))
+			case name == "ask_user":
+				sections = append(sections, fmt.Sprintf("[user_answer #%d] %s\n%s", index, name, clipBytes(message.Content, compactionResultBytes)))
+			default:
+				sections = append(sections, fmt.Sprintf("[tool_result #%d] %s changed %s\n%s", index, name,
+					clipBytes(strings.Join(message.ChangedFiles, ", "), compactionToolArgumentBytes), clipBytes(firstLine(message.Content), compactionErrorBytes)))
+			}
+		}
+	}
+	if len(sections) == 0 && previousSummary == "" {
+		return compactionProjection{}
+	}
+	brief, briefTruncated := capCompactionBrief(strings.Join(sections, "\n\n"))
+	truncated = truncated || briefTruncated
+	if previousSummary != "" {
+		brief = "[previous summary]\n" + previousSummary + "\n\n" + brief
+	}
+	return compactionProjection{
+		messages:  []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: strings.TrimSpace(brief)}},
+		truncated: truncated,
+	}
+}
+
+func capCompactionBrief(brief string) (string, bool) {
+	if len(brief) <= compactionBriefMaxBytes {
+		return brief, false
+	}
+	marker := "\n\n...[middle transcript omitted to fit compaction budget]...\n\n"
+	available := compactionBriefMaxBytes - len(marker)
+	// Keep both chronological edges: the oldest material has not necessarily
+	// been summarized before, while the newest material is most actionable.
+	headBytes := available * 2 / 5
+	tailBytes := available - headBytes
+	head := clipPrefixAtBoundary(brief, headBytes)
+	tail := clipSuffixAtBoundary(brief, tailBytes)
+	return strings.TrimSpace(head) + marker + strings.TrimSpace(tail), true
+}
+
+func compactionToolCallLine(call zeroruntime.ToolCall) string {
+	detail := ""
+	var arguments map[string]any
+	if 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
+				break
+			}
+		}
+		if detail == "" && call.Name == "ask_user" {
+			detail = askUserQuestionsDetail(arguments)
+		}
+		if detail == "" && call.Name == "apply_patch" {
+			if patch, ok := arguments["patch"].(string); ok {
+				detail = strings.Join(patchPaths(patch), ", ")
+			}
+		}
+	}
+	if detail == "" {
+		detail = commandFromArguments(call.Arguments)
+	}
+	if detail == "" {
+		return "* " + call.Name
+	}
+	return fmt.Sprintf("* %s %q", call.Name, clipBytes(detail, compactionToolArgumentBytes))
+}
+
+func isLikelyToolError(content string) bool {
+	prefix := strings.TrimSpace(content)
+	if len(prefix) > compactionErrorBytes {
+		prefix = prefix[:compactionErrorBytes]
+	}
+	lower := strings.ToLower(prefix)
+	for _, prefix := range []string{"error:", "tool error:", "failed:", "permission denied", "command failed"} {
+		if strings.HasPrefix(lower, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func clipInformativeWords(text string, limit int) string {
+	flat := strings.Join(strings.Fields(text), " ")
+	if flat == "" || limit <= 0 {
+		return ""
+	}
+	count := 0
+	for _, location := range compactionWordPattern.FindAllStringIndex(flat, -1) {
+		word := strings.ToLower(flat[location[0]:location[1]])
+		if compactionStopWords[word] {
+			continue
+		}
+		count++
+		if count > limit {
+			end := location[0]
+			return strings.TrimSpace(flat[:end]) + "...(truncated)"
+		}
+	}
+	return flat
+}
+
+func clipBytes(text string, limit int) string {
+	text = strings.TrimSpace(text)
+	if limit <= 0 {
+		return ""
+	}
+	if len(text) <= limit {
+		return text
+	}
+	if limit <= 3 {
+		end := limit
+		for end > 0 && end < len(text) && text[end]&0xc0 == 0x80 {
+			end--
+		}
+		return text[:end]
+	}
+	end := limit - 3
+	for end > 0 && end < len(text) && text[end]&0xc0 == 0x80 {
+		end--
+	}
+	return strings.TrimSpace(text[:end]) + "..."
+}
+
+func clipHeadTailBytes(text string, limit int) string {
+	text = strings.TrimSpace(text)
+	if len(text) <= limit {
+		return text
+	}
+	if limit <= 0 {
+		return ""
+	}
+	marker := "\n...[middle omitted]...\n"
+	if limit <= len(marker) {
+		return clipBytes(text, limit)
+	}
+	available := limit - len(marker)
+	head := clipPrefixAtBoundary(text, available/2)
+	tail := clipSuffixAtBoundary(text, available-available/2)
+	return strings.TrimSpace(head) + marker + strings.TrimSpace(tail)
+}
+
+func clipPrefixAtBoundary(text string, limit int) string {
+	if limit <= 0 {
+		return ""
+	}
+	if len(text) <= limit {
+		return text
+	}
+	end := limit
+	for end > 0 && text[end]&0xc0 == 0x80 {
+		end--
+	}
+	if boundary := strings.LastIndex(text[:end], "\n\n["); boundary > 0 {
+		end = boundary
+	}
+	return text[:end]
+}
+
+func clipSuffixAtBoundary(text string, limit int) string {
+	if limit <= 0 {
+		return ""
+	}
+	if len(text) <= limit {
+		return text
+	}
+	start := len(text) - limit
+	for start < len(text) && text[start]&0xc0 == 0x80 {
+		start++
+	}
+	if boundary := strings.Index(text[start:], "\n\n["); boundary >= 0 {
+		start += boundary + 2
+	}
+	return text[start:]
+}
+
+func askUserQuestionsDetail(arguments map[string]any) string {
+	raw, ok := arguments["questions"].([]any)
+	if !ok {
+		return ""
+	}
+	questions := make([]string, 0, len(raw))
+	for _, item := range raw {
+		object, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		if question, ok := object["question"].(string); ok && strings.TrimSpace(question) != "" {
+			questions = append(questions, strings.TrimSpace(question))
+		}
+	}
+	return strings.Join(questions, " | ")
+}
+
+func patchPaths(patch string) []string {
+	var paths []string
+	seen := map[string]bool{}
+	for _, line := range strings.Split(patch, "\n") {
+		for _, prefix := range []string{"*** Add File: ", "*** Update File: ", "*** Delete File: ", "*** Move to: "} {
+			if !strings.HasPrefix(line, prefix) {
+				continue
+			}
+			path := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+			if path != "" && !seen[path] {
+				seen[path] = true
+				paths = append(paths, path)
+			}
+		}
+	}
+	return paths
+}
+
+var compactionStopWords = map[string]bool{
+	"a": true, "an": true, "the": true, "is": true, "are": true, "was": true, "were": true,
+	"be": true, "been": true, "being": true, "have": true, "has": true, "had": true,
+	"do": true, "does": true, "did": true, "will": true, "would": true, "could": true,
+	"should": true, "may": true, "might": true, "shall": true, "can": true, "need": true, "must": true,
+	"to": true, "of": true, "in": true, "for": true, "on": true, "with": true, "at": true,
+	"by": true, "from": true, "as": true, "into": true, "through": true, "during": true,
+	"before": true, "after": true, "above": true, "below": true, "between": true, "under": true, "over": true,
+	"and": true, "but": true, "or": true, "nor": true, "not": true, "so": true, "yet": true,
+	"both": true, "either": true, "neither": true, "each": true, "every": true, "all": true,
+	"any": true, "few": true, "more": true, "most": true, "other": true, "some": true, "such": true, "no": true,
+	"that": true, "this": true, "these": true, "those": true, "it": true, "its": true,
+	"i": true, "me": true, "my": true, "we": true, "our": true, "you": true, "your": true,
+	"he": true, "him": true, "his": true, "she": true, "her": true, "they": true, "them": true, "their": true,
+	"who": true, "which": true, "what": true, "if": true, "then": true, "than": true,
+	"when": true, "where": true, "how": true, "just": true, "also": true,
+}

internal/agent/compaction_projection_test.go

@@ -0,0 +1,130 @@
+package agent
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func TestClipBytesHandlesTinyLimitsOnRuneBoundaries(t *testing.T) {
+	for _, limit := range []int{0, 1, 2, 3} {
+		if clipped := clipBytes("世界", limit); len(clipped) > limit || !utf8.ValidString(clipped) {
+			t.Fatalf("clipBytes limit %d returned invalid result %q", limit, clipped)
+		}
+	}
+}
+
+func TestBoundaryClippersHandleNonPositiveLimits(t *testing.T) {
+	for _, clip := range []func(string, int) string{clipPrefixAtBoundary, clipSuffixAtBoundary} {
+		for _, limit := range []int{-1, 0} {
+			if got := clip("世界", limit); got != "" {
+				t.Fatalf("clipper limit %d = %q, want empty", limit, got)
+			}
+		}
+	}
+}
+
+func TestProjectCompactionInputDropsRecoverableToolBodies(t *testing.T) {
+	largeBody := strings.Repeat("recoverable source line\n", 1000)
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleUser, Content: "Inspect the parser and preserve its current behavior."},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "I will inspect before editing.", ToolCalls: []zeroruntime.ToolCall{{ID: "read", Name: "read_file", Arguments: `{"path":"internal/parser.go"}`}}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "read", Content: largeBody},
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{ID: "test", Name: "exec_command", Arguments: `{"cmd":"go test ./internal/parser"}`}}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "test", Content: "Error: parser regression\nlong diagnostic details"},
+	}
+
+	projection := projectCompactionInput(messages)
+	projected := projection.messages
+	if len(projected) != 1 {
+		t.Fatalf("projection = %#v, want one compact message", projected)
+	}
+	content := projected[0].Content
+	for _, want := range []string{"Inspect the parser", `read_file "internal/parser.go"`, `exec_command "go test ./internal/parser"`, "Error: parser regression"} {
+		if !strings.Contains(content, want) {
+			t.Fatalf("projection missing %q: %q", want, content)
+		}
+	}
+	if strings.Contains(content, "recoverable source line") || strings.Contains(content, "long diagnostic details") {
+		t.Fatalf("projection retained reconstructible or overlong tool output: %q", content)
+	}
+	if estimateTokens(projected)*20 >= estimateTokens(messages) {
+		t.Fatalf("projection did not materially reduce tokens: before=%d after=%d", estimateTokens(messages), estimateTokens(projected))
+	}
+}
+
+func TestProjectCompactionInputRetainsStructurallyMarkedToolErrors(t *testing.T) {
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{ID: "git", Name: "exec_command", Arguments: `{"cmd":"git status"}`}}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "git", Content: "fatal: not a git repository", IsError: true},
+	}
+
+	projected := projectCompactionInput(messages).messages
+	if len(projected) != 1 || !strings.Contains(projected[0].Content, "fatal: not a git repository") {
+		t.Fatalf("structured tool error was dropped from projection: %#v", projected)
+	}
+}
+
+func TestProjectCompactionInputRetainsAskUserExchangeAndSemanticArguments(t *testing.T) {
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{ID: "ask", Name: "ask_user", Arguments: `{"questions":[{"question":"Which database should remain?"}]}`}}},
+		{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: "fetch", Name: "web_fetch", Arguments: `{"url":"https://example.com/spec"}`},
+			{ID: "task", Name: "task", Arguments: `{"prompt":"Inspect the Windows implementation"}`},
+		}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "patch", Content: "Done!", ChangedFiles: []string{"internal/db.go"}},
+	}
+
+	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"} {
+		if !strings.Contains(content, want) {
+			t.Fatalf("projection missing %q: %q", want, content)
+		}
+	}
+}
+
+func TestProjectCompactionInputCapsToolCallsPerTurn(t *testing.T) {
+	calls := make([]zeroruntime.ToolCall, 12)
+	for index := range calls {
+		calls[index] = zeroruntime.ToolCall{Name: "read_file", Arguments: `{"path":"file.go"}`}
+	}
+	projected := projectCompactionInput([]zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: calls}}).messages
+	content := projected[0].Content
+	if strings.Count(content, "* read_file") != compactionToolCallsPerTurn || !strings.Contains(content, "4 earlier tool calls omitted") {
+		t.Fatalf("tool-call tail was not bounded: %q", content)
+	}
+}
+
+func TestProjectCompactionInputCarriesPreviousSummaryOutsideBriefCap(t *testing.T) {
+	previous := "keep the earlier architecture decision\n" + strings.Repeat("prior detail ", 2000) + "\nkeep the newest prior decision"
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: summaryLabel + "\n" + previous + "\n\n" + preservedStateLabel + "\n{}"}}
+	for index := range 500 {
+		messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: strings.Repeat("later transcript detail ", 20)})
+		messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "later request " + strings.Repeat("context ", 20) + string(rune('a'+index%26))})
+	}
+
+	projection := projectCompactionInput(messages)
+	content := projection.messages[0].Content
+	if !strings.Contains(content, "[previous summary]\nkeep the earlier architecture decision") || !strings.Contains(content, "keep the newest prior decision") {
+		t.Fatalf("previous summary was lost when the brief tail was capped: %q", content)
+	}
+	if !strings.Contains(content, "middle transcript omitted to fit compaction budget") {
+		t.Fatalf("oversized brief was not head/tail capped: %q", content)
+	}
+	if !projection.truncated {
+		t.Fatal("projection did not structurally report truncation")
+	}
+}
+
+func TestProjectCompactionInputDoesNotInferTruncationFromUserText(t *testing.T) {
+	projection := projectCompactionInput([]zeroruntime.Message{{
+		Role: zeroruntime.MessageRoleUser, Content: "Keep this literal marker: [middle omitted]",
+	}})
+	if projection.truncated {
+		t.Fatal("literal user text produced a false truncation signal")
+	}
+}

internal/agent/compaction_recent_edits_test.go

@@ -20,11 +20,15 @@ func TestRecentEditsExtractsPathsAndNotes(t *testing.T) {
 			{ID: "e2", Name: "edit_file", Arguments: `{"path":"internal/bar.go","old_string":"a","new_string":"b"}`},
 		}},
 		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e2", Content: "Applied edit to internal/bar.go"},
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+			{ID: "e3", Name: "apply_patch", Arguments: `{"patch":"*** Update File: internal/baz.go"}`},
+		}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e3", Content: "Done!", ChangedFiles: []string{"internal/baz.go"}},
 	}
 
 	edits := recentEdits(messages)
-	if len(edits) != 2 {
-		t.Fatalf("expected 2 edited files, got %d: %#v", len(edits), edits)
+	if len(edits) != 3 {
+		t.Fatalf("expected 3 edited files, got %d: %#v", len(edits), edits)
 	}
 	if edits[0].name != "internal/foo.go" || !strings.Contains(edits[0].body, "12 lines") {
 		t.Fatalf("first edit = %#v, want foo.go with its note", edits[0])
@@ -32,6 +36,9 @@ func TestRecentEditsExtractsPathsAndNotes(t *testing.T) {
 	if edits[1].name != "internal/bar.go" || !strings.Contains(edits[1].body, "Applied edit") {
 		t.Fatalf("second edit = %#v, want bar.go with its note", edits[1])
 	}
+	if edits[2].name != "internal/baz.go" || edits[2].body != "Done!" {
+		t.Fatalf("third edit = %#v, want apply_patch changed file with its note", edits[2])
+	}
 }
 
 // After compaction elides the editing turns, the preserved-state block still

internal/agent/compaction_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/trace"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
@@ -58,12 +59,15 @@ func TestCompactKeepsSystemAndPreservedSuffix(t *testing.T) {
 	if last.Content != "most recent question" {
 		t.Fatalf("expected most recent message preserved, got %q", last.Content)
 	}
-	// The summarized middle excludes system and preserved suffix.
-	if len(captured) != 3 {
-		t.Fatalf("expected 3 summarized messages, got %d: %#v", len(captured), captured)
+	// The summarizer receives a compact semantic projection of the middle rather
+	// than reconstructible raw tool output.
+	if len(captured) != 1 || captured[0].Role != zeroruntime.MessageRoleUser {
+		t.Fatalf("expected one projected summary input, got %#v", captured)
 	}
-	if captured[0].Content != "first question" {
-		t.Fatalf("expected oldest non-system message first, got %#v", captured[0])
+	for _, want := range []string{"[user #0]", "first question", "[assistant #1]", "first answer", "second question"} {
+		if !strings.Contains(captured[0].Content, want) {
+			t.Fatalf("projected summary input missing %q: %q", want, captured[0].Content)
+		}
 	}
 	// Compaction must shrink the conversation.
 	if estimateTokens(result) >= estimateTokens(messages) {
@@ -379,6 +383,43 @@ func TestRunNoCompactionWhenContextWindowZero(t *testing.T) {
 	}
 }
 
+func TestMaybeCompactStopsAfterSupersededReadsReachThreshold(t *testing.T) {
+	body := strings.Repeat("same source line\n", 1000)
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "system"},
+		toolCallWithArgs("old", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "old", Content: body},
+		toolCallWithArgs("new", "read_file", `{"path":"a.go"}`),
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "new", Content: body},
+	}
+	pruned, reclaimed := pruneSupersededReadResults(messages)
+	if reclaimed <= 0 {
+		t.Fatal("test setup did not reclaim superseded read output")
+	}
+	prunedSize := estimateTokens(pruned)
+	if estimateTokens(messages) <= prunedSize {
+		t.Fatal("test setup does not cross the compaction threshold")
+	}
+
+	provider := &summarizeRecordingProvider{}
+	state := &compactionState{
+		enabled:      true,
+		threshold:    prunedSize,
+		preserveLast: 2,
+	}
+	got := state.maybeCompact(context.Background(), provider, messages, nil)
+
+	if provider.summarizeCalls != 0 {
+		t.Fatalf("cheap pruning should avoid the summarizer, got %d calls", provider.summarizeCalls)
+	}
+	if state.lowWaterMark != prunedSize {
+		t.Fatalf("lowWaterMark = %d, want %d", state.lowWaterMark, prunedSize)
+	}
+	if !strings.Contains(got[2].Content, "superseded identical") || got[4].Content != body {
+		t.Fatalf("unexpected pruned messages: %#v", got)
+	}
+}
+
 // reactiveProvider builds up history with a tool call on turn 1, then errors
 // with a context-limit message on turn 2 (once the history is large enough that
 // compaction can shrink it), then succeeds on the same-turn retry. Summary
@@ -388,6 +429,7 @@ type reactiveProvider struct {
 	summarizeCalls int
 	turnRequests   int
 	failedOnce     bool
+	connectError   bool
 	bigText        string
 	finalText      string
 }
@@ -409,6 +451,9 @@ func (provider *reactiveProvider) StreamCompletion(ctx context.Context, request
 		return streamEvents(toolTurnWithText(provider.bigText, "1", "read_file", `{"path":"x"}`)), nil
 	case provider.turnRequests == 2 && !provider.failedOnce:
 		provider.failedOnce = true
+		if provider.connectError {
+			return nil, errors.New("context_length_exceeded")
+		}
 		return streamEvents([]zeroruntime.StreamEvent{
 			{Type: zeroruntime.StreamEventError, Error: "This model's maximum context length is 1000 tokens. Please reduce the length of the messages."},
 		}), nil
@@ -417,6 +462,39 @@ func (provider *reactiveProvider) StreamCompletion(ctx context.Context, request
 	}
 }
 
+func TestRunConnectErrorCompactionRecordsReplacementPlan(t *testing.T) {
+	provider := &reactiveProvider{
+		connectError: true,
+		bigText:      strings.Repeat("b", 6000),
+		finalText:    "recovered",
+	}
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))
+	recorder := trace.NewRecorder("connect-compaction", "run-1", "test")
+	var contextPlans []ContextBreakdown
+
+	result, err := Run(context.Background(), strings.Repeat("z", 6000), provider, Options{
+		Registry:               registry,
+		PermissionMode:         PermissionModeUnsafe,
+		ContextWindow:          10_000_000,
+		CompactionPreserveLast: 2,
+		Trace:                  recorder,
+		OnContext: func(breakdown ContextBreakdown) {
+			contextPlans = append(contextPlans, breakdown)
+		},
+	})
+	if err != nil || result.FinalAnswer != "recovered" {
+		t.Fatalf("connect-error compaction failed: result=%#v err=%v", result, err)
+	}
+	if len(contextPlans) != 3 || contextPlans[2].MessageTokens >= contextPlans[1].MessageTokens {
+		t.Fatalf("replacement request context not reported: %#v", contextPlans)
+	}
+	gotTrace := recorder.Finish()
+	if len(gotTrace.PrefixHashes) != 4 || gotTrace.PrefixHashes[3].InvalidationReason != "unchanged" {
+		t.Fatalf("replacement request trace not recorded: %#v", gotTrace.PrefixHashes)
+	}
+}
+
 func TestRunReactiveCompactionRecovers(t *testing.T) {
 	provider := &reactiveProvider{
 		bigText:   strings.Repeat("b", 6000),
@@ -428,6 +506,8 @@ func TestRunReactiveCompactionRecovers(t *testing.T) {
 	// bloats the history.
 	registry := tools.NewRegistry()
 	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))
+	recorder := trace.NewRecorder("reactive-compaction", "run-1", "test")
+	var contextPlans []ContextBreakdown
 
 	// ContextWindow large enough that proactive compaction never triggers, so
 	// only the reactive path can save the run.
@@ -436,6 +516,10 @@ func TestRunReactiveCompactionRecovers(t *testing.T) {
 		PermissionMode:         PermissionModeUnsafe,
 		ContextWindow:          10_000_000,
 		CompactionPreserveLast: 2,
+		Trace:                  recorder,
+		OnContext: func(breakdown ContextBreakdown) {
+			contextPlans = append(contextPlans, breakdown)
+		},
 	})
 	if err != nil {
 		t.Fatalf("expected reactive compaction to recover the run, got error: %v", err)
@@ -446,6 +530,25 @@ func TestRunReactiveCompactionRecovers(t *testing.T) {
 	if provider.summarizeCalls == 0 {
 		t.Fatal("expected reactive compaction to invoke the summarizer")
 	}
+	if len(contextPlans) != 3 {
+		t.Fatalf("main request context callbacks = %d, want initial turns plus compacted retry", len(contextPlans))
+	}
+	if contextPlans[2].MessageTokens >= contextPlans[1].MessageTokens {
+		t.Fatalf("retry context was not updated after compaction: before=%d after=%d", contextPlans[1].MessageTokens, contextPlans[2].MessageTokens)
+	}
+	gotTrace := recorder.Finish()
+	if len(gotTrace.PrefixHashes) != 4 {
+		t.Fatalf("prefix evidence count = %d, want two turns, compaction, and retry: %#v", len(gotTrace.PrefixHashes), gotTrace.PrefixHashes)
+	}
+	if gotTrace.PrefixHashes[0].InvalidationReason != "initial" ||
+		gotTrace.PrefixHashes[1].InvalidationReason != "unchanged" ||
+		gotTrace.PrefixHashes[2].InvalidationReason != "initial" ||
+		gotTrace.PrefixHashes[3].InvalidationReason != "unchanged" {
+		t.Fatalf("unexpected request-specific invalidation evidence: %#v", gotTrace.PrefixHashes)
+	}
+	if gotTrace.PrefixHashes[2].CompletePrefixHash == gotTrace.PrefixHashes[1].CompletePrefixHash {
+		t.Fatalf("compaction fingerprint reused the main request prefix: %#v", gotTrace.PrefixHashes)
+	}
 }
 
 // midStreamReactiveProvider forwards some text BEFORE surfacing a context-limit

internal/agent/context_measurement.go

@@ -23,6 +23,24 @@ type ContextBreakdown struct {
 	TotalTokens   int     // SystemTokens + ToolTokens + MessageTokens
 	ContextWindow int     // model context window; 0 when unknown
 	UsedFraction  float64 // TotalTokens / ContextWindow; 0 when window unknown
+	// Blocks explain why each model-visible category is present without exposing
+	// its content. The planner currently preserves all three categories.
+	Blocks []ContextBlock
+	// CompletePrefixHash identifies the provider-visible system+tool prefix.
+	CompletePrefixHash string
+	// PrefixInvalidationReason is "initial", "unchanged", or a stable comma-
+	// separated list of changed prefix categories.
+	PrefixInvalidationReason string
+}
+
+// ContextBlock is content-free evidence for one model-visible context category.
+type ContextBlock struct {
+	Kind        string
+	Tokens      int
+	CacheClass  string
+	Authority   string
+	Recoverable bool
+	Reason      string
 }
 
 // MeasureContext estimates the per-category token footprint of a request: the
@@ -41,6 +59,24 @@ func MeasureContext(messages []zeroruntime.Message, tools []zeroruntime.ToolDefi
 		ContextWindow: contextWindow,
 	}
 	breakdown.TotalTokens = breakdown.SystemTokens + breakdown.ToolTokens + breakdown.MessageTokens
+	if breakdown.SystemTokens > 0 {
+		breakdown.Blocks = append(breakdown.Blocks, ContextBlock{
+			Kind: "system", Tokens: breakdown.SystemTokens, CacheClass: "stable_prefix",
+			Authority: "required", Reason: "instructions, workspace policy, and safety policy",
+		})
+	}
+	if breakdown.ToolTokens > 0 {
+		breakdown.Blocks = append(breakdown.Blocks, ContextBlock{
+			Kind: "tools", Tokens: breakdown.ToolTokens, CacheClass: "stable_prefix",
+			Authority: "capability", Reason: "currently permitted and selected tool definitions",
+		})
+	}
+	if breakdown.MessageTokens > 0 {
+		breakdown.Blocks = append(breakdown.Blocks, ContextBlock{
+			Kind: "conversation", Tokens: breakdown.MessageTokens, CacheClass: "dynamic_tail",
+			Authority: "transcript", Reason: "valid provider replay history and current task context",
+		})
+	}
 	if contextWindow > 0 {
 		breakdown.UsedFraction = float64(breakdown.TotalTokens) / float64(contextWindow)
 	}

internal/agent/context_measurement_test.go

@@ -32,6 +32,9 @@ func TestMeasureContextSplitsByCategory(t *testing.T) {
 	if breakdown.UsedFraction != wantFraction {
 		t.Fatalf("UsedFraction = %v, want %v", breakdown.UsedFraction, wantFraction)
 	}
+	if len(breakdown.Blocks) != 3 {
+		t.Fatalf("Blocks = %#v, want system/tools/conversation", breakdown.Blocks)
+	}
 }
 
 func TestMeasureContextUnknownWindowHasZeroFraction(t *testing.T) {

internal/agent/context_planner.go

@@ -0,0 +1,183 @@
+package agent
+
+import (
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+type contextPlannerConfig struct {
+	contextWindow  int
+	promptCacheKey string
+	promptParts    systemPromptParts
+}
+
+// contextPlanner is the single seam for constructing model-visible requests.
+// Planning is deterministic and does not retrieve content, execute tools, or
+// change permissions. The initial implementation deliberately preserves every
+// message and tool definition while making composition and cache drift
+// inspectable; later selection policies must continue to cross this seam.
+type contextPlanner struct {
+	config          contextPlannerConfig
+	previousPrefix  prefixFingerprint
+	hasPrevious     bool
+	toolSnapshotKey string
+	toolSnapshot    []zeroruntime.ToolDefinition
+}
+
+type contextPlan struct {
+	Request           zeroruntime.CompletionRequest
+	Breakdown         ContextBreakdown
+	PrefixFingerprint prefixFingerprint
+}
+
+func newContextPlanner(config contextPlannerConfig) *contextPlanner {
+	return &contextPlanner{config: config}
+}
+
+// Plan returns a provider request snapshot plus content-free accounting.
+// It intentionally performs no relevance filtering: preserving current model
+// capability is the baseline contract for future planner policies.
+func (planner *contextPlanner) Plan(messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, reasoningEffort string) contextPlan {
+	return planner.plan(messages, toolDefs, reasoningEffort, planner.config.promptParts)
+}
+
+// planWithPromptParts plans a request whose stable system sections differ from
+// the planner's configured main-run prompt, such as a compaction summary call.
+func (planner *contextPlanner) planWithPromptParts(messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, reasoningEffort string, parts systemPromptParts) contextPlan {
+	return planner.plan(messages, toolDefs, reasoningEffort, parts)
+}
+
+func (planner *contextPlanner) plan(messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, reasoningEffort string, parts systemPromptParts) contextPlan {
+	requestMessages := copyMessages(messages)
+	requestSystemPrompt := leadingSystemContent(requestMessages)
+	if parts.prompt != requestSystemPrompt {
+		// Component boundaries from a different request would make the detailed
+		// invalidation reason misleading. Retain the exact request prefix and
+		// classify it conservatively as an unstructured system prompt instead.
+		parts = systemPromptParts{prompt: requestSystemPrompt}
+	}
+	fingerprint := computePrefixFingerprint(buildPromptSubstringsFromParts(parts, toolDefs))
+	request := zeroruntime.CompletionRequest{
+		Messages:        requestMessages,
+		Tools:           planner.snapshotTools(toolDefs, fingerprint),
+		ReasoningEffort: reasoningEffort,
+		PromptCacheKey:  planner.config.promptCacheKey,
+	}
+	breakdown := MeasureContext(request.Messages, request.Tools, planner.config.contextWindow)
+	breakdown.CompletePrefixHash = fingerprint.CompletePrefixHash
+	var previous *prefixFingerprint
+	if planner.hasPrevious {
+		previous = &planner.previousPrefix
+	}
+	breakdown.PrefixInvalidationReason = explainPrefixChange(previous, fingerprint)
+	planner.previousPrefix = fingerprint
+	planner.hasPrevious = true
+	return contextPlan{
+		Request:           request,
+		Breakdown:         breakdown,
+		PrefixFingerprint: fingerprint,
+	}
+}
+
+// snapshotTools freezes provider-visible tool definitions when their semantic
+// fingerprint changes. Stable turns reuse the frozen schemas instead of
+// recursively cloning every map and slice for every request.
+func (planner *contextPlanner) snapshotTools(toolDefs []zeroruntime.ToolDefinition, fingerprint prefixFingerprint) []zeroruntime.ToolDefinition {
+	key := fingerprint.ToolsHash + "\x00" + fingerprint.SchemaHash
+	if planner.toolSnapshotKey != key {
+		planner.toolSnapshot = copyToolDefinitions(toolDefs)
+		planner.toolSnapshotKey = key
+	}
+	return planner.toolSnapshot
+}
+
+func copyToolDefinitions(toolDefs []zeroruntime.ToolDefinition) []zeroruntime.ToolDefinition {
+	if toolDefs == nil {
+		return nil
+	}
+	copied := make([]zeroruntime.ToolDefinition, len(toolDefs))
+	for index, definition := range toolDefs {
+		copied[index] = definition
+		copied[index].Parameters = copySchemaMap(definition.Parameters)
+	}
+	return copied
+}
+
+func copySchemaMap(schema map[string]any) map[string]any {
+	if schema == nil {
+		return nil
+	}
+	copied := make(map[string]any, len(schema))
+	for key, value := range schema {
+		copied[key] = copySchemaValue(value)
+	}
+	return copied
+}
+
+func copySchemaValue(value any) any {
+	switch typed := value.(type) {
+	case map[string]any:
+		return copySchemaMap(typed)
+	case []any:
+		copied := make([]any, len(typed))
+		for index, item := range typed {
+			copied[index] = copySchemaValue(item)
+		}
+		return copied
+	case []string:
+		return append([]string(nil), typed...)
+	default:
+		return value
+	}
+}
+
+func leadingSystemContent(messages []zeroruntime.Message) string {
+	contents := make([]string, 0, 1)
+	for _, message := range messages {
+		if message.Role != zeroruntime.MessageRoleSystem {
+			break
+		}
+		contents = append(contents, message.Content)
+	}
+	return strings.Join(contents, "\n\n")
+}
+
+func explainPrefixChange(previous *prefixFingerprint, current prefixFingerprint) string {
+	if previous == nil {
+		return "initial"
+	}
+	if previous.CompletePrefixHash == current.CompletePrefixHash {
+		return "unchanged"
+	}
+	reasons := make([]string, 0, 3)
+	if previous.SystemPromptHash != current.SystemPromptHash {
+		parts := make([]string, 0, 4)
+		if previous.BaseInstructionsHash != current.BaseInstructionsHash {
+			parts = append(parts, "base_instructions")
+		}
+		if previous.ConfirmationPolicyHash != current.ConfirmationPolicyHash {
+			parts = append(parts, "confirmation_policy")
+		}
+		if previous.ProjectContextHash != current.ProjectContextHash {
+			parts = append(parts, "project_context")
+		}
+		if previous.SkillsHash != current.SkillsHash {
+			parts = append(parts, "skills")
+		}
+		if len(parts) == 0 {
+			parts = append(parts, "system_prompt")
+		}
+		reasons = append(reasons, parts...)
+	}
+	if previous.ToolsHash != current.ToolsHash {
+		reasons = append(reasons, "tools")
+	}
+	if previous.SchemaHash != current.SchemaHash {
+		reasons = append(reasons, "schema")
+	}
+	if len(reasons) == 0 {
+		return "prefix_changed"
+	}
+	return strings.Join(reasons, ",")
+}

internal/agent/context_planner_test.go

@@ -0,0 +1,185 @@
+package agent
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func TestContextPlannerPreservesProviderRequest(t *testing.T) {
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "system"},
+		{Role: zeroruntime.MessageRoleUser, Content: "inspect this", Images: []zeroruntime.ImageBlock{{MediaType: "image/png", Data: []byte{1, 2, 3}}}},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "working", ToolCalls: []zeroruntime.ToolCall{{ID: "call-1", Name: "read_file", Arguments: `{"path":"main.go"}`}}, Reasoning: []zeroruntime.ReasoningBlock{{Provider: "test", Type: "thinking", Signature: "sig"}}},
+	}
+	toolDefs := []zeroruntime.ToolDefinition{{
+		Name: "read_file", Description: "Read a file",
+		Parameters: map[string]any{
+			"type":       "object",
+			"required":   []string{"path"},
+			"properties": map[string]any{"path": map[string]any{"type": "string"}},
+			"anyOf":      []any{map[string]any{"type": "object"}},
+		},
+	}}
+	planner := newContextPlanner(contextPlannerConfig{
+		contextWindow:  128_000,
+		promptCacheKey: "session-1",
+		promptParts:    systemPromptParts{prompt: "system", baseInstructions: "system"},
+	})
+
+	plan := planner.Plan(messages, toolDefs, "medium")
+	want := zeroruntime.CompletionRequest{
+		Messages:        copyMessages(messages),
+		Tools:           toolDefs,
+		ReasoningEffort: "medium",
+		PromptCacheKey:  "session-1",
+	}
+	if !reflect.DeepEqual(plan.Request, want) {
+		t.Fatalf("planned request changed provider input:\n got: %#v\nwant: %#v", plan.Request, want)
+	}
+	stable := planner.Plan(messages, toolDefs, "medium")
+	if &stable.Request.Tools[0] != &plan.Request.Tools[0] {
+		t.Fatal("stable tool fingerprint rebuilt the immutable schema snapshot")
+	}
+
+	// A plan owns its request snapshot; later caller mutation cannot change its
+	// messages or its recursively nested tool schema.
+	messages[1].Content = "changed"
+	messages[1].Images[0].Data[0] = 9
+	toolDefs[0].Name = "changed_tool"
+	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"
+	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].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" {
+		t.Fatalf("planned tools alias caller state: %#v", plan.Request.Tools[0])
+	}
+
+	next := planner.Plan(messages, toolDefs, "medium")
+	if next.PrefixFingerprint == plan.PrefixFingerprint || next.Request.Tools[0].Name != "changed_tool" {
+		t.Fatalf("changed tool schema did not refresh snapshot: %#v", next)
+	}
+	if plan.Request.Tools[0].Name != "read_file" {
+		t.Fatalf("refresh mutated earlier request: %#v", plan.Request.Tools[0])
+	}
+}
+
+func TestContextPlannerReportsInspectableBlocks(t *testing.T) {
+	planner := newContextPlanner(contextPlannerConfig{contextWindow: 100_000})
+	plan := planner.Plan([]zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: filler(400)},
+		{Role: zeroruntime.MessageRoleUser, Content: filler(200)},
+	}, []zeroruntime.ToolDefinition{{Name: "read_file", Description: "Read a file"}}, "")
+
+	if plan.Breakdown.PrefixInvalidationReason != "initial" || plan.Breakdown.CompletePrefixHash == "" {
+		t.Fatalf("prefix evidence = %#v", plan.Breakdown)
+	}
+	if len(plan.Breakdown.Blocks) != 3 {
+		t.Fatalf("blocks = %#v, want system/tools/conversation", plan.Breakdown.Blocks)
+	}
+	wantKinds := []string{"system", "tools", "conversation"}
+	total := 0
+	for index, block := range plan.Breakdown.Blocks {
+		if block.Kind != wantKinds[index] || block.Tokens <= 0 || block.Reason == "" || block.Authority == "" || block.CacheClass == "" {
+			t.Fatalf("block %d = %#v", index, block)
+		}
+		total += block.Tokens
+	}
+	if total != plan.Breakdown.TotalTokens {
+		t.Fatalf("block tokens = %d, want total %d", total, plan.Breakdown.TotalTokens)
+	}
+}
+
+func TestContextPlannerFingerprintsActualRequestSystemPrompt(t *testing.T) {
+	planner := newContextPlanner(contextPlannerConfig{promptParts: systemPromptParts{
+		prompt: "configured system", baseInstructions: "configured system",
+	}})
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "request-specific system"},
+		{Role: zeroruntime.MessageRoleUser, Content: "task"},
+	}
+
+	plan := planner.Plan(messages, nil, "")
+	want := computePrefixFingerprint(buildPromptSubstringsFromParts(
+		systemPromptParts{prompt: "request-specific system"}, nil,
+	))
+	if plan.PrefixFingerprint != want {
+		t.Fatalf("fingerprint describes configured prompt instead of request:\n got: %#v\nwant: %#v", plan.PrefixFingerprint, want)
+	}
+}
+
+func TestContextPlannerExplainsPrefixInvalidation(t *testing.T) {
+	planner := newContextPlanner(contextPlannerConfig{promptParts: systemPromptParts{
+		prompt: "system", baseInstructions: "base", projectContext: "project",
+	}})
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleSystem, Content: "system"}, {Role: zeroruntime.MessageRoleUser, Content: "task"}}
+	tools := []zeroruntime.ToolDefinition{{Name: "read_file", Description: "Read", Parameters: map[string]any{"type": "object"}}}
+
+	if got := planner.Plan(messages, tools, "").Breakdown.PrefixInvalidationReason; got != "initial" {
+		t.Fatalf("first reason = %q, want initial", got)
+	}
+	if got := planner.Plan(messages, tools, "").Breakdown.PrefixInvalidationReason; got != "unchanged" {
+		t.Fatalf("stable reason = %q, want unchanged", got)
+	}
+	tools[0].Description = "Read an exact file"
+	if got := planner.Plan(messages, tools, "").Breakdown.PrefixInvalidationReason; got != "tools" {
+		t.Fatalf("tool reason = %q, want tools", got)
+	}
+	tools[0].Parameters["required"] = []any{"path"}
+	if got := planner.Plan(messages, tools, "").Breakdown.PrefixInvalidationReason; got != "schema" {
+		t.Fatalf("schema reason = %q, want schema", got)
+	}
+	planner.config.promptParts.prompt = "system with changed project"
+	planner.config.promptParts.projectContext = "changed project"
+	messages[0].Content = "system with changed project"
+	if got := planner.Plan(messages, tools, "").Breakdown.PrefixInvalidationReason; got != "project_context" {
+		t.Fatalf("project reason = %q, want project_context", got)
+	}
+}
+
+func TestExplainPrefixChangeNamesEveryChangedComponent(t *testing.T) {
+	baseline := prefixFingerprint{
+		SystemPromptHash:       "system",
+		BaseInstructionsHash:   "base",
+		ConfirmationPolicyHash: "policy",
+		ProjectContextHash:     "project",
+		SkillsHash:             "skills",
+		ToolsHash:              "tools",
+		SchemaHash:             "schema",
+		CompletePrefixHash:     "complete",
+	}
+	tests := []struct {
+		name   string
+		mutate func(*prefixFingerprint)
+		want   string
+	}{
+		{name: "base instructions", mutate: func(value *prefixFingerprint) {
+			value.SystemPromptHash, value.BaseInstructionsHash = "changed", "changed"
+		}, want: "base_instructions"},
+		{name: "confirmation policy", mutate: func(value *prefixFingerprint) {
+			value.SystemPromptHash, value.ConfirmationPolicyHash = "changed", "changed"
+		}, want: "confirmation_policy"},
+		{name: "project context", mutate: func(value *prefixFingerprint) {
+			value.SystemPromptHash, value.ProjectContextHash = "changed", "changed"
+		}, want: "project_context"},
+		{name: "skills", mutate: func(value *prefixFingerprint) { value.SystemPromptHash, value.SkillsHash = "changed", "changed" }, want: "skills"},
+		{name: "unclassified system prompt", mutate: func(value *prefixFingerprint) { value.SystemPromptHash = "changed" }, want: "system_prompt"},
+		{name: "tools and schema", mutate: func(value *prefixFingerprint) { value.ToolsHash, value.SchemaHash = "changed", "changed" }, want: "tools,schema"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			current := baseline
+			test.mutate(&current)
+			current.CompletePrefixHash = "changed"
+			if got := explainPrefixChange(&baseline, current); got != test.want {
+				t.Fatalf("reason = %q, want %q", got, test.want)
+			}
+		})
+	}
+}

internal/agent/deferred_loop_test.go

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

internal/agent/loop.go

@@ -183,10 +183,22 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 	defer runPermissions.cleanup()
 
 	promptParts := buildSystemPromptParts(options)
+	planner := newContextPlanner(contextPlannerConfig{
+		contextWindow:  options.ContextWindow,
+		promptCacheKey: options.SessionID,
+		promptParts:    promptParts,
+	})
 	messages := zeroruntime.SeedMessagesWithImages(promptParts.prompt, prompt, options.Images)
 
 	guards := newGuardState()
 	task := newTaskState(prompt, options.Trace)
+	onPermission := options.OnPermission
+	options.OnPermission = func(event PermissionEvent) {
+		task.observe(taskStateEvent{kind: taskStateEventPermission, permission: event})
+		if onPermission != nil {
+			onPermission(event)
+		}
+	}
 	compactor := newCompactionState(options, task)
 	defer func() {
 		// A final transcript comparison is observational. It records drift but
@@ -275,42 +287,15 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		exposed, _ := partitionToolsCached(registry, permissionMode, options, loaded, toolDefCache)
 		toolPartitionSpan.End()
 
-		// Fingerprint the exact system prompt built at run start plus this turn's
-		// provider-visible tool definitions in their emitted order. Reusing the
-		// retained prompt parts avoids rebuilding workspace context while ensuring
-		// the trace describes the same bytes carried by the request.
-		if options.Trace != nil {
-			fp := computePrefixFingerprint(buildPromptSubstringsFromParts(promptParts, exposed))
-			options.Trace.EmitPrefixHash(trace.PrefixHash{
-				SystemPromptHash:       fp.SystemPromptHash,
-				BaseInstructionsHash:   fp.BaseInstructionsHash,
-				ConfirmationPolicyHash: fp.ConfirmationPolicyHash,
-				ProjectContextHash:     fp.ProjectContextHash,
-				SkillsHash:             fp.SkillsHash,
-				ToolsHash:              fp.ToolsHash,
-				SchemaHash:             fp.SchemaHash,
-				CompletePrefixHash:     fp.CompletePrefixHash,
-			})
-		}
-
 		// PROACTIVE compaction: if the history is approaching the model's
 		// context window, summarize the oldest middle before building the
 		// request. A no-op when ContextWindow == 0 (compaction disabled).
 		compactionSpan := options.Trace.Span(trace.SpanCompaction)
 		messages = compactor.maybeCompact(ctx, provider, messages, exposed)
 		compactionSpan.End()
-		request := zeroruntime.CompletionRequest{
-			Messages:        copyMessages(messages),
-			Tools:           exposed,
-			ReasoningEffort: options.ReasoningEffort,
-			PromptCacheKey:  options.SessionID,
-		}
-
-		// Report the per-category context budget for this turn so a surface can
-		// show utilization. Opt-in: a no-op when OnContext is unset.
-		if options.OnContext != nil {
-			options.OnContext(MeasureContext(messages, request.Tools, options.ContextWindow))
-		}
+		plan := planner.Plan(messages, exposed, options.ReasoningEffort)
+		request := plan.Request
+		recordContextPlan(options, plan)
 
 		// A transient upstream disconnect on the initial connect is retried with
 		// backoff (before any content is forwarded, so no OnText is duplicated);
@@ -335,12 +320,9 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				// on registry+loaded, not on the messages, so they stay valid after
 				// compaction. Using the bare toolDefinitions here would route through an
 				// empty-loaded partition, re-hiding every already-loaded deferred tool.
-				request = zeroruntime.CompletionRequest{
-					Messages:        copyMessages(messages),
-					Tools:           exposed,
-					ReasoningEffort: options.ReasoningEffort,
-					PromptCacheKey:  options.SessionID,
-				}
+				retryPlan := planner.Plan(messages, exposed, options.ReasoningEffort)
+				request = retryPlan.Request
+				recordContextPlan(options, retryPlan)
 				// Pre-content connect after a context-limit compaction: route through the
 				// reconnect helper so a transient upstream hiccup here doesn't fail the
 				// whole run and re-burn every token (AUDIT-L1).
@@ -424,12 +406,9 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				// Reuse the SAME active-mode partition (exposed) from this turn rather
 				// than the bare toolDefinitions: exposed depends on registry+loaded (not
 				// the messages), so it stays valid after compaction.
-				retryRequest := zeroruntime.CompletionRequest{
-					Messages:        copyMessages(messages),
-					Tools:           exposed,
-					ReasoningEffort: options.ReasoningEffort,
-					PromptCacheKey:  options.SessionID,
-				}
+				retryPlan := planner.Plan(messages, exposed, options.ReasoningEffort)
+				retryRequest := retryPlan.Request
+				recordContextPlan(options, retryPlan)
 				retryStream, retryStreamErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
 				if retryStreamErr != nil {
 					return collected, retryStreamErr
@@ -487,12 +466,9 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				result.Messages = copyMessages(messages)
 				return result, err
 			}
-			retryRequest := zeroruntime.CompletionRequest{
-				Messages:        copyMessages(messages),
-				Tools:           exposed,
-				ReasoningEffort: options.ReasoningEffort,
-				PromptCacheKey:  options.SessionID,
-			}
+			retryPlan := planner.Plan(messages, exposed, options.ReasoningEffort)
+			retryRequest := retryPlan.Request
+			recordContextPlan(options, retryPlan)
 			retryStream, retryErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
 			if retryErr != nil {
 				result.Messages = copyMessages(messages)
@@ -656,6 +632,13 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		// between tool_results breaks strict provider replay) — same after-batch
 		// rationale as turnRequestedModel above.
 		var changedFilesThisBatch []string
+		// Images produced by tools this turn, held until every tool_result is
+		// recorded. They travel as user messages, and a user message between two
+		// tool_results breaks strict provider replay — Anthropic coalesces them
+		// into one user block list and requires the tool_result blocks first, so
+		// interleaving yields [tool_result, text, image, tool_result] and a 400.
+		// Same reason the self-correction feedback below is deferred.
+		var toolImageMessages []zeroruntime.Message
 		// Parallel read-ahead state: results for calls[precomputedStart:precomputedEnd]
 		// executed concurrently, consumed strictly in order below.
 		var precomputed []precomputedToolResult
@@ -691,7 +674,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 			options.Trace.Counter(trace.CounterToolCalls, 1)
 			recordOutputBudgetTrace(options.Trace, toolResult)
-			task.observe(taskStateEvent{kind: taskStateEventToolResult, toolResult: toolResult})
+			task.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: call.Arguments, toolResult: toolResult})
 			if options.OnToolResult != nil {
 				options.OnToolResult(toolResult)
 			}
@@ -705,10 +688,22 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				turnRequestedModel = toolResult.RequestedModel
 			}
 			messages = append(messages, zeroruntime.Message{
-				Role:       zeroruntime.MessageRoleTool,
-				Content:    toolResult.Output,
-				ToolCallID: toolResult.ToolCallID,
+				Role:         zeroruntime.MessageRoleTool,
+				Content:      toolResult.Output,
+				ToolCallID:   toolResult.ToolCallID,
+				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 —
+			// Anthropic's tool_result content is a string, Gemini's is a
+			// functionResponse, and OpenAI guards its image parts to the user role
+			// — so attaching them there would silently deliver nothing. A separate
+			// message also keeps the one-tool-result-per-tool-call pairing intact,
+			// which the providers validate.
+			if imageMessage, ok := toolResultImageMessage(toolResult); ok {
+				toolImageMessages = append(toolImageMessages, imageMessage)
+			}
 
 			// A tool may demand the run ABORT — a canceled/timed-out ask_user prompt
 			// returns context.Canceled rather than fabricating a headless answer. Stop
@@ -719,11 +714,13 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 			if abortErr != nil {
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.Messages = copyMessages(messages)
 				return result, abortErr
 			}
 			if stopReason := stopReasonFromToolResult(toolResult); stopReason != "" {
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.FinalAnswer = toolResult.Output
 				result.StopReason = stopReason
 				result.Messages = copyMessages(messages)
@@ -747,6 +744,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				// messages stay valid for a strict provider replay (Anthropic
 				// rejects a tool_use with no answering tool_result).
 				messages = appendAbortedToolResults(messages, collected.ToolCalls[index+1:])
+				messages = append(messages, toolImageMessages...)
 				result.FinalAnswer = toolFailureStopAnswer(call.Name, outcome.Count)
 				result.Messages = copyMessages(messages)
 				return result, nil
@@ -765,6 +763,10 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				postEditDiagnostics.enqueue(ctx, toolResult.ChangedFiles)
 			}
 		}
+		// Every tool_result for this turn is now recorded, including aborted
+		// placeholders, so the images can follow without splitting them.
+		messages = append(messages, toolImageMessages...)
+		toolImageMessages = nil
 
 		// Run post-edit self-correction once over the union of files this turn
 		// changed, then append any feedback after every tool_result is recorded so
@@ -896,7 +898,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		})
 	}
 	finalExposed, _ := partitionToolsCached(registry, permissionMode, options, loaded, toolDefCache)
-	if answer, finalMessages, finishReason := finalAnswerAfterMaxTurns(ctx, provider, messages, finalExposed, options); strings.TrimSpace(answer) != "" {
+	if answer, finalMessages, finishReason := finalAnswerAfterMaxTurns(ctx, provider, planner, messages, finalExposed, options); strings.TrimSpace(answer) != "" {
 		result.FinalAnswer = answer
 		result.FinishReason = finishReason
 		result.Messages = copyMessages(finalMessages)
@@ -938,7 +940,32 @@ func recordOutputBudgetTrace(recorder *trace.Recorder, result ToolResult) {
 	})
 }
 
-func finalAnswerAfterMaxTurns(ctx context.Context, provider Provider, messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, options Options) (string, []zeroruntime.Message, string) {
+func recordContextPlan(options Options, plan contextPlan) {
+	recordContextPlanTrace(options.Trace, plan)
+	if options.OnContext != nil {
+		options.OnContext(plan.Breakdown)
+	}
+}
+
+func recordContextPlanTrace(recorder *trace.Recorder, plan contextPlan) {
+	if recorder == nil {
+		return
+	}
+	fingerprint := plan.PrefixFingerprint
+	recorder.EmitPrefixHash(trace.PrefixHash{
+		SystemPromptHash:       fingerprint.SystemPromptHash,
+		BaseInstructionsHash:   fingerprint.BaseInstructionsHash,
+		ConfirmationPolicyHash: fingerprint.ConfirmationPolicyHash,
+		ProjectContextHash:     fingerprint.ProjectContextHash,
+		SkillsHash:             fingerprint.SkillsHash,
+		ToolsHash:              fingerprint.ToolsHash,
+		SchemaHash:             fingerprint.SchemaHash,
+		CompletePrefixHash:     fingerprint.CompletePrefixHash,
+		InvalidationReason:     plan.Breakdown.PrefixInvalidationReason,
+	})
+}
+
+func finalAnswerAfterMaxTurns(ctx context.Context, provider Provider, planner *contextPlanner, messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, options Options) (string, []zeroruntime.Message, string) {
 	finalMessages := copyMessages(messages)
 	finalMessages = append(finalMessages, zeroruntime.Message{
 		Role:    zeroruntime.MessageRoleUser,
@@ -947,12 +974,9 @@ func finalAnswerAfterMaxTurns(ctx context.Context, provider Provider, messages [
 	// The max-turns final-answer call is a pre-content connect, often after a long
 	// autonomous/cron run — route it through the reconnect helper so a single
 	// transient hiccup doesn't drop the final summary (AUDIT-L1).
-	stream, err := streamWithReconnect(ctx, provider, zeroruntime.CompletionRequest{
-		Messages:        copyMessages(finalMessages),
-		Tools:           toolDefs,
-		ReasoningEffort: options.ReasoningEffort,
-		PromptCacheKey:  options.SessionID,
-	}, reconnectNoticeFor(options))
+	plan := planner.Plan(finalMessages, toolDefs, options.ReasoningEffort)
+	recordContextPlan(options, plan)
+	stream, err := streamWithReconnect(ctx, provider, plan.Request, reconnectNoticeFor(options))
 	if err != nil {
 		return "", messages, ""
 	}
@@ -1076,6 +1100,9 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			}, nil
 		}
 	}
+	if isShellCommandTool(call.Name) {
+		normalizeNoopAdditionalPermissions(args, options.Cwd, options.Sandbox)
+	}
 	// tool_search is the gateway to the allowlisted deferred tools, so a non-empty
 	// EnabledTools allowlist that omits it must NOT reject the call — otherwise the
 	// discovery tool exposed to the model rejects at dispatch time (an inescapable
@@ -1354,7 +1381,8 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 		Cwd:               options.Cwd,
 		// Per-session file version tracker so write_file/edit_file refuse to clobber
 		// a file that changed on disk outside Zero since it was last read.
-		FileTracker: options.FileTracker,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
 		// Post-edit diagnostics are NOT forwarded to the tools: they used to run
 		// synchronously inside edit_file/write_file and block every mutating tool
 		// call on the language server (≥300ms debounce floor, 10s cap). The loop
@@ -1406,6 +1434,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 			result = registry.RebudgetAfterHook(call.Name, args, result)
 		}
 	}
+	result = registry.CommitFileObservation(result, options.FileTracker)
 	// Stamp the sandbox risk classification for this EXECUTED call so run-policy
 	// observers can see the risk of an allowed mutation. Prefer the preflight
 	// decision's classification when the sandbox evaluated the call; otherwise
@@ -1431,6 +1460,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 		Output:          result.Output,
 		Truncated:       result.Truncated,
 		Meta:            result.Meta,
+		Images:          result.Images,
 		Redacted:        result.Redacted,
 		ChangedFiles:    result.ChangedFiles,
 		ChangeSummaries: result.ChangeSummaries,
@@ -1690,20 +1720,21 @@ func sandboxRestrictionRetryReason(result tools.Result) string {
 
 func runToolForNetworkRetry(ctx context.Context, registry *tools.Registry, name string, toolCallID string, args map[string]any, permissionMode PermissionMode, options Options, progressCallback func(streamjson.Event)) tools.Result {
 	return registry.RunWithOptions(ctx, name, cloneArgs(args), tools.RunOptions{
-		PermissionGranted: true,
-		PermissionMode:    string(permissionMode),
-		Autonomy:          options.Autonomy,
-		Sandbox:           options.Sandbox,
-		ToolCallID:        toolCallID,
-		SessionID:         options.SessionID,
-		Model:             options.Model,
-		ReasoningEffort:   options.ReasoningEffort,
-		Depth:             options.Depth,
-		Cwd:               options.Cwd,
-		FileTracker:       options.FileTracker,
-		EnabledTools:      options.EnabledTools,
-		DisabledTools:     options.DisabledTools,
-		Progress:          progressCallback,
+		PermissionGranted:          true,
+		PermissionMode:             string(permissionMode),
+		Autonomy:                   options.Autonomy,
+		Sandbox:                    options.Sandbox,
+		ToolCallID:                 toolCallID,
+		SessionID:                  options.SessionID,
+		Model:                      options.Model,
+		ReasoningEffort:            options.ReasoningEffort,
+		Depth:                      options.Depth,
+		Cwd:                        options.Cwd,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
+		EnabledTools:               options.EnabledTools,
+		DisabledTools:              options.DisabledTools,
+		Progress:                   progressCallback,
 	})
 }
 
@@ -1718,20 +1749,21 @@ func unsandboxedRetryArgs(args map[string]any) map[string]any {
 
 func runToolForUnsandboxedRetry(ctx context.Context, registry *tools.Registry, name string, toolCallID string, args map[string]any, permissionMode PermissionMode, options Options, progressCallback func(streamjson.Event)) tools.Result {
 	return registry.RunWithOptions(ctx, name, args, tools.RunOptions{
-		PermissionGranted: true,
-		PermissionMode:    string(permissionMode),
-		Autonomy:          options.Autonomy,
-		Sandbox:           options.Sandbox,
-		ToolCallID:        toolCallID,
-		SessionID:         options.SessionID,
-		Model:             options.Model,
-		ReasoningEffort:   options.ReasoningEffort,
-		Depth:             options.Depth,
-		Cwd:               options.Cwd,
-		FileTracker:       options.FileTracker,
-		EnabledTools:      options.EnabledTools,
-		DisabledTools:     options.DisabledTools,
-		Progress:          progressCallback,
+		PermissionGranted:          true,
+		PermissionMode:             string(permissionMode),
+		Autonomy:                   options.Autonomy,
+		Sandbox:                    options.Sandbox,
+		ToolCallID:                 toolCallID,
+		SessionID:                  options.SessionID,
+		Model:                      options.Model,
+		ReasoningEffort:            options.ReasoningEffort,
+		Depth:                      options.Depth,
+		Cwd:                        options.Cwd,
+		FileTracker:                options.FileTracker,
+		DeferFileObservationCommit: true,
+		EnabledTools:               options.EnabledTools,
+		DisabledTools:              options.DisabledTools,
+		Progress:                   progressCallback,
 	})
 }
 
@@ -2748,21 +2780,89 @@ func shellCommandAdditionalPermissionsRequested(args map[string]any) bool {
 	return strings.TrimSpace(value) == string(tools.SandboxPermissionsWithAdditionalPermissions)
 }
 
+// normalizeNoopAdditionalPermissions treats a provider-expanded empty or
+// already-covered additional_permissions object as if it had been omitted.
+// Some strict-schema providers materialize every optional property and may add
+// a workspace read that the default sandbox already grants; rejecting either
+// no-op makes the model retry an otherwise valid command. Requests that broaden
+// access and malformed payloads are left untouched so validation stays closed.
+func normalizeNoopAdditionalPermissions(args map[string]any, basePath string, engine *sandbox.Engine) {
+	raw, exists := args["additional_permissions"]
+	if !exists {
+		return
+	}
+	// An explicit null is the field omitted, not a request: drop the key so the
+	// rest of the pipeline sees the same args a model that omitted it would send.
+	// sandbox_permissions is deliberately left alone — a flagged null must reach
+	// the same "no additional_permissions object was provided" error as a flagged
+	// absent field rather than being silently downgraded to a different outcome.
+	if raw == nil {
+		delete(args, "additional_permissions")
+		return
+	}
+	data, err := json.Marshal(raw)
+	if err != nil {
+		return
+	}
+	var profile sandbox.RequestPermissionProfile
+	if err := json.Unmarshal(data, &profile); err != nil {
+		return
+	}
+	normalized, err := sandbox.NormalizeRequestPermissionProfile(profile, basePath)
+	if err != nil {
+		return
+	}
+	noop := normalized.Empty()
+	if !noop && engine != nil {
+		if grantProfile, grantErr := sandbox.RequestPermissionGrantProfile(normalized); grantErr == nil {
+			noop = engine.CoversRequestPermissions(grantProfile)
+		}
+	}
+	if !noop {
+		return
+	}
+	delete(args, "additional_permissions")
+	if rawMode, ok := args["sandbox_permissions"].(string); ok &&
+		strings.TrimSpace(rawMode) == string(tools.SandboxPermissionsWithAdditionalPermissions) {
+		args["sandbox_permissions"] = string(tools.SandboxPermissionsUseDefault)
+	}
+}
+
+// omitAdditionalPermissionsHint is the one instruction that ends the retry loop
+// in #845/#847. Every additional_permissions rejection must carry it: the model
+// reaches these errors by attaching a permission object to a command that needs
+// none, so "omit it and retry" is the answer in practice, and an error that
+// only explains how to build a VALID permission object sends the model round
+// the loop again with a different invalid shape.
+const omitAdditionalPermissionsHint = "If this command does not need extra sandbox access — ordinary " +
+	"read-only commands such as `git branch --show-current` do not — omit both sandbox_permissions and " +
+	"additional_permissions entirely and retry; that is the fix in almost every case."
+
 func inlineAdditionalPermissionsProfile(args map[string]any, basePath string) (sandbox.RequestPermissionProfile, bool, error) {
 	if !shellCommandAdditionalPermissionsRequested(args) {
-		if _, exists := args["additional_permissions"]; exists {
-			return sandbox.RequestPermissionProfile{}, false, fmt.Errorf("additional_permissions requires sandbox_permissions set to %q", tools.SandboxPermissionsWithAdditionalPermissions)
+		// An explicit null grants nothing and carries no flag, so it is
+		// indistinguishable from an omitted field; rejecting it would be a pure
+		// false positive against providers that materialize every optional
+		// property.
+		if raw, exists := args["additional_permissions"]; exists && raw != nil {
+			return sandbox.RequestPermissionProfile{}, false, fmt.Errorf(
+				"additional_permissions was provided without sandbox_permissions set to %q, so it cannot be applied. %s "+
+					"Only if the command genuinely needs file or network access the sandbox denies, resend with "+
+					`sandbox_permissions: %q AND a non-empty additional_permissions, for example {"network": {"enabled": true}}`,
+				tools.SandboxPermissionsWithAdditionalPermissions,
+				omitAdditionalPermissionsHint,
+				tools.SandboxPermissionsWithAdditionalPermissions)
 		}
 		return sandbox.RequestPermissionProfile{}, false, nil
 	}
 	raw, ok := args["additional_permissions"]
 	if !ok || raw == nil {
 		return sandbox.RequestPermissionProfile{}, true, fmt.Errorf(
-			"sandbox_permissions was set to %q but no additional_permissions object was provided. "+
-				`Include one, for example additional_permissions: {"network": {"enabled": true}} or `+
-				`{"file_system": {"write": ["/path"]}}. If this command does not need elevated permissions, `+
-				"omit sandbox_permissions entirely and retry",
-			tools.SandboxPermissionsWithAdditionalPermissions)
+			"sandbox_permissions was set to %q but no additional_permissions object was provided. %s "+
+				`Otherwise include one, for example additional_permissions: {"network": {"enabled": true}} or `+
+				`{"file_system": {"write": ["/path"]}}`,
+			tools.SandboxPermissionsWithAdditionalPermissions,
+			omitAdditionalPermissionsHint)
 	}
 	data, err := json.Marshal(raw)
 	if err != nil {
@@ -2778,8 +2878,10 @@ func inlineAdditionalPermissionsProfile(args map[string]any, basePath string) (s
 	}
 	if normalized.Empty() {
 		return sandbox.RequestPermissionProfile{}, true, fmt.Errorf(
-			"additional_permissions must include at least one of network or file_system, for example " +
-				`{"network": {"enabled": true}} or {"file_system": {"write": ["/path"]}}`)
+			"additional_permissions granted nothing, so it cannot be applied. %s "+
+				`Otherwise include a real permission, for example {"network": {"enabled": true}} or `+
+				`{"file_system": {"write": ["/path"]}}`,
+			omitAdditionalPermissionsHint)
 	}
 	grantProfile, err := sandbox.RequestPermissionGrantProfile(normalized)
 	if err != nil {
@@ -2938,22 +3040,20 @@ func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMod
 	//   2. tool_search — always present, right after the stable block;
 	//   3. loaded deferred tools, alpha-sorted — APPENDED, so an unloaded->loaded
 	//      transition grows the tail instead of inserting into the eager block.
-	// (tool_search's discovery text still shrinks as tools load, so keeping it and
-	// the loaded tail AFTER the eager block preserves the eager tools' cache across a
-	// load; fully stabilizing the loader's own description is a scoped follow-up.)
+	// tool_search's compact catalog also stays byte-stable as tools load, so only
+	// the appended full-schema tail changes.
 	eager := make([]zeroruntime.ToolDefinition, 0, len(visible))
 	loadedTail := make([]zeroruntime.ToolDefinition, 0)
-	var hiddenTools []tools.Tool
+	var deferredCatalog []tools.Tool
 	for _, tool := range visible {
 		name := tool.Name()
 		if name == tools.ToolSearchToolName {
 			continue // added explicitly between the eager block and the loaded tail
 		}
 		if tools.IsDeferred(tool) {
+			deferredCatalog = append(deferredCatalog, tool)
 			if loaded[name] {
 				loadedTail = append(loadedTail, cachedRuntimeToolDefinition(defCache, tool))
-			} else {
-				hiddenTools = append(hiddenTools, tool)
 			}
 			continue
 		}
@@ -2966,15 +3066,16 @@ func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMod
 		return loadedTail[left].Name < loadedTail[right].Name
 	})
 
-	discovery := ""
-	if len(hiddenTools) > 0 {
-		discovery = tools.BuildToolSearchDescription(hiddenTools)
-	}
+	// Keep the catalog byte-stable as tools load. tool_search already redirects
+	// requests for an exposed tool back to the current tool list, so retaining
+	// loaded names costs only compact catalog lines and avoids invalidating the
+	// provider cache at the loader definition on every load.
+	discovery := tools.BuildToolSearchDescription(deferredCatalog)
 
 	// tool_search is guaranteed runnable on the active path, so it is ALWAYS exposed
 	// — even when a non-empty EnabledTools allowlist omits it (the operator
 	// allowlisted the deferred tools, not the loader). It sits right after the stable
-	// eager block and carries the discovery list for still-hidden tools.
+	// eager block and carries the stable deferred-tool catalog.
 	description := loader.Description()
 	if discovery != "" {
 		description = discovery
@@ -3177,6 +3278,7 @@ func appendAbortedToolResults(messages []Message, remaining []ToolCall) []Messag
 			Role:       zeroruntime.MessageRoleTool,
 			Content:    abortedToolResultNotice,
 			ToolCallID: call.ID,
+			IsError:    true,
 		})
 	}
 	return messages
@@ -3207,9 +3309,46 @@ func copyMessages(messages []Message) []Message {
 		if message.Reasoning != nil {
 			copied[index].Reasoning = append([]zeroruntime.ReasoningBlock{}, message.Reasoning...)
 		}
+		if message.ChangedFiles != nil {
+			copied[index].ChangedFiles = append([]string(nil), message.ChangedFiles...)
+		}
 		// Deep-copy image attachments (slice AND each Data byte slice) so the
 		// raw image bytes are never aliased across history/request/result copies.
 		copied[index].Images = zeroruntime.CloneImageBlocks(message.Images)
 	}
 	return copied
 }
+
+// toolResultImageMessage builds the user message that carries a tool's images
+// to the model, or reports false when the tool produced none.
+//
+// The text names the tool so the model can tell which call an image came from
+// when several ran in one turn — the images arrive detached from their tool
+// result, so nothing else associates them.
+func toolResultImageMessage(result ToolResult) (zeroruntime.Message, bool) {
+	images := make([]zeroruntime.ImageBlock, 0, len(result.Images))
+	for _, image := range result.Images {
+		if len(image.Data) == 0 {
+			continue
+		}
+		mediaType := zeroruntime.NormalizeImageMediaType(image.MediaType)
+		if mediaType == "" {
+			// Outside the provider allow-list. Dropping it beats sending bytes a
+			// provider will reject and failing the whole turn.
+			continue
+		}
+		images = append(images, zeroruntime.ImageBlock{MediaType: mediaType, Data: image.Data})
+	}
+	if len(images) == 0 {
+		return zeroruntime.Message{}, false
+	}
+	label := result.Name
+	if label == "" {
+		label = "tool"
+	}
+	return zeroruntime.Message{
+		Role:    zeroruntime.MessageRoleUser,
+		Content: "Image output from " + label + ":",
+		Images:  images,
+	}, true
+}

internal/agent/loop_test.go

@@ -332,7 +332,8 @@ type sandboxDeniedExecCommandRetryTool struct {
 func (tool *sandboxDeniedExecCommandRetryTool) Name() string { return "exec_command" }
 
 type sandboxNetworkDeniedRetryTool struct {
-	calls []map[string]any
+	calls                      []map[string]any
+	deferFileObservationCommit []bool
 }
 
 func (tool *sandboxNetworkDeniedRetryTool) Name() string        { return "bash" }
@@ -355,6 +356,7 @@ func (tool *sandboxNetworkDeniedRetryTool) Run(ctx context.Context, args map[str
 }
 func (tool *sandboxNetworkDeniedRetryTool) RunWithOptions(ctx context.Context, args map[string]any, options tools.RunOptions) tools.Result {
 	tool.calls = append(tool.calls, cloneArgs(args))
+	tool.deferFileObservationCommit = append(tool.deferFileObservationCommit, options.DeferFileObservationCommit)
 	if shellNetworkAllowed(ctx, options.Sandbox, args) {
 		return tools.Result{Status: tools.StatusOK, Output: "server started"}
 	}
@@ -397,7 +399,8 @@ func agentNativeBackendStub() sandbox.Backend {
 }
 
 type sandboxNamespaceLimitedRetryTool struct {
-	calls []map[string]any
+	calls                      []map[string]any
+	deferFileObservationCommit []bool
 }
 
 func (tool *sandboxNamespaceLimitedRetryTool) Name() string        { return "bash" }
@@ -416,8 +419,12 @@ func (tool *sandboxNamespaceLimitedRetryTool) Parameters() tools.Schema {
 func (tool *sandboxNamespaceLimitedRetryTool) Safety() tools.Safety {
 	return tools.Safety{SideEffect: tools.SideEffectShell, Permission: tools.PermissionPrompt, Reason: "runs shell commands"}
 }
-func (tool *sandboxNamespaceLimitedRetryTool) Run(_ context.Context, args map[string]any) tools.Result {
+func (tool *sandboxNamespaceLimitedRetryTool) Run(ctx context.Context, args map[string]any) tools.Result {
+	return tool.RunWithOptions(ctx, args, tools.RunOptions{})
+}
+func (tool *sandboxNamespaceLimitedRetryTool) RunWithOptions(_ context.Context, args map[string]any, options tools.RunOptions) tools.Result {
 	tool.calls = append(tool.calls, cloneArgs(args))
+	tool.deferFileObservationCommit = append(tool.deferFileObservationCommit, options.DeferFileObservationCommit)
 	if args["sandbox_permissions"] == string(tools.SandboxPermissionsRequireEscalated) {
 		return tools.Result{Status: tools.StatusOK, Output: "stdout:\nUSER PID COMMAND\nanaxy 42 firefox\nanaxy 43 Discord"}
 	}
@@ -483,6 +490,9 @@ func TestRunRetriesShellUnsandboxedAfterSandboxNamespaceLimitedOutput(t *testing
 	if retryTool.calls[1]["sandbox_permissions"] != string(tools.SandboxPermissionsRequireEscalated) {
 		t.Fatalf("retry args = %#v, want require_escalated", retryTool.calls[1])
 	}
+	if len(retryTool.deferFileObservationCommit) != 2 || !retryTool.deferFileObservationCommit[1] {
+		t.Fatalf("retry defer flags = %#v, want retry observation deferred", retryTool.deferFileObservationCommit)
+	}
 	if len(requests) != 1 {
 		t.Fatalf("permission requests = %#v, want one unsandboxed retry approval", requests)
 	}
@@ -634,6 +644,9 @@ func TestRunRetriesNetworkDeniedShellWithNetworkGrant(t *testing.T) {
 	if _, escalated := retryTool.calls[1]["sandbox_permissions"]; escalated {
 		t.Fatalf("network retry must stay sandboxed, got retry args %#v", retryTool.calls[1])
 	}
+	if len(retryTool.deferFileObservationCommit) != 2 || !retryTool.deferFileObservationCommit[1] {
+		t.Fatalf("retry defer flags = %#v, want retry observation deferred", retryTool.deferFileObservationCommit)
+	}
 	if len(requests) != 1 || requests[0].Reason != sandbox.ReasonNetworkBlocked {
 		t.Fatalf("permission requests = %#v, want one network approval", requests)
 	}
@@ -3579,6 +3592,11 @@ func TestRunAppendsAbortedPlaceholderForUnexecutedToolCallsOnGuardStop(t *testin
 	if !strings.Contains(strings.ToLower(placeholder), "aborted") {
 		t.Fatalf("expected the placeholder result to mark the call as aborted, got %q", placeholder)
 	}
+	for _, message := range result.Messages {
+		if message.ToolCallID == "flaky-2" && !message.IsError {
+			t.Fatalf("aborted placeholder must carry error status: %#v", message)
+		}
+	}
 
 	// Every tool_use in the final assistant message must have a matching result.
 	for _, message := range result.Messages {
@@ -3593,6 +3611,33 @@ func TestRunAppendsAbortedPlaceholderForUnexecutedToolCallsOnGuardStop(t *testin
 	}
 }
 
+func TestRunCarriesToolErrorStatusIntoMessageHistory(t *testing.T) {
+	registry := tools.NewRegistry()
+	registry.Register(alwaysFailingTool{})
+	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{
+		{
+			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "failed-call", ToolName: "flaky"},
+			{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "failed-call"},
+			{Type: zeroruntime.StreamEventDone},
+		},
+		{{Type: zeroruntime.StreamEventText, Content: "done"}, {Type: zeroruntime.StreamEventDone}},
+	}}
+
+	result, err := Run(context.Background(), "go", provider, Options{Registry: registry})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, message := range result.Messages {
+		if message.ToolCallID == "failed-call" {
+			if !message.IsError {
+				t.Fatalf("failed tool result lost its structured status: %#v", message)
+			}
+			return
+		}
+	}
+	t.Fatalf("failed tool result missing from message history: %#v", result.Messages)
+}
+
 type secretEmittingTool struct{ output string }
 
 func (t secretEmittingTool) Name() string        { return "leak" }
@@ -3684,6 +3729,8 @@ func TestRunTracingWrapperStampsUsage(t *testing.T) {
 		{Type: zeroruntime.StreamEventDone},
 	}}}
 	onUsageCalls := 0
+	onContextCalls := 0
+	var contextPlan ContextBreakdown
 	rec := trace.NewRecorder("tracing-session", "run-1", "test")
 	if _, err := Run(context.Background(), "hi", provider, Options{
 		SessionID:    "tracing-session",
@@ -3692,6 +3739,10 @@ func TestRunTracingWrapperStampsUsage(t *testing.T) {
 		Model:        "test-model",
 		Trace:        rec,
 		OnUsage:      func(Usage) { onUsageCalls++ },
+		OnContext: func(breakdown ContextBreakdown) {
+			onContextCalls++
+			contextPlan = breakdown
+		},
 	}); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
@@ -3718,6 +3769,12 @@ func TestRunTracingWrapperStampsUsage(t *testing.T) {
 	if onUsageCalls == 0 {
 		t.Fatal("wrapped OnUsage did not forward to the caller's callback")
 	}
+	if onContextCalls != 1 || len(contextPlan.Blocks) != 2 || contextPlan.PrefixInvalidationReason != "initial" {
+		t.Fatalf("context plan callback = calls %d, plan %#v", onContextCalls, contextPlan)
+	}
+	if len(tr.PrefixHashes) != 1 || tr.PrefixHashes[0].InvalidationReason != "initial" || tr.PrefixHashes[0].CompletePrefixHash != contextPlan.CompletePrefixHash {
+		t.Fatalf("trace context evidence = %#v, plan %#v", tr.PrefixHashes, contextPlan)
+	}
 }
 
 // TestRunNilTraceForwardsUsage verifies a nil recorder leaves the loop

internal/agent/output_budget_propagation_test.go

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

internal/agent/prompt_fingerprint_test.go

@@ -123,6 +123,21 @@ func TestComputePrefixFingerprintCoversEverySystemPromptSection(t *testing.T) {
 	}
 }
 
+func TestComputePrefixFingerprintCoversTransientSystemPrompt(t *testing.T) {
+	base := Options{Cwd: t.TempDir(), SystemPrompt: "core"}
+	changed := base
+	changed.TransientSystemPrompt = "turn-only guidance"
+
+	fpBase := ComputePrefixFingerprint(base, nil)
+	fpChanged := ComputePrefixFingerprint(changed, nil)
+	if fpBase.SystemPromptHash == fpChanged.SystemPromptHash {
+		t.Fatal("SystemPromptHash must change for transient system guidance")
+	}
+	if fpBase.CompletePrefixHash == fpChanged.CompletePrefixHash {
+		t.Fatal("CompletePrefixHash must cover transient system guidance")
+	}
+}
+
 // TestBuildPromptSubstringsDefaultOptions asserts the invariants of the
 // substrings helper for default Options: which substrings are non-empty,
 // which are empty, and that the substring-to-hash round-trip is lossless.

internal/agent/prune.go

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

internal/agent/prune_test.go

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

internal/agent/specialist_delegation_test.go

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

internal/agent/system_prompt.go

@@ -95,6 +95,9 @@ func buildSystemPromptParts(options Options) systemPromptParts {
 		core = fallbackSystemPrompt
 	}
 	sections := []string{core}
+	if transient := strings.TrimSpace(options.TransientSystemPrompt); transient != "" {
+		sections = append(sections, transient)
+	}
 	if addendum := modelPromptAddendum(options.Model); addendum != "" {
 		sections = append(sections, addendum)
 	}
@@ -179,21 +182,19 @@ func approvedCommandPrefixContext(options Options) string {
 	return "## Approved Command Prefixes\n\nThe following command prefixes have already been approved and do not need another permission prompt:\n" + strings.Join(lines, "\n")
 }
 
-// specialistDelegationContext nudges the orchestrator to offload read-heavy or
-// parallelizable work to a specialist sub-agent via the Task tool, keeping large
-// tool outputs out of the main context. It renders only when specialists are
-// known (which is only where the Task tool is actually registered), so a run with
-// no delegatable specialists produces the previous prompt unchanged.
+// specialistDelegationContext describes when a specialist earns its extra
+// context and coordination cost. It renders only when specialists are known
+// (which is only where the Task tool is actually registered), so a run with no
+// delegatable specialists produces the previous prompt unchanged.
 func specialistDelegationContext(options Options) string {
 	if len(options.Specialists) == 0 {
 		return ""
 	}
 	var b strings.Builder
 	b.WriteString("<specialists>\n")
-	b.WriteString("Delegate focused or read-heavy work to a specialist sub-agent with the Task tool instead of doing it inline. ")
-	b.WriteString("When a request matches a specialist's purpose, delegate to it proactively — you do not need the user to ask first. ")
-	b.WriteString("This keeps large tool outputs — searches, file dumps, multi-step exploration — out of your own context, so you stay fast and token-efficient. ")
-	b.WriteString("Prefer delegating codebase search and exploration; for independent subtasks, launch several specialists in parallel. Handle small, direct edits yourself.\n")
+	b.WriteString("Use the Task tool when a specialist's focused context, expertise, or an independent parallel subtask is likely to improve quality or reduce total context. ")
+	b.WriteString("Do not delegate small direct work, duplicate exploration, or split sequential steps merely because a specialist is available. ")
+	b.WriteString("When delegating, give a bounded assignment and consume its concise evidence instead of importing a long transcript.\n")
 	b.WriteString("Available specialists (call Task with the matching name when the task fits its purpose):\n")
 	for _, info := range options.Specialists {
 		name := strings.TrimSpace(info.Name)

internal/agent/system_prompt.md

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

internal/agent/system_prompt_models.go

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

internal/agent/system_prompt_test.go

@@ -51,6 +51,16 @@ func TestCoreSystemPromptIncludesCodingQualityRules(t *testing.T) {
 	}
 }
 
+func TestTransientSystemPromptIsIncludedOnlyWhenProvided(t *testing.T) {
+	const transient = "Handle this peer request under the current session policy."
+	if prompt := buildSystemPrompt(Options{}); strings.Contains(prompt, transient) {
+		t.Fatal("ordinary system prompt unexpectedly contains transient instructions")
+	}
+	if prompt := buildSystemPrompt(Options{TransientSystemPrompt: transient}); !strings.Contains(prompt, transient) {
+		t.Fatalf("transient instructions missing from system prompt:\n%s", prompt)
+	}
+}
+
 func TestSystemPromptExplainsSandboxEscalationForHiddenHostState(t *testing.T) {
 	prompt := strings.ToLower(buildSystemPrompt(Options{}))
 	for _, want := range []string{

internal/agent/task_state.go

@@ -1,10 +1,14 @@
 package agent
 
 import (
+	"crypto/sha256"
 	"encoding/json"
+	"fmt"
 	"reflect"
+	"regexp"
 	"sort"
 	"strings"
+	"unicode/utf8"
 
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/trace"
@@ -52,17 +56,41 @@ type taskVerificationState struct {
 	LastOutcome Outcome `json:"last_outcome,omitempty"`
 }
 
+type taskFailureState struct {
+	Key     string `json:"key,omitempty"`
+	Tool    string `json:"tool"`
+	Command string `json:"command,omitempty"`
+	Summary string `json:"summary"`
+}
+
+type taskApprovalState struct {
+	Tool     string                   `json:"tool"`
+	Decision PermissionDecisionAction `json:"decision,omitempty"`
+	Scope    string                   `json:"scope,omitempty"`
+	Reason   string                   `json:"reason,omitempty"`
+}
+
+type taskArtifactState struct {
+	Tool string `json:"tool"`
+	Path string `json:"path"`
+}
+
 type taskStateSnapshot struct {
-	Revision           int                   `json:"revision"`
-	Objective          string                `json:"objective"`
-	Status             taskStatus            `json:"status"`
-	Plan               taskPlanState         `json:"plan"`
-	Tools              taskToolState         `json:"tools"`
-	Verification       taskVerificationState `json:"verification"`
-	ChangedFiles       []string              `json:"changed_files,omitempty"`
-	CompletionDecision CompletionDecision    `json:"completion_decision,omitempty"`
-	CompletionReason   string                `json:"completion_reason,omitempty"`
-	PlanParity         taskPlanParity        `json:"plan_parity"`
+	Revision            int                   `json:"revision"`
+	Objective           string                `json:"objective"`
+	Status              taskStatus            `json:"status"`
+	Plan                taskPlanState         `json:"plan"`
+	Tools               taskToolState         `json:"tools"`
+	Verification        taskVerificationState `json:"verification"`
+	ChangedFiles        []string              `json:"changed_files,omitempty"`
+	Constraints         []string              `json:"constraints,omitempty"`
+	UnresolvedFailures  []taskFailureState    `json:"unresolved_failures,omitempty"`
+	Approvals           []taskApprovalState   `json:"approvals,omitempty"`
+	Artifacts           []taskArtifactState   `json:"artifacts,omitempty"`
+	ResolvedFailureKeys []string              `json:"-"`
+	CompletionDecision  CompletionDecision    `json:"completion_decision,omitempty"`
+	CompletionReason    string                `json:"completion_reason,omitempty"`
+	PlanParity          taskPlanParity        `json:"plan_parity"`
 }
 
 type taskStateEventKind int
@@ -72,6 +100,7 @@ const (
 	taskStateEventToolResult
 	taskStateEventVerification
 	taskStateEventCompletion
+	taskStateEventPermission
 )
 
 type taskStateEvent struct {
@@ -80,6 +109,7 @@ type taskStateEvent struct {
 	toolResult   ToolResult
 	verification Outcome
 	completion   completionEvaluation
+	permission   PermissionEvent
 }
 
 // taskState is a deterministic projection of facts the loop already observes.
@@ -101,6 +131,7 @@ func newTaskState(objective string, recorder *trace.Recorder) *taskState {
 		},
 		changedFiles: map[string]struct{}{},
 	}
+	state.snapshotValue.Constraints = extractExplicitConstraints(objective)
 	state.recorder = recorder
 	return state
 }
@@ -134,6 +165,7 @@ func (state *taskState) observe(event taskStateEvent) bool {
 			}
 		}
 		state.snapshotValue.ChangedFiles = sortedKeys(state.changedFiles)
+		state.observeToolEvidence(event.arguments, event.toolResult)
 		changed = true
 	case taskStateEventVerification:
 		if event.verification == OutcomeDisabled {
@@ -160,6 +192,10 @@ func (state *taskState) observe(event taskStateEvent) bool {
 			state.snapshotValue.Status = taskStatusActive
 		}
 		changed = true
+	case taskStateEventPermission:
+		state.markActive()
+		state.observePermission(event.permission)
+		changed = true
 	}
 	if changed {
 		state.snapshotValue.Revision++
@@ -183,9 +219,180 @@ func (state *taskState) snapshot() taskStateSnapshot {
 	snapshot := state.snapshotValue
 	snapshot.Plan.Items = append([]taskPlanItem(nil), state.snapshotValue.Plan.Items...)
 	snapshot.ChangedFiles = append([]string(nil), state.snapshotValue.ChangedFiles...)
+	snapshot.Constraints = append([]string(nil), state.snapshotValue.Constraints...)
+	snapshot.UnresolvedFailures = append([]taskFailureState(nil), state.snapshotValue.UnresolvedFailures...)
+	snapshot.Approvals = append([]taskApprovalState(nil), state.snapshotValue.Approvals...)
+	snapshot.Artifacts = append([]taskArtifactState(nil), state.snapshotValue.Artifacts...)
+	snapshot.ResolvedFailureKeys = append([]string(nil), state.snapshotValue.ResolvedFailureKeys...)
 	return snapshot
 }
 
+const (
+	maxTaskEvidenceEntries = 8
+	maxTaskEvidenceBytes   = 320
+	maxTaskConstraints     = 10
+)
+
+func (state *taskState) observeToolEvidence(arguments string, result ToolResult) {
+	command := capTaskEvidence(commandFromArguments(arguments))
+	key := taskFailureKey(result.Name, command, arguments)
+	if result.Status == tools.StatusOK {
+		if hasTaskFailure(state.snapshotValue.UnresolvedFailures, key) {
+			state.snapshotValue.UnresolvedFailures = removeTaskFailure(state.snapshotValue.UnresolvedFailures, key)
+			state.snapshotValue.ResolvedFailureKeys = appendBoundedUnique(state.snapshotValue.ResolvedFailureKeys, key, maxTaskEvidenceEntries)
+		}
+	} else {
+		state.snapshotValue.ResolvedFailureKeys = removeString(state.snapshotValue.ResolvedFailureKeys, key)
+		state.snapshotValue.UnresolvedFailures = removeTaskFailure(state.snapshotValue.UnresolvedFailures, key)
+		state.snapshotValue.UnresolvedFailures = appendBounded(state.snapshotValue.UnresolvedFailures, taskFailureState{
+			Key: key, Tool: result.Name, Command: command, Summary: capTaskEvidence(firstLine(result.Output)),
+		}, maxTaskEvidenceEntries)
+	}
+	for _, metaKey := range []string{"spill_path", "artifact_path"} {
+		if path := strings.TrimSpace(result.Meta[metaKey]); path != "" {
+			state.snapshotValue.Artifacts = appendBoundedUnique(state.snapshotValue.Artifacts,
+				taskArtifactState{Tool: result.Name, Path: capTaskEvidence(path)}, maxTaskEvidenceEntries)
+		}
+	}
+}
+
+func taskFailureKey(toolName, command, arguments string) string {
+	identity := command
+	if identity == "" {
+		canonical := []byte(strings.TrimSpace(arguments))
+		var value any
+		if json.Unmarshal(canonical, &value) == nil {
+			if encoded, err := json.Marshal(value); err == nil {
+				canonical = encoded
+			}
+		}
+		digest := sha256.Sum256(canonical)
+		identity = fmt.Sprintf("args:%x", digest[:8])
+	}
+	return strings.TrimSpace(toolName) + "\x00" + identity
+}
+
+func (state *taskState) observePermission(event PermissionEvent) {
+	decision := event.DecisionAction
+	if decision == "" {
+		decision = PermissionDecisionAction(event.Action)
+	}
+	state.snapshotValue.Approvals = appendBoundedUnique(state.snapshotValue.Approvals, taskApprovalState{
+		Tool: event.ToolName, Decision: decision, Scope: capTaskEvidence(event.Scope),
+		Reason: capTaskEvidence(firstNonEmptyString(event.DecisionReason, event.Reason)),
+	}, maxTaskEvidenceEntries)
+}
+
+func commandFromArguments(arguments string) string {
+	var object map[string]json.RawMessage
+	if json.Unmarshal([]byte(strings.TrimSpace(arguments)), &object) != nil {
+		return ""
+	}
+	for _, key := range []string{"cmd", "command", "script", "shell"} {
+		var command string
+		if raw, ok := object[key]; ok && json.Unmarshal(raw, &command) == nil {
+			return strings.TrimSpace(command)
+		}
+	}
+	return ""
+}
+
+func firstLine(value string) string {
+	value = strings.TrimSpace(value)
+	if index := strings.IndexByte(value, '\n'); index >= 0 {
+		value = value[:index]
+	}
+	return value
+}
+
+func capTaskEvidence(value string) string {
+	value = strings.TrimSpace(value)
+	if len(value) <= maxTaskEvidenceBytes {
+		return value
+	}
+	limit := maxTaskEvidenceBytes - 3
+	for limit > 0 && !utf8.RuneStart(value[limit]) {
+		limit--
+	}
+	return strings.TrimSpace(value[:limit]) + "..."
+}
+
+var explicitConstraintPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`(?i)\bprefer(?:s|red|ring)?\s+\w`),
+	regexp.MustCompile(`(?i)\bdon'?t want\b`),
+	regexp.MustCompile(`(?i)\balways (?:use|do|run|prefer|keep|make|format|write|add|set|put|prefix|start|include|append)\b`),
+	regexp.MustCompile(`(?i)\bnever (?:use|do|run|push|commit|write|ignore|add|set|put|remove|delete|include|deploy)\b`),
+	regexp.MustCompile(`(?i)\bplease (?:use|avoid|keep|make|don'?t|do not|format|write)\b`),
+	regexp.MustCompile(`(?i)\b(?:style|format|language|naming)\s*[:=]\s*\S`),
+}
+
+func extractExplicitConstraints(text string) []string {
+	var constraints []string
+	for _, line := range strings.Split(text, "\n") {
+		line = strings.TrimSpace(line)
+		if len(line) < 5 || len(line) > 200 || strings.HasSuffix(line, "?") || strings.Contains(line, "?...") {
+			continue
+		}
+		for _, pattern := range explicitConstraintPatterns {
+			if pattern.MatchString(line) {
+				constraints = appendBoundedUnique(constraints, line, maxTaskConstraints)
+				break
+			}
+		}
+		if len(constraints) == maxTaskConstraints {
+			break
+		}
+	}
+	return constraints
+}
+
+func appendBounded[T any](values []T, value T, limit int) []T {
+	values = append(values, value)
+	if len(values) > limit {
+		values = values[len(values)-limit:]
+	}
+	return values
+}
+
+func appendBoundedUnique[T comparable](values []T, value T, limit int) []T {
+	filtered := values[:0]
+	for _, existing := range values {
+		if existing != value {
+			filtered = append(filtered, existing)
+		}
+	}
+	return appendBounded(filtered, value, limit)
+}
+
+func hasTaskFailure(values []taskFailureState, key string) bool {
+	for _, value := range values {
+		if value.Key == key {
+			return true
+		}
+	}
+	return false
+}
+
+func removeTaskFailure(values []taskFailureState, key string) []taskFailureState {
+	out := values[:0]
+	for _, value := range values {
+		if value.Key != key {
+			out = append(out, value)
+		}
+	}
+	return out
+}
+
+func removeString(values []string, target string) []string {
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		if value != target {
+			out = append(out, value)
+		}
+	}
+	return out
+}
+
 // observePlanParity compares only the latest plan projection with the plan tool
 // calls still present in messages. It mutates the snapshot and emits when the
 // parity value changes; objective, tool, and verification fields are not part of

internal/agent/task_state_test.go

@@ -115,6 +115,68 @@ func TestTaskStateSnapshotIsImmutable(t *testing.T) {
 	}
 }
 
+func TestTaskStateRecordsDurableRuntimeEvidence(t *testing.T) {
+	state := newTaskState("Please keep the change focused.\nNever commit generated reports.", nil)
+	arguments := `{"cmd":"go test ./internal/agent"}`
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: arguments, toolResult: ToolResult{
+		ToolCallID: "test-1", Name: "exec_command", Status: tools.StatusError,
+		Output: "Error: TestResumeRetainsState failed\nfull diagnostic",
+		Meta:   map[string]string{"spill_path": ".zero/artifacts/test-1.txt"},
+	}})
+	state.observe(taskStateEvent{kind: taskStateEventPermission, permission: PermissionEvent{
+		ToolName: "exec_command", DecisionAction: PermissionDecisionAllowForSession,
+		Scope: "/tmp", DecisionReason: "write a temporary fixture",
+	}})
+
+	snapshot := state.snapshot()
+	if !reflect.DeepEqual(snapshot.Constraints, []string{"Please keep the change focused.", "Never commit generated reports."}) {
+		t.Fatalf("unexpected explicit constraints: %#v", snapshot.Constraints)
+	}
+	if len(snapshot.UnresolvedFailures) != 1 || snapshot.UnresolvedFailures[0].Command != "go test ./internal/agent" || snapshot.UnresolvedFailures[0].Summary != "Error: TestResumeRetainsState failed" {
+		t.Fatalf("unexpected failure evidence: %#v", snapshot.UnresolvedFailures)
+	}
+	if len(snapshot.Artifacts) != 1 || snapshot.Artifacts[0].Path != ".zero/artifacts/test-1.txt" {
+		t.Fatalf("unexpected artifact evidence: %#v", snapshot.Artifacts)
+	}
+	if len(snapshot.Approvals) != 1 || snapshot.Approvals[0].Decision != PermissionDecisionAllowForSession || snapshot.Approvals[0].Scope != "/tmp" {
+		t.Fatalf("unexpected approval evidence: %#v", snapshot.Approvals)
+	}
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"path":"a.go"}`, toolResult: ToolResult{
+		ToolCallID: "read-a", Name: "read_file", Status: tools.StatusError, Output: "Error: a.go is unavailable",
+	}})
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"path":"b.go"}`, toolResult: ToolResult{
+		ToolCallID: "read-b", Name: "read_file", Status: tools.StatusOK, Output: "package b",
+	}})
+	if failures := state.snapshot().UnresolvedFailures; len(failures) != 2 || failures[1].Summary != "Error: a.go is unavailable" {
+		t.Fatalf("success for a different target resolved the wrong failure: %#v", failures)
+	}
+
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: arguments, toolResult: ToolResult{
+		ToolCallID: "test-2", Name: "exec_command", Status: tools.StatusOK, Output: "ok",
+	}})
+	if failures := state.snapshot().UnresolvedFailures; len(failures) != 1 || failures[0].Summary != "Error: a.go is unavailable" {
+		t.Fatalf("successful retry did not resolve only its matching failure: %#v", failures)
+	}
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"path":"a.go"}`, toolResult: ToolResult{
+		ToolCallID: "read-a-2", Name: "read_file", Status: tools.StatusOK, Output: "package a",
+	}})
+	if failures := state.snapshot().UnresolvedFailures; len(failures) != 0 {
+		t.Fatalf("successful non-command retry did not resolve its matching failure: %#v", failures)
+	}
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, arguments: `{"path":"a.go"}`, toolResult: ToolResult{
+		ToolCallID: "read-a-3", Name: "read_file", Status: tools.StatusError, Output: "Error: a.go failed again",
+	}})
+	snapshot = state.snapshot()
+	if len(snapshot.UnresolvedFailures) != 1 || snapshot.UnresolvedFailures[0].Summary != "Error: a.go failed again" {
+		t.Fatalf("a failure recurring after success was hidden: %#v", snapshot.UnresolvedFailures)
+	}
+	for _, key := range snapshot.ResolvedFailureKeys {
+		if key == snapshot.UnresolvedFailures[0].Key {
+			t.Fatalf("recurring failure retained a stale resolved key: %#v", snapshot.ResolvedFailureKeys)
+		}
+	}
+}
+
 func TestTaskStatePlanParityUsesLatestPlan(t *testing.T) {
 	state := newTaskState("objective", nil)
 	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"old","status":"completed"}]}`})

internal/agent/tool_result_images_test.go

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

internal/agent/types.go

@@ -68,8 +68,11 @@ type ToolResult struct {
 	Output     string
 	// Truncated reports that the tool's model-visible output omitted content.
 	// The full result may be recoverable through Meta["spill_path"].
-	Truncated    bool
-	Meta         map[string]string
+	Truncated bool
+	Meta      map[string]string
+	// Images the tool produced, delivered to the model as a following user
+	// message rather than on this result. See tools.Result.Images.
+	Images       []zeroruntime.ImageBlock
 	Redacted     bool
 	ChangedFiles []string
 	// ChangeSummaries are non-selectable generated-tree summaries emitted by
@@ -280,6 +283,9 @@ type Options struct {
 	ReasoningEffort  string
 	Cwd              string
 	SystemPrompt     string
+	// TransientSystemPrompt adds trusted runtime guidance for this run only.
+	// Empty preserves the ordinary system prompt byte-for-byte.
+	TransientSystemPrompt string
 	// ResponseStyle is the operator-selected reply style from the TUI /style
 	// command (e.g. "concise", "explanatory", "review"). It is rendered into the
 	// system prompt as a short directive. Empty or "balanced" adds nothing — the
@@ -330,9 +336,11 @@ type Options struct {
 	// specialist child process emits while running. The toolCallID identifies
 	// which Task tool call the progress belongs to. nil is a no-op.
 	OnToolProgress func(toolCallID string, event streamjson.Event)
-	// OnContext, when set, is called once per turn with the per-category context
-	// budget of the request about to be sent, so a surface (TUI/CLI) can show
-	// context utilization. Opt-in like the other callbacks; nil is a no-op.
+	// OnContext, when set, is called for each main agent request with its
+	// per-category context budget, including a replacement request after
+	// compaction or a stall retry. Internal summarizer requests are excluded so
+	// surfaces keep showing the active conversation budget. Opt-in like the other
+	// callbacks; nil is a no-op.
 	OnContext func(ContextBreakdown)
 	// ModelSwitcher, when set, lets a tool escalate the run to a stronger model
 	// mid-run: the loop calls it with the requested model id and, on success,

internal/cli/app.go

@@ -23,6 +23,7 @@ import (
 	"github.com/Gitlawb/zero/internal/mcp"
 	"github.com/Gitlawb/zero/internal/modelregistry"
 	"github.com/Gitlawb/zero/internal/observability"
+	"github.com/Gitlawb/zero/internal/peermsg"
 	"github.com/Gitlawb/zero/internal/plugins"
 	"github.com/Gitlawb/zero/internal/providerhealth"
 	"github.com/Gitlawb/zero/internal/providermodeldiscovery"
@@ -585,6 +586,9 @@ func fillAppDeps(deps appDeps) appDeps {
 	baseProbeProviderHealth := deps.probeProviderHealth
 	deps.probeProviderHealth = func(ctx context.Context, options providerhealth.Options) providerhealth.Result {
 		options.Profile = applyStoredProviderKeyAt(options.Profile, userConfigPath)
+		if options.OAuthResolver == nil {
+			options.OAuthResolver, _ = oauthLoginForProfile(options.Profile)
+		}
 		return baseProbeProviderHealth(ctx, options)
 	}
 	return deps
@@ -783,6 +787,26 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 	if permissionMode == "" {
 		permissionMode = agent.PermissionModeAsk
 	}
+	sessionStore := deps.newSessionStore()
+	peerClass := peermsg.PermissionPrompting
+	if permissionMode == agent.PermissionModeUnsafe {
+		peerClass = peermsg.PermissionBypass
+	}
+	peerService, peerErr := peermsg.New(peermsg.Options{
+		Identity: peermsg.Identity{
+			Cwd:             workspaceRoot,
+			PermissionClass: peerClass,
+		},
+		InboundPolicy: peermsg.InboundPolicy(resolved.CrossSessionInbound),
+	})
+	if peerErr != nil {
+		fmt.Fprintf(stderr, "warning: cross-session messaging unavailable: %s\n", peerErr)
+		peerService = nil
+	} else {
+		for _, tool := range tools.NewPeerSessionTools(peerService) {
+			registry.Register(tool)
+		}
+	}
 	// 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
@@ -834,7 +858,8 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 			return scratchFileWarning(workspaceRoot, scratchBaseline)
 		},
 		Registry:           registry,
-		SessionStore:       deps.newSessionStore(),
+		SessionStore:       sessionStore,
+		PeerService:        peerService,
 		SandboxStore:       sandboxStore,
 		MCPConfig:          mcpConfig,
 		MCPPermissionStore: mcpPermissionStore,

internal/cli/context.go

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

internal/cli/deferred_wiring_test.go

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

internal/cli/mcp_config.go

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

internal/cli/mcp_trust_edge_test.go

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

internal/cli/observability_test.go

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

internal/config/resolver.go

@@ -103,6 +103,7 @@ func Resolve(options ResolveOptions) (ResolvedConfig, error) {
 		// here rather than in mergeConfig because that helper is shared with the
 		// trusted global-config merge, which must keep honouring the setting.
 		commandConfig.Sandbox.Enabled = nil
+		commandConfig.CrossSessionInbound = ""
 		mergeConfig(&cfg, commandConfig)
 	}
 
@@ -140,6 +141,13 @@ func Resolve(options ResolveOptions) (ResolvedConfig, error) {
 			return ResolvedConfig{}, fmt.Errorf("invalid notify.focusMode %q: expected unfocused, always, or focused", focusMode)
 		}
 	}
+	if inbound := strings.TrimSpace(cfg.CrossSessionInbound); inbound != "" {
+		switch inbound {
+		case "accept", "hold", "refuse":
+		default:
+			return ResolvedConfig{}, fmt.Errorf("invalid crossSessionInbound %q: expected accept, hold, or refuse", inbound)
+		}
+	}
 	if err := validateSTTConfig(cfg.STT); err != nil {
 		return ResolvedConfig{}, err
 	}
@@ -154,19 +162,20 @@ func Resolve(options ResolveOptions) (ResolvedConfig, error) {
 	}
 
 	return ResolvedConfig{
-		ActiveProvider: active.Name,
-		Providers:      providers,
-		Provider:       active,
-		MaxTurns:       cfg.MaxTurns,
-		MCP:            cfg.MCP,
-		Sandbox:        cfg.Sandbox,
-		Notify:         cfg.Notify,
-		Tools:          cfg.Tools,
-		Swarm:          cfg.Swarm,
-		Preferences:    cfg.Preferences,
-		KeyBindings:    cfg.KeyBindings,
-		LocalControl:   cfg.LocalControl,
-		STT:            cfg.STT,
+		ActiveProvider:      active.Name,
+		Providers:           providers,
+		Provider:            active,
+		MaxTurns:            cfg.MaxTurns,
+		MCP:                 cfg.MCP,
+		Sandbox:             cfg.Sandbox,
+		Notify:              cfg.Notify,
+		Tools:               cfg.Tools,
+		Swarm:               cfg.Swarm,
+		Preferences:         cfg.Preferences,
+		KeyBindings:         cfg.KeyBindings,
+		LocalControl:        cfg.LocalControl,
+		STT:                 cfg.STT,
+		CrossSessionInbound: cfg.CrossSessionInbound,
 	}, nil
 }
 
@@ -267,6 +276,9 @@ func mergeConfig(dst *FileConfig, src FileConfig) {
 	mergeLocalControlConfig(&dst.LocalControl, src.LocalControl)
 	mergeKeyBindings(&dst.KeyBindings, src.KeyBindings)
 	mergeSTTConfig(&dst.STT, src.STT)
+	if inbound := strings.TrimSpace(src.CrossSessionInbound); inbound != "" {
+		dst.CrossSessionInbound = inbound
+	}
 }
 
 func mergeProjectConfig(dst *FileConfig, src FileConfig) error {
@@ -325,6 +337,9 @@ func mergeProjectConfig(dst *FileConfig, src FileConfig) error {
 	if src.Swarm.MaxTeamSize != 0 {
 		dst.Swarm.MaxTeamSize = src.Swarm.MaxTeamSize
 	}
+	if inbound := strings.TrimSpace(src.CrossSessionInbound); inboundPolicyRank(inbound) > inboundPolicyRank(dst.CrossSessionInbound) {
+		dst.CrossSessionInbound = inbound
+	}
 	mergeKeyBindings(&dst.KeyBindings, src.KeyBindings)
 	// Local control is intentionally user-config/override only. A cloned project
 	// must not be able to make browser, desktop, or terminal automation tools
@@ -727,6 +742,9 @@ func applyOverrides(cfg *FileConfig, overrides Overrides) {
 	mergeLocalControlConfig(&cfg.LocalControl, overrides.LocalControl)
 	mergeKeyBindings(&cfg.KeyBindings, overrides.KeyBindings)
 	mergeSTTConfig(&cfg.STT, overrides.STT)
+	if inbound := strings.TrimSpace(overrides.CrossSessionInbound); inbound != "" {
+		cfg.CrossSessionInbound = inbound
+	}
 	for _, provider := range overrides.Providers {
 		mergeProvider(cfg, provider)
 	}
@@ -736,6 +754,19 @@ func applyOverrides(cfg *FileConfig, overrides Overrides) {
 	mergeMCPConfig(&cfg.MCP, overrides.MCP, true)
 }
 
+func inboundPolicyRank(policy string) int {
+	switch strings.TrimSpace(policy) {
+	case "refuse":
+		return 3
+	case "hold":
+		return 2
+	case "accept":
+		return 0
+	default:
+		return 1 // permission-mode parity
+	}
+}
+
 func mergeLocalControlConfig(dst *LocalControlConfig, src LocalControlConfig) {
 	if src.enabledSet {
 		dst.Enabled = src.Enabled

internal/config/resolver_test.go

@@ -2199,3 +2199,40 @@ func TestResolveRequiresModelErrorIsSetupFixable(t *testing.T) {
 		t.Fatalf("error leaked API key: %q", err.Error())
 	}
 }
+
+func TestCrossSessionInboundProjectConfigCanOnlyTighten(t *testing.T) {
+	tests := []struct {
+		name    string
+		user    string
+		project string
+		want    string
+	}{
+		{name: "hold tightens accept", user: "accept", project: "hold", want: "hold"},
+		{name: "refuse stays refuse", user: "refuse", project: "accept", want: "refuse"},
+		{name: "accept cannot weaken parity", project: "accept", want: ""},
+		{name: "refuse tightens parity", project: "refuse", want: "refuse"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			cfg := FileConfig{CrossSessionInbound: test.user}
+			if err := mergeProjectConfig(&cfg, FileConfig{CrossSessionInbound: test.project}); err != nil {
+				t.Fatal(err)
+			}
+			if cfg.CrossSessionInbound != test.want {
+				t.Fatalf("crossSessionInbound = %q, want %q", cfg.CrossSessionInbound, test.want)
+			}
+		})
+	}
+}
+
+func TestResolveRejectsInvalidCrossSessionInbound(t *testing.T) {
+	path := writeConfig(t, `{
+		"activeProvider": "openai",
+		"providers": [{"name":"openai","provider_kind":"openai","apiKey":"sk-x","model":"gpt-5"}],
+		"crossSessionInbound": "sometimes"
+	}`)
+	_, err := Resolve(ResolveOptions{UserConfigPath: path, Env: map[string]string{}})
+	if err == nil || !strings.Contains(err.Error(), "expected accept, hold, or refuse") {
+		t.Fatalf("error = %v", err)
+	}
+}

internal/config/types.go

@@ -113,7 +113,7 @@ type PreferencesConfig struct {
 	// ZERO_THEME, so a /theme choice survives restart. Empty = unset (defaults auto).
 	Theme string `json:"theme,omitempty"`
 	// Recaps is a tri-state: nil (unset) defaults to ON; an explicit false means
-	// the user turned post-turn recaps off. A *bool is its own tri-state, so no
+	// the user turned idle recaps off. A *bool is its own tri-state, so no
 	// custom unmarshal is needed (unlike ToolsConfig.DeferThreshold's int).
 	Recaps *bool `json:"recaps,omitempty"`
 }
@@ -130,7 +130,7 @@ type RecentModelEntry struct {
 // MaxRecentModels caps the persisted/displayed recent-selection history.
 const MaxRecentModels = 5
 
-// RecapsEnabled reports whether post-turn recaps are on. Unset defaults to ON.
+// RecapsEnabled reports whether idle recaps are on. Unset defaults to ON.
 func (p PreferencesConfig) RecapsEnabled() bool {
 	return p.Recaps == nil || *p.Recaps
 }
@@ -340,46 +340,49 @@ func (cfg *ToolsConfig) UnmarshalJSON(data []byte) error {
 }
 
 type FileConfig struct {
-	ActiveProvider string             `json:"activeProvider,omitempty"`
-	Providers      []ProviderProfile  `json:"providers,omitempty"`
-	MaxTurns       int                `json:"maxTurns,omitempty"`
-	MCP            MCPConfig          `json:"mcp,omitempty"`
-	Sandbox        SandboxConfig      `json:"sandbox,omitempty"`
-	Notify         NotifyConfig       `json:"notify,omitempty"`
-	Tools          ToolsConfig        `json:"tools,omitempty"`
-	Swarm          SwarmConfig        `json:"swarm,omitempty"`
-	Preferences    PreferencesConfig  `json:"preferences,omitempty"`
-	KeyBindings    KeyBindingsConfig  `json:"keybindings,omitempty"`
-	LocalControl   LocalControlConfig `json:"localControl,omitempty"`
-	STT            STTConfig          `json:"stt,omitempty"`
+	ActiveProvider      string             `json:"activeProvider,omitempty"`
+	Providers           []ProviderProfile  `json:"providers,omitempty"`
+	MaxTurns            int                `json:"maxTurns,omitempty"`
+	MCP                 MCPConfig          `json:"mcp,omitempty"`
+	Sandbox             SandboxConfig      `json:"sandbox,omitempty"`
+	Notify              NotifyConfig       `json:"notify,omitempty"`
+	Tools               ToolsConfig        `json:"tools,omitempty"`
+	Swarm               SwarmConfig        `json:"swarm,omitempty"`
+	Preferences         PreferencesConfig  `json:"preferences,omitempty"`
+	KeyBindings         KeyBindingsConfig  `json:"keybindings,omitempty"`
+	LocalControl        LocalControlConfig `json:"localControl,omitempty"`
+	STT                 STTConfig          `json:"stt,omitempty"`
+	CrossSessionInbound string             `json:"crossSessionInbound,omitempty"`
 }
 
 func (cfg FileConfig) MarshalJSON() ([]byte, error) {
 	type rawConfig struct {
-		ActiveProvider string              `json:"activeProvider,omitempty"`
-		Providers      []ProviderProfile   `json:"providers,omitempty"`
-		MaxTurns       int                 `json:"maxTurns,omitempty"`
-		MCP            MCPConfig           `json:"mcp,omitempty"`
-		Sandbox        SandboxConfig       `json:"sandbox,omitempty"`
-		Notify         NotifyConfig        `json:"notify,omitempty"`
-		Tools          ToolsConfig         `json:"tools,omitempty"`
-		Swarm          SwarmConfig         `json:"swarm,omitempty"`
-		Preferences    PreferencesConfig   `json:"preferences,omitempty"`
-		KeyBindings    KeyBindingsConfig   `json:"keybindings,omitempty"`
-		LocalControl   *LocalControlConfig `json:"localControl,omitempty"`
-		STT            *STTConfig          `json:"stt,omitempty"`
+		ActiveProvider      string              `json:"activeProvider,omitempty"`
+		Providers           []ProviderProfile   `json:"providers,omitempty"`
+		MaxTurns            int                 `json:"maxTurns,omitempty"`
+		MCP                 MCPConfig           `json:"mcp,omitempty"`
+		Sandbox             SandboxConfig       `json:"sandbox,omitempty"`
+		Notify              NotifyConfig        `json:"notify,omitempty"`
+		Tools               ToolsConfig         `json:"tools,omitempty"`
+		Swarm               SwarmConfig         `json:"swarm,omitempty"`
+		Preferences         PreferencesConfig   `json:"preferences,omitempty"`
+		KeyBindings         KeyBindingsConfig   `json:"keybindings,omitempty"`
+		LocalControl        *LocalControlConfig `json:"localControl,omitempty"`
+		STT                 *STTConfig          `json:"stt,omitempty"`
+		CrossSessionInbound string              `json:"crossSessionInbound,omitempty"`
 	}
 	raw := rawConfig{
-		ActiveProvider: cfg.ActiveProvider,
-		Providers:      cfg.Providers,
-		MaxTurns:       cfg.MaxTurns,
-		MCP:            cfg.MCP,
-		Sandbox:        cfg.Sandbox,
-		Notify:         cfg.Notify,
-		Tools:          cfg.Tools,
-		Swarm:          cfg.Swarm,
-		Preferences:    cfg.Preferences,
-		KeyBindings:    cfg.KeyBindings,
+		ActiveProvider:      cfg.ActiveProvider,
+		Providers:           cfg.Providers,
+		MaxTurns:            cfg.MaxTurns,
+		MCP:                 cfg.MCP,
+		Sandbox:             cfg.Sandbox,
+		Notify:              cfg.Notify,
+		Tools:               cfg.Tools,
+		Swarm:               cfg.Swarm,
+		Preferences:         cfg.Preferences,
+		KeyBindings:         cfg.KeyBindings,
+		CrossSessionInbound: cfg.CrossSessionInbound,
 	}
 	if !cfg.LocalControl.Empty() {
 		raw.LocalControl = &cfg.LocalControl
@@ -404,33 +407,35 @@ type ResolveOptions struct {
 }
 
 type Overrides struct {
-	ActiveProvider string
-	Providers      []ProviderProfile
-	Provider       ProviderProfile
-	MaxTurns       int
-	MCP            MCPConfig
-	Sandbox        SandboxConfig
-	Notify         NotifyConfig
-	Tools          ToolsConfig
-	KeyBindings    KeyBindingsConfig
-	LocalControl   LocalControlConfig
-	STT            STTConfig
+	ActiveProvider      string
+	Providers           []ProviderProfile
+	Provider            ProviderProfile
+	MaxTurns            int
+	MCP                 MCPConfig
+	Sandbox             SandboxConfig
+	Notify              NotifyConfig
+	Tools               ToolsConfig
+	KeyBindings         KeyBindingsConfig
+	LocalControl        LocalControlConfig
+	STT                 STTConfig
+	CrossSessionInbound string
 }
 
 type ResolvedConfig struct {
-	ActiveProvider string
-	Providers      []ProviderProfile
-	Provider       ProviderProfile
-	MaxTurns       int
-	MCP            MCPConfig
-	Sandbox        SandboxConfig
-	Notify         NotifyConfig
-	Tools          ToolsConfig
-	Swarm          SwarmConfig
-	Preferences    PreferencesConfig
-	KeyBindings    KeyBindingsConfig
-	LocalControl   LocalControlConfig
-	STT            STTConfig
+	ActiveProvider      string
+	Providers           []ProviderProfile
+	Provider            ProviderProfile
+	MaxTurns            int
+	MCP                 MCPConfig
+	Sandbox             SandboxConfig
+	Notify              NotifyConfig
+	Tools               ToolsConfig
+	Swarm               SwarmConfig
+	Preferences         PreferencesConfig
+	KeyBindings         KeyBindingsConfig
+	LocalControl        LocalControlConfig
+	STT                 STTConfig
+	CrossSessionInbound string
 }
 
 type MCPConfig struct {
@@ -480,20 +485,21 @@ type MCPOAuthConfig struct {
 
 func (cfg *FileConfig) UnmarshalJSON(data []byte) error {
 	type rawConfig struct {
-		ActiveProvider  string                     `json:"activeProvider"`
-		Providers       []ProviderProfile          `json:"providers"`
-		MaxTurns        int                        `json:"maxTurns"`
-		MCP             MCPConfig                  `json:"mcp"`
-		Sandbox         SandboxConfig              `json:"sandbox"`
-		Notify          NotifyConfig               `json:"notify"`
-		Tools           ToolsConfig                `json:"tools"`
-		Swarm           SwarmConfig                `json:"swarm"`
-		Preferences     PreferencesConfig          `json:"preferences"`
-		KeyBindings     KeyBindingsConfig          `json:"keybindings"`
-		LocalControl    LocalControlConfig         `json:"localControl"`
-		STT             STTConfig                  `json:"stt"`
-		MCPServers      map[string]MCPServerConfig `json:"mcpServers"`
-		MCPServersSnake map[string]MCPServerConfig `json:"mcp_servers"`
+		ActiveProvider      string                     `json:"activeProvider"`
+		Providers           []ProviderProfile          `json:"providers"`
+		MaxTurns            int                        `json:"maxTurns"`
+		MCP                 MCPConfig                  `json:"mcp"`
+		Sandbox             SandboxConfig              `json:"sandbox"`
+		Notify              NotifyConfig               `json:"notify"`
+		Tools               ToolsConfig                `json:"tools"`
+		Swarm               SwarmConfig                `json:"swarm"`
+		Preferences         PreferencesConfig          `json:"preferences"`
+		KeyBindings         KeyBindingsConfig          `json:"keybindings"`
+		LocalControl        LocalControlConfig         `json:"localControl"`
+		STT                 STTConfig                  `json:"stt"`
+		CrossSessionInbound string                     `json:"crossSessionInbound"`
+		MCPServers          map[string]MCPServerConfig `json:"mcpServers"`
+		MCPServersSnake     map[string]MCPServerConfig `json:"mcp_servers"`
 	}
 
 	var raw rawConfig
@@ -520,6 +526,7 @@ func (cfg *FileConfig) UnmarshalJSON(data []byte) error {
 	cfg.KeyBindings = raw.KeyBindings
 	cfg.LocalControl = raw.LocalControl
 	cfg.STT = raw.STT
+	cfg.CrossSessionInbound = raw.CrossSessionInbound
 	if cfg.MCP.Servers == nil && (len(raw.MCPServers) > 0 || len(raw.MCPServersSnake) > 0) {
 		cfg.MCP.Servers = map[string]MCPServerConfig{}
 	}

internal/config/writer.go

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

internal/contextreport/contextreport.go

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

internal/contextreport/contextreport_test.go

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

internal/minify/minify.go

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

internal/minify/minify_test.go

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

internal/peermsg/private_dir_other.go

@@ -0,0 +1,40 @@
+//go:build !unix && !windows
+
+package peermsg
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func ensurePrivateDir(path string) error {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return err
+	}
+	volume := filepath.VolumeName(abs)
+	current := volume + string(filepath.Separator)
+	for _, component := range strings.Split(strings.TrimPrefix(abs[len(volume):], string(filepath.Separator)), string(filepath.Separator)) {
+		if component == "" {
+			continue
+		}
+		current = filepath.Join(current, component)
+		info, statErr := os.Lstat(current)
+		if errors.Is(statErr, os.ErrNotExist) {
+			if err := os.Mkdir(current, 0o700); err != nil && !errors.Is(err, os.ErrExist) {
+				return err
+			}
+			info, statErr = os.Lstat(current)
+		}
+		if statErr != nil {
+			return statErr
+		}
+		if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("refusing non-directory or symlink runtime path %q", current)
+		}
+	}
+	return os.Chmod(abs, 0o700)
+}

internal/peermsg/private_dir_unix.go

@@ -0,0 +1,62 @@
+//go:build unix
+
+package peermsg
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/sys/unix"
+)
+
+func ensurePrivateDir(path string) error {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return err
+	}
+	components := strings.Split(strings.TrimPrefix(filepath.Clean(abs), string(filepath.Separator)), string(filepath.Separator))
+	parentFD, err := unix.Open(string(filepath.Separator), unix.O_RDONLY|unix.O_DIRECTORY|unix.O_CLOEXEC, 0)
+	if err != nil {
+		return err
+	}
+	defer unix.Close(parentFD)
+	for index, component := range components {
+		if component == "" {
+			continue
+		}
+		var stat unix.Stat_t
+		err = unix.Fstatat(parentFD, component, &stat, unix.AT_SYMLINK_NOFOLLOW)
+		if errors.Is(err, unix.ENOENT) {
+			if err = unix.Mkdirat(parentFD, component, 0o700); err != nil && !errors.Is(err, unix.EEXIST) {
+				return err
+			}
+			err = unix.Fstatat(parentFD, component, &stat, unix.AT_SYMLINK_NOFOLLOW)
+		}
+		if err != nil {
+			return err
+		}
+		if stat.Mode&unix.S_IFMT != unix.S_IFDIR {
+			return fmt.Errorf("refusing non-directory or symlink runtime path component %q", component)
+		}
+		nextFD, openErr := unix.Openat(parentFD, component, unix.O_RDONLY|unix.O_DIRECTORY|unix.O_CLOEXEC|unix.O_NOFOLLOW, 0)
+		if openErr != nil {
+			return openErr
+		}
+		if index == len(components)-1 {
+			if int(stat.Uid) != os.Getuid() {
+				unix.Close(nextFD)
+				return fmt.Errorf("refusing runtime directory not owned by the current user: %q", path)
+			}
+			if err = unix.Fchmod(nextFD, 0o700); err != nil {
+				unix.Close(nextFD)
+				return err
+			}
+		}
+		unix.Close(parentFD)
+		parentFD = nextFD
+	}
+	return nil
+}

internal/peermsg/private_dir_unix_test.go

@@ -0,0 +1,39 @@
+//go:build unix
+
+package peermsg
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEnsurePrivateDirRejectsSymlink(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "target")
+	if err := os.Mkdir(target, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(root, "link")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatal(err)
+	}
+	if err := ensurePrivateDir(link); err == nil {
+		t.Fatal("expected symlink runtime directory to be rejected")
+	}
+}
+
+func TestEnsurePrivateDirRejectsSymlinkedParent(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "target")
+	if err := os.Mkdir(target, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(root, "link")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatal(err)
+	}
+	if err := ensurePrivateDir(filepath.Join(link, "peers")); err == nil {
+		t.Fatal("expected symlinked parent to be rejected")
+	}
+}

internal/peermsg/private_dir_windows.go

@@ -0,0 +1,239 @@
+//go:build windows
+
+package peermsg
+
+import (
+	"errors"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+func ensurePrivateDir(path string) (resultErr error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return err
+	}
+	descriptor, userSID, tokenOwnerSID, err := privateDirectoryDescriptor()
+	if err != nil {
+		return err
+	}
+	volume := filepath.VolumeName(abs)
+	current := volume + string(filepath.Separator)
+	parent, err := openWindowsDirectory(current, windows.FILE_READ_ATTRIBUTES|windows.FILE_TRAVERSE|windows.SYNCHRONIZE)
+	if err != nil {
+		return err
+	}
+	parentPath := current
+	defer func() {
+		if parent != 0 {
+			resultErr = errors.Join(resultErr, closePrivateWindowsHandle(parent, parentPath))
+		}
+	}()
+	components := strings.Split(strings.TrimPrefix(abs[len(volume):], string(filepath.Separator)), string(filepath.Separator))
+	for index, component := range components {
+		if component == "" {
+			continue
+		}
+		current = filepath.Join(current, component)
+		access := uint32(windows.FILE_READ_ATTRIBUTES | windows.FILE_TRAVERSE | windows.SYNCHRONIZE)
+		if index == len(components)-1 {
+			access |= windows.READ_CONTROL | windows.WRITE_DAC
+		}
+		next, openErr := openOrCreatePrivateWindowsDirectory(parent, component, access, descriptor)
+		if openErr != nil {
+			return fmt.Errorf("open private runtime path component %q: %w", current, openErr)
+		}
+		if closeErr := closePrivateWindowsHandle(parent, parentPath); closeErr != nil {
+			return errors.Join(closeErr, closePrivateWindowsHandle(next, current))
+		}
+		parent = next
+		parentPath = current
+	}
+	if err := securePrivateDirectory(parent, abs, descriptor, userSID, tokenOwnerSID); err != nil {
+		return err
+	}
+	if err := closePrivateWindowsHandle(parent, abs); err != nil {
+		return err
+	}
+	parent = 0
+	return nil
+}
+
+func closePrivateWindowsHandle(handle windows.Handle, path string) error {
+	if err := windows.CloseHandle(handle); err != nil {
+		return fmt.Errorf("close private runtime directory %q: %w", path, err)
+	}
+	return nil
+}
+
+func privateDirectoryDescriptor() (*windows.SECURITY_DESCRIPTOR, *windows.SID, *windows.SID, error) {
+	token := windows.GetCurrentProcessToken()
+	user, err := token.GetTokenUser()
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("resolve current Windows user: %w", err)
+	}
+	sid := user.User.Sid
+	tokenOwnerSID, err := windowsTokenOwner(token)
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("resolve current Windows token owner: %w", err)
+	}
+	descriptor, err := windows.SecurityDescriptorFromString(fmt.Sprintf("O:%sD:P(A;OICI;GA;;;%s)(A;OICI;GA;;;SY)", sid.String(), sid.String()))
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("build private Windows directory ACL: %w", err)
+	}
+	return descriptor, sid, tokenOwnerSID, nil
+}
+
+type windowsTokenOwnerInfo struct {
+	owner *windows.SID
+}
+
+func windowsTokenOwner(token windows.Token) (*windows.SID, error) {
+	var size uint32
+	err := windows.GetTokenInformation(token, windows.TokenOwner, nil, 0, &size)
+	if err != windows.ERROR_INSUFFICIENT_BUFFER {
+		return nil, err
+	}
+	buffer := make([]byte, size)
+	if err := windows.GetTokenInformation(token, windows.TokenOwner, &buffer[0], size, &size); err != nil {
+		return nil, err
+	}
+	owner := (*windowsTokenOwnerInfo)(unsafe.Pointer(&buffer[0])).owner
+	if owner == nil {
+		return nil, errors.New("Windows access token has no default owner")
+	}
+	return owner.Copy()
+}
+
+func openWindowsDirectory(path string, access uint32) (windows.Handle, error) {
+	pathPtr, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return 0, err
+	}
+	handle, err := windows.CreateFile(
+		pathPtr,
+		access,
+		windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
+		nil,
+		windows.OPEN_EXISTING,
+		windows.FILE_FLAG_BACKUP_SEMANTICS|windows.FILE_FLAG_OPEN_REPARSE_POINT,
+		0,
+	)
+	if err != nil {
+		return 0, fmt.Errorf("open private runtime directory %q: %w", path, err)
+	}
+	return handle, nil
+}
+
+func openOrCreatePrivateWindowsDirectory(parent windows.Handle, name string, access uint32, descriptor *windows.SECURITY_DESCRIPTOR) (windows.Handle, error) {
+	handle, err := openPrivateWindowsDirectoryAt(parent, name, access, windows.FILE_OPEN, nil)
+	if err == nil {
+		return handle, nil
+	}
+	if !windowsDirectoryMissing(err) {
+		return 0, err
+	}
+	handle, err = openPrivateWindowsDirectoryAt(parent, name, access, windows.FILE_CREATE, descriptor)
+	if err == windows.STATUS_OBJECT_NAME_COLLISION || errors.Is(err, windows.ERROR_ALREADY_EXISTS) {
+		return openPrivateWindowsDirectoryAt(parent, name, access, windows.FILE_OPEN, nil)
+	}
+	return handle, err
+}
+
+func openPrivateWindowsDirectoryAt(parent windows.Handle, name string, access, disposition uint32, descriptor *windows.SECURITY_DESCRIPTOR) (windows.Handle, error) {
+	objectName, err := windows.NewNTUnicodeString(name)
+	if err != nil {
+		return 0, err
+	}
+	objectAttributes := &windows.OBJECT_ATTRIBUTES{
+		Length:             uint32(unsafe.Sizeof(windows.OBJECT_ATTRIBUTES{})),
+		RootDirectory:      parent,
+		ObjectName:         objectName,
+		Attributes:         windows.OBJ_CASE_INSENSITIVE | windows.OBJ_DONT_REPARSE,
+		SecurityDescriptor: descriptor,
+	}
+	var handle windows.Handle
+	err = windows.NtCreateFile(
+		&handle,
+		access,
+		objectAttributes,
+		&windows.IO_STATUS_BLOCK{},
+		nil,
+		windows.FILE_ATTRIBUTE_DIRECTORY,
+		windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
+		disposition,
+		windows.FILE_DIRECTORY_FILE|windows.FILE_SYNCHRONOUS_IO_NONALERT|windows.FILE_OPEN_REPARSE_POINT,
+		0,
+		0,
+	)
+	if err != nil {
+		return 0, err
+	}
+	var info windows.ByHandleFileInformation
+	if err := windows.GetFileInformationByHandle(handle, &info); err != nil {
+		return 0, errors.Join(err, closePrivateWindowsHandle(handle, name))
+	}
+	if info.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0 || info.FileAttributes&windows.FILE_ATTRIBUTE_DIRECTORY == 0 {
+		return 0, errors.Join(
+			fmt.Errorf("refusing non-directory or reparse-point component %q", name),
+			closePrivateWindowsHandle(handle, name),
+		)
+	}
+	return handle, nil
+}
+
+func windowsDirectoryMissing(err error) bool {
+	return err == windows.STATUS_NO_SUCH_FILE ||
+		err == windows.STATUS_OBJECT_NAME_NOT_FOUND ||
+		err == windows.STATUS_OBJECT_PATH_NOT_FOUND ||
+		errors.Is(err, windows.ERROR_FILE_NOT_FOUND) ||
+		errors.Is(err, windows.ERROR_PATH_NOT_FOUND)
+}
+
+func securePrivateDirectory(handle windows.Handle, path string, desired *windows.SECURITY_DESCRIPTOR, allowedOwners ...*windows.SID) error {
+	var info windows.ByHandleFileInformation
+	if err := windows.GetFileInformationByHandle(handle, &info); err != nil {
+		return fmt.Errorf("inspect private runtime directory %q: %w", path, err)
+	}
+	if info.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0 || info.FileAttributes&windows.FILE_ATTRIBUTE_DIRECTORY == 0 {
+		return fmt.Errorf("refusing non-directory or reparse-point runtime path %q", path)
+	}
+	current, err := windows.GetSecurityInfo(handle, windows.SE_FILE_OBJECT, windows.OWNER_SECURITY_INFORMATION)
+	if err != nil {
+		return fmt.Errorf("read owner of private runtime directory %q: %w", path, err)
+	}
+	owner, _, err := current.Owner()
+	if err != nil {
+		return fmt.Errorf("read owner of private runtime directory %q: %w", path, err)
+	}
+	ownedByCurrentToken := false
+	for _, allowedOwner := range allowedOwners {
+		if allowedOwner != nil && owner.Equals(allowedOwner) {
+			ownedByCurrentToken = true
+			break
+		}
+	}
+	if !ownedByCurrentToken {
+		return fmt.Errorf("refusing runtime directory %q not owned by the current user", path)
+	}
+	dacl, _, err := desired.DACL()
+	if err != nil {
+		return fmt.Errorf("read private Windows directory DACL: %w", err)
+	}
+	if err := windows.SetSecurityInfo(
+		handle,
+		windows.SE_FILE_OBJECT,
+		windows.DACL_SECURITY_INFORMATION|windows.PROTECTED_DACL_SECURITY_INFORMATION,
+		nil,
+		nil,
+		dacl,
+		nil,
+	); err != nil {
+		return fmt.Errorf("secure private runtime directory %q: %w", path, err)
+	}
+	return nil
+}

internal/peermsg/private_dir_windows_test.go

@@ -0,0 +1,223 @@
+//go:build windows
+
+package peermsg
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+func TestEnsurePrivateDirAppliesOwnerOnlyProtectedDACL(t *testing.T) {
+	const directoryAllAccess = windows.STANDARD_RIGHTS_REQUIRED | windows.SYNCHRONIZE | 0x1ff
+
+	path := filepath.Join(t.TempDir(), "zero", "peers", "registry")
+	if err := os.MkdirAll(path, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	worldSID, err := windows.CreateWellKnownSid(windows.WinWorldSid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var pinner runtime.Pinner
+	pinner.Pin(worldSID)
+	defer pinner.Unpin()
+	broadDACL, err := windows.ACLFromEntries([]windows.EXPLICIT_ACCESS{{
+		AccessPermissions: windows.GENERIC_ALL,
+		AccessMode:        windows.GRANT_ACCESS,
+		Inheritance:       windows.SUB_CONTAINERS_AND_OBJECTS_INHERIT,
+		Trustee: windows.TRUSTEE{
+			TrusteeForm:  windows.TRUSTEE_IS_SID,
+			TrusteeType:  windows.TRUSTEE_IS_WELL_KNOWN_GROUP,
+			TrusteeValue: windows.TrusteeValueFromSID(worldSID),
+		},
+	}}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := windows.SetNamedSecurityInfo(
+		path,
+		windows.SE_FILE_OBJECT,
+		windows.DACL_SECURITY_INFORMATION|windows.PROTECTED_DACL_SECURITY_INFORMATION,
+		nil,
+		nil,
+		broadDACL,
+		nil,
+	); err != nil {
+		t.Fatal(err)
+	}
+	if !windowsDirectoryDACLContains(t, path, worldSID) {
+		t.Fatal("test setup did not grant the broad Everyone ACE")
+	}
+	if err := ensurePrivateDir(path); err != nil {
+		t.Fatal(err)
+	}
+	descriptor, err := windows.GetNamedSecurityInfo(
+		path,
+		windows.SE_FILE_OBJECT,
+		windows.OWNER_SECURITY_INFORMATION|windows.DACL_SECURITY_INFORMATION,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	control, _, err := descriptor.Control()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if control&windows.SE_DACL_PROTECTED == 0 {
+		t.Fatal("runtime directory DACL inherits access from its parent")
+	}
+	user, err := windows.GetCurrentProcessToken().GetTokenUser()
+	if err != nil {
+		t.Fatal(err)
+	}
+	owner, _, err := descriptor.Owner()
+	if err != nil {
+		t.Fatal(err)
+	}
+	tokenOwner, err := windowsTokenOwner(windows.GetCurrentProcessToken())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !owner.Equals(user.User.Sid) && !owner.Equals(tokenOwner) {
+		t.Fatalf("runtime directory owner = %s, want user %s or token owner %s", owner.String(), user.User.Sid.String(), tokenOwner.String())
+	}
+	systemSID, err := windows.CreateWellKnownSid(windows.WinLocalSystemSid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	dacl, _, err := descriptor.DACL()
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantTrustees := []*windows.SID{user.User.Sid, systemSID}
+	seen := make([]bool, len(wantTrustees))
+	for index := uint32(0); ; index++ {
+		var ace *windows.ACCESS_ALLOWED_ACE
+		if err := windows.GetAce(dacl, index, &ace); err != nil {
+			break
+		}
+		hasFullAccess := ace.Mask == windows.GENERIC_ALL || ace.Mask&directoryAllAccess == directoryAllAccess
+		if ace.Header.AceType != windows.ACCESS_ALLOWED_ACE_TYPE || !hasFullAccess {
+			t.Fatalf("DACL ACE %d has type %d and mask %#x", index, ace.Header.AceType, ace.Mask)
+		}
+		trustee := (*windows.SID)(unsafe.Pointer(&ace.SidStart))
+		matched := false
+		for trusteeIndex, wanted := range wantTrustees {
+			if trustee.Equals(wanted) {
+				seen[trusteeIndex] = true
+				matched = true
+				break
+			}
+		}
+		if !matched {
+			t.Fatalf("DACL ACE %d grants access to unexpected trustee %s", index, trustee.String())
+		}
+	}
+	for index, found := range seen {
+		if !found {
+			t.Fatalf("DACL does not grant access to required trustee %s", wantTrustees[index].String())
+		}
+	}
+}
+
+func windowsDirectoryDACLContains(t *testing.T, path string, wanted *windows.SID) bool {
+	t.Helper()
+	descriptor, err := windows.GetNamedSecurityInfo(path, windows.SE_FILE_OBJECT, windows.DACL_SECURITY_INFORMATION)
+	if err != nil {
+		t.Fatal(err)
+	}
+	dacl, _, err := descriptor.DACL()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for index := uint32(0); ; index++ {
+		var ace *windows.ACCESS_ALLOWED_ACE
+		if err := windows.GetAce(dacl, index, &ace); err != nil {
+			return false
+		}
+		if (*windows.SID)(unsafe.Pointer(&ace.SidStart)).Equals(wanted) {
+			return true
+		}
+	}
+}
+
+func TestSecurePrivateDirectoryRejectsOwnerMismatch(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "private")
+	if err := ensurePrivateDir(path); err != nil {
+		t.Fatal(err)
+	}
+	handle, err := openWindowsDirectory(path, windows.FILE_LIST_DIRECTORY|windows.FILE_TRAVERSE|windows.SYNCHRONIZE|windows.READ_CONTROL|windows.WRITE_DAC)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer windows.CloseHandle(handle)
+	descriptor, _, _, err := privateDirectoryDescriptor()
+	if err != nil {
+		t.Fatal(err)
+	}
+	unexpectedOwner, err := windows.CreateWellKnownSid(windows.WinWorldSid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := securePrivateDirectory(handle, path, descriptor, unexpectedOwner); err == nil || !strings.Contains(err.Error(), "not owned") {
+		t.Fatalf("owner mismatch error = %v", err)
+	}
+}
+
+func TestSecurePrivateDirectoryReportsDACLWriteFailure(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "private")
+	if err := ensurePrivateDir(path); err != nil {
+		t.Fatal(err)
+	}
+	handle, err := openWindowsDirectory(path, windows.FILE_LIST_DIRECTORY|windows.FILE_TRAVERSE|windows.SYNCHRONIZE|windows.READ_CONTROL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer windows.CloseHandle(handle)
+	descriptor, userSID, tokenOwnerSID, err := privateDirectoryDescriptor()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := securePrivateDirectory(handle, path, descriptor, userSID, tokenOwnerSID); err == nil || !strings.Contains(err.Error(), "secure private runtime directory") {
+		t.Fatalf("DACL write error = %v", err)
+	}
+}
+
+func TestClosePrivateWindowsHandleReportsFailure(t *testing.T) {
+	err := closePrivateWindowsHandle(windows.Handle(0), `C:\private`)
+	if err == nil || !strings.Contains(err.Error(), "close private runtime directory") {
+		t.Fatalf("close handle error = %v", err)
+	}
+}
+
+func TestEnsurePrivateDirRejectsWindowsReparseParent(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "target")
+	if err := os.Mkdir(target, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(root, "link")
+	if err := os.Symlink(target, link); err != nil {
+		t.Skipf("cannot create Windows directory symlink: %v", err)
+	}
+	if err := ensurePrivateDir(filepath.Join(link, "peers")); err == nil {
+		t.Fatal("expected reparse-point parent to be rejected")
+	}
+}
+
+func TestEnsurePrivateDirRejectsWindowsFileComponent(t *testing.T) {
+	root := t.TempDir()
+	file := filepath.Join(root, "file")
+	if err := os.WriteFile(file, []byte("not a directory"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := ensurePrivateDir(filepath.Join(file, "peers")); err == nil {
+		t.Fatal("expected file path component to be rejected")
+	}
+}

internal/peermsg/service_test.go

@@ -0,0 +1,896 @@
+package peermsg
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestServicesDiscoverAndDeliverAcceptedMessage(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newStartedService(t, root, transport, 9102, Identity{
+		SessionID:       "receiver-session",
+		Name:            "reviewer",
+		Cwd:             root,
+		PermissionClass: PermissionPrompting,
+	})
+	sender := newStartedService(t, root, transport, 9101, Identity{
+		SessionID:       "sender-session",
+		Name:            "builder",
+		Cwd:             root,
+		PermissionClass: PermissionPrompting,
+	})
+
+	received := make(chan InboundMessage, 1)
+	receiver.mu.Lock()
+	receiver.handler = func(message InboundMessage) bool { received <- message; return true }
+	receiver.mu.Unlock()
+
+	peers, err := sender.List(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(peers) != 1 || peers[0].SessionID != "receiver-session" || peers[0].Ref == "" {
+		t.Fatalf("peers = %#v", peers)
+	}
+
+	result, err := sender.Send(context.Background(), "reviewer", "check status", "Are the tests green?")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Status != DeliveryAccepted || result.Peer.SessionID != "receiver-session" || result.MessageID == "" {
+		t.Fatalf("result = %#v", result)
+	}
+	select {
+	case message := <-received:
+		if message.Body != "Are the tests green?" || message.Summary != "check status" || message.RequiresApproval {
+			t.Fatalf("message = %#v", message)
+		}
+		if message.From.SessionID != "sender-session" {
+			t.Fatalf("from = %#v", message.From)
+		}
+		if len(message.HopChain) != 1 || message.HopChain[0] != sender.Self().Ref {
+			t.Fatalf("hop chain = %#v", message.HopChain)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for message")
+	}
+}
+
+func TestFreshSessionIsDiscoverableBeforeItsFirstPrompt(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newStartedService(t, root, transport, 9152, Identity{Name: ""})
+	sender := newStartedService(t, root, transport, 9151, Identity{SessionID: "sender", Name: "sender"})
+	peers, err := sender.List(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(peers) != 1 || !strings.HasPrefix(peers[0].SessionID, "live-") || displayPeer(peers[0]) != "Zero session ["+peers[0].Ref+"]" {
+		t.Fatalf("fresh peer = %#v", peers)
+	}
+	if receiver.Self().SessionID != peers[0].SessionID {
+		t.Fatalf("receiver identity = %#v, discovered = %#v", receiver.Self(), peers[0])
+	}
+}
+
+func TestPermissionClassMismatchHoldsMessage(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	received := make(chan InboundMessage, 1)
+	receiver := newService(t, root, transport, 9202, Identity{SessionID: "receiver", Name: "safe", PermissionClass: PermissionPrompting})
+	if err := receiver.Start(func(message InboundMessage) bool { received <- message; return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := newStartedService(t, root, transport, 9201, Identity{SessionID: "sender", Name: "unsafe", PermissionClass: PermissionBypass})
+
+	result, err := sender.Send(context.Background(), "safe", "request", "run this")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Status != DeliveryHeld {
+		t.Fatalf("status = %q", result.Status)
+	}
+	select {
+	case message := <-received:
+		if !message.RequiresApproval || message.HoldCause != HoldCauseModeMismatch {
+			t.Fatalf("message should require approval: %#v", message)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held message")
+	}
+}
+
+func TestExplicitInboundPoliciesOverridePermissionParity(t *testing.T) {
+	tests := []struct {
+		name       string
+		policy     InboundPolicy
+		senderMode PermissionClass
+		want       DeliveryStatus
+		wantCause  HoldCause
+		wantRecv   bool
+	}{
+		{name: "accept mismatch", policy: InboundPolicyAccept, senderMode: PermissionBypass, want: DeliveryAccepted, wantRecv: true},
+		{name: "hold match", policy: InboundPolicyHold, senderMode: PermissionPrompting, want: DeliveryHeld, wantCause: HoldCauseExplicit, wantRecv: true},
+		{name: "refuse match", policy: InboundPolicyRefuse, senderMode: PermissionPrompting, want: DeliveryRefused},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root := t.TempDir()
+			transport := newMemoryTransport()
+			receiver, err := New(Options{
+				RootDir: root, PID: 9602, Transport: transport, InboundPolicy: test.policy,
+				Identity: Identity{SessionID: "receiver", Name: "receiver", PermissionClass: PermissionPrompting},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			received := make(chan InboundMessage, 1)
+			if err := receiver.Start(func(message InboundMessage) bool { received <- message; return true }); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = receiver.Close() })
+			sender := newStartedService(t, root, transport, 9601, Identity{SessionID: "sender", Name: "sender", PermissionClass: test.senderMode})
+
+			result, err := sender.Send(context.Background(), "receiver", "policy", "hello")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if result.Status != test.want {
+				t.Fatalf("status = %q, want %q", result.Status, test.want)
+			}
+			select {
+			case message := <-received:
+				if !test.wantRecv {
+					t.Fatalf("refused message delivered: %#v", message)
+				}
+				if message.HoldCause != test.wantCause {
+					t.Fatalf("hold cause = %q, want %q", message.HoldCause, test.wantCause)
+				}
+			default:
+				if test.wantRecv {
+					t.Fatal("message was not delivered to handler")
+				}
+			}
+		})
+	}
+}
+
+func TestUnknownSenderPermissionModeHoldsOnlyForBypassReceiver(t *testing.T) {
+	tests := []struct {
+		name         string
+		receiverMode PermissionClass
+		wantStatus   DeliveryStatus
+		wantCause    HoldCause
+	}{
+		{name: "prompting receiver accepts", receiverMode: PermissionPrompting, wantStatus: DeliveryAccepted},
+		{name: "bypass receiver holds", receiverMode: PermissionBypass, wantStatus: DeliveryHeld, wantCause: HoldCauseModeUnknown},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			service := &Service{policy: InboundPolicyParity}
+			status, cause := service.inboundDecision("", test.receiverMode)
+			if status != test.wantStatus || cause != test.wantCause {
+				t.Fatalf("inboundDecision() = (%q, %q), want (%q, %q)", status, cause, test.wantStatus, test.wantCause)
+			}
+		})
+	}
+}
+
+func TestHeldMessageResolutionSendsTerminalReceipt(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	received := make(chan InboundMessage, 1)
+	receiver := newService(t, root, transport, 9702, Identity{SessionID: "receiver", Name: "reviewer", PermissionClass: PermissionPrompting})
+	if err := receiver.Start(func(message InboundMessage) bool { received <- message; return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := newStartedService(t, root, transport, 9701, Identity{SessionID: "sender", Name: "builder", PermissionClass: PermissionBypass})
+	statuses := make(chan StatusEvent, 1)
+	sender.SetStatusHandler(func(event StatusEvent) { statuses <- event })
+
+	result, err := sender.Send(context.Background(), "reviewer", "question", "How many files?")
+	if err != nil || result.Status != DeliveryHeld {
+		t.Fatalf("send result = %#v, err = %v", result, err)
+	}
+	var message InboundMessage
+	select {
+	case message = <-received:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held message")
+	}
+	if err := receiver.ResolveHeld(context.Background(), message.ID, DeliveryDelivered); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case event := <-statuses:
+		if event.MessageID != result.MessageID || event.Status != DeliveryDelivered || event.Peer.SessionID != "receiver" {
+			t.Fatalf("status event = %#v", event)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for delivery receipt")
+	}
+}
+
+func TestPermissionModeChangeReleasesNewlyCompatibleHeldMessage(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	held := make(chan InboundMessage, 1)
+	released := make(chan InboundMessage, 1)
+	receiver := newService(t, root, transport, 9752, Identity{SessionID: "receiver", Name: "reviewer", PermissionClass: PermissionPrompting})
+	receiver.SetHeldReleaseHandler(func(message InboundMessage) { released <- message })
+	if err := receiver.Start(func(message InboundMessage) bool { held <- message; return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := newStartedService(t, root, transport, 9751, Identity{SessionID: "sender", Name: "builder", PermissionClass: PermissionBypass})
+	statuses := make(chan StatusEvent, 1)
+	sender.SetStatusHandler(func(event StatusEvent) { statuses <- event })
+
+	result, err := sender.Send(context.Background(), "reviewer", "question", "How many files?")
+	if err != nil || result.Status != DeliveryHeld {
+		t.Fatalf("send result = %#v, err = %v", result, err)
+	}
+	var message InboundMessage
+	select {
+	case message = <-held:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held message")
+	}
+	if err := receiver.UpdateIdentity(Identity{SessionID: "receiver", Name: "reviewer", PermissionClass: PermissionBypass}); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case got := <-released:
+		if got.ID != message.ID || got.RequiresApproval || got.HoldCause != "" {
+			t.Fatalf("released message = %#v", got)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held message release")
+	}
+	select {
+	case event := <-statuses:
+		if event.MessageID != result.MessageID || event.Status != DeliveryDelivered {
+			t.Fatalf("status event = %#v", event)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for release receipt")
+	}
+}
+
+func TestReceiverAdmissionAndLoopGuardsFailClosed(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newService(t, root, transport, 9802, Identity{SessionID: "receiver", Name: "receiver"})
+	if err := receiver.Start(func(InboundMessage) bool { return false }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := newStartedService(t, root, transport, 9801, Identity{SessionID: "sender", Name: "sender"})
+	if _, err := sender.Send(context.Background(), "receiver", "full", "not admitted"); err == nil || !strings.Contains(err.Error(), "receiver queue") {
+		t.Fatalf("admission error = %v", err)
+	}
+
+	receiver.mu.Lock()
+	receiver.handler = func(InboundMessage) bool { return true }
+	receiver.mu.Unlock()
+	if _, err := sender.Send(context.Background(), "receiver", "once", "duplicate body"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sender.Send(context.Background(), "receiver", "twice", "duplicate body"); err == nil || !strings.Contains(err.Error(), "duplicate") {
+		t.Fatalf("duplicate error = %v", err)
+	}
+
+	chain := make([]string, peerMaxSelfHops)
+	for index := range chain {
+		chain[index] = receiver.Self().Ref
+	}
+	ctx := context.WithValue(context.Background(), inboundContextKey{}, chain)
+	if _, err := sender.Send(ctx, "receiver", "loop", "different body"); err == nil || !strings.Contains(err.Error(), "loop") {
+		t.Fatalf("loop error = %v", err)
+	}
+}
+
+func TestUntitledPeerAddressResolvesByNeutralNameAndRef(t *testing.T) {
+	peer := Peer{Identity: Identity{SessionID: "zero_opaque"}, Ref: "22222222"}
+	resolved, err := resolvePeer([]Peer{peer}, "Zero session [22222222]")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved.SessionID != peer.SessionID {
+		t.Fatalf("resolved peer = %#v", resolved)
+	}
+}
+
+func TestIdentityUpdateChangesAddressableSession(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newStartedService(t, root, transport, 9302, Identity{SessionID: "old", Name: "old name"})
+	sender := newStartedService(t, root, transport, 9301, Identity{SessionID: "sender", Name: "sender"})
+
+	if err := receiver.UpdateIdentity(Identity{SessionID: "new", Name: "new name"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sender.Send(context.Background(), "old", "stale", "hello"); err == nil || !strings.Contains(err.Error(), "no reachable") {
+		t.Fatalf("old identity error = %v", err)
+	}
+	result, err := sender.Send(context.Background(), "new name", "fresh", "hello")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Peer.SessionID != "new" {
+		t.Fatalf("peer = %#v", result.Peer)
+	}
+}
+
+func TestClosedServiceDisappearsFromDiscovery(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newStartedService(t, root, transport, 9402, Identity{SessionID: "receiver", Name: "receiver"})
+	sender := newStartedService(t, root, transport, 9401, Identity{SessionID: "sender", Name: "sender"})
+	if err := receiver.Close(); err != nil {
+		t.Fatal(err)
+	}
+	peers, err := sender.List(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(peers) != 0 {
+		t.Fatalf("peers after close = %#v", peers)
+	}
+}
+
+func TestListReturnsCancellationInsteadOfPartialResults(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	service := newStartedService(t, root, transport, 9401, Identity{SessionID: "sender", Name: "sender"})
+	_ = newStartedService(t, root, transport, 9402, Identity{SessionID: "receiver", Name: "receiver"})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	peers, err := service.List(ctx)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("List() error = %v, want context.Canceled", err)
+	}
+	if peers != nil {
+		t.Fatalf("List() peers = %#v, want nil after cancellation", peers)
+	}
+}
+
+func TestCloseReportsTransportCleanupFailure(t *testing.T) {
+	transport := &removeErrorTransport{memoryTransport: newMemoryTransport()}
+	service := newService(t, t.TempDir(), transport, 9403, Identity{SessionID: "sender", Name: "sender"})
+	if err := service.Start(func(InboundMessage) bool { return true }); err != nil {
+		t.Fatal(err)
+	}
+	if err := service.Close(); err == nil || !strings.Contains(err.Error(), "forced remove failure") {
+		t.Fatalf("Close() error = %v, want transport cleanup failure", err)
+	}
+}
+
+func TestDiscoveryDoesNotDeleteRecordAfterTransientDialFailure(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	service := newStartedService(t, root, transport, 9411, Identity{SessionID: "sender", Name: "sender"})
+	endpoint := "memory:temporarily-unreachable"
+	peer := Peer{Identity: Identity{SessionID: "receiver", Name: "receiver"}, Endpoint: endpoint, PID: 9412,
+		StartedAt: time.Now(), UpdatedAt: time.Now(), Ref: peerRef(endpoint)}
+	data, err := json.Marshal(peer)
+	if err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(service.registryDir(), "9412-test.json")
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	peers, err := service.List(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(peers) != 0 {
+		t.Fatalf("unreachable peers = %#v", peers)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("transient failure removed registry record: %v", err)
+	}
+}
+
+func TestReceiverRefusesForgedSenderReference(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	received := make(chan InboundMessage, 1)
+	receiver := newService(t, root, transport, 9502, Identity{SessionID: "receiver", Name: "receiver"})
+	if err := receiver.Start(func(message InboundMessage) bool { received <- message; return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+
+	conn, err := transport.Dial(context.Background(), receiver.Self().Endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	frame := sendFrame{
+		Version: ProtocolVersion,
+		Type:    "message",
+		ID:      "forged-message",
+		From: Peer{
+			Identity: Identity{SessionID: "sender", Name: "sender"},
+			Endpoint: "memory:sender",
+			Ref:      "forged",
+		},
+		To:      "receiver",
+		Summary: "hello",
+		Body:    "This must not be delivered.",
+	}
+	if err := json.NewEncoder(conn).Encode(frame); err != nil {
+		t.Fatal(err)
+	}
+	var response responseFrame
+	if err := decodeFrame(conn, &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Status != DeliveryRefused || !strings.Contains(response.Error, "invalid message envelope") {
+		t.Fatalf("response = %#v", response)
+	}
+	select {
+	case message := <-received:
+		t.Fatalf("forged message was delivered: %#v", message)
+	default:
+	}
+}
+
+func TestReceiverRefusesUnregisteredSenderWithValidReference(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	receiver := newStartedService(t, root, transport, 9512, Identity{SessionID: "receiver", Name: "receiver"})
+	conn, err := transport.Dial(context.Background(), receiver.Self().Endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	endpoint := "memory:unregistered"
+	frame := sendFrame{
+		Version: ProtocolVersion, Type: "message", ID: "forged-valid-ref",
+		From: Peer{Identity: Identity{SessionID: "attacker", PermissionClass: PermissionPrompting}, Endpoint: endpoint, Ref: peerRef(endpoint)},
+		To:   receiver.Self().SessionID, Summary: "spoof", Body: "must not arrive",
+	}
+	frame.HopChain = []string{frame.From.Ref}
+	if err := json.NewEncoder(conn).Encode(frame); err != nil {
+		t.Fatal(err)
+	}
+	var response responseFrame
+	if err := decodeFrame(conn, &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Status != DeliveryRefused || !strings.Contains(response.Error, "not registered") {
+		t.Fatalf("response = %#v", response)
+	}
+}
+
+func TestReceiverUsesRegisteredPermissionClass(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	received := make(chan InboundMessage, 1)
+	receiver := newService(t, root, transport, 9522, Identity{SessionID: "receiver", PermissionClass: PermissionPrompting})
+	if err := receiver.Start(func(message InboundMessage) bool { received <- message; return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := newStartedService(t, root, transport, 9521, Identity{SessionID: "sender", PermissionClass: PermissionBypass})
+	conn, err := transport.Dial(context.Background(), receiver.Self().Endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	claimed := sender.Self()
+	claimed.PermissionClass = PermissionPrompting
+	frame := sendFrame{Version: ProtocolVersion, Type: "message", ID: "permission-spoof", From: claimed,
+		To: receiver.Self().SessionID, Summary: "spoof", Body: "hold this", HopChain: []string{claimed.Ref}}
+	if err := json.NewEncoder(conn).Encode(frame); err != nil {
+		t.Fatal(err)
+	}
+	var response responseFrame
+	if err := decodeFrame(conn, &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Status != DeliveryHeld {
+		t.Fatalf("status = %q, want held", response.Status)
+	}
+	select {
+	case message := <-received:
+		if message.From.PermissionClass != PermissionBypass || !message.RequiresApproval {
+			t.Fatalf("message = %#v", message)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held message")
+	}
+}
+
+func TestOutstandingMessagesAreBoundedAndExpired(t *testing.T) {
+	now := time.Unix(1000, 0)
+	service := &Service{outstanding: make(map[string]outstandingMessage)}
+	for index := range peerMaxOutstanding + 20 {
+		service.outstanding[fmt.Sprint(index)] = outstandingMessage{createdAt: now.Add(time.Duration(index) * time.Second)}
+	}
+	service.pruneOutstandingLocked(now.Add(peerOutstandingTTL + time.Hour))
+	if len(service.outstanding) != 0 {
+		t.Fatalf("expired outstanding entries = %d", len(service.outstanding))
+	}
+	for index := range peerMaxOutstanding + 20 {
+		service.outstanding[fmt.Sprint(index)] = outstandingMessage{createdAt: now.Add(time.Duration(index) * time.Second)}
+	}
+	service.pruneOutstandingLocked(now)
+	if len(service.outstanding) >= peerMaxOutstanding {
+		t.Fatalf("bounded outstanding entries = %d", len(service.outstanding))
+	}
+}
+
+func TestDuplicateAttemptsConsumeRateCapacityWithoutRefreshingActivity(t *testing.T) {
+	now := time.Unix(1000, 0)
+	service := &Service{now: func() time.Time { return now }, guards: make(map[string]*senderGuard)}
+	sender := Peer{Endpoint: "memory:sender"}
+	if reason := service.admitMessage(sender, "same", []string{"11111111"}, "22222222"); reason != "" {
+		t.Fatal(reason)
+	}
+	activity := service.guards[sender.Endpoint].lastActivity
+	for range int(peerBucketCapacity) - 1 {
+		if reason := service.admitMessage(sender, "same", []string{"11111111"}, "22222222"); !strings.Contains(reason, "duplicate") {
+			t.Fatalf("reason = %q", reason)
+		}
+	}
+	if reason := service.admitMessage(sender, "different", []string{"11111111"}, "22222222"); !strings.Contains(reason, "rate limit") {
+		t.Fatalf("reason = %q", reason)
+	}
+	if !service.guards[sender.Endpoint].lastActivity.Equal(activity) {
+		t.Fatal("rejected duplicates refreshed sender activity")
+	}
+}
+
+func TestHeldEvictionRepairsMissingOrderEntry(t *testing.T) {
+	service := &Service{held: make(map[string]InboundMessage)}
+	for index := range peerMaxHeldMessages {
+		id := fmt.Sprint(index)
+		service.held[id] = InboundMessage{ID: id, ReceivedAt: time.Unix(int64(index), 0)}
+	}
+	evicted := service.popOldestHeldLocked()
+	if evicted.ID != "0" || len(service.held) != peerMaxHeldMessages-1 {
+		t.Fatalf("evicted=%#v remaining=%d", evicted, len(service.held))
+	}
+}
+
+func TestHeldEvictionReceiptDoesNotDelayInboundResponse(t *testing.T) {
+	root := t.TempDir()
+	transport := &slowEndpointTransport{memoryTransport: newMemoryTransport(), slowEndpoint: "memory:slow-sender"}
+	receiver := newService(t, root, transport, 9812, Identity{
+		SessionID: "receiver", PermissionClass: PermissionPrompting,
+	})
+	evicted := make(chan string, 1)
+	receiver.SetHeldEvictionHandler(func(messageID string) { evicted <- messageID })
+	if err := receiver.Start(func(InboundMessage) bool { return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = receiver.Close() })
+	sender := Peer{
+		Identity: Identity{SessionID: "sender", PermissionClass: PermissionBypass},
+		Endpoint: transport.slowEndpoint,
+		PID:      9811,
+		Ref:      peerRef(transport.slowEndpoint),
+	}
+	record, err := json.Marshal(sender)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(receiver.registryDir(), "9811-sender.json"), record, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	receiver.mu.Lock()
+	for index := range peerMaxHeldMessages {
+		id := fmt.Sprintf("held-%d", index)
+		receiver.held[id] = InboundMessage{ID: id, From: sender, ReceivedAt: time.Unix(int64(index), 0)}
+		receiver.heldOrder = append(receiver.heldOrder, id)
+	}
+	receiver.mu.Unlock()
+
+	conn, err := transport.memoryTransport.Dial(context.Background(), receiver.Self().Endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	frame := sendFrame{
+		Version: ProtocolVersion, Type: "message", ID: "new-held", From: sender,
+		To: receiver.Self().SessionID, Summary: "question", Body: "answer this", HopChain: []string{sender.Ref},
+	}
+	started := time.Now()
+	if err := json.NewEncoder(conn).Encode(frame); err != nil {
+		t.Fatal(err)
+	}
+	var response responseFrame
+	if err := decodeFrame(conn, &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Status != DeliveryHeld {
+		t.Fatalf("response = %#v", response)
+	}
+	if elapsed := time.Since(started); elapsed >= peerReceiptTimeout/2 {
+		t.Fatalf("inbound response waited %s for an eviction receipt", elapsed)
+	}
+	select {
+	case messageID := <-evicted:
+		if messageID != "held-0" {
+			t.Fatalf("eviction callback message ID = %q, want held-0", messageID)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for held-message eviction callback")
+	}
+}
+
+func TestIdentityUpdateSkipsStaleHeldOrderEntries(t *testing.T) {
+	root := t.TempDir()
+	transport := newMemoryTransport()
+	service := newService(t, root, transport, 9822, Identity{SessionID: "receiver", PermissionClass: PermissionPrompting})
+	released := make(chan InboundMessage, 2)
+	service.SetHeldReleaseHandler(func(message InboundMessage) { released <- message })
+	if err := service.Start(func(InboundMessage) bool { return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = service.Close() })
+	valid := InboundMessage{
+		ID: "valid", From: Peer{Identity: Identity{SessionID: "sender", PermissionClass: PermissionPrompting}, Endpoint: "memory:gone", Ref: peerRef("memory:gone")},
+	}
+	service.mu.Lock()
+	service.held[valid.ID] = valid
+	service.heldOrder = []string{"missing", valid.ID}
+	service.mu.Unlock()
+	if err := service.UpdateIdentity(Identity{SessionID: "receiver", PermissionClass: PermissionPrompting}); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case message := <-released:
+		if message.ID != valid.ID {
+			t.Fatalf("released stale entry as %#v", message)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("valid held message was not released")
+	}
+	select {
+	case message := <-released:
+		t.Fatalf("unexpected additional release: %#v", message)
+	default:
+	}
+}
+
+func TestSendStatusesGivesEveryReceiptAnIndependentDeadline(t *testing.T) {
+	transport := &receiptTransport{}
+	service := &Service{transport: transport, now: time.Now}
+	service.self = Peer{Identity: Identity{SessionID: "receiver"}, Endpoint: "receiver", Ref: peerRef("receiver")}
+	messages := make([]InboundMessage, 0, peerReceiptWorkers+1)
+	for index := range peerReceiptWorkers + 1 {
+		endpoint := fmt.Sprintf("fast-%d", index)
+		if index == 0 {
+			endpoint = "slow"
+		}
+		messages = append(messages, InboundMessage{ID: fmt.Sprint(index), From: Peer{
+			Identity: Identity{SessionID: fmt.Sprintf("sender-%d", index)}, Endpoint: endpoint, Ref: peerRef(endpoint),
+		}})
+	}
+	started := time.Now()
+	service.sendStatuses(messages, DeliveryExpired)
+	if elapsed := time.Since(started); elapsed > 2*peerReceiptTimeout {
+		t.Fatalf("receipt batch took %s; attempts appear serialized", elapsed)
+	}
+	if got, want := transport.fastDials.Load(), int32(len(messages)-1); got != want {
+		t.Fatalf("fast receipt attempts = %d, want %d", got, want)
+	}
+}
+
+func TestSenderGuardEvictsLeastRecentlyAcceptedSender(t *testing.T) {
+	now := time.Unix(1000, 0)
+	service := &Service{now: func() time.Time { return now }, guards: make(map[string]*senderGuard)}
+	for index := range peerMaxTrackedSenders {
+		service.guards[fmt.Sprint(index)] = &senderGuard{lastActivity: now.Add(time.Duration(index) * time.Second)}
+	}
+	if reason := service.admitMessage(Peer{Endpoint: "new"}, "body", []string{"11111111"}, "22222222"); reason != "" {
+		t.Fatal(reason)
+	}
+	if _, exists := service.guards["0"]; exists {
+		t.Fatal("least-recently-active sender was not evicted")
+	}
+	if _, exists := service.guards["new"]; !exists {
+		t.Fatal("new sender was not tracked")
+	}
+}
+
+func TestResolvePeerRequiresReferenceForDuplicateNames(t *testing.T) {
+	peers := []Peer{
+		{Identity: Identity{SessionID: "one", Name: "worker"}, Ref: "11111111"},
+		{Identity: Identity{SessionID: "two", Name: "worker"}, Ref: "22222222"},
+	}
+	if _, err := resolvePeer(peers, "worker"); err == nil || !strings.Contains(err.Error(), "ambiguous") {
+		t.Fatalf("ambiguous resolution error = %v", err)
+	}
+	peer, err := resolvePeer(peers, "worker [22222222]")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if peer.SessionID != "two" {
+		t.Fatalf("peer = %#v", peer)
+	}
+}
+
+func TestPlainTextNormalizationRemovesTerminalControls(t *testing.T) {
+	if got := normalizeBody("  hello\x1b[31m\nworld\x00  "); got != "hello[31m\nworld" {
+		t.Fatalf("normalized body = %q", got)
+	}
+	if got := normalizeSummary("  status\x1b[31m\nignored  "); got != "status[31m" {
+		t.Fatalf("normalized summary = %q", got)
+	}
+}
+
+func TestRemoteErrorNormalizationStripsControlsAndCapsLength(t *testing.T) {
+	got := normalizeRemoteError("\x1b[31m" + strings.Repeat("x", peerErrorMaxRunes+20))
+	if strings.ContainsRune(got, '\x1b') || len([]rune(got)) != peerErrorMaxRunes {
+		t.Fatalf("normalized remote error length=%d value=%q", len([]rune(got)), got)
+	}
+	if got := normalizeRemoteError("\x00\x1b"); got != "receiver rejected the message" {
+		t.Fatalf("empty remote error = %q", got)
+	}
+}
+
+func newStartedService(t *testing.T, root string, transport localTransport, pid int, identity Identity) *Service {
+	t.Helper()
+	service := newService(t, root, transport, pid, identity)
+	if err := service.Start(func(InboundMessage) bool { return true }); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = service.Close() })
+	return service
+}
+
+func newService(t *testing.T, root string, transport localTransport, pid int, identity Identity) *Service {
+	t.Helper()
+	service, err := New(Options{RootDir: root, PID: pid, Identity: identity, Transport: transport})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return service
+}
+
+type memoryTransport struct {
+	mu        sync.Mutex
+	listeners map[string]*memoryListener
+}
+
+type removeErrorTransport struct{ *memoryTransport }
+
+func (transport *removeErrorTransport) Remove(endpoint string) error {
+	_ = transport.memoryTransport.Remove(endpoint)
+	return errors.New("forced remove failure")
+}
+
+type slowEndpointTransport struct {
+	*memoryTransport
+	slowEndpoint string
+}
+
+func (transport *slowEndpointTransport) Dial(ctx context.Context, endpoint string) (net.Conn, error) {
+	if endpoint == transport.slowEndpoint {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	return transport.memoryTransport.Dial(ctx, endpoint)
+}
+
+type receiptTransport struct{ fastDials atomic.Int32 }
+
+func (transport *receiptTransport) Endpoint(_ string, _ string, _ int) (string, error) {
+	return "", errors.New("not implemented")
+}
+
+func (transport *receiptTransport) Listen(string) (net.Listener, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (transport *receiptTransport) Dial(ctx context.Context, endpoint string) (net.Conn, error) {
+	if endpoint == "slow" {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	transport.fastDials.Add(1)
+	client, server := net.Pipe()
+	go func() {
+		_, _ = io.Copy(io.Discard, server)
+		_ = server.Close()
+	}()
+	return client, nil
+}
+
+func (transport *receiptTransport) Remove(string) error { return nil }
+
+func newMemoryTransport() *memoryTransport {
+	return &memoryTransport{listeners: map[string]*memoryListener{}}
+}
+
+func (transport *memoryTransport) Endpoint(_ string, nonce string, pid int) (string, error) {
+	return fmt.Sprintf("memory:%d:%s", pid, nonce), nil
+}
+
+func (transport *memoryTransport) Listen(endpoint string) (net.Listener, error) {
+	transport.mu.Lock()
+	defer transport.mu.Unlock()
+	if _, exists := transport.listeners[endpoint]; exists {
+		return nil, errors.New("already listening")
+	}
+	listener := &memoryListener{endpoint: endpoint, conns: make(chan net.Conn), done: make(chan struct{})}
+	transport.listeners[endpoint] = listener
+	return listener, nil
+}
+
+func (transport *memoryTransport) Dial(ctx context.Context, endpoint string) (net.Conn, error) {
+	transport.mu.Lock()
+	listener := transport.listeners[endpoint]
+	transport.mu.Unlock()
+	if listener == nil {
+		return nil, errors.New("not listening")
+	}
+	client, server := net.Pipe()
+	select {
+	case listener.conns <- server:
+		return client, nil
+	case <-listener.done:
+		_ = client.Close()
+		_ = server.Close()
+		return nil, net.ErrClosed
+	case <-ctx.Done():
+		_ = client.Close()
+		_ = server.Close()
+		return nil, ctx.Err()
+	}
+}
+
+func (transport *memoryTransport) Remove(endpoint string) error {
+	transport.mu.Lock()
+	delete(transport.listeners, endpoint)
+	transport.mu.Unlock()
+	return nil
+}
+
+type memoryListener struct {
+	endpoint string
+	conns    chan net.Conn
+	done     chan struct{}
+	once     sync.Once
+}
+
+func (listener *memoryListener) Accept() (net.Conn, error) {
+	select {
+	case conn := <-listener.conns:
+		return conn, nil
+	case <-listener.done:
+		return nil, net.ErrClosed
+	}
+}
+
+func (listener *memoryListener) Close() error {
+	listener.once.Do(func() { close(listener.done) })
+	return nil
+}
+
+func (listener *memoryListener) Addr() net.Addr { return memoryAddr(listener.endpoint) }
+
+type memoryAddr string
+
+func (address memoryAddr) Network() string { return "memory" }
+func (address memoryAddr) String() string  { return string(address) }

internal/peermsg/transport.go

@@ -0,0 +1,15 @@
+package peermsg
+
+import (
+	"context"
+	"net"
+)
+
+type localTransport interface {
+	Endpoint(root, nonce string, pid int) (string, error)
+	Listen(endpoint string) (net.Listener, error)
+	Dial(context.Context, string) (net.Conn, error)
+	Remove(string) error
+}
+
+func platformTransport() localTransport { return newPlatformTransport() }

internal/peermsg/transport_integration_test.go

@@ -0,0 +1,62 @@
+package peermsg
+
+import (
+	"context"
+	"io"
+	"testing"
+	"time"
+)
+
+func TestPlatformTransportRoundTrip(t *testing.T) {
+	transport := platformTransport()
+	endpoint, err := transport.Endpoint(t.TempDir(), "0123456789abcdef", 4242)
+	if err != nil {
+		t.Fatal(err)
+	}
+	listener, err := transport.Listen(endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		_ = listener.Close()
+		_ = transport.Remove(endpoint)
+	})
+
+	serverErr := make(chan error, 1)
+	go func() {
+		conn, acceptErr := listener.Accept()
+		if acceptErr != nil {
+			serverErr <- acceptErr
+			return
+		}
+		defer conn.Close()
+		payload := make([]byte, 4)
+		if _, readErr := io.ReadFull(conn, payload); readErr != nil {
+			serverErr <- readErr
+			return
+		}
+		_, writeErr := conn.Write(payload)
+		serverErr <- writeErr
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	conn, err := transport.Dial(ctx, endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if _, err := conn.Write([]byte("ping")); err != nil {
+		t.Fatal(err)
+	}
+	reply := make([]byte, 4)
+	if _, err := io.ReadFull(conn, reply); err != nil {
+		t.Fatal(err)
+	}
+	if string(reply) != "ping" {
+		t.Fatalf("reply = %q", reply)
+	}
+	if err := <-serverErr; err != nil {
+		t.Fatal(err)
+	}
+}

internal/peermsg/transport_unix.go

@@ -0,0 +1,78 @@
+//go:build !windows
+
+package peermsg
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+type unixTransport struct{}
+
+const unixSocketPathMax = 103
+
+func newPlatformTransport() localTransport { return unixTransport{} }
+
+func (unixTransport) Endpoint(root, nonce string, pid int) (string, error) {
+	dir := filepath.Join(root, "sockets")
+	dir, err := canonicalPrivateDir(dir)
+	if err != nil {
+		return "", fmt.Errorf("peer messaging: create socket directory: %w", err)
+	}
+	path := filepath.Join(dir, fmt.Sprintf("%d-%s.sock", pid, nonce))
+	// macOS has the smallest supported sockaddr_un path (103 usable bytes).
+	if len(path) > unixSocketPathMax {
+		dir = filepath.Join(os.TempDir(), fmt.Sprintf("zero-peers-%d", os.Getuid()))
+		dir, err = canonicalPrivateDir(dir)
+		if err != nil {
+			return "", fmt.Errorf("peer messaging: create fallback socket directory: %w", err)
+		}
+		path = filepath.Join(dir, fmt.Sprintf("%d-%s.sock", pid, nonce))
+	}
+	if len(path) > unixSocketPathMax {
+		return "", fmt.Errorf("peer messaging: socket path is too long: %s", path)
+	}
+	return path, nil
+}
+
+func canonicalPrivateDir(path string) (string, error) {
+	canonical, err := canonicalRuntimePath(path)
+	if err != nil {
+		return "", err
+	}
+	if err := ensurePrivateDir(canonical); err != nil {
+		return "", err
+	}
+	return canonical, nil
+}
+
+func (unixTransport) Listen(endpoint string) (net.Listener, error) {
+	_ = os.Remove(endpoint)
+	listener, err := net.Listen("unix", endpoint)
+	if err != nil {
+		return nil, err
+	}
+	if err := os.Chmod(endpoint, 0o600); err != nil {
+		_ = listener.Close()
+		_ = os.Remove(endpoint)
+		return nil, err
+	}
+	return listener, nil
+}
+
+func (unixTransport) Dial(ctx context.Context, endpoint string) (net.Conn, error) {
+	dialer := net.Dialer{Timeout: 5 * time.Second}
+	return dialer.DialContext(ctx, "unix", endpoint)
+}
+
+func (unixTransport) Remove(endpoint string) error {
+	err := os.Remove(endpoint)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	return err
+}

internal/peermsg/transport_unix_test.go

@@ -0,0 +1,74 @@
+//go:build unix
+
+package peermsg
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestUnixTransportFallbackAndSocketMode(t *testing.T) {
+	transport := unixTransport{}
+	longRoot := filepath.Join(t.TempDir(), strings.Repeat("long", 30))
+	endpoint, err := transport.Endpoint(longRoot, "0123456789abcdef", 4242)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(endpoint) > unixSocketPathMax {
+		t.Fatalf("endpoint length = %d", len(endpoint))
+	}
+	listener, err := transport.Listen(endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = listener.Close(); _ = transport.Remove(endpoint) })
+	info, err := os.Stat(endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("socket mode = %o", info.Mode().Perm())
+	}
+}
+
+func TestUnixTransportCanonicalizesSymlinkedRoot(t *testing.T) {
+	root, err := os.MkdirTemp("/tmp", "zp-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := os.RemoveAll(root); err != nil {
+			t.Errorf("remove temporary transport root: %v", err)
+		}
+	})
+	target := filepath.Join(root, "physical")
+	if err := os.Mkdir(target, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	alias := filepath.Join(root, "alias")
+	if err := os.Symlink(target, alias); err != nil {
+		t.Fatal(err)
+	}
+	endpoint, err := (unixTransport{}).Endpoint(alias, "0123456789abcdef", 4242)
+	if err != nil {
+		t.Fatal(err)
+	}
+	canonicalTarget, err := filepath.EvalSymlinks(target)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(endpoint, canonicalTarget+string(filepath.Separator)) {
+		t.Fatalf("endpoint %q is not rooted at canonical target %q", endpoint, canonicalTarget)
+	}
+}
+
+func TestUnixTransportRejectsPathLongerThanFallback(t *testing.T) {
+	transport := unixTransport{}
+	longTmp := filepath.Join(t.TempDir(), strings.Repeat("x", unixSocketPathMax))
+	t.Setenv("TMPDIR", longTmp)
+	if _, err := transport.Endpoint(filepath.Join(t.TempDir(), strings.Repeat("y", unixSocketPathMax)), "0123456789abcdef", 4242); err == nil {
+		t.Fatal("expected too-long fallback path error")
+	}
+}

internal/peermsg/transport_windows.go

@@ -0,0 +1,51 @@
+//go:build windows
+
+package peermsg
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"time"
+
+	winio "github.com/Microsoft/go-winio"
+	"golang.org/x/sys/windows"
+)
+
+type windowsPipeTransport struct{}
+
+func newPlatformTransport() localTransport { return windowsPipeTransport{} }
+
+func (windowsPipeTransport) Endpoint(_ string, nonce string, pid int) (string, error) {
+	return fmt.Sprintf(`\\.\pipe\zero-peer-%d-%s`, pid, nonce), nil
+}
+
+func (windowsPipeTransport) Listen(endpoint string) (net.Listener, error) {
+	var token windows.Token
+	if err := windows.OpenProcessToken(windows.CurrentProcess(), windows.TOKEN_QUERY, &token); err != nil {
+		return nil, fmt.Errorf("peer messaging: query current process token: %w", err)
+	}
+	defer token.Close()
+	user, err := token.GetTokenUser()
+	if err != nil {
+		return nil, fmt.Errorf("peer messaging: query current user: %w", err)
+	}
+	userSID := user.User.Sid.String()
+	return winio.ListenPipe(endpoint, &winio.PipeConfig{
+		// Limit the pipe to LocalSystem and the exact user running this process.
+		// The receiver still treats every peer message as untrusted agent input,
+		// never as user authority.
+		SecurityDescriptor: fmt.Sprintf("D:P(A;;GA;;;SY)(A;;GA;;;%s)", userSID),
+		MessageMode:        false,
+		InputBufferSize:    maxFrameBytes,
+		OutputBufferSize:   4096,
+	})
+}
+
+func (windowsPipeTransport) Dial(ctx context.Context, endpoint string) (net.Conn, error) {
+	dialCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	return winio.DialPipeContext(dialCtx, endpoint)
+}
+
+func (windowsPipeTransport) Remove(string) error { return nil }

internal/peermsg/types.go

@@ -0,0 +1,110 @@
+package peermsg
+
+import "time"
+
+const (
+	ProtocolVersion = 1
+	maxMessageBytes = 64 * 1024
+	maxFrameBytes   = 128 * 1024
+)
+
+type PermissionClass string
+
+const (
+	PermissionPrompting PermissionClass = "prompting"
+	PermissionBypass    PermissionClass = "bypass"
+)
+
+type DeliveryStatus string
+
+const (
+	DeliveryAccepted  DeliveryStatus = "accepted"
+	DeliveryHeld      DeliveryStatus = "held"
+	DeliveryRefused   DeliveryStatus = "refused"
+	DeliveryDelivered DeliveryStatus = "delivered"
+	DeliveryDenied    DeliveryStatus = "denied"
+	DeliveryExpired   DeliveryStatus = "expired"
+)
+
+type InboundPolicy string
+
+const (
+	InboundPolicyParity InboundPolicy = ""
+	InboundPolicyAccept InboundPolicy = "accept"
+	InboundPolicyHold   InboundPolicy = "hold"
+	InboundPolicyRefuse InboundPolicy = "refuse"
+)
+
+type HoldCause string
+
+const (
+	HoldCauseModeMismatch HoldCause = "mode-mismatch"
+	HoldCauseExplicit     HoldCause = "explicit-setting"
+	HoldCauseModeUnknown  HoldCause = "mode-unknown"
+)
+
+// Identity is the model-independent identity published by one live Zero
+// process. SessionID and Name are updated when the TUI creates, resumes, or
+// renames its active session.
+type Identity struct {
+	SessionID       string          `json:"sessionId,omitempty"`
+	Name            string          `json:"name,omitempty"`
+	Cwd             string          `json:"cwd,omitempty"`
+	PermissionClass PermissionClass `json:"permissionClass"`
+}
+
+// Peer is one reachable local Zero session.
+type Peer struct {
+	Identity
+	Endpoint  string    `json:"endpoint"`
+	PID       int       `json:"pid"`
+	StartedAt time.Time `json:"startedAt"`
+	UpdatedAt time.Time `json:"updatedAt"`
+	Ref       string    `json:"ref"`
+}
+
+// InboundMessage is delivered to the receiving application. RequiresApproval
+// is true when local policy requires the user to approve delivery.
+type InboundMessage struct {
+	ID               string
+	From             Peer
+	Body             string
+	Summary          string
+	ReceivedAt       time.Time
+	RequiresApproval bool
+	HoldCause        HoldCause
+	HopChain         []string
+}
+
+type sendFrame struct {
+	Version  int            `json:"version"`
+	Type     string         `json:"type"`
+	ID       string         `json:"id"`
+	From     Peer           `json:"from"`
+	To       string         `json:"to"`
+	Summary  string         `json:"summary"`
+	Body     string         `json:"body"`
+	HopChain []string       `json:"hopChain,omitempty"`
+	OrigID   string         `json:"origMessageId,omitempty"`
+	Status   DeliveryStatus `json:"status,omitempty"`
+}
+
+type responseFrame struct {
+	Version int            `json:"version"`
+	Type    string         `json:"type"`
+	ID      string         `json:"id"`
+	Status  DeliveryStatus `json:"status"`
+	Error   string         `json:"error,omitempty"`
+}
+
+type SendResult struct {
+	MessageID string
+	Peer      Peer
+	Status    DeliveryStatus
+}
+
+type StatusEvent struct {
+	MessageID string
+	Peer      Peer
+	Status    DeliveryStatus
+}

internal/providerhealth/providerhealth.go

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

internal/providerhealth/providerhealth_test.go

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

internal/sandbox/runner_windows_integration_test.go

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

internal/sandbox/windows_token_windows.go

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

internal/sessions/replay.go

@@ -7,6 +7,7 @@ import (
 	"unicode/utf8"
 
 	"github.com/Gitlawb/zero/internal/redaction"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
 type EventRef struct {
@@ -37,6 +38,7 @@ type RewindPlan struct {
 type CompactionOptions struct {
 	PreserveLast   int
 	MaxPromptChars int
+	SkipPrompt     bool
 }
 
 type CompactionPlan struct {
@@ -47,8 +49,9 @@ type CompactionPlan struct {
 	CompactableEvents []EventRef `json:"compactableEvents"`
 	PreservedEvents   []EventRef `json:"preservedEvents"`
 	SummaryPrompt     string     `json:"summaryPrompt"`
-	PromptChars       int        `json:"promptChars"`
-	Truncated         bool       `json:"truncated,omitempty"`
+	// PromptChars counts prompt text content and excludes provider protocol framing.
+	PromptChars int  `json:"promptChars"`
+	Truncated   bool `json:"truncated,omitempty"`
 }
 
 type RecordCompactionInput struct {
@@ -164,7 +167,11 @@ func (store *Store) PlanCompaction(sessionID string, options CompactionOptions)
 	}
 	compactable := events[:split]
 	preserved := events[split:]
-	prompt, truncated := buildCompactionPrompt(compactable, maxPromptChars)
+	prompt := ""
+	truncated := false
+	if !options.SkipPrompt {
+		prompt, truncated = buildCompactionPrompt(compactable, maxPromptChars)
+	}
 	return CompactionPlan{
 		SessionID:         sessionID,
 		PreserveLast:      preserveLast,
@@ -312,6 +319,88 @@ func buildCompactionPrompt(events []Event, maxChars int) (string, bool) {
 	return prompt, false
 }
 
+// CompactionMessages converts durable session events into the same normalized
+// message shape used by the running agent's compaction pipeline. Provider usage
+// and checkpoint blobs are omitted. Message/tool fields rely on the session
+// writer's invariant that tool output is scrubbed before persistence;
+// ask_user answers and generic event previews are redacted here.
+func CompactionMessages(events []Event) []zeroruntime.Message {
+	messages := make([]zeroruntime.Message, 0, len(events))
+	for _, event := range events {
+		var payload map[string]any
+		_ = json.Unmarshal(event.Payload, &payload)
+		stringField := func(key string) string {
+			value, _ := payload[key].(string)
+			return strings.TrimSpace(value)
+		}
+		switch event.Type {
+		case EventMessage:
+			role := strings.ToLower(stringField("role"))
+			content := stringField("content")
+			switch role {
+			case "user":
+				messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: content})
+			case "assistant":
+				messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: content})
+			case "ask_user_answers":
+				if answers, ok := payload["answers"]; ok {
+					encoded, _ := json.Marshal(answers)
+					messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "User answers: " + redaction.RedactString(string(encoded), redaction.Options{})})
+				}
+			default:
+				if content != "" {
+					messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: content})
+				}
+			}
+		case EventToolCall:
+			messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{
+				ID: firstSessionString(stringField("toolCallId"), stringField("id")), Name: firstSessionString(stringField("name"), stringField("toolName")), Arguments: stringField("arguments"),
+			}}})
+		case EventToolResult:
+			status := strings.ToLower(stringField("status"))
+			messages = append(messages, zeroruntime.Message{
+				Role: zeroruntime.MessageRoleTool, ToolCallID: firstSessionString(stringField("toolCallId"), stringField("id")),
+				Content: stringField("output"), IsError: status != "" && status != "ok", ChangedFiles: sessionStringSlice(payload["changedFiles"]),
+			})
+		case EventCompaction:
+			if summary := stringField("summary"); summary != "" {
+				messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "[Summary of earlier conversation]\n" + summary})
+			}
+		case EventProviderUsage, EventSessionCheckpoint:
+			continue
+		default:
+			preview := shapedPayloadPreview(event)
+			if strings.TrimSpace(preview) != "" && preview != "{}" {
+				messages = append(messages, zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: fmt.Sprintf("[%s] %s", event.Type, preview)})
+			}
+		}
+	}
+	return messages
+}
+
+func firstSessionString(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
+func sessionStringSlice(value any) []string {
+	raw, ok := value.([]any)
+	if !ok {
+		return nil
+	}
+	values := make([]string, 0, len(raw))
+	for _, item := range raw {
+		if text, ok := item.(string); ok && strings.TrimSpace(text) != "" {
+			values = append(values, strings.TrimSpace(text))
+		}
+	}
+	return values
+}
+
 func shapedPayloadPreview(event Event) string {
 	switch event.Type {
 	case EventPermission, EventPermissionRequest, EventPermissionDecision:

internal/sessions/replay_test.go

@@ -5,8 +5,27 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
+func TestCompactionMessagesPreservesInteractiveAndMutationEvidence(t *testing.T) {
+	events := []Event{
+		{Type: EventToolCall, Payload: json.RawMessage(`{"id":"ask","name":"ask_user","arguments":"{\"questions\":[{\"question\":\"Which database?\"}]}"}`)},
+		{Type: EventToolResult, Payload: json.RawMessage(`{"toolCallId":"ask","name":"ask_user","status":"ok","output":"Postgres only"}`)},
+		{Type: EventToolCall, Payload: json.RawMessage(`{"id":"patch","name":"apply_patch","arguments":"{\"patch\":\"*** Update File: db.go\"}"}`)},
+		{Type: EventToolResult, Payload: json.RawMessage(`{"toolCallId":"patch","name":"apply_patch","status":"ok","output":"Done!","changedFiles":["db.go"]}`)},
+	}
+
+	messages := CompactionMessages(events)
+	if len(messages) != 4 || messages[0].Role != zeroruntime.MessageRoleAssistant || messages[1].Role != zeroruntime.MessageRoleTool {
+		t.Fatalf("unexpected normalized compaction messages: %#v", messages)
+	}
+	if messages[1].Content != "Postgres only" || len(messages[3].ChangedFiles) != 1 || messages[3].ChangedFiles[0] != "db.go" {
+		t.Fatalf("interactive or mutation evidence was lost: %#v", messages)
+	}
+}
+
 func TestStorePlansRewindBySequence(t *testing.T) {
 	store := NewStore(StoreOptions{RootDir: t.TempDir(), Now: sequenceClock([]time.Time{
 		time.Date(2026, 6, 6, 10, 0, 0, 0, time.UTC),
@@ -130,6 +149,26 @@ func TestStorePlansCompactionWindow(t *testing.T) {
 	}
 }
 
+func TestStoreCanPlanCompactionWithoutBuildingLegacyPrompt(t *testing.T) {
+	store := NewStore(StoreOptions{RootDir: t.TempDir()})
+	session, err := store.Create(CreateInput{SessionID: "compactnoprompt"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, content := range []string{"one", "two", "three"} {
+		if _, err := store.AppendEvent(session.SessionID, AppendEventInput{Type: EventMessage, Payload: map[string]string{"content": content}}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	plan, err := store.PlanCompaction(session.SessionID, CompactionOptions{PreserveLast: 1, SkipPrompt: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if plan.CompactableCount != 2 || plan.SummaryPrompt != "" || plan.PromptChars != 0 || plan.Truncated {
+		t.Fatalf("unexpected prompt-free plan: %#v", plan)
+	}
+}
+
 func TestStoreCompactionShapesSensitivePermissionEvents(t *testing.T) {
 	secret := "sk-proj-abcdefghijklmnopqrstuvwxyz"
 	store := NewStore(StoreOptions{RootDir: t.TempDir()})

internal/sessions/session_title_test.go

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

internal/sessions/store.go

@@ -719,7 +719,7 @@ func (store *Store) appendPreparedEventsLocked(sessionID string, inputs []prepar
 // serialized under the same per-session lock as AppendEvent and re-reads the
 // latest metadata under that lock before rewriting, so a concurrent append can't
 // clobber the new title (nor the title clobber a concurrent append's event
-// count/timestamp). UpdatedAt is deliberately left untouched: a retitle is not
+// count/timestamp). UpdatedAt is deliberately left untouched: a rename is not
 // activity, so it must not reorder the session in the resumable list. A blank
 // title is rejected so a failed model generation can never erase a useful
 // first-message title, and an unchanged title is a no-op (no rewrite/fsync).
@@ -751,6 +751,40 @@ func (store *Store) UpdateTitle(sessionID string, title string) (Metadata, error
 	return session, nil
 }
 
+// UpdateTitleIfCurrent replaces a session title only when it still matches
+// expected. It lets background automatic naming avoid overwriting a newer manual
+// rename while keeping the check and write under the same per-session lock.
+func (store *Store) UpdateTitleIfCurrent(sessionID string, expected string, title string) (Metadata, bool, error) {
+	if !ValidSessionID(sessionID) {
+		return Metadata{}, false, fmt.Errorf("invalid zero session id %q", sessionID)
+	}
+	trimmed := strings.TrimSpace(title)
+	if trimmed == "" {
+		return Metadata{}, false, fmt.Errorf("zero session title is required")
+	}
+	unlock, err := store.lockSession(sessionID)
+	if err != nil {
+		return Metadata{}, false, err
+	}
+	defer unlock()
+
+	session, err := store.readMetadata(sessionID)
+	if err != nil {
+		return Metadata{}, false, err
+	}
+	if session.Title != strings.TrimSpace(expected) {
+		return session, false, nil
+	}
+	if session.Title == trimmed {
+		return session, true, nil
+	}
+	session.Title = trimmed
+	if err := store.writeMetadata(session); err != nil {
+		return Metadata{}, false, err
+	}
+	return session, true, nil
+}
+
 // UpdateModel replaces a session's selected model without changing its activity
 // timestamp or event counters. An empty model clears the session override.
 func (store *Store) UpdateModel(sessionID string, modelID string) (Metadata, error) {

internal/specialist/exec.go

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

internal/specialist/exec_test.go

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

internal/specialist/manifest.go

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

internal/specialist/view_image_category_test.go

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

internal/tools/apply_patch.go

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

internal/tools/args.go

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

internal/tools/bash.go

@@ -43,16 +43,17 @@ func NewScopedBashTool(workspaceRoot string, scope PathScope) Tool {
 		baseTool: baseTool{
 			name:        "bash",
 			description: "Execute a shell command inside the workspace (or an explicitly granted extra directory) after permission is granted. " + shellGuidance,
+			deferred:    true,
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
 					"command":             {Type: "string", Description: "Shell command to execute using the host shell. " + shellGuidance},
 					"cwd":                 {Type: "string", Description: "Directory to run the command in. Relative paths stay in the workspace; use an absolute path to run in a granted extra directory. Defaults to workspace root. Prefer cwd over cd when changing directories.", Default: "."},
 					"timeout_ms":          {Type: "integer", Description: "Command timeout in milliseconds.", Default: defaultBashTimeoutMS, Minimum: intPtr(1), Maximum: intPtr(maxBashTimeoutMS)},
-					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions` for sandboxed file/network access, or `require_escalated` only when the command must run outside the sandbox, such as host/global process, socket, service, or desktop state hidden by sandbox namespaces.", Default: string(SandboxPermissionsUseDefault)},
+					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: sandboxPermissionsDescription, Default: string(SandboxPermissionsUseDefault)},
 					"additional_permissions": {
 						Type:        "object",
-						Description: "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`.",
+						Description: additionalPermissionsDescription,
 						Properties:  additionalPermissionsProperties(),
 					},
 					"justification": {Type: "string", Description: "User-facing approval question for `require_escalated`; omit otherwise."},

internal/tools/edit_file.go

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

internal/tools/exec_command.go

@@ -91,10 +91,10 @@ func NewScopedExecCommandTool(workspaceRoot string, scope PathScope, manager *ex
 					"cwd":                 {Type: "string", Description: "Alias for workdir. Prefer workdir.", Default: "."},
 					"yield_time_ms":       {Type: "integer", Description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.", Default: defaultExecYieldTimeMS, Minimum: intPtr(1), Maximum: intPtr(maxExecYieldTimeMS)},
 					"max_output_tokens":   {Type: "integer", Description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.", Default: defaultMaxOutputTokens, Minimum: intPtr(1), Maximum: intPtr(maxExecOutputTokenRequest)},
-					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions` for sandboxed file/network access, or `require_escalated` only when the command must run outside the sandbox, such as host/global process, socket, service, or desktop state hidden by sandbox namespaces.", Default: string(SandboxPermissionsUseDefault)},
+					"sandbox_permissions": {Type: "string", Enum: []string{string(SandboxPermissionsUseDefault), string(SandboxPermissionsWithAdditionalPermissions), string(SandboxPermissionsRequireEscalated)}, Description: sandboxPermissionsDescription, Default: string(SandboxPermissionsUseDefault)},
 					"additional_permissions": {
 						Type:        "object",
-						Description: "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`.",
+						Description: additionalPermissionsDescription,
 						Properties:  additionalPermissionsProperties(),
 					},
 					"justification": {Type: "string", Description: "User-facing approval question for `require_escalated`; omit otherwise."},

internal/tools/file_safety_test.go

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

internal/tools/file_tools_test.go

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

internal/tools/file_tracker.go

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

internal/tools/file_tracker_coverage_test.go

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

internal/tools/file_tracker_largefile_test.go

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

internal/tools/format_on_write_test.go

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

internal/tools/grep.go

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

internal/tools/local_browser.go

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

internal/tools/local_capture.go

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

internal/tools/local_desktop.go

@@ -27,6 +27,7 @@ func newDesktopWindowsTool(options localcontrol.DesktopOptions) Tool {
 	return desktopWindowsTool{
 		baseTool: baseTool{
 			name:        "desktop_windows",
+			deferred:    true,
 			description: "List native desktop windows through the local desktop automation helper.",
 			parameters: Schema{
 				Type: "object",
@@ -70,6 +71,7 @@ func newDesktopSnapshotTool(options localcontrol.DesktopOptions) Tool {
 	return desktopSnapshotTool{
 		baseTool: baseTool{
 			name:        "desktop_snapshot",
+			deferred:    true,
 			description: "Read a native desktop window accessibility snapshot through the local desktop automation helper.",
 			parameters: Schema{
 				Type: "object",
@@ -117,6 +119,7 @@ func newDesktopActionTool(options localcontrol.DesktopOptions) Tool {
 	return desktopActionTool{
 		baseTool: baseTool{
 			name:        "desktop_action",
+			deferred:    true,
 			description: "Run an allowed native desktop action through the local desktop automation helper.",
 			parameters: Schema{
 				Type: "object",

internal/tools/local_terminal.go

@@ -23,6 +23,7 @@ func newTerminalSessionTool(options localcontrol.TerminalOptions) Tool {
 	return terminalSessionTool{
 		baseTool: baseTool{
 			name:        "terminal_session",
+			deferred:    true,
 			description: "Launch or control a local virtual terminal session through the local terminal automation helper.",
 			parameters: Schema{
 				Type: "object",

internal/tools/lsp_navigate.go

@@ -32,7 +32,8 @@ func NewScopedLSPNavigateTool(workspaceRoot string, scope PathScope) Tool {
 	root := normalizeWorkspaceRoot(workspaceRoot)
 	return lspNavigateTool{
 		baseTool: baseTool{
-			name: "lsp_navigate",
+			name:     "lsp_navigate",
+			deferred: true,
 			description: "Navigate code semantically via the language server: jump to a symbol's " +
 				"definition, find all references, find implementations of an interface/method, or " +
 				"search workspace symbols by name. Use this instead of grep when you need precise " +

internal/tools/output_boundary.go

@@ -57,6 +57,9 @@ func applySelfManagedOutputBudget(tool Tool, toolName string, args map[string]an
 
 	category := resolveOutputCategory(tool, toolName, args)
 	budgeted := budgetSemanticOutput(result.Output, category, budget)
+	if result.Truncated && budgeted.spillPath == "" {
+		budgeted.spillPath = result.Meta["spill_path"]
+	}
 	if result.Truncated && !budgeted.truncated {
 		budgeted.truncated = true
 		budgeted.reason = result.Meta["truncation_reason"]
@@ -64,7 +67,7 @@ func applySelfManagedOutputBudget(tool Tool, toolName string, args map[string]an
 			budgeted.reason = "upstream_tool_budget"
 		}
 	}
-	if budgeted.truncated {
+	if budgeted.truncated && budgeted.spillPath == "" {
 		budgeted = attachExistingSpill(toolName, result.Output, budget, budgeted)
 	}
 	result.Output = budgeted.text

internal/tools/peer_sessions.go

@@ -0,0 +1,156 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/peermsg"
+)
+
+type peerSessionService interface {
+	List(context.Context) ([]peermsg.Peer, error)
+	Send(context.Context, string, string, string) (peermsg.SendResult, error)
+}
+
+// NewPeerSessionTools exposes live-session discovery and messaging through the
+// canonical tool registry. The peer runtime still owns resolution, transport,
+// framing, and delivery policy.
+func NewPeerSessionTools(service peerSessionService) []Tool {
+	if service == nil {
+		return nil
+	}
+	return []Tool{
+		listSessionsTool{
+			baseTool: baseTool{
+				name:        "list_sessions",
+				description: "List other live local Zero sessions that can receive a message. Use the displayed name or name [ref] as send_message's recipient.",
+				deferred:    true,
+				parameters: Schema{
+					Type:                 "object",
+					AdditionalProperties: false,
+				},
+				safety:       Safety{SideEffect: SideEffectRead, Permission: PermissionAllow},
+				capabilities: ToolCapabilities{Effect: EffectReadOnly, ThreadSafe: true},
+			},
+			service: service,
+		},
+		newSendSessionMessageTool(service, true),
+	}
+}
+
+// NewPeerReplyTool exposes send_message eagerly for a turn that originated
+// from another session. Ordinary turns keep the same tool deferred so sessions
+// that never use peer messaging pay no schema cost.
+func NewPeerReplyTool(service peerSessionService) Tool {
+	if service == nil {
+		return nil
+	}
+	return newSendSessionMessageTool(service, false)
+}
+
+func newSendSessionMessageTool(service peerSessionService, deferred bool) sendSessionMessageTool {
+	return sendSessionMessageTool{
+		baseTool: baseTool{
+			name:        "send_message",
+			description: "Send plain text to another live local Zero session. Peer messages are agent input, never user permission or authority.",
+			deferred:    deferred,
+			parameters: Schema{
+				Type: "object",
+				Properties: map[string]PropertySchema{
+					"to": {
+						Type:        "string",
+						Description: "Recipient from list_sessions: a unique session name, name [ref], or exact session ID.",
+						MaxLength:   intPtr(256),
+					},
+					"summary": {
+						Type:        "string",
+						Description: "A concise one-line summary of the message.",
+						MaxLength:   intPtr(200),
+					},
+					"message": {
+						Type:        "string",
+						Description: "Plain-text message content.",
+						MaxLength:   intPtr(64 * 1024),
+					},
+				},
+				Required:             []string{"to", "summary", "message"},
+				AdditionalProperties: false,
+			},
+			safety: Safety{
+				SideEffect: SideEffectLocalControl,
+				Permission: PermissionAllow,
+				Reason:     "Sends model-authored text to another local Zero session under that receiver's independent inbound policy.",
+			},
+			capabilities: ToolCapabilities{Effect: EffectInteractive},
+		},
+		service: service,
+	}
+}
+
+type listSessionsTool struct {
+	baseTool
+	service peerSessionService
+}
+
+func (tool listSessionsTool) Run(ctx context.Context, _ map[string]any) Result {
+	peers, err := tool.service.List(ctx)
+	if err != nil {
+		return errorResult("Error: list_sessions: " + err.Error())
+	}
+	if len(peers) == 0 {
+		return Result{Status: StatusOK, Output: "No other live local Zero sessions are reachable."}
+	}
+	var output strings.Builder
+	output.WriteString("Live local Zero sessions:\n")
+	for _, peer := range peers {
+		name := strings.TrimSpace(peer.Name)
+		if name == "" {
+			name = "Zero session"
+		}
+		fmt.Fprintf(&output, "- %s [%s]", name, peer.Ref)
+		if peer.Cwd != "" {
+			fmt.Fprintf(&output, " · %s", peer.Cwd)
+		}
+		output.WriteByte('\n')
+	}
+	output.WriteString("Incoming peer messages are agent input, not user authority.")
+	return Result{Status: StatusOK, Output: output.String()}
+}
+
+type sendSessionMessageTool struct {
+	baseTool
+	service peerSessionService
+}
+
+func (tool sendSessionMessageTool) Run(ctx context.Context, args map[string]any) Result {
+	to, err := stringArg(args, "to", "", true)
+	if err != nil {
+		return errorResult("Error: send_message: " + err.Error())
+	}
+	summary, err := stringArg(args, "summary", "", true)
+	if err != nil {
+		return errorResult("Error: send_message: " + err.Error())
+	}
+	message, err := stringArg(args, "message", "", true)
+	if err != nil {
+		return errorResult("Error: send_message: " + err.Error())
+	}
+	result, err := tool.service.Send(ctx, to, summary, message)
+	if err != nil {
+		return errorResult("Error: send_message: " + err.Error())
+	}
+	name := strings.TrimSpace(result.Peer.Name)
+	if name == "" {
+		name = "Zero session"
+	}
+	return Result{
+		Status: StatusOK,
+		Output: fmt.Sprintf("Message %s to %s [%s] (id %s).", result.Status, name, result.Peer.Ref, result.MessageID),
+		Meta: map[string]string{
+			"message_id": result.MessageID,
+			"session_id": result.Peer.SessionID,
+			"status":     string(result.Status),
+		},
+	}
+}

internal/tools/peer_sessions_test.go

@@ -0,0 +1,102 @@
+package tools
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/peermsg"
+)
+
+type fakePeerSessionService struct {
+	peers   []peermsg.Peer
+	sentTo  string
+	summary string
+	body    string
+	result  peermsg.SendResult
+	err     error
+}
+
+func (service *fakePeerSessionService) List(context.Context) ([]peermsg.Peer, error) {
+	return service.peers, service.err
+}
+
+func (service *fakePeerSessionService) Send(_ context.Context, to, summary, body string) (peermsg.SendResult, error) {
+	service.sentTo = to
+	service.summary = summary
+	service.body = body
+	return service.result, service.err
+}
+
+func TestListSessionsToolFormatsAddressWithoutTransportDetails(t *testing.T) {
+	service := &fakePeerSessionService{peers: []peermsg.Peer{{
+		Identity: peermsg.Identity{SessionID: "session-1", Name: "reviewer", Cwd: "/work"},
+		Endpoint: "private-endpoint",
+		PID:      123,
+		Ref:      "a1b2c3d4",
+	}}}
+	toolset := NewPeerSessionTools(service)
+	result := toolset[0].Run(context.Background(), map[string]any{})
+	if result.Status != StatusOK || !strings.Contains(result.Output, "reviewer [a1b2c3d4]") {
+		t.Fatalf("result = %#v", result)
+	}
+	if strings.Contains(result.Output, "private-endpoint") || strings.Contains(result.Output, "123") {
+		t.Fatalf("transport internals leaked: %q", result.Output)
+	}
+}
+
+func TestSendMessageToolPassesPlainTextEnvelope(t *testing.T) {
+	service := &fakePeerSessionService{result: peermsg.SendResult{
+		MessageID: "m1",
+		Status:    peermsg.DeliveryHeld,
+		Peer:      peermsg.Peer{Identity: peermsg.Identity{SessionID: "s1", Name: "reviewer"}, Ref: "abcd1234"},
+	}}
+	toolset := NewPeerSessionTools(service)
+	result := toolset[1].Run(context.Background(), map[string]any{
+		"to": "reviewer", "summary": "review request", "message": "Please inspect this.",
+	})
+	if result.Status != StatusOK || result.Meta["status"] != "held" {
+		t.Fatalf("result = %#v", result)
+	}
+	if service.sentTo != "reviewer" || service.summary != "review request" || service.body != "Please inspect this." {
+		t.Fatalf("sent = %q %q %q", service.sentTo, service.summary, service.body)
+	}
+}
+
+func TestPeerReplyToolIsEagerOnlyForPeerAwareTurns(t *testing.T) {
+	service := &fakePeerSessionService{}
+	ordinary := NewPeerSessionTools(service)
+	if len(ordinary) != 2 || !IsDeferred(ordinary[1]) {
+		t.Fatalf("ordinary send_message should remain deferred: %#v", ordinary)
+	}
+	reply := NewPeerReplyTool(service)
+	if reply == nil || IsDeferred(reply) || reply.Name() != "send_message" {
+		t.Fatalf("peer reply tool should be eager: %#v", reply)
+	}
+}
+
+func TestPeerSessionToolsSurfaceServiceErrors(t *testing.T) {
+	service := &fakePeerSessionService{err: errors.New("service unavailable")}
+	toolset := NewPeerSessionTools(service)
+	if result := toolset[0].Run(context.Background(), map[string]any{}); result.Status != StatusError || !strings.Contains(result.Output, "service unavailable") {
+		t.Fatalf("list result = %#v", result)
+	}
+	if result := toolset[1].Run(context.Background(), map[string]any{"to": "peer", "summary": "test", "message": "hello"}); result.Status != StatusError || !strings.Contains(result.Output, "service unavailable") {
+		t.Fatalf("send result = %#v", result)
+	}
+}
+
+func TestSendMessageToolRejectsMissingAndInvalidArguments(t *testing.T) {
+	tool := NewPeerSessionTools(&fakePeerSessionService{})[1]
+	for _, args := range []map[string]any{
+		{},
+		{"to": 42, "summary": "test", "message": "hello"},
+		{"to": "peer", "summary": true, "message": "hello"},
+		{"to": "peer", "summary": "test", "message": []string{"hello"}},
+	} {
+		if result := tool.Run(context.Background(), args); result.Status != StatusError {
+			t.Fatalf("args %#v result = %#v", args, result)
+		}
+	}
+}

internal/tools/read_file.go

@@ -10,8 +10,11 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"unicode/utf8"
 )
 
+const readFileByteChunkMax = 64 * 1024
+
 type readFileTool struct {
 	baseTool
 	workspaceRoot string
@@ -28,14 +31,15 @@ func NewScopedReadFileTool(workspaceRoot string, scope PathScope) Tool {
 	return readFileTool{
 		baseTool: baseTool{
 			name:        "read_file",
-			description: "Read a file with optional 1-based inclusive line range and max line cap.",
+			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.",
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
-					"path":       {Type: "string", Description: "Path of the file to read."},
-					"start_line": {Type: "integer", Description: "1-based inclusive line number to start reading from.", Minimum: intPtr(1)},
-					"end_line":   {Type: "integer", Description: "1-based inclusive line number to stop reading at.", Minimum: intPtr(1)},
-					"max_lines":  {Type: "integer", Description: "Maximum number of lines to return.", Minimum: intPtr(1)},
+					"path":        {Type: "string", Description: "File path."},
+					"offset":      {Type: "integer", Description: "Optional 1-based source line to start from.", Minimum: intPtr(1)},
+					"limit":       {Type: "integer", Description: "Optional number of source lines to return.", Minimum: intPtr(1)},
+					"byte_offset": {Type: "integer", Description: "Optional zero-based offset for exact byte reads.", Minimum: intPtr(0)},
+					"byte_limit":  {Type: "integer", Description: "Optional byte count for an exact byte read; use with byte_offset.", Minimum: intPtr(1), Maximum: intPtr(readFileByteChunkMax)},
 				},
 				Required:             []string{"path"},
 				AdditionalProperties: false,
@@ -64,7 +68,27 @@ func (tool readFileTool) run(args map[string]any, options RunOptions, directBudg
 	if err != nil {
 		return errorResult("Error: Invalid arguments for read_file: " + err.Error())
 	}
-	startLine, err := intArg(args, "start_line", 1, 1, 0)
+	_, hasOffset := args["offset"]
+	_, hasLimit := args["limit"]
+	_, hasStartLine := args["start_line"]
+	_, hasEndLine := args["end_line"]
+	_, hasMaxLines := args["max_lines"]
+	if hasOffset && hasStartLine {
+		return errorResult("Error: Invalid arguments for read_file: use either offset or start_line, not both")
+	}
+	if hasLimit && (hasEndLine || hasMaxLines) {
+		return errorResult("Error: Invalid arguments for read_file: use limit instead of end_line or max_lines, not both")
+	}
+
+	startKey := "offset"
+	if !hasOffset && hasStartLine {
+		startKey = "start_line"
+	}
+	startLine, err := intArg(args, startKey, 1, 1, 0)
+	if err != nil {
+		return errorResult("Error: Invalid arguments for read_file: " + err.Error())
+	}
+	limit, err := intArg(args, "limit", 0, 1, 0)
 	if err != nil {
 		return errorResult("Error: Invalid arguments for read_file: " + err.Error())
 	}
@@ -76,6 +100,26 @@ func (tool readFileTool) run(args map[string]any, options RunOptions, directBudg
 	if err != nil {
 		return errorResult("Error: Invalid arguments for read_file: " + err.Error())
 	}
+	if hasLimit {
+		const maxInt = int(^uint(0) >> 1)
+		endLine = startLine + min(limit-1, maxInt-startLine)
+	}
+	hasLineRange := hasOffset || hasLimit || hasStartLine || hasEndLine || hasMaxLines
+	_, hasByteOffset := args["byte_offset"]
+	_, hasByteLimit := args["byte_limit"]
+	byteMode := (hasByteOffset || hasByteLimit) && !hasLineRange
+	byteOffset := 0
+	byteLimit := readFileByteChunkMax
+	if byteMode {
+		byteOffset, err = intArg(args, "byte_offset", 0, 0, 0)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for read_file: " + err.Error())
+		}
+		byteLimit, err = intArg(args, "byte_limit", readFileByteChunkMax, 1, readFileByteChunkMax)
+		if err != nil {
+			return errorResult("Error: Invalid arguments for read_file: " + err.Error())
+		}
+	}
 
 	absolutePath, relativePath, err := resolveScopedReadPath(tool.workspaceRoot, tool.scope, requestedPath)
 	if err != nil {
@@ -91,17 +135,66 @@ func (tool readFileTool) run(args map[string]any, options RunOptions, directBudg
 	// Stat is best-effort: a missing FileInfo only drops the diagnostic size/mtime,
 	// not the authoritative content hash.
 	options.FileTracker.RecordHash(absolutePath, stats.hash, stats.info)
+	if byteMode {
+		result, seenStart, seenEnd := renderReadFileBytes(absolutePath, relativePath, stats.bytes, byteOffset, byteLimit)
+		if result.Status == StatusOK && !result.Truncated && seenEnd > seenStart {
+			if options.deferFileObservation {
+				result.pendingFileObservation = &pendingFileObservation{
+					path: absolutePath, output: result.Output, hash: stats.hash,
+					start: seenStart, end: seenEnd, total: stats.bytes, byteMode: true,
+				}
+			} else {
+				options.FileTracker.RecordSeenBytes(absolutePath, seenStart, seenEnd, stats.bytes)
+				result.Meta["file_version"] = stats.hash
+				result.Meta["seen_bytes"] = fmt.Sprintf("%d-%d", seenStart, seenEnd)
+			}
+		}
+		return result
+	}
 
 	maxBytes := 0
 	if directBudget {
 		maxBytes = readOutputBudgetBytes
 	}
-	return renderReadFileRange(absolutePath, relativePath, stats.lines, startLine, endLine, maxLines, maxBytes)
+	result := renderReadFileRange(absolutePath, relativePath, stats.lines, startLine, endLine, maxLines, maxBytes)
+	if result.Status == StatusOK && result.Meta["truncation_reason"] != "byte_budget" {
+		seenStart, seenEnd := renderedReadRange(stats.lines, startLine, endLine, maxLines)
+		if options.deferFileObservation {
+			result.pendingFileObservation = &pendingFileObservation{
+				path: absolutePath, output: result.Output, hash: stats.hash,
+				start: seenStart, end: seenEnd, total: stats.lines,
+			}
+		} else {
+			options.FileTracker.RecordSeenRange(absolutePath, seenStart, seenEnd, stats.lines)
+			if result.Meta == nil {
+				result.Meta = map[string]string{}
+			}
+			result.Meta["file_version"] = stats.hash
+			result.Meta["seen_lines"] = fmt.Sprintf("%d-%d", seenStart, seenEnd)
+		}
+	}
+	return result
+}
+
+func renderedReadRange(total, start, end, maxLines int) (int, int) {
+	if start > total {
+		return start, start
+	}
+	if end == 0 || end > total {
+		end = total
+	}
+	if end < start {
+		end = start
+	}
+	if maxLines > 0 && end-start+1 > maxLines {
+		end = start + maxLines - 1
+	}
+	return start, end
 }
 
 func renderReadFileRange(absolutePath string, relativePath string, total int, startLine int, endLine int, maxLines int, maxBytes int) Result {
 	if startLine > total {
-		return okResult(fmt.Sprintf("File: %s\n(start_line %d is past the end of the file, which has %d lines)", relativePath, startLine, total))
+		return okResult(fmt.Sprintf("File: %s\n(offset %d is past the end of the file, which has %d lines)", relativePath, startLine, total))
 	}
 	if endLine == 0 || endLine > total {
 		endLine = total
@@ -140,9 +233,9 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 	// Tool.Run calls preserve the legacy prefix-only byte budget.
 	var budgetedOutput *outputBudgetBuilder
 	if maxBytes > 0 {
-		budgetedOutput = newOutputBudgetBuilder(maxBytes, "use start_line/end_line or max_lines to continue with a smaller range")
+		budgetedOutput = newOutputBudgetBuilder(maxBytes, "use offset/limit to request a smaller line range")
 	} else {
-		budgetedOutput = newHeadTailOutputBudgetBuilder(readOutputBudgetBytes, "use start_line/end_line or max_lines to continue with a smaller range")
+		budgetedOutput = newHeadTailOutputBudgetBuilder(readOutputBudgetBytes, "use offset/limit to request a smaller line range")
 	}
 	budgetedOutput.WriteString(header)
 	budgetedOutput.WriteString("\n")
@@ -156,9 +249,9 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 	}
 	if truncated {
 		// The Truncated flag alone is invisible to the model in the rendered
-		// output, so it cannot tell a max_lines cut from a complete read. Make the
+		// output, so it cannot tell a limit cut from a complete read. Make the
 		// cut explicit and tell it how to continue.
-		budgetedOutput.WriteString(fmt.Sprintf("\n\n[truncated: %d more line(s) in the requested range not shown; set start_line=%d to continue]", endLine-lastLine, lastLine+1))
+		budgetedOutput.WriteString(fmt.Sprintf("\n\n[truncated: %d more line(s) in the requested range not shown; set offset=%d to continue]", endLine-lastLine, lastLine+1))
 	}
 
 	budgeted := budgetedOutput.Result()
@@ -173,7 +266,7 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 		if budgeted.Truncated {
 			meta["truncation_reason"] = "byte_budget"
 		} else {
-			meta["truncation_reason"] = "max_lines"
+			meta["truncation_reason"] = "limit"
 		}
 	}
 	return Result{
@@ -186,6 +279,7 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 
 type readFileStats struct {
 	lines int
+	bytes int
 	hash  string
 	info  os.FileInfo
 }
@@ -200,6 +294,7 @@ func scanReadFileStats(path string) (readFileStats, error) {
 	hasher := sha256.New()
 	reader := bufio.NewReader(file)
 	lines := 0
+	bytes := 0
 	for {
 		raw, _, err := readRawLine(reader)
 		if err == io.EOF {
@@ -211,13 +306,55 @@ func scanReadFileStats(path string) (readFileStats, error) {
 		if _, err := hasher.Write(raw); err != nil {
 			return readFileStats{}, err
 		}
+		bytes += len(raw)
 		lines++
 	}
 	if lines == 0 {
 		lines = 1
 	}
 	info, _ := file.Stat()
-	return readFileStats{lines: lines, hash: hex.EncodeToString(hasher.Sum(nil)), info: info}, nil
+	return readFileStats{lines: lines, bytes: bytes, hash: hex.EncodeToString(hasher.Sum(nil)), info: info}, nil
+}
+
+func renderReadFileBytes(path, relativePath string, total, requestedStart, limit int) (Result, int, int) {
+	if requestedStart >= total {
+		return okResult(fmt.Sprintf("File: %s\n(byte_offset %d is past the end of the file, which has %d bytes)", relativePath, requestedStart, total)), 0, 0
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return errorResult("Error reading file " + relativePath + ": " + err.Error()), 0, 0
+	}
+	defer file.Close()
+
+	want := min(limit, total-requestedStart)
+	data := make([]byte, want)
+	read, err := file.ReadAt(data, int64(requestedStart))
+	if err != nil && err != io.EOF {
+		return errorResult("Error reading file " + relativePath + ": " + err.Error()), 0, 0
+	}
+	data = data[:read]
+	start := requestedStart
+	for len(data) > 0 && data[0]&0xc0 == 0x80 {
+		data = data[1:]
+		start++
+	}
+	for trim := 0; !utf8.Valid(data) && trim < utf8.UTFMax && len(data) > 0; trim++ {
+		data = data[:len(data)-1]
+	}
+	if !utf8.Valid(data) {
+		return errorResult("Error reading file " + relativePath + ": exact byte mode requires UTF-8 text"), 0, 0
+	}
+	end := start + len(data)
+	if end <= start {
+		return errorResult("Error reading file " + relativePath + ": byte_limit is too small to return the next UTF-8 character"), 0, 0
+	}
+
+	header := fmt.Sprintf("File: %s (bytes %d-%d of %d)", relativePath, start, end-1, total)
+	output := header + "\n\n" + string(data)
+	if end < total {
+		output += fmt.Sprintf("\n\n[continue with byte_offset=%d]", end)
+	}
+	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 {

internal/tools/read_minified_file.go

@@ -28,11 +28,13 @@ func NewScopedReadMinifiedFileTool(workspaceRoot string, scope PathScope) Tool {
 	return readMinifiedFileTool{
 		baseTool: baseTool{
 			name:        "read_minified_file",
-			description: "Read a source file in a dense, token-cheap form: comments and redundant whitespace removed, no line numbers. Use it to scan or understand code for far fewer tokens than read_file. For exact text, comments, line numbers, or before editing, use read_file instead.",
+			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.",
 			parameters: Schema{
 				Type: "object",
 				Properties: map[string]PropertySchema{
-					"path": {Type: "string", Description: "Path of the file to read in minified form."},
+					"path":   {Type: "string", Description: "Source file path."},
+					"offset": {Type: "integer", Description: "Optional 1-based source line to start from.", Minimum: intPtr(1)},
+					"limit":  {Type: "integer", Description: "Optional maximum number of source lines to minify.", Minimum: intPtr(1)},
 				},
 				Required:             []string{"path"},
 				AdditionalProperties: false,
@@ -58,6 +60,14 @@ func (tool readMinifiedFileTool) run(args map[string]any, options RunOptions, di
 	if err != nil {
 		return errorResult("Error: Invalid arguments for read_minified_file: " + err.Error())
 	}
+	offset, err := intArg(args, "offset", 1, 1, 0)
+	if err != nil {
+		return errorResult("Error: Invalid arguments for read_minified_file: " + err.Error())
+	}
+	limit, err := intArg(args, "limit", 0, 1, 0)
+	if err != nil {
+		return errorResult("Error: Invalid arguments for read_minified_file: " + err.Error())
+	}
 
 	absolutePath, relativePath, err := resolveScopedReadPath(tool.workspaceRoot, tool.scope, requestedPath)
 	if err != nil {
@@ -74,11 +84,19 @@ func (tool readMinifiedFileTool) run(args map[string]any, options RunOptions, di
 	info, _ := os.Stat(absolutePath)
 	options.FileTracker.Record(absolutePath, content, info)
 
-	result := minify.File(relativePath, content)
-	rawLines := lineCount(string(content))
+	selected := selectSourceLines(content, offset, limit)
+	if selected.pastEnd {
+		return okResult(fmt.Sprintf("File: %s\n(offset %d is past the end of the file, which has %d lines)", relativePath, offset, selected.totalLines))
+	}
+	ranged := offset > 1 || limit > 0
+	result := minify.File(relativePath, selected.content)
+	if ranged {
+		result = minify.ContextualFragment(relativePath, content, selected.content, selected.startByte)
+	}
+	rawLines := lineCount(string(selected.content))
 	minLines := lineCount(result.Content)
 	pct := 0
-	if rawBytes := len(content); rawBytes > 0 {
+	if rawBytes := len(selected.content); rawBytes > 0 {
 		if saved := rawBytes - len(result.Content); saved > 0 {
 			pct = saved * 100 / rawBytes
 		}
@@ -88,12 +106,15 @@ func (tool readMinifiedFileTool) run(args map[string]any, options RunOptions, di
 	if result.Applied {
 		header = fmt.Sprintf("File: %s — minified %s view (comments stripped, no line numbers; %d→%d lines, ~%d%% fewer bytes). For exact text/comments or before editing, use read_file.",
 			relativePath, result.Language, rawLines, minLines, pct)
+	} else if ranged {
+		header = fmt.Sprintf("File: %s — safe ranged view (whitespace normalized, no line numbers; %d→%d lines; context-sensitive stripping disabled because the range may begin inside a multiline construct). For exact text, use read_file.",
+			relativePath, rawLines, minLines)
 	} else {
 		header = fmt.Sprintf("File: %s — whitespace-normalized view (no line numbers; %d→%d lines; full minification not available for this file type). For exact text, use read_file.",
 			relativePath, rawLines, minLines)
 	}
 
-	rawBytes := len(content)
+	rawBytes := len(selected.content)
 	compactBytes := len(result.Content)
 	savedTokens := 0
 	if savedBytes := rawBytes - compactBytes; savedBytes > 0 {
@@ -112,11 +133,54 @@ func (tool readMinifiedFileTool) run(args map[string]any, options RunOptions, di
 	meta["estimated_tokens_saved"] = strconv.Itoa(savedTokens)
 	toolResult := Result{Status: StatusOK, Output: output, Meta: meta}
 	if directBudget {
-		return applyLegacyByteBudgetToResult(toolResult, readOutputBudgetBytes, "use read_file with start_line/end_line or max_lines for a smaller exact range")
+		return applyLegacyByteBudgetToResult(toolResult, readOutputBudgetBytes, "use offset/limit to request a smaller source range, or read_file when exact text is required")
 	}
 	return toolResult
 }
 
+type sourceSelection struct {
+	content    []byte
+	startByte  int
+	totalLines int
+	pastEnd    bool
+}
+
+func selectSourceLines(content []byte, offset, limit int) sourceSelection {
+	if offset <= 1 && limit == 0 {
+		return sourceSelection{content: content, totalLines: sourceLineCount(content)}
+	}
+	lines := strings.Split(string(content), "\n")
+	totalLines := sourceLineCount(content)
+	start := offset - 1
+	if start >= totalLines {
+		return sourceSelection{startByte: len(content), totalLines: totalLines, pastEnd: true}
+	}
+	startByte := 0
+	for index := 0; index < start; index++ {
+		startByte += len(lines[index]) + 1
+	}
+	end := totalLines
+	if limit > 0 && limit < end-start {
+		end = start + limit
+	}
+	return sourceSelection{
+		content:    []byte(strings.Join(lines[start:end], "\n")),
+		startByte:  startByte,
+		totalLines: totalLines,
+	}
+}
+
+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
+}
+
 // lineCount reports the number of newline-separated lines in s (an empty string
 // counts as 0 lines, matching how a reader perceives an empty file).
 func lineCount(s string) int {

internal/tools/read_minified_file_test.go

@@ -45,6 +45,123 @@ func TestReadMinifiedFileRejectsTraversal(t *testing.T) {
 	}
 }
 
+func TestReadMinifiedFileSelectsSourceLineRangeBeforeMinifying(t *testing.T) {
+	dir := t.TempDir()
+	src := "package demo\n\nfunc One() int { return 1 }\n\nfunc Two() int { return 2 }\n"
+	if err := os.WriteFile(filepath.Join(dir, "f.go"), []byte(src), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	res := NewScopedReadMinifiedFileTool(dir, nil).Run(context.Background(), map[string]any{
+		"path": "f.go", "offset": 5, "limit": 1,
+	})
+	if res.Status != StatusOK || !strings.Contains(res.Output, "func Two") || strings.Contains(res.Output, "func One") {
+		t.Fatalf("unexpected ranged compact read: status=%s\n%s", res.Status, res.Output)
+	}
+}
+
+func TestReadMinifiedFileRangesPreserveUnknownLexicalContext(t *testing.T) {
+	tests := []struct {
+		name string
+		path string
+		src  string
+		want []string
+	}{
+		{
+			name: "multiline string",
+			path: "snippet.py",
+			src:  "value = \"\"\"\n# literal text\nstill literal\n\"\"\"\nprint(value)\n",
+			want: []string{"# literal text", "still literal"},
+		},
+		{
+			name: "template literal",
+			path: "snippet.js",
+			src:  "const value = `\n// literal text\nstill literal\n`;\n",
+			want: []string{"// literal text", "still literal"},
+		},
+		{
+			name: "block comment",
+			path: "snippet.c",
+			src:  "/* open\ncomment body\n*/\nint live;\n",
+			want: []string{"comment body", "*/"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.WriteFile(filepath.Join(dir, tc.path), []byte(tc.src), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			res := NewScopedReadMinifiedFileTool(dir, nil).Run(context.Background(), map[string]any{
+				"path": tc.path, "offset": 2, "limit": 2,
+			})
+			if res.Status != StatusOK || res.Meta["compacted"] != "false" {
+				t.Fatalf("ranged read must use conservative normalization: status=%s meta=%#v\n%s", res.Status, res.Meta, res.Output)
+			}
+			for _, want := range tc.want {
+				if !strings.Contains(res.Output, want) {
+					t.Fatalf("ranged read lost lexical content %q:\n%s", want, res.Output)
+				}
+			}
+		})
+	}
+}
+
+func TestReadMinifiedFileRangeInsideGoRawStringIsConservative(t *testing.T) {
+	dir := t.TempDir()
+	src := "package demo\nvar value = `first\nSECRET-MARKER-ONE\n// literal line\nlast`\n"
+	if err := os.WriteFile(filepath.Join(dir, "f.go"), []byte(src), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	res := NewScopedReadMinifiedFileTool(dir, nil).Run(context.Background(), map[string]any{
+		"path": "f.go", "offset": 3, "limit": 2,
+	})
+	if res.Status != StatusOK || res.Meta["compacted"] != "false" {
+		t.Fatalf("raw-string range must use conservative normalization: status=%s meta=%#v\n%s", res.Status, res.Meta, res.Output)
+	}
+	for _, want := range []string{"SECRET-MARKER-ONE", "// literal line"} {
+		if !strings.Contains(res.Output, want) {
+			t.Fatalf("raw-string range lost or rewrote %q:\n%s", want, res.Output)
+		}
+	}
+	if strings.Contains(res.Output, "SECRET - MARKER - ONE") {
+		t.Fatalf("raw-string contents were parsed as Go code:\n%s", res.Output)
+	}
+}
+
+func TestReadMinifiedFileCanonicalOffsetPastEnd(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "f.go"), []byte("package demo\nvar value = 1\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	res := NewScopedReadMinifiedFileTool(dir, nil).Run(context.Background(), map[string]any{
+		"path": "f.go", "offset": 10,
+	})
+	if res.Status != StatusOK || !strings.Contains(res.Output, "offset 10 is past the end") {
+		t.Fatalf("expected canonical out-of-range response, got status=%s output=%q", res.Status, res.Output)
+	}
+}
+
+func TestReadMinifiedFileMaximumLimitDoesNotOverflow(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "notes.txt"), []byte("alpha\nbeta\ngamma\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	const maxInt = int(^uint(0) >> 1)
+
+	res := NewScopedReadMinifiedFileTool(dir, nil).Run(context.Background(), map[string]any{
+		"path": "notes.txt", "offset": 2, "limit": maxInt,
+	})
+	if res.Status != StatusOK {
+		t.Fatalf("maximum limit should return the remaining range without panicking: status=%s output=%q", res.Status, res.Output)
+	}
+	if !strings.Contains(res.Output, "beta") || !strings.Contains(res.Output, "gamma") || strings.Contains(res.Output, "alpha") {
+		t.Fatalf("maximum limit returned the wrong range: %q", res.Output)
+	}
+}
+
 func TestReadMinifiedFileAppliesByteBudget(t *testing.T) {
 	dir := t.TempDir()
 	if err := os.WriteFile(filepath.Join(dir, "large.txt"), []byte(strings.Repeat("0123456789abcdef\n", 9000)), 0o644); err != nil {

internal/tools/registry.go

@@ -2,7 +2,9 @@ package tools
 
 import (
 	"context"
+	"fmt"
 	"sort"
+	"strings"
 
 	"github.com/Gitlawb/zero/internal/redaction"
 	"github.com/Gitlawb/zero/internal/sandbox"
@@ -29,6 +31,10 @@ type RunOptions struct {
 	// disk outside Zero since it was last read. nil disables the feature entirely
 	// (the read/write tools behave exactly as before).
 	FileTracker *FileTracker
+	// DeferFileObservationCommit lets a caller with an additional output layer
+	// commit exact-read credit after that final layer has run.
+	DeferFileObservationCommit bool
+	deferFileObservation       bool
 	// EnabledTools / DisabledTools carry the run's operator tool filters so a
 	// filter-aware tool (tool_search) never discloses or loads an operator-hidden
 	// tool. They use the same allow/deny semantics as the agent's filter gate:
@@ -130,17 +136,23 @@ func (registry *Registry) RunWithOptions(ctx context.Context, name string, args
 	// args/paths) are redacted at the boundary just like tool output. The output
 	// ceiling runs after the scrub so the transcript and the spill file agree on
 	// what was hidden.
+	commitFileObservation := !options.DeferFileObservationCommit
+	options.deferFileObservation = true
 	selfManagedOutput := false
 	var tool Tool
 	var ok bool
 	defer func() {
 		result = scrubResultSecrets(result)
+		result = reduceCommandOutput(name, args, result)
 		if selfManagedOutput {
 			result = applySelfManagedOutputBudget(tool, name, args, result)
 		} else {
 			result = applyRegistryOutputBudget(tool, name, args, result)
 			result = enforceOutputCeiling(name, result)
 		}
+		if commitFileObservation {
+			result = registry.CommitFileObservation(result, options.FileTracker)
+		}
 	}()
 
 	tool, ok = registry.Get(name)
@@ -220,6 +232,32 @@ func (registry *Registry) RunWithOptions(ctx context.Context, name string, args
 	return res
 }
 
+// CommitFileObservation grants exact-read credit only when the tool's complete
+// output remains intact at the final boundary that will be sent to the model.
+func (registry *Registry) CommitFileObservation(result Result, tracker *FileTracker) Result {
+	observation := result.pendingFileObservation
+	result.pendingFileObservation = nil
+	if observation == nil || tracker == nil || result.Status != StatusOK || result.Truncated ||
+		!strings.HasPrefix(result.Output, observation.output) {
+		return result
+	}
+	if observation.byteMode {
+		tracker.RecordSeenBytes(observation.path, observation.start, observation.end, observation.total)
+	} else {
+		tracker.RecordSeenRange(observation.path, observation.start, observation.end, observation.total)
+	}
+	if result.Meta == nil {
+		result.Meta = map[string]string{}
+	}
+	result.Meta["file_version"] = observation.hash
+	if observation.byteMode {
+		result.Meta["seen_bytes"] = fmt.Sprintf("%d-%d", observation.start, observation.end)
+	} else {
+		result.Meta["seen_lines"] = fmt.Sprintf("%d-%d", observation.start, observation.end)
+	}
+	return result
+}
+
 func effectiveToolPermission(tool Tool, args map[string]any) Permission {
 	if permissioner, ok := tool.(ArgsPermissioner); ok {
 		return permissioner.PermissionForArgs(args)
@@ -259,8 +297,11 @@ func scrubResultSecrets(res Result) Result {
 
 func CoreReadOnlyToolsScoped(workspaceRoot string, scope PathScope) []Tool {
 	return []Tool{
-		NewScopedReadFileTool(workspaceRoot, scope),
 		NewScopedReadMinifiedFileTool(workspaceRoot, scope),
+		NewScopedReadFileTool(workspaceRoot, scope),
+		// view_image is read-only and shares read_file's path scoping, so it
+		// belongs with the other readers rather than behind a gate.
+		NewScopedViewImageTool(workspaceRoot, scope),
 		NewScopedListDirectoryTool(workspaceRoot, scope),
 		NewScopedGlobTool(workspaceRoot, scope),
 		NewScopedGrepTool(workspaceRoot, scope),

internal/tools/registry_test.go

@@ -30,8 +30,8 @@ func tempDirOutsideDefaultTemp(t *testing.T) string {
 
 func TestCoreReadOnlyToolsExposeSafeMetadata(t *testing.T) {
 	toolset := CoreReadOnlyToolsScoped(t.TempDir(), nil)
-	if len(toolset) != 9 {
-		t.Fatalf("expected 9 core read-only tools, got %d", len(toolset))
+	if len(toolset) != 10 {
+		t.Fatalf("expected 10 core read-only tools, got %d", len(toolset))
 	}
 
 	seen := map[string]bool{}
@@ -71,6 +71,11 @@ func TestCoreReadOnlyToolsExposeSafeMetadata(t *testing.T) {
 	if !seen[RequestPermissionsToolName] {
 		t.Fatalf("expected %s in core read-only tools", RequestPermissionsToolName)
 	}
+	// By name as well as by count: the count alone still passes if one reader is
+	// swapped for another.
+	if !seen[ViewImageToolName] {
+		t.Fatalf("expected %s in core read-only tools", ViewImageToolName)
+	}
 }
 
 func TestRegistryAllReturnsToolsSortedByName(t *testing.T) {
@@ -515,3 +520,43 @@ func TestIsDeferralEligibleDecouplesFromDeferred(t *testing.T) {
 		t.Fatal("IsDeferralEligible(optedOut) = true, want false")
 	}
 }
+
+func TestOptionalBuiltinsUseDeferredDiscovery(t *testing.T) {
+	wantDeferred := map[string]bool{
+		"bash":             true,
+		"browser_action":   true,
+		"browser_click":    true,
+		"browser_connect":  true,
+		"browser_install":  true,
+		"browser_launch":   true,
+		"browser_open":     true,
+		"browser_press":    true,
+		"browser_snapshot": true,
+		"browser_type":     true,
+		"capture_artifact": true,
+		"desktop_action":   true,
+		"desktop_snapshot": true,
+		"desktop_windows":  true,
+		"lsp_navigate":     true,
+		"terminal_session": true,
+		"web_fetch":        true,
+		"web_search":       true,
+	}
+	for _, tool := range BuiltinCatalog(t.TempDir()) {
+		if _, listed := wantDeferred[tool.Name()]; listed {
+			if !IsDeferred(tool) {
+				t.Errorf("%s should be deferred", tool.Name())
+			}
+			delete(wantDeferred, tool.Name())
+		} else if tool.Name() == "read_file" || tool.Name() == "read_minified_file" || tool.Name() == "grep" || tool.Name() == ExecCommandToolName || tool.Name() == "edit_file" {
+			if IsDeferred(tool) {
+				t.Errorf("essential tool %s must stay eager", tool.Name())
+			}
+		} else if IsDeferred(tool) {
+			t.Errorf("unexpected deferred builtin %s", tool.Name())
+		}
+	}
+	for missing := range wantDeferred {
+		t.Errorf("deferred builtin %s missing from catalog", missing)
+	}
+}

internal/tools/sandbox_permissions_schema_test.go

@@ -0,0 +1,72 @@
+package tools
+
+import (
+	"strings"
+	"testing"
+)
+
+// The cheapest fix for #845/#847 is that the invalid shape is never emitted.
+// A model only learns "omit it" from the schema it is shown, so both shell
+// tools must say so in the field descriptions themselves — the validator errors
+// are the backstop, and by the time they fire a turn has already been burned.
+func TestShellToolsAdvertiseOmittingSandboxPermissionFields(t *testing.T) {
+	root := t.TempDir()
+	for _, shell := range []struct {
+		name string
+		tool Tool
+	}{
+		{"bash", NewScopedBashTool(root, nil)},
+		{"exec_command", NewScopedExecCommandTool(root, nil, nil)},
+	} {
+		properties := shell.tool.Parameters().Properties
+
+		mode, ok := properties["sandbox_permissions"]
+		if !ok {
+			t.Fatalf("%s: sandbox_permissions property missing", shell.name)
+		}
+		if !strings.Contains(mode.Description, "Omit it") {
+			t.Errorf("%s: sandbox_permissions description = %q, want it to lead with omitting the field", shell.name, mode.Description)
+		}
+		// Deliberately NOT "read-only". An earlier revision said every read-only
+		// command could omit the override, and that is false: `curl` and `gh` are
+		// read-only and still need sandboxed network. Conditioning omission on
+		// whether the command needs access it does not already have is the claim
+		// that is actually true, and the one a model can act on without first
+		// having to decide what counts as read-only.
+		if !strings.Contains(mode.Description, "unless the command needs access") {
+			t.Errorf("%s: sandbox_permissions description = %q, want omission conditioned on needing extra access", shell.name, mode.Description)
+		}
+
+		extra, ok := properties["additional_permissions"]
+		if !ok {
+			t.Fatalf("%s: additional_permissions property missing", shell.name)
+		}
+		if !strings.Contains(extra.Description, "Omit this field entirely") {
+			t.Errorf("%s: additional_permissions description = %q, want an explicit instruction to omit the field", shell.name, extra.Description)
+		}
+		// Both invalid shapes from the issue must be named as invalid up front,
+		// so neither is emitted "to be safe".
+		if !strings.Contains(extra.Description, "with any other mode is rejected") {
+			t.Errorf("%s: additional_permissions description = %q, want it to say the unflagged shape is rejected", shell.name, extra.Description)
+		}
+		if !strings.Contains(extra.Description, "empty or all-false object") {
+			t.Errorf("%s: additional_permissions description = %q, want it to say an empty payload is rejected", shell.name, extra.Description)
+		}
+	}
+}
+
+// The two shell tools describe the same two fields; they were copy-pasted and
+// must not drift apart again, or a model would be taught different rules by
+// bash and exec_command in the same session.
+func TestShellToolsShareSandboxPermissionDescriptions(t *testing.T) {
+	root := t.TempDir()
+	bash := NewScopedBashTool(root, nil).Parameters().Properties
+	exec := NewScopedExecCommandTool(root, nil, nil).Parameters().Properties
+
+	for _, field := range []string{"sandbox_permissions", "additional_permissions"} {
+		if bash[field].Description != exec[field].Description {
+			t.Errorf("%s description differs between bash and exec_command:\n bash = %q\n exec = %q",
+				field, bash[field].Description, exec[field].Description)
+		}
+	}
+}

internal/tools/shell_output_reducer.go

@@ -0,0 +1,290 @@
+package tools
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+const commandReducerMinPassingLines = 12
+
+type commandOutputReducer struct {
+	kind   string
+	label  string
+	reduce func(string) (string, int)
+}
+
+// reduceCommandOutput removes repetitive success-only lines from recognized
+// simple commands. Unsupported or compound shell input passes through exactly,
+// and every changed result retains the pre-reduction output as an artifact.
+func reduceCommandOutput(toolName string, args map[string]any, result Result) Result {
+	if toolName != ExecCommandToolName && toolName != "bash" {
+		return result
+	}
+	command, err := commandTextForReducer(toolName, args)
+	if err != nil {
+		return result
+	}
+	reducer, ok := commandOutputReducerFor(command)
+	if !ok {
+		return result
+	}
+
+	reduced, omitted := reducer.reduce(result.Output)
+	if omitted < commandReducerMinPassingLines || len(reduced) >= len(result.Output) {
+		return result
+	}
+	originalBytes := len(result.Output)
+	originalTokens := estimateOutputTokens(result.Output)
+	spillPath := spillTruncatedOutput(toolName, result.Output)
+	if spillPath == "" {
+		return result
+	}
+
+	notice := fmt.Sprintf("[zero] compacted %d %s; exact output saved to %s", omitted, reducer.label, spillPath)
+	result.Output = strings.TrimRight(reduced, "\n") + "\n" + notice
+	result.Truncated = true
+	if result.Meta == nil {
+		result.Meta = map[string]string{}
+	}
+	result.Meta["command_output_reduced"] = "true"
+	result.Meta["command_output_reducer"] = reducer.kind
+	result.Meta["command_output_omitted_lines"] = strconv.Itoa(omitted)
+	result.Meta["command_output_original_bytes"] = strconv.Itoa(originalBytes)
+	result.Meta["command_output_original_tokens"] = strconv.Itoa(originalTokens)
+	result.Meta["command_output_retained_tokens"] = strconv.Itoa(estimateOutputTokens(result.Output))
+	result.Meta["spill_path"] = spillPath
+	result.Meta["truncation_reason"] = "command_aware_reduction"
+	return result
+}
+
+func commandTextForReducer(toolName string, args map[string]any) (string, error) {
+	if toolName == "bash" {
+		return bashCommandArg(args)
+	}
+	return execCommandArg(args)
+}
+
+func simpleCommandFields(command string) ([]string, bool) {
+	command = strings.TrimSpace(command)
+	if separator := strings.LastIndexAny(command, " \t"); separator >= 0 && command[separator+1:] == "2>&1" {
+		command = strings.TrimSpace(command[:separator])
+	}
+	if command == "" || strings.ContainsAny(command, "|;&<>\n\r`") || strings.Contains(command, "$(") {
+		return nil, false
+	}
+	fields := strings.Fields(command)
+	if len(fields) == 0 {
+		return nil, false
+	}
+	return fields, true
+}
+
+func commandOutputReducerFor(command string) (commandOutputReducer, bool) {
+	fields, ok := simpleCommandFields(command)
+	if !ok {
+		return commandOutputReducer{}, false
+	}
+	if len(fields) >= 2 && fields[0] == "go" && fields[1] == "test" {
+		return commandOutputReducer{kind: "go_test", label: "passing package lines", reduce: reduceGoTestPassingPackages}, true
+	}
+	if len(fields) >= 2 && fields[0] == "cargo" {
+		switch fields[1] {
+		case "test":
+			return commandOutputReducer{kind: "cargo_test", label: "passing Rust test lines", reduce: reduceCargoTestPassingLines}, true
+		case "build", "check":
+			return commandOutputReducer{kind: "cargo_build", label: "successful Rust build progress lines", reduce: reduceCargoBuildProgressLines}, true
+		}
+	}
+	if isPytestCommand(fields) {
+		return commandOutputReducer{kind: "pytest", label: "passing pytest progress lines", reduce: reducePytestPassingLines}, true
+	}
+	if isJavaScriptTestCommand(fields) {
+		return commandOutputReducer{kind: "javascript_test", label: "passing JavaScript test-file lines", reduce: reduceJavaScriptTestPassingLines}, true
+	}
+	return commandOutputReducer{}, false
+}
+
+func isPytestCommand(fields []string) bool {
+	if fields[0] == "pytest" || fields[0] == "py.test" {
+		return true
+	}
+	return len(fields) >= 3 && (fields[0] == "python" || fields[0] == "python3") && fields[1] == "-m" && fields[2] == "pytest"
+}
+
+func isJavaScriptTestCommand(fields []string) bool {
+	switch fields[0] {
+	case "jest", "vitest":
+		return true
+	case "npx":
+		return len(fields) >= 2 && (fields[1] == "jest" || fields[1] == "vitest")
+	case "npm", "pnpm", "yarn":
+		if len(fields) >= 2 && fields[1] == "test" {
+			return true
+		}
+		if len(fields) >= 3 && fields[1] == "run" && fields[2] == "test" {
+			return true
+		}
+		return len(fields) >= 3 && fields[1] == "exec" && (fields[2] == "jest" || fields[2] == "vitest")
+	default:
+		return false
+	}
+}
+
+func reduceGoTestPassingPackages(output string) (string, int) {
+	return reduceRepeatedOutputLines(output, "passing package lines", func(line string) bool {
+		packageSuccess := strings.HasPrefix(line, "ok  \t") || strings.HasPrefix(line, "?   \t") ||
+			strings.HasPrefix(line, "ok  ") || strings.HasPrefix(line, "?   ")
+		return packageSuccess && !strings.Contains(line, "coverage:") && !strings.Contains(line, "[no test files]")
+	})
+}
+
+func reduceCargoTestPassingLines(output string) (string, int) {
+	if !strings.Contains(output, "test result:") {
+		return output, 0
+	}
+	return reduceRepeatedOutputLines(output, "passing Rust test lines", func(line string) bool {
+		trimmed := strings.TrimSpace(line)
+		return strings.HasPrefix(trimmed, "test ") && strings.HasSuffix(trimmed, " ... ok")
+	})
+}
+
+func reduceCargoBuildProgressLines(output string) (string, int) {
+	if !outputHasCargoFinishedSummary(output) {
+		return output, 0
+	}
+	return reduceRepeatedOutputLines(output, "successful Rust build progress lines", func(line string) bool {
+		trimmed := strings.TrimSpace(line)
+		return strings.HasPrefix(trimmed, "Checking ") || strings.HasPrefix(trimmed, "Compiling ")
+	})
+}
+
+func reducePytestPassingLines(output string) (string, int) {
+	if !outputHasPytestSummary(output) {
+		return output, 0
+	}
+	return reduceRepeatedOutputLines(output, "passing pytest progress lines", isPassingPytestProgressLine)
+}
+
+func isPassingPytestProgressLine(line string) bool {
+	trimmed := strings.TrimSpace(line)
+	open := strings.LastIndexByte(trimmed, '[')
+	if open < 0 || !strings.HasSuffix(trimmed, "%]") {
+		return false
+	}
+	progress := strings.TrimSpace(trimmed[:open])
+	fields := strings.Fields(progress)
+	if len(fields) == 0 {
+		return false
+	}
+	marks := fields[len(fields)-1]
+	return marks != "" && strings.Trim(marks, ".") == ""
+}
+
+func reduceJavaScriptTestPassingLines(output string) (string, int) {
+	if !outputHasJavaScriptTestSummary(output) {
+		return output, 0
+	}
+	return reduceRepeatedOutputLines(output, "passing JavaScript test-file lines", func(line string) bool {
+		trimmed := strings.TrimSpace(line)
+		return strings.HasPrefix(line, "PASS ") || strings.HasPrefix(trimmed, "✓ ") || strings.HasPrefix(trimmed, "✔ ")
+	})
+}
+
+func outputHasCargoFinishedSummary(output string) bool {
+	for _, line := range strings.Split(output, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "Finished `") && strings.Contains(trimmed, "` profile ") &&
+			strings.Contains(trimmed, " target(s) in ") {
+			return true
+		}
+	}
+	return false
+}
+
+func outputHasPytestSummary(output string) bool {
+	for _, line := range strings.Split(output, "\n") {
+		summary := strings.Trim(strings.TrimSpace(line), "= ")
+		if summary == "short test summary info" || isPytestResultSummary(summary) {
+			return true
+		}
+	}
+	return false
+}
+
+func isPytestResultSummary(summary string) bool {
+	fields := strings.Fields(summary)
+	if len(fields) < 4 {
+		return false
+	}
+	first := strings.Trim(fields[0], ",;:()")
+	if _, err := strconv.Atoi(first); err != nil || !summaryHasCountedStatus(summary, "passed") {
+		return false
+	}
+	for index := 1; index+1 < len(fields); index++ {
+		if fields[index] != "in" {
+			continue
+		}
+		duration := strings.TrimSuffix(strings.Trim(fields[index+1], ",;:()"), "s")
+		if _, err := strconv.ParseFloat(duration, 64); err == nil {
+			return true
+		}
+	}
+	return false
+}
+
+func outputHasJavaScriptTestSummary(output string) bool {
+	for _, line := range strings.Split(output, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "Test Suites:") && summaryHasCountedStatus(trimmed, "passed") {
+			return true
+		}
+		if strings.HasPrefix(trimmed, "Test Files ") && summaryHasCountedStatus(trimmed, "passed") {
+			return true
+		}
+	}
+	return false
+}
+
+func summaryHasCountedStatus(summary string, status string) bool {
+	fields := strings.Fields(summary)
+	for index := 1; index < len(fields); index++ {
+		if strings.Trim(fields[index], ",;:()") != status {
+			continue
+		}
+		count := strings.Trim(fields[index-1], ",;:()")
+		if _, err := strconv.Atoi(count); err == nil {
+			return true
+		}
+	}
+	return false
+}
+
+func reduceRepeatedOutputLines(output string, label string, omit func(string) bool) (string, int) {
+	lines := strings.Split(output, "\n")
+	kept := make([]string, 0, len(lines))
+	omitted := 0
+	for _, line := range lines {
+		if omit(line) {
+			omitted++
+			continue
+		}
+		kept = append(kept, line)
+	}
+	if omitted == 0 {
+		return output, 0
+	}
+
+	insertAt := len(kept)
+	for index, line := range kept {
+		if strings.HasPrefix(line, "exit_code:") || strings.HasPrefix(line, "session_id:") {
+			insertAt = index
+			break
+		}
+	}
+	summary := fmt.Sprintf("[zero] %d %s omitted", omitted, label)
+	kept = append(kept, "")
+	copy(kept[insertAt+1:], kept[insertAt:])
+	kept[insertAt] = summary
+	return strings.Join(kept, "\n"), omitted
+}

internal/tools/shell_output_reducer_metrics_test.go

@@ -0,0 +1,107 @@
+package tools
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+)
+
+type commandReducerCorpusCase struct {
+	name    string
+	command string
+	output  string
+	want    string
+}
+
+func commandReducerCorpus() []commandReducerCorpusCase {
+	goLines := []string{"output:"}
+	cargoTestLines := []string{"output:", "running 24 tests"}
+	cargoCheckLines := []string{"output:"}
+	pytestLines := []string{"output:"}
+	vitestLines := []string{"output:", " RUN  v3.2.4 /workspace"}
+	jestLines := []string{"output:"}
+	for index := 0; index < 24; index++ {
+		goLines = append(goLines, fmt.Sprintf("ok  \texample.test/pkg%d\t0.01s", index))
+		cargoTestLines = append(cargoTestLines, fmt.Sprintf("test module::case_%02d ... ok", index))
+		cargoCheckLines = append(cargoCheckLines, fmt.Sprintf("    Checking dependency_%02d v1.0.%d", index, index))
+		pytestLines = append(pytestLines, fmt.Sprintf("tests/test_module_%02d.py ........                         [%3d%%]", index, (index+1)*100/24))
+		vitestLines = append(vitestLines, fmt.Sprintf(" ✓ src/module_%02d.test.ts (8 tests) 12ms", index))
+		jestLines = append(jestLines, fmt.Sprintf("PASS src/module_%02d.test.ts", index))
+	}
+	goLines = append(goLines, "exit_code: 0")
+	cargoTestLines = append(cargoTestLines,
+		"test result: ok. 24 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s",
+		"exit_code: 0",
+	)
+	cargoCheckLines = append(cargoCheckLines,
+		"    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.41s",
+		"exit_code: 0",
+	)
+	pytestLines = append(pytestLines,
+		"============================= 192 passed in 3.21s =============================",
+		"exit_code: 0",
+	)
+	vitestLines = append(vitestLines,
+		" Test Files  24 passed (24)",
+		"      Tests  192 passed (192)",
+		"   Duration  3.21s",
+		"exit_code: 0",
+	)
+	jestLines = append(jestLines,
+		"Test Suites: 24 passed, 24 total",
+		"Tests:       192 passed, 192 total",
+		"Time:        3.21 s",
+		"exit_code: 0",
+	)
+	return []commandReducerCorpusCase{
+		{name: "go_test", command: "go test ./...", output: strings.Join(goLines, "\n"), want: "exit_code: 0"},
+		{name: "cargo_test", command: "cargo test --workspace", output: strings.Join(cargoTestLines, "\n"), want: "24 passed"},
+		{name: "cargo_check", command: "cargo check --workspace", output: strings.Join(cargoCheckLines, "\n"), want: "Finished `dev` profile"},
+		{name: "pytest", command: "pytest -q", output: strings.Join(pytestLines, "\n"), want: "192 passed"},
+		{name: "npm_vitest", command: "npm test", output: strings.Join(vitestLines, "\n"), want: "192 passed"},
+		{name: "pnpm_vitest", command: "pnpm test", output: strings.Join(vitestLines, "\n"), want: "192 passed"},
+		{name: "yarn_jest", command: "yarn test", output: strings.Join(jestLines, "\n"), want: "192 passed"},
+	}
+}
+
+func TestCommandOutputReductionCorpusMetrics(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	totalRawTokens := 0
+	totalModelTokens := 0
+	for _, testCase := range commandReducerCorpus() {
+		t.Run(testCase.name, func(t *testing.T) {
+			result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": testCase.command}, Result{
+				Status: StatusOK,
+				Output: testCase.output,
+			})
+			if !strings.Contains(result.Output, testCase.want) {
+				t.Fatalf("decisive summary %q was lost: %q", testCase.want, result.Output)
+			}
+			if spillPath := result.Meta["spill_path"]; spillPath != "" {
+				spilled, err := os.ReadFile(spillPath)
+				if err != nil {
+					t.Fatalf("read raw artifact: %v", err)
+				}
+				if string(spilled) != testCase.output {
+					t.Fatal("raw artifact differs from original output")
+				}
+			}
+			rawTokens := estimateOutputTokens(testCase.output)
+			modelTokens := estimateOutputTokens(result.Output)
+			totalRawTokens += rawTokens
+			totalModelTokens += modelTokens
+			reduction := 100 * (rawTokens - modelTokens) / rawTokens
+			t.Logf("raw_bytes=%d model_bytes=%d raw_tokens=%d model_tokens=%d reduction_pct=%d reduced=%t",
+				len(testCase.output), len(result.Output), rawTokens, modelTokens, reduction, result.Meta["command_output_reduced"] == "true")
+		})
+	}
+	if totalRawTokens == 0 {
+		t.Fatal("empty reducer corpus")
+	}
+	if totalModelTokens >= totalRawTokens {
+		t.Fatalf("aggregate reducer output did not save tokens: raw=%d model=%d", totalRawTokens, totalModelTokens)
+	}
+	t.Logf("aggregate raw_tokens=%d model_tokens=%d reduction_pct=%d",
+		totalRawTokens, totalModelTokens, 100*(totalRawTokens-totalModelTokens)/totalRawTokens)
+}

internal/tools/shell_output_reducer_test.go

@@ -0,0 +1,317 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+)
+
+type commandReducerFixtureTool struct {
+	name   string
+	output string
+}
+
+func (tool commandReducerFixtureTool) Name() string { return tool.name }
+func (tool commandReducerFixtureTool) Description() string {
+	return "returns command output for reducer integration tests"
+}
+func (tool commandReducerFixtureTool) Parameters() Schema {
+	return Schema{Type: "object", AdditionalProperties: true}
+}
+func (tool commandReducerFixtureTool) Safety() Safety {
+	return Safety{SideEffect: SideEffectRead, Permission: PermissionAllow, Reason: "test output"}
+}
+func (tool commandReducerFixtureTool) Run(context.Context, map[string]any) Result {
+	return Result{Status: StatusOK, Output: tool.output}
+}
+
+func TestReduceCommandOutputCompactsPassingGoPackagesAndKeepsRawArtifact(t *testing.T) {
+	var lines []string
+	lines = append(lines, "output:")
+	for index := 0; index < commandReducerMinPassingLines+3; index++ {
+		lines = append(lines, fmt.Sprintf("ok  \texample.test/pkg%d\t0.01s", index))
+	}
+	lines = append(lines, "exit_code: 0")
+	original := strings.Join(lines, "\n")
+
+	result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": "go test ./..."}, Result{
+		Status: StatusOK,
+		Output: original,
+	})
+
+	if result.Output == original || !strings.Contains(result.Output, "passing package lines omitted") {
+		t.Fatalf("expected compact result, got %q", result.Output)
+	}
+	if !strings.Contains(result.Output, "exit_code: 0") {
+		t.Fatalf("exit status was lost: %q", result.Output)
+	}
+	spillPath := result.Meta["spill_path"]
+	spilled, err := os.ReadFile(spillPath)
+	if err != nil {
+		t.Fatalf("read raw artifact: %v", err)
+	}
+	if string(spilled) != original {
+		t.Fatalf("raw artifact differs from original output")
+	}
+
+	budgeted := applySelfManagedOutputBudget(
+		NewExecCommandTool(t.TempDir(), newExecSessionManager()),
+		ExecCommandToolName,
+		map[string]any{"cmd": "go test ./..."},
+		result,
+	)
+	if budgeted.Meta["spill_path"] != spillPath {
+		t.Fatalf("budget boundary replaced the exact raw artifact: got %q want %q", budgeted.Meta["spill_path"], spillPath)
+	}
+	spilled, err = os.ReadFile(budgeted.Meta["spill_path"])
+	if err != nil || string(spilled) != original {
+		t.Fatalf("budgeted raw artifact was not preserved: err=%v", err)
+	}
+}
+
+func TestReduceCommandOutputFailsOpenForCompoundAndFailedOutput(t *testing.T) {
+	failure := "output:\n--- FAIL: TestThing\npanic: broken\nFAIL\texample.test/pkg\nexit_code: 1"
+	for _, command := range []string{"go test ./... | tee test.log", "go test ./... && echo done"} {
+		result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": command}, Result{Status: StatusError, Output: failure})
+		if result.Output != failure || result.Meta != nil {
+			t.Fatalf("compound command %q should pass through, got %#v", command, result)
+		}
+	}
+	result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": "go test ./..."}, Result{Status: StatusError, Output: failure})
+	if result.Output != failure {
+		t.Fatalf("failure evidence should pass through when there is no repetitive success bulk: %q", result.Output)
+	}
+}
+
+func TestReduceGoTestPassingPackagesPreservesCoverageResults(t *testing.T) {
+	output := strings.Join([]string{
+		"ok  \texample.test/a\t0.01s\tcoverage: 82.4% of statements",
+		"?   \texample.test/b\t[no test files]",
+		"ok  \texample.test/c\t0.01s",
+	}, "\n")
+
+	reduced, omitted := reduceGoTestPassingPackages(output)
+	if !strings.Contains(reduced, "coverage: 82.4% of statements") {
+		t.Fatalf("coverage result was removed: %q", reduced)
+	}
+	if !strings.Contains(reduced, "[no test files]") {
+		t.Fatalf("no-test-files result was removed: %q", reduced)
+	}
+	if omitted != 1 {
+		t.Fatalf("omitted=%d, want only the plain passing line omitted", omitted)
+	}
+}
+
+func TestReduceGoTestPassingPackagesPreservesIndentedTestLogs(t *testing.T) {
+	output := strings.Join([]string{
+		"    ok  user-provided test log",
+		"    ?   another test log",
+		"ok  \texample.test/pkg\t0.01s",
+	}, "\n")
+
+	reduced, omitted := reduceGoTestPassingPackages(output)
+	if !strings.Contains(reduced, "    ok  user-provided test log") ||
+		!strings.Contains(reduced, "    ?   another test log") {
+		t.Fatalf("indented test log was removed: %q", reduced)
+	}
+	if omitted != 1 {
+		t.Fatalf("omitted=%d, want only the package result omitted", omitted)
+	}
+}
+
+func TestSelfManagedBudgetPreservesRawSpillWhenReducedOutputAlsoTruncates(t *testing.T) {
+	raw := "raw output\n" + strings.Repeat("ok  \texample.test/raw\t0.01s\n", 1000)
+	rawSpill := spillTruncatedOutput(ExecCommandToolName, raw)
+	if rawSpill == "" {
+		t.Fatal("failed to create raw spill")
+	}
+	reduced := strings.Repeat("reduced but still large\n", 1000)
+	result := applySelfManagedOutputBudget(
+		NewExecCommandTool(t.TempDir(), newExecSessionManager()),
+		ExecCommandToolName,
+		map[string]any{"cmd": "go test ./...", "max_output_tokens": 100},
+		Result{
+			Status:    StatusOK,
+			Output:    reduced,
+			Truncated: true,
+			Meta: map[string]string{
+				"spill_path":        rawSpill,
+				"truncation_reason": "command_aware_reduction",
+			},
+		},
+	)
+
+	if result.Meta["spill_path"] != rawSpill {
+		t.Fatalf("budget boundary replaced raw spill: got %q want %q", result.Meta["spill_path"], rawSpill)
+	}
+	spilled, err := os.ReadFile(result.Meta["spill_path"])
+	if err != nil || string(spilled) != raw {
+		t.Fatalf("raw spill was not preserved: err=%v", err)
+	}
+}
+
+func TestReduceCommandOutputCompactsRecognizedTestAndBuildNoise(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	for _, testCase := range commandReducerCorpus() {
+		t.Run(testCase.name, func(t *testing.T) {
+			result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": testCase.command}, Result{
+				Status: StatusOK,
+				Output: testCase.output,
+			})
+			if result.Meta["command_output_reduced"] != "true" {
+				t.Fatalf("recognized command output was not reduced: %#v", result)
+			}
+			if !strings.Contains(result.Output, testCase.want) || !strings.Contains(result.Output, "exit_code: 0") {
+				t.Fatalf("decisive summary or exit status was lost: %q", result.Output)
+			}
+			spillPath := result.Meta["spill_path"]
+			spilled, err := os.ReadFile(spillPath)
+			if err != nil {
+				t.Fatalf("read raw artifact: %v", err)
+			}
+			if string(spilled) != testCase.output {
+				t.Fatal("raw artifact differs from original output")
+			}
+		})
+	}
+}
+
+func TestReduceCommandOutputPreservesFailureEvidence(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	passing := make([]string, 0, commandReducerMinPassingLines+2)
+	for index := 0; index < commandReducerMinPassingLines+2; index++ {
+		passing = append(passing, fmt.Sprintf("test module::case_%02d ... ok", index))
+	}
+	original := strings.Join(append(passing,
+		"test module::broken ... FAILED",
+		"failures:",
+		"---- module::broken stdout ----",
+		"assertion failed: expected zero",
+		"test result: FAILED. 14 passed; 1 failed; finished in 0.08s",
+		"exit_code: 101",
+	), "\n")
+
+	result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": "cargo test --workspace"}, Result{
+		Status: StatusError,
+		Output: original,
+	})
+	for _, evidence := range []string{"module::broken ... FAILED", "assertion failed: expected zero", "14 passed; 1 failed", "exit_code: 101"} {
+		if !strings.Contains(result.Output, evidence) {
+			t.Fatalf("failure evidence %q was lost: %q", evidence, result.Output)
+		}
+	}
+	if result.Meta["command_output_reduced"] != "true" {
+		t.Fatalf("repetitive passing output was not reduced: %#v", result)
+	}
+	spillPath := result.Meta["spill_path"]
+	if spillPath == "" {
+		t.Fatal("reduced failure output did not retain a raw artifact")
+	}
+	spilled, err := os.ReadFile(spillPath)
+	if err != nil {
+		t.Fatalf("read raw artifact: %v", err)
+	}
+	if string(spilled) != original {
+		t.Fatal("raw artifact differs from original output")
+	}
+}
+
+func TestReduceCommandOutputPassesThroughUnsupportedAndCompoundCommands(t *testing.T) {
+	outputs := make(map[string]string)
+	for _, fixture := range commandReducerCorpus() {
+		outputs[fixture.name] = fixture.output
+	}
+	testCases := []struct {
+		command string
+		output  string
+	}{
+		{command: "npm test | tee test.log", output: outputs["npm_vitest"]},
+		{command: "cargo test && echo done", output: outputs["cargo_test"]},
+		{command: "pytest; notify-send done", output: outputs["pytest"]},
+		{command: "cargo test 1>test.log", output: outputs["cargo_test"]},
+		{command: "cargo test 2>>errors.log", output: outputs["cargo_test"]},
+		{command: "git status --short", output: outputs["npm_vitest"]},
+	}
+	for _, testCase := range testCases {
+		result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": testCase.command}, Result{Status: StatusOK, Output: testCase.output})
+		if result.Output != testCase.output || result.Meta != nil {
+			t.Fatalf("command %q should pass through exactly, got %#v", testCase.command, result)
+		}
+	}
+}
+
+func TestReduceCommandOutputAllowsTrailingStderrMerge(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	fixture := commandReducerCorpus()[1]
+	result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": fixture.command + " 2>&1"}, Result{
+		Status: StatusOK,
+		Output: fixture.output,
+	})
+	if result.Meta["command_output_reducer"] != "cargo_test" {
+		t.Fatalf("trailing stderr merge prevented reduction: %#v", result)
+	}
+}
+
+func TestReduceCommandOutputRequiresAuthoritativeRunnerSummary(t *testing.T) {
+	lookalikes := map[string]string{
+		"cargo test":  "test user::message ... ok",
+		"cargo check": "Checking a custom deployment state",
+		"pytest":      "application log ........ [100%]",
+		"npm test":    "PASS user-provided log message",
+	}
+	for command, line := range lookalikes {
+		original := strings.Repeat(line+"\n", commandReducerMinPassingLines+2) + "exit_code: 0"
+		result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": command}, Result{Status: StatusOK, Output: original})
+		if result.Output != original || result.Meta != nil {
+			t.Fatalf("summary-free output for %q should pass through, got %#v", command, result)
+		}
+	}
+}
+
+func TestReduceCommandOutputRejectsLookalikeRunnerSummaries(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	testCases := []struct {
+		command string
+		line    string
+		summary string
+	}{
+		{command: "cargo check", line: "Compiling dependency v1.0.0", summary: "Finished generating bindings"},
+		{command: "pytest", line: "tests/test_module.py ........ [100%]", summary: "application log: 14 passed validation in staging"},
+		{command: "npm test", line: "PASS src/example.test.ts", summary: "Test Files discovered: 14"},
+	}
+	for _, testCase := range testCases {
+		original := strings.Repeat(testCase.line+"\n", commandReducerMinPassingLines+2) + testCase.summary + "\nexit_code: 1"
+		result := reduceCommandOutput(ExecCommandToolName, map[string]any{"cmd": testCase.command}, Result{Status: StatusError, Output: original})
+		if result.Output != original || result.Meta != nil {
+			t.Fatalf("lookalike summary for %q should pass through exactly, got %#v", testCase.command, result)
+		}
+	}
+}
+
+func TestRegistryAppliesCommandReducerToExecAndBashTools(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	fixture := commandReducerCorpus()[1]
+	for _, toolName := range []string{ExecCommandToolName, "bash"} {
+		t.Run(toolName, func(t *testing.T) {
+			registry := NewRegistry()
+			registry.Register(commandReducerFixtureTool{name: toolName, output: fixture.output})
+			args := map[string]any{"cmd": fixture.command}
+			if toolName == "bash" {
+				args = map[string]any{"command": fixture.command}
+			}
+			result := registry.Run(context.Background(), toolName, args)
+			if result.Status != StatusOK || result.Meta["command_output_reducer"] != "cargo_test" {
+				t.Fatalf("registry result was not reduced: %#v", result)
+			}
+			if !strings.Contains(result.Output, fixture.want) {
+				t.Fatalf("registry reduction lost summary: %q", result.Output)
+			}
+			spilled, err := os.ReadFile(result.Meta["spill_path"])
+			if err != nil || string(spilled) != fixture.output {
+				t.Fatalf("registry raw artifact mismatch: err=%v", err)
+			}
+		})
+	}
+}