Fix Elvish completion syntax

Close generated Elvish conditional branches, use value equality, and validate generated script structure plus native Bash and Zsh syntax.

Refs #499

internal/agent/compaction.go

@@ -56,6 +56,10 @@ type CompactionOptions struct {
 	// injected so Compact stays pure and testable; the agent loop wires it to a
 	// real provider call.
 	Summarize func(toSummarize []zeroruntime.Message) (string, error)
+	// taskState is a snapshot supplied by the running agent. Its immutable
+	// objective is always preserved; mutable fields are admitted only when its
+	// plan projection still matches the transcript.
+	taskState *taskStateSnapshot
 }
 
 // CompactionResult is the metadata-bearing result returned by CompactMessages.
@@ -220,7 +224,7 @@ func CompactMessages(messages []zeroruntime.Message, opts CompactionOptions) (Co
 
 	// Preserve structured state (active plan + loaded skills) from the elided
 	// middle verbatim, so it is not lost or paraphrased away by the prose summary.
-	content := appendPreservedState(summaryLabel+"\n"+summary, middle)
+	content := appendPreservedState(summaryLabel+"\n"+summary, middle, opts.taskState)
 
 	compacted := make([]zeroruntime.Message, 0, systemEnd+1+(len(messages)-boundary))
 	compacted = append(compacted, messages[:systemEnd]...)
@@ -326,6 +330,7 @@ type compactionState struct {
 	// OnText is deliberately NOT forwarded (compaction stays invisible to the user),
 	// but its token COST must still be counted so usage reports and budgets include it.
 	onUsage func(Usage)
+	task    *taskState
 
 	// calibrationRatio scales the raw byte/4 token estimate toward the provider's
 	// real prompt-token count. ApproxTextTokens over-counts code-heavy content by
@@ -365,13 +370,15 @@ func (state *compactionState) calibratedTokens(raw int) int {
 	return int(float64(raw) * state.calibrationRatio)
 }
 
-func newCompactionState(options Options) *compactionState {
-	return &compactionState{
+func newCompactionState(options Options, task *taskState) *compactionState {
+	state := &compactionState{
 		enabled:      options.ContextWindow > 0,
 		threshold:    compactionThreshold(options.ContextWindow),
 		preserveLast: options.CompactionPreserveLast,
 		onUsage:      options.OnUsage,
+		task:         task,
 	}
+	return state
 }
 
 // maybeCompact runs proactive compaction at the top of a turn. It returns the
@@ -418,6 +425,7 @@ func (state *compactionState) maybeCompact(
 	compacted, err := Compact(messages, CompactionOptions{
 		PreserveLast: state.preserveLast,
 		Summarize:    summarizeClosure(ctx, provider, state.onUsage),
+		taskState:    state.task.snapshotForCompaction(messages),
 	})
 	if err != nil {
 		// Summarizer failed: keep the original history. The reactive path (or a
@@ -468,6 +476,7 @@ func (state *compactionState) recover(
 	result, compactErr := Compact(messages, CompactionOptions{
 		PreserveLast: state.preserveLast,
 		Summarize:    summarizeClosure(ctx, provider, state.onUsage),
+		taskState:    state.task.snapshotForCompaction(messages),
 	})
 	if compactErr != nil {
 		// A genuine compaction attempt was made (and failed): the budget is spent

internal/agent/compaction_preserve.go

@@ -30,6 +30,10 @@ const (
 const (
 	maxRecentEdits   = 20
 	maxEditNoteBytes = 160
+	// maxTaskObjectiveBytes keeps the original objective recognizable after
+	// compaction without allowing an unusually large prompt to recreate the
+	// context pressure the compaction just removed.
+	maxTaskObjectiveBytes = 512
 )
 
 const (
@@ -76,32 +80,14 @@ func extractLatestPlan(messages []zeroruntime.Message) string {
 // ({"plan":[{content,status,...}]}) as terse status-tagged bullet lines. Returns
 // "" on malformed arguments or an empty plan.
 func formatPlanArguments(arguments string) string {
-	var parsed struct {
-		Plan []struct {
-			Content string `json:"content"`
-			Step    string `json:"step"`
-			Status  string `json:"status"`
-			Notes   string `json:"notes"`
-		} `json:"plan"`
-	}
-	if err := json.Unmarshal([]byte(strings.TrimSpace(arguments)), &parsed); err != nil {
+	plan, ok := parseTaskPlan(arguments)
+	if !ok {
 		return ""
 	}
-	lines := make([]string, 0, len(parsed.Plan))
-	for _, item := range parsed.Plan {
-		content := strings.TrimSpace(item.Content)
-		if content == "" {
-			content = strings.TrimSpace(item.Step)
-		}
-		if content == "" {
-			continue
-		}
-		status := strings.TrimSpace(item.Status)
-		if status == "" {
-			status = "pending"
-		}
-		line := "- [" + status + "] " + content
-		if notes := strings.TrimSpace(item.Notes); notes != "" {
+	lines := make([]string, 0, len(plan))
+	for _, item := range plan {
+		line := "- [" + item.Status + "] " + item.Content
+		if notes := item.Notes; notes != "" {
 			line += "\n  Notes: " + notes
 		}
 		lines = append(lines, line)
@@ -431,12 +417,25 @@ func capBody(body string) string {
 // preservedState is the JSON shape of the carried-across-compaction block.
 type preservedState struct {
 	Plan                string                 `json:"plan,omitempty"`
+	Task                *preservedTaskState    `json:"task,omitempty"`
 	RecentEdits         []preservedEdit        `json:"recent_edits,omitempty"`
 	Tools               []preservedTool        `json:"tools,omitempty"`
 	Skills              []preservedSkill       `json:"skills,omitempty"`
 	ProjectInstructions []preservedInstruction `json:"project_instructions,omitempty"`
 }
 
+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"`
+}
+
 type preservedEdit struct {
 	Path string `json:"path"`
 	Note string `json:"note,omitempty"`
@@ -464,8 +463,27 @@ type preservedInstruction struct {
 // may live only inside the injected summary message, which on a later compaction
 // lands in middle with no real tool calls left to extract. Fresh tool calls and
 // instruction blocks override the carried-forward copy by name/source.
-func appendPreservedState(summary string, middle []zeroruntime.Message) string {
+func appendPreservedState(summary string, middle []zeroruntime.Message, taskSnapshot *taskStateSnapshot) string {
 	priorState := parsePreservedStateBlock(latestSummaryContent(middle))
+	task := priorState.Task
+	if taskSnapshot != nil {
+		task = &preservedTaskState{
+			Objective: capTaskObjective(taskSnapshot.Objective),
+		}
+		// Plan parity corroborates only the mutable task projection. The objective
+		// comes directly from the run prompt and is immutable, so it must survive
+		// even after compaction removes the plan tool call needed for comparison.
+		if taskSnapshot.PlanParity == taskPlanParityMatch {
+			task.Status = taskSnapshot.Status
+			task.Pending = taskSnapshot.Plan.Pending
+			task.InProgress = taskSnapshot.Plan.InProgress
+			task.Completed = taskSnapshot.Plan.Completed
+			task.Failed = taskSnapshot.Plan.Failed
+			task.VerificationPassed = taskSnapshot.Verification.Passed
+			task.VerificationFailed = taskSnapshot.Verification.Failed
+			task.VerificationOutcome = taskSnapshot.Verification.LastOutcome
+		}
+	}
 
 	// Plan: a fresh update_plan in middle is authoritative; otherwise carry the
 	// plan preserved by an earlier compaction.
@@ -493,12 +511,25 @@ func appendPreservedState(summary string, middle []zeroruntime.Message) string {
 		projectInstructionEntries(middle),
 	)
 
-	if block := formatPreservedState(plan, edits, tools, skills, instructions); block != "" {
+	if block := formatPreservedState(plan, task, edits, tools, skills, instructions); block != "" {
 		summary += "\n\n" + block
 	}
 	return summary
 }
 
+func capTaskObjective(objective string) string {
+	objective = strings.TrimSpace(objective)
+	if len(objective) <= maxTaskObjectiveBytes {
+		return objective
+	}
+	const suffix = "…"
+	limit := maxTaskObjectiveBytes - len(suffix)
+	for limit > 0 && !utf8.RuneStart(objective[limit]) {
+		limit--
+	}
+	return strings.TrimSpace(objective[:limit]) + suffix
+}
+
 // mergeRecentEdits overlays fresh edits onto edits preserved by an earlier
 // compaction. Unlike mergeSkillEntries (which keeps refreshed entries in their
 // original slot), a path touched again by a fresh edit MOVES to the newest
@@ -555,11 +586,11 @@ func preservedEditsToEntries(edits []preservedEdit) []skillEntry {
 
 // formatPreservedState renders state as the labelled, single-line
 // JSON block. Returns "" when there is nothing to preserve.
-func formatPreservedState(plan string, edits, tools, skills, instructions []skillEntry) string {
-	if plan == "" && len(edits) == 0 && len(tools) == 0 && len(skills) == 0 && len(instructions) == 0 {
+func formatPreservedState(plan string, task *preservedTaskState, edits, tools, skills, instructions []skillEntry) string {
+	if plan == "" && task == nil && len(edits) == 0 && len(tools) == 0 && len(skills) == 0 && len(instructions) == 0 {
 		return ""
 	}
-	state := preservedState{Plan: plan}
+	state := preservedState{Plan: plan, Task: task}
 	for _, e := range edits {
 		state.RecentEdits = append(state.RecentEdits, preservedEdit{Path: e.name, Note: e.body})
 	}

internal/agent/compaction_preserve_test.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 	"unicode/utf8"
@@ -59,6 +60,103 @@ func TestCompactPreservesActivePlan(t *testing.T) {
 	}
 }
 
+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"}]}`})
+	messages := stateConversation()
+	compacted, err := Compact(messages, CompactionOptions{
+		PreserveLast: 2,
+		Summarize:    func([]zeroruntime.Message) (string, error) { return "SUMMARY", nil },
+		taskState:    task.snapshotForCompaction(messages),
+	})
+	if err != nil {
+		t.Fatalf("Compact: %v", err)
+	}
+	state := parsePreservedStateBlock(compacted[1].Content)
+	if state.Task == nil || state.Task.Status != taskStatusActive || state.Task.InProgress != 1 || state.Task.Pending != 1 {
+		t.Fatalf("unexpected compact task state: %#v", state.Task)
+	}
+	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)
+	}
+}
+
+func TestCompactPreservesObjectiveAfterPlanParityMismatch(t *testing.T) {
+	prior := preservedState{Task: &preservedTaskState{Objective: "stale objective", Status: taskStatusActive, Pending: 1}}
+	encoded, err := json.Marshal(prior)
+	if err != nil {
+		t.Fatal(err)
+	}
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "system"},
+		{Role: zeroruntime.MessageRoleUser, Content: summaryLabel + "\nold\n\n" + preservedStateLabel + "\n" + string(encoded)},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "continuing"},
+		{Role: zeroruntime.MessageRoleUser, Content: "more"},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "working"},
+		{Role: zeroruntime.MessageRoleUser, Content: "again"},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "done"},
+	}
+	compacted, err := Compact(messages, CompactionOptions{
+		PreserveLast: 2,
+		Summarize:    func([]zeroruntime.Message) (string, error) { return "SUMMARY", nil },
+		taskState: &taskStateSnapshot{
+			Objective:  "current objective",
+			PlanParity: taskPlanParityMismatch,
+		},
+	})
+	if err != nil {
+		t.Fatalf("Compact: %v", err)
+	}
+	state := parsePreservedStateBlock(compacted[1].Content)
+	if state.Task == nil || state.Task.Objective != "current objective" {
+		t.Fatalf("immutable objective was lost on plan mismatch: %#v", state.Task)
+	}
+	if state.Task.Status != "" || state.Task.Pending != 0 {
+		t.Fatalf("uncorroborated mutable task fields survived plan mismatch: %#v", state.Task)
+	}
+}
+
+func TestTaskObjectiveSurvivesRepeatedCompactionWithoutPlanRefresh(t *testing.T) {
+	task := newTaskState("keep this objective", nil)
+	task.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"write code","status":"in_progress"},{"content":"add tests","status":"pending"}]}`})
+	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.Fatalf("first Compact: %v", err)
+	}
+	secondInput := append(append([]zeroruntime.Message{}, first...),
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "more"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "working"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleUser, Content: "again"},
+		zeroruntime.Message{Role: zeroruntime.MessageRoleAssistant, Content: "done"},
+	)
+	snapshot := task.snapshotForCompaction(secondInput)
+	if snapshot.PlanParity != taskPlanParityMismatch {
+		t.Fatalf("plan call should be absent after first compaction, parity=%q", snapshot.PlanParity)
+	}
+	second, err := Compact(secondInput, CompactionOptions{
+		PreserveLast: 2,
+		Summarize:    func([]zeroruntime.Message) (string, error) { return "SECOND", nil },
+		taskState:    snapshot,
+	})
+	if err != nil {
+		t.Fatalf("second Compact: %v", err)
+	}
+	state := parsePreservedStateBlock(second[1].Content)
+	if state.Task == nil || state.Task.Objective != "keep this objective" {
+		t.Fatalf("objective lost after second compaction: %#v", state.Task)
+	}
+	if state.Task.Status != "" || state.Task.InProgress != 0 {
+		t.Fatalf("uncorroborated mutable fields survived second compaction: %#v", state.Task)
+	}
+}
+
 func TestCompactPreservesLoadedSkills(t *testing.T) {
 	summary := compactStateConversation(t, stateConversation())
 	if !strings.Contains(summary, preservedStateLabel) {
@@ -283,12 +381,10 @@ func TestExtractLatestPlanReturnsMostRecent(t *testing.T) {
 	}
 }
 
-func TestFormatPlanArgumentsAcceptsStepAlias(t *testing.T) {
+func TestFormatPlanArgumentsRejectsUnsupportedStepAlias(t *testing.T) {
 	got := formatPlanArguments(`{"plan":[{"step":"write failing test","status":"in_progress"},{"content":"keep existing shape","status":"pending"}]}`)
-	for _, want := range []string{"- [in_progress] write failing test", "- [pending] keep existing shape"} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("expected %q in formatted plan, got %q", want, got)
-		}
+	if got != "" {
+		t.Fatalf("unsupported alias should reject the whole plan like update_plan, got %q", got)
 	}
 }
 

internal/agent/compaction_test.go

@@ -581,7 +581,7 @@ func TestCompactNeverProducesConsecutiveUserMessages(t *testing.T) {
 }
 
 func TestRecoverNoopDoesNotConsumeReactiveBudget(t *testing.T) {
-	st := newCompactionState(Options{ContextWindow: 1000, CompactionPreserveLast: 2})
+	st := newCompactionState(Options{ContextWindow: 1000, CompactionPreserveLast: 2}, nil)
 	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{{
 		{Type: zeroruntime.StreamEventText, Content: "SUMMARY"}, {Type: zeroruntime.StreamEventDone},
 	}}}
@@ -628,7 +628,7 @@ func TestRecoverNoopDoesNotConsumeReactiveBudget(t *testing.T) {
 }
 
 func TestRecoverDisabledIsNoop(t *testing.T) {
-	st := newCompactionState(Options{ContextWindow: 0})
+	st := newCompactionState(Options{ContextWindow: 0}, nil)
 	msgs := []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "x"}}
 	called := false
 	// recover must not invoke the provider/summarize when disabled, even on a

internal/agent/completion_policy.go

@@ -39,7 +39,7 @@ func newCompletionPolicy(requireSemanticCheck bool) *completionPolicy {
 	return &completionPolicy{requireSemanticCheck: requireSemanticCheck}
 }
 
-func (policy *completionPolicy) evaluate(text string, planPending bool) completionEvaluation {
+func (policy *completionPolicy) evaluate(text string, context completionContext) completionEvaluation {
 	// A direct admission is strong local evidence and takes precedence over all
 	// weaker signals, avoiding both continuation nudges and semantic checks.
 	if reason := selfReportedIncompletion(text); reason != "" {
@@ -50,7 +50,7 @@ func (policy *completionPolicy) evaluate(text string, planPending bool) completi
 	// weak evidence because bookkeeping can be stale. Both get a bounded chance
 	// to continue, but only a persisted cue is ultimately incomplete.
 	cue := endsWithContinuationCue(text)
-	if cue || planPending {
+	if cue || context.PlanPending {
 		if policy.continueNudges < maxContinueNudges {
 			policy.continueNudges++
 			reason := "your message ended mid-step"

internal/agent/completion_policy_test.go

@@ -1,16 +1,19 @@
 package agent
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestCompletionPolicyLocalEvidenceDecidesWithoutSemanticCheck(t *testing.T) {
 	policy := newCompletionPolicy(false)
 
-	complete := policy.evaluate("Done. All required checks pass.", false)
+	complete := policy.evaluate("Done. All required checks pass.", completionContext{})
 	if complete.Decision != CompletionComplete {
 		t.Fatalf("confident completion decision = %q, want %q", complete.Decision, CompletionComplete)
 	}
 
-	incomplete := policy.evaluate("I couldn't verify the result, so this is my best guess.", false)
+	incomplete := policy.evaluate("I couldn't verify the result, so this is my best guess.", completionContext{})
 	if incomplete.Decision != CompletionIncomplete {
 		t.Fatalf("admitted failure decision = %q, want %q", incomplete.Decision, CompletionIncomplete)
 	}
@@ -19,13 +22,13 @@ func TestCompletionPolicyLocalEvidenceDecidesWithoutSemanticCheck(t *testing.T)
 func TestCompletionPolicyPreservesBoundedPlanStallProtection(t *testing.T) {
 	policy := newCompletionPolicy(false)
 	for attempt := 0; attempt < maxContinueNudges; attempt++ {
-		got := policy.evaluate("Let me inspect the remaining configuration:", true)
+		got := policy.evaluate("Let me inspect the remaining configuration:", completionContext{PlanPending: true})
 		if got.Decision != CompletionUncertain || got.Action != completionActionContinue {
 			t.Fatalf("attempt %d = (%q, %q), want uncertain continue", attempt+1, got.Decision, got.Action)
 		}
 	}
 
-	got := policy.evaluate("Let me inspect the remaining configuration:", true)
+	got := policy.evaluate("Let me inspect the remaining configuration:", completionContext{PlanPending: true})
 	if got.Decision != CompletionIncomplete {
 		t.Fatalf("decision after nudge budget = %q, want %q", got.Decision, CompletionIncomplete)
 	}
@@ -34,13 +37,13 @@ func TestCompletionPolicyPreservesBoundedPlanStallProtection(t *testing.T) {
 func TestCompletionPolicyTreatsPendingPlanAsWeakEvidence(t *testing.T) {
 	policy := newCompletionPolicy(false)
 	for attempt := 0; attempt < maxContinueNudges; attempt++ {
-		got := policy.evaluate("All set.", true)
+		got := policy.evaluate("All set.", completionContext{PlanPending: true})
 		if got.Decision != CompletionUncertain || got.Action != completionActionContinue {
 			t.Fatalf("attempt %d = (%q, %q), want uncertain continue", attempt+1, got.Decision, got.Action)
 		}
 	}
 
-	got := policy.evaluate("All set.", true)
+	got := policy.evaluate("All set.", completionContext{PlanPending: true})
 	if got.Decision != CompletionComplete {
 		t.Fatalf("stale plan decision after nudge budget = %q, want %q", got.Decision, CompletionComplete)
 	}
@@ -49,12 +52,12 @@ func TestCompletionPolicyTreatsPendingPlanAsWeakEvidence(t *testing.T) {
 func TestCompletionPolicyAllowsExactlyOneRequiredSemanticCheck(t *testing.T) {
 	policy := newCompletionPolicy(true)
 
-	first := policy.evaluate("Implemented and tested.", false)
+	first := policy.evaluate("Implemented and tested.", completionContext{})
 	if first.Decision != CompletionUncertain || first.Action != completionActionSemanticCheck {
 		t.Fatalf("first decision = (%q, %q), want uncertain semantic check", first.Decision, first.Action)
 	}
 
-	second := policy.evaluate("PASS. The result meets the task criterion.", false)
+	second := policy.evaluate("PASS. The result meets the task criterion.", completionContext{})
 	if second.Decision != CompletionComplete {
 		t.Fatalf("post-check decision = %q, want %q", second.Decision, CompletionComplete)
 	}
@@ -62,3 +65,11 @@ func TestCompletionPolicyAllowsExactlyOneRequiredSemanticCheck(t *testing.T) {
 		t.Fatal("semantic check was requested more than once")
 	}
 }
+
+func TestAcceptanceVerificationNudgeIncludesBoundedObjective(t *testing.T) {
+	objective := "make the requested behavior observable"
+	nudge := acceptanceVerificationNudge(objective)
+	if !strings.Contains(nudge, "Task objective: "+objective) {
+		t.Fatalf("semantic check was not grounded in the objective: %q", nudge)
+	}
+}

internal/agent/guardrails.go

@@ -1,7 +1,6 @@
 package agent
 
 import (
-	"encoding/json"
 	"strconv"
 	"strings"
 
@@ -127,9 +126,8 @@ func endsWithContinuationCue(text string) bool {
 // which the update_plan tool coerces to "pending") counts as remaining, matching
 // that tool's own status normalization.
 func planStatusRemaining(status string) bool {
-	switch strings.ToLower(strings.TrimSpace(status)) {
-	case "completed", "complete", "done", "finished", "resolved", "✓", "x", "[x]",
-		"failed", "fail", "error", "errored", "blocked", "cancelled", "canceled", "abandoned", "skipped":
+	switch normalizeTaskPlanStatus(status) {
+	case "completed", "failed":
 		return false
 	default:
 		return true
@@ -307,8 +305,8 @@ func hasAnyPrefix(s string, prefixes []string) bool {
 // the bug-hunt surfaced: well-formed output treated as correct; pre-existing tests
 // passing treated as the objective being met; and a result that merely matches a
 // baseline the task asked to beat or improve. General — no task-specific content.
-func acceptanceVerificationNudge() string {
-	return "Before this task can be marked complete, " + acceptanceNudgeMarker + " — " +
+func acceptanceVerificationNudge(objective string) string {
+	nudge := "Before this task can be marked complete, " + acceptanceNudgeMarker + " — " +
 		"NOT the shape or format of your output, NOT that pre-existing tests pass, and NOT that your " +
 		"result merely matches a baseline you were asked to beat or improve. " +
 		"Re-read the original task, then run a concrete check that exercises the actual requirement: " +
@@ -316,6 +314,10 @@ func acceptanceVerificationNudge() string {
 		"thing the task asked you to produce, recover, fix, or optimize. " +
 		"If that check passes, reply PASS and cite the evidence. " +
 		"If it does not pass — or you cannot run such a check — say so plainly and keep working; do not claim success."
+	if objective = capTaskObjective(objective); objective != "" {
+		nudge += "\n\nTask objective: " + objective
+	}
+	return nudge
 }
 
 // toolFailureHintMarker is a stable substring for tests.
@@ -553,16 +555,12 @@ func (state *guardState) pendingPlanItems() bool {
 // many items are still remaining. Malformed arguments leave the prior count
 // unchanged (best-effort — the plan panel itself tolerates the same).
 func (state *guardState) observePlanUpdate(arguments string) {
-	var parsed struct {
-		Plan []struct {
-			Status string `json:"status"`
-		} `json:"plan"`
-	}
-	if json.Unmarshal([]byte(arguments), &parsed) != nil {
+	plan, ok := parseTaskPlan(arguments)
+	if !ok {
 		return
 	}
 	pending := 0
-	for _, item := range parsed.Plan {
+	for _, item := range plan {
 		if planStatusRemaining(item.Status) {
 			pending++
 		}

internal/agent/loop.go

@@ -185,7 +185,16 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 	messages := zeroruntime.SeedMessagesWithImages(promptParts.prompt, prompt, options.Images)
 
 	guards := newGuardState()
-	compactor := newCompactionState(options)
+	task := newTaskState(prompt, options.Trace)
+	compactor := newCompactionState(options, task)
+	defer func() {
+		// A final transcript comparison is observational. It records drift but
+		// never rewrites the result or changes execution after the fact.
+		task.observePlanParity(result.Messages)
+		// Tool-result observations are intentionally coalesced; this final event
+		// guarantees their aggregate counts are present even on an early return.
+		task.emit()
+	}()
 	// The execution-profile posture controller. nil Options.Profile (every
 	// existing caller) makes every observe/decide call a no-op, keeping the
 	// loop byte-identical for unprofiled runs.
@@ -570,7 +579,9 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			// model's final answer ONLY when the work is actually done. Default off
 			// (RequireCompletionSignal), so interactive runs stay byte-identical.
 			if options.RequireCompletionSignal {
-				evaluation := completionPolicy.evaluate(collected.Text, guards.pendingPlanItems())
+				completionContext := task.completionContext(messages, guards.pendingPlanItems())
+				evaluation := completionPolicy.evaluate(collected.Text, completionContext)
+				task.observe(taskStateEvent{kind: taskStateEventCompletion, completion: evaluation})
 				switch evaluation.Decision {
 				case CompletionIncomplete:
 					result.Incomplete = true
@@ -595,13 +606,15 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 						options.Trace.Counter(trace.CounterAcceptanceChecks, 1)
 						messages = append(messages, zeroruntime.Message{
 							Role:    zeroruntime.MessageRoleUser,
-							Content: acceptanceVerificationNudge(),
+							Content: acceptanceVerificationNudge(completionContext.Objective),
 						})
 					}
 					continue
 				case CompletionComplete:
 					// Local evidence is sufficient; proceed to final diagnostics.
 				}
+			} else {
+				task.observe(taskStateEvent{kind: taskStateEventCompletion, completion: completionEvaluation{Decision: CompletionComplete}})
 			}
 			// Finalization diagnostics gate: edits from this run may still have
 			// checks in flight — the per-turn drain waits only briefly and defers
@@ -625,6 +638,11 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		// executing so the empty-turn counter resets and plan-tracking signals
 		// stay current.
 		guards.observeTurn(collected)
+		for _, call := range collected.ToolCalls {
+			if call.Name == planToolName {
+				task.observe(taskStateEvent{kind: taskStateEventPlan, arguments: call.Arguments})
+			}
+		}
 
 		failureHint := ""
 		// turnRequestedModel records the FIRST mid-run escalation target requested
@@ -676,6 +694,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})
 			if options.OnToolResult != nil {
 				options.OnToolResult(toolResult)
 			}
@@ -757,6 +776,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		if options.SelfCorrect != nil && len(changedFilesThisBatch) > 0 {
 			feedback, selfCorrectOutcome := options.SelfCorrect.AfterEdit(ctx, dedupeStrings(changedFilesThisBatch))
 			posture.observeSelfCorrect(selfCorrectOutcome)
+			task.observe(taskStateEvent{kind: taskStateEventVerification, verification: selfCorrectOutcome})
 			if feedback != "" {
 				messages = append(messages, zeroruntime.Message{
 					Role:    zeroruntime.MessageRoleUser,

internal/agent/task_state.go

@@ -0,0 +1,359 @@
+package agent
+
+import (
+	"encoding/json"
+	"reflect"
+	"sort"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/trace"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+type taskStatus string
+
+const (
+	taskStatusActive     taskStatus = "active"
+	taskStatusComplete   taskStatus = "complete"
+	taskStatusIncomplete taskStatus = "incomplete"
+)
+
+type taskPlanParity string
+
+const (
+	taskPlanParityUnknown  taskPlanParity = "unknown"
+	taskPlanParityMatch    taskPlanParity = "match"
+	taskPlanParityMismatch taskPlanParity = "mismatch"
+)
+
+type taskPlanItem struct {
+	Content string `json:"content"`
+	Status  string `json:"status"`
+	Notes   string `json:"notes,omitempty"`
+}
+
+type taskPlanState struct {
+	Items      []taskPlanItem `json:"items,omitempty"`
+	Pending    int            `json:"pending"`
+	InProgress int            `json:"in_progress"`
+	Completed  int            `json:"completed"`
+	Failed     int            `json:"failed"`
+}
+
+type taskToolState struct {
+	Succeeded int `json:"succeeded"`
+	Failed    int `json:"failed"`
+}
+
+type taskVerificationState struct {
+	Passed      int     `json:"passed"`
+	Failed      int     `json:"failed"`
+	LastOutcome Outcome `json:"last_outcome,omitempty"`
+}
+
+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"`
+}
+
+type taskStateEventKind int
+
+const (
+	taskStateEventPlan taskStateEventKind = iota + 1
+	taskStateEventToolResult
+	taskStateEventVerification
+	taskStateEventCompletion
+)
+
+type taskStateEvent struct {
+	kind         taskStateEventKind
+	arguments    string
+	toolResult   ToolResult
+	verification Outcome
+	completion   completionEvaluation
+}
+
+// taskState is a deterministic projection of facts the loop already observes.
+// It does not initiate work or replace the transcript; consumers must check
+// transcript parity before using its compact representation.
+type taskState struct {
+	snapshotValue taskStateSnapshot
+	changedFiles  map[string]struct{}
+	recorder      *trace.Recorder
+	planObserved  bool
+}
+
+func newTaskState(objective string, recorder *trace.Recorder) *taskState {
+	state := &taskState{
+		snapshotValue: taskStateSnapshot{
+			Objective:  strings.TrimSpace(objective),
+			Status:     taskStatusActive,
+			PlanParity: taskPlanParityUnknown,
+		},
+		changedFiles: map[string]struct{}{},
+	}
+	state.recorder = recorder
+	return state
+}
+
+func (state *taskState) observe(event taskStateEvent) bool {
+	if state == nil {
+		return false
+	}
+	changed := false
+	switch event.kind {
+	case taskStateEventPlan:
+		plan, ok := parseTaskPlan(event.arguments)
+		if !ok {
+			return false
+		}
+		state.snapshotValue.Plan = summarizeTaskPlan(plan)
+		state.planObserved = true
+		state.markActive()
+		changed = true
+	case taskStateEventToolResult:
+		state.markActive()
+		if event.toolResult.Status == tools.StatusOK {
+			state.snapshotValue.Tools.Succeeded++
+		} else {
+			state.snapshotValue.Tools.Failed++
+		}
+		for _, path := range event.toolResult.ChangedFiles {
+			path = strings.TrimSpace(path)
+			if path != "" {
+				state.changedFiles[path] = struct{}{}
+			}
+		}
+		state.snapshotValue.ChangedFiles = sortedKeys(state.changedFiles)
+		changed = true
+	case taskStateEventVerification:
+		if event.verification == OutcomeDisabled {
+			return false
+		}
+		state.markActive()
+		state.snapshotValue.Verification.LastOutcome = event.verification
+		switch event.verification {
+		case OutcomePassed:
+			state.snapshotValue.Verification.Passed++
+		case OutcomeCorrecting, OutcomeReported, OutcomeAborted:
+			state.snapshotValue.Verification.Failed++
+		}
+		changed = true
+	case taskStateEventCompletion:
+		state.snapshotValue.CompletionDecision = event.completion.Decision
+		state.snapshotValue.CompletionReason = event.completion.Reason
+		switch event.completion.Decision {
+		case CompletionComplete:
+			state.snapshotValue.Status = taskStatusComplete
+		case CompletionIncomplete:
+			state.snapshotValue.Status = taskStatusIncomplete
+		default:
+			state.snapshotValue.Status = taskStatusActive
+		}
+		changed = true
+	}
+	if changed {
+		state.snapshotValue.Revision++
+		if event.kind != taskStateEventToolResult {
+			state.emit()
+		}
+	}
+	return changed
+}
+
+func (state *taskState) markActive() {
+	state.snapshotValue.Status = taskStatusActive
+	state.snapshotValue.CompletionDecision = ""
+	state.snapshotValue.CompletionReason = ""
+}
+
+func (state *taskState) snapshot() taskStateSnapshot {
+	if state == nil {
+		return taskStateSnapshot{}
+	}
+	snapshot := state.snapshotValue
+	snapshot.Plan.Items = append([]taskPlanItem(nil), state.snapshotValue.Plan.Items...)
+	snapshot.ChangedFiles = append([]string(nil), state.snapshotValue.ChangedFiles...)
+	return snapshot
+}
+
+// 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
+// this comparison.
+func (state *taskState) observePlanParity(messages []zeroruntime.Message) taskPlanParity {
+	if state == nil {
+		return taskPlanParityUnknown
+	}
+	transcriptPlan, found, valid := latestTaskPlan(messages)
+	tracked := state.snapshotValue.Plan.Items
+	parity := taskPlanParityMatch
+	if !valid || found != state.planObserved || (found && !reflect.DeepEqual(transcriptPlan, tracked)) {
+		parity = taskPlanParityMismatch
+	}
+	if state.snapshotValue.PlanParity != parity {
+		state.snapshotValue.PlanParity = parity
+		state.snapshotValue.Revision++
+		state.emit()
+	}
+	return parity
+}
+
+type completionContext struct {
+	Objective             string
+	PlanPending           bool
+	PlanMatchesTranscript bool
+}
+
+func (state *taskState) completionContext(messages []zeroruntime.Message, transcriptPlanPending bool) completionContext {
+	context := completionContext{PlanPending: transcriptPlanPending}
+	if state == nil {
+		return context
+	}
+	context.Objective = state.snapshotValue.Objective
+	context.PlanMatchesTranscript = state.observePlanParity(messages) == taskPlanParityMatch
+	if context.PlanMatchesTranscript {
+		context.PlanPending = state.snapshotValue.Plan.Pending+state.snapshotValue.Plan.InProgress > 0
+	}
+	return context
+}
+
+func (state *taskState) snapshotForCompaction(messages []zeroruntime.Message) *taskStateSnapshot {
+	if state == nil {
+		return nil
+	}
+	state.observePlanParity(messages)
+	snapshot := state.snapshot()
+	return &snapshot
+}
+
+func (state *taskState) emit() {
+	if state == nil || state.recorder == nil {
+		return
+	}
+	snapshot := state.snapshotValue
+	state.recorder.EmitTaskState(trace.TaskStateEvent{
+		Revision:            snapshot.Revision,
+		Status:              string(snapshot.Status),
+		PlanPending:         snapshot.Plan.Pending,
+		PlanInProgress:      snapshot.Plan.InProgress,
+		PlanCompleted:       snapshot.Plan.Completed,
+		PlanFailed:          snapshot.Plan.Failed,
+		ToolsSucceeded:      snapshot.Tools.Succeeded,
+		ToolsFailed:         snapshot.Tools.Failed,
+		VerificationPassed:  snapshot.Verification.Passed,
+		VerificationFailed:  snapshot.Verification.Failed,
+		VerificationOutcome: string(snapshot.Verification.LastOutcome),
+		ChangedFileCount:    len(snapshot.ChangedFiles),
+		CompletionDecision:  string(snapshot.CompletionDecision),
+		PlanParity:          string(snapshot.PlanParity),
+	})
+}
+
+func parseTaskPlan(arguments string) ([]taskPlanItem, bool) {
+	var object map[string]json.RawMessage
+	if json.Unmarshal([]byte(strings.TrimSpace(arguments)), &object) != nil {
+		return nil, false
+	}
+	rawPlan, ok := object["plan"]
+	if !ok || string(rawPlan) == "null" {
+		return nil, false
+	}
+	var parsed []struct {
+		ID      *string `json:"id"`
+		Content string  `json:"content"`
+		Status  string  `json:"status"`
+		Notes   string  `json:"notes"`
+	}
+	if json.Unmarshal(rawPlan, &parsed) != nil {
+		return nil, false
+	}
+	plan := make([]taskPlanItem, 0, len(parsed))
+	for _, raw := range parsed {
+		if raw.Content == "" {
+			return nil, false
+		}
+		plan = append(plan, taskPlanItem{
+			Content: raw.Content,
+			Status:  normalizeTaskPlanStatus(raw.Status),
+			Notes:   raw.Notes,
+		})
+	}
+	lastInProgress := -1
+	for index := range plan {
+		if plan[index].Status == "in_progress" {
+			if lastInProgress >= 0 {
+				plan[lastInProgress].Status = "completed"
+			}
+			lastInProgress = index
+		}
+	}
+	if len(plan) == 0 {
+		return nil, true
+	}
+	return plan, true
+}
+
+func normalizeTaskPlanStatus(status string) string {
+	switch strings.ToLower(strings.TrimSpace(status)) {
+	case "completed", "complete", "done", "finished", "resolved", "✓", "x", "[x]":
+		return "completed"
+	case "in_progress", "in-progress", "inprogress", "in progress", "active", "doing", "started", "current", "wip", "ongoing", "running":
+		return "in_progress"
+	case "failed", "fail", "error", "errored", "blocked", "cancelled", "canceled", "abandoned", "skipped":
+		return "failed"
+	default:
+		return "pending"
+	}
+}
+
+func summarizeTaskPlan(items []taskPlanItem) taskPlanState {
+	plan := taskPlanState{Items: append([]taskPlanItem(nil), items...)}
+	for _, item := range items {
+		switch item.Status {
+		case "completed":
+			plan.Completed++
+		case "in_progress":
+			plan.InProgress++
+		case "failed":
+			plan.Failed++
+		default:
+			plan.Pending++
+		}
+	}
+	return plan
+}
+
+func latestTaskPlan(messages []zeroruntime.Message) ([]taskPlanItem, bool, bool) {
+	for i := len(messages) - 1; i >= 0; i-- {
+		for j := len(messages[i].ToolCalls) - 1; j >= 0; j-- {
+			call := messages[i].ToolCalls[j]
+			if call.Name != planToolName {
+				continue
+			}
+			plan, ok := parseTaskPlan(call.Arguments)
+			return plan, true, ok
+		}
+	}
+	return nil, false, true
+}
+
+func sortedKeys(values map[string]struct{}) []string {
+	keys := make([]string, 0, len(values))
+	for value := range values {
+		keys = append(keys, value)
+	}
+	// Paths are evidence, not chronology. Stable ordering makes replay snapshots
+	// deterministic even if events originate from parallel read batches later.
+	sort.Strings(keys)
+	return keys
+}

internal/agent/task_state_test.go

@@ -0,0 +1,204 @@
+package agent
+
+import (
+	"context"
+	"reflect"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/trace"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func TestTaskStateReplayIsDeterministic(t *testing.T) {
+	events := []taskStateEvent{
+		{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"inspect","status":"done"},{"content":"implement","status":"in progress"},{"content":"verify"}]}`},
+		{kind: taskStateEventToolResult, toolResult: ToolResult{Name: "apply_patch", Status: tools.StatusOK, ChangedFiles: []string{"a.go", "a.go", "b.go"}}},
+		{kind: taskStateEventToolResult, toolResult: ToolResult{Name: "go test", Status: tools.StatusError}},
+		{kind: taskStateEventVerification, verification: OutcomePassed},
+		{kind: taskStateEventCompletion, completion: completionEvaluation{Decision: CompletionUncertain, Reason: "pending work"}},
+	}
+
+	first := newTaskState("ship the change", nil)
+	second := newTaskState("ship the change", nil)
+	for _, event := range events {
+		first.observe(event)
+		second.observe(event)
+	}
+
+	if !reflect.DeepEqual(first.snapshot(), second.snapshot()) {
+		t.Fatalf("replaying the same events produced different snapshots:\nfirst:  %#v\nsecond: %#v", first.snapshot(), second.snapshot())
+	}
+	got := first.snapshot()
+	if got.Status != taskStatusActive || got.Plan.Pending != 1 || got.Plan.InProgress != 1 || got.Plan.Completed != 1 {
+		t.Fatalf("unexpected plan snapshot: %#v", got)
+	}
+	if got.Tools.Succeeded != 1 || got.Tools.Failed != 1 || len(got.ChangedFiles) != 2 {
+		t.Fatalf("unexpected evidence snapshot: %#v", got)
+	}
+	if got.Verification.Passed != 1 || got.Verification.Failed != 0 || got.Verification.LastOutcome != OutcomePassed {
+		t.Fatalf("unexpected verification snapshot: %#v", got.Verification)
+	}
+}
+
+func TestTaskStateCoalescesToolResultsIntoNextTraceEvent(t *testing.T) {
+	recorder := trace.NewRecorder("session", "run", "")
+	state := newTaskState("objective", recorder)
+	for range 20 {
+		state.observe(taskStateEvent{kind: taskStateEventToolResult, toolResult: ToolResult{Status: tools.StatusOK}})
+	}
+	if events := recorder.Finish().TaskStates; len(events) != 0 {
+		t.Fatalf("tool results should be coalesced, got %d trace events", len(events))
+	}
+
+	recorder = trace.NewRecorder("session", "run-2", "")
+	state = newTaskState("objective", recorder)
+	for range 20 {
+		state.observe(taskStateEvent{kind: taskStateEventToolResult, toolResult: ToolResult{Status: tools.StatusOK}})
+	}
+	state.observe(taskStateEvent{kind: taskStateEventCompletion, completion: completionEvaluation{Decision: CompletionComplete}})
+	events := recorder.Finish().TaskStates
+	if len(events) != 1 || events[0].ToolsSucceeded != 20 {
+		t.Fatalf("coalesced tool total missing from completion snapshot: %#v", events)
+	}
+}
+
+func TestRunEmitsTaskStateFromExistingLoopEvents(t *testing.T) {
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewUpdatePlanTool())
+	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{
+		{
+			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "plan-1", ToolName: planToolName},
+			{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "plan-1", ArgumentsFragment: `{"plan":[{"content":"implement","status":"completed"}]}`},
+			{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "plan-1"},
+			{Type: zeroruntime.StreamEventDone},
+		},
+		{
+			{Type: zeroruntime.StreamEventText, Content: "done"},
+			{Type: zeroruntime.StreamEventDone},
+		},
+	}}
+	recorder := trace.NewRecorder("session", "run", "")
+
+	result, err := Run(context.Background(), "implement the change", provider, Options{
+		Registry: registry,
+		Trace:    recorder,
+	})
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("final answer = %q, want done", result.FinalAnswer)
+	}
+	events := recorder.Finish().TaskStates
+	if len(events) < 3 {
+		t.Fatalf("expected plan, tool, completion, and parity snapshots, got %#v", events)
+	}
+	last := events[len(events)-1]
+	if last.Status != string(taskStatusComplete) || last.PlanCompleted != 1 || last.ToolsSucceeded != 1 || last.PlanParity != string(taskPlanParityMatch) {
+		t.Fatalf("unexpected final task snapshot: %#v", last)
+	}
+}
+
+func TestTaskStateSnapshotIsImmutable(t *testing.T) {
+	state := newTaskState("objective", nil)
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"one","status":"pending"}]}`})
+	state.observe(taskStateEvent{kind: taskStateEventToolResult, toolResult: ToolResult{Status: tools.StatusOK, ChangedFiles: []string{"one.go"}}})
+
+	snapshot := state.snapshot()
+	snapshot.Plan.Items[0].Content = "mutated"
+	snapshot.ChangedFiles[0] = "mutated.go"
+
+	fresh := state.snapshot()
+	if fresh.Plan.Items[0].Content != "one" || fresh.ChangedFiles[0] != "one.go" {
+		t.Fatalf("snapshot mutation leaked into task state: %#v", fresh)
+	}
+}
+
+func TestTaskStatePlanParityUsesLatestPlan(t *testing.T) {
+	state := newTaskState("objective", nil)
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"old","status":"completed"}]}`})
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"new","status":"in_progress"}]}`})
+
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+		{Name: planToolName, Arguments: `{"plan":[{"content":"new","status":"in_progress"}]}`},
+	}}}
+	if parity := state.observePlanParity(messages); parity != taskPlanParityMatch {
+		t.Fatalf("parity = %q, want match", parity)
+	}
+
+	messages[0].ToolCalls[0].Arguments = `{"plan":[{"content":"different","status":"pending"}]}`
+	if parity := state.observePlanParity(messages); parity != taskPlanParityMismatch {
+		t.Fatalf("parity = %q, want mismatch", parity)
+	}
+}
+
+func TestTaskStateMatchesPlanToolNormalization(t *testing.T) {
+	state := newTaskState("objective", nil)
+	arguments := `{"plan":[{"content":"first","status":"in_progress"},{"content":"second","status":"in_progress"}]}`
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: arguments})
+
+	snapshot := state.snapshot()
+	if snapshot.Plan.Completed != 1 || snapshot.Plan.InProgress != 1 {
+		t.Fatalf("multiple active items were not normalized like the plan tool: %#v", snapshot.Plan)
+	}
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{Name: planToolName, Arguments: arguments}}}}
+	if parity := state.observePlanParity(messages); parity != taskPlanParityMatch {
+		t.Fatalf("normalized state should still match its transcript event, got %q", parity)
+	}
+
+	empty := newTaskState("objective", nil)
+	empty.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[]}`})
+	emptyMessages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{{Name: planToolName, Arguments: `{"plan":[]}`}}}}
+	if parity := empty.observePlanParity(emptyMessages); parity != taskPlanParityMatch {
+		t.Fatalf("explicit empty plan should match transcript, got %q", parity)
+	}
+}
+
+func TestTaskStateContextFallsBackWhenTranscriptDiffers(t *testing.T) {
+	state := newTaskState("objective", nil)
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"tracked","status":"completed"}]}`})
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+		{Name: planToolName, Arguments: `{"plan":[{"content":"transcript","status":"pending"}]}`},
+	}}}
+
+	context := state.completionContext(messages, true)
+	if !context.PlanPending || context.PlanMatchesTranscript {
+		t.Fatalf("completion context must retain transcript truth on mismatch: %#v", context)
+	}
+	if context.Objective != "objective" {
+		t.Fatalf("objective lost from completion context: %#v", context)
+	}
+}
+
+func TestTaskStateCompactionSnapshotRetainsObjectiveOnPlanMismatch(t *testing.T) {
+	state := newTaskState("objective", nil)
+	state.observe(taskStateEvent{kind: taskStateEventPlan, arguments: `{"plan":[{"content":"verify","status":"pending"}]}`})
+	matching := []zeroruntime.Message{{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+		{Name: planToolName, Arguments: `{"plan":[{"content":"verify","status":"pending"}]}`},
+	}}}
+	if snapshot := state.snapshotForCompaction(matching); snapshot == nil || snapshot.Objective != "objective" {
+		t.Fatalf("matching transcript should produce compact state, got %#v", snapshot)
+	}
+
+	mismatching := append([]zeroruntime.Message(nil), matching...)
+	mismatching[0].ToolCalls = []zeroruntime.ToolCall{{Name: planToolName, Arguments: `{"plan":[{"content":"other","status":"pending"}]}`}}
+	if snapshot := state.snapshotForCompaction(mismatching); snapshot == nil || snapshot.Objective != "objective" || snapshot.PlanParity != taskPlanParityMismatch {
+		t.Fatalf("plan mismatch must retain immutable objective and mark mutable state uncorroborated, got %#v", snapshot)
+	}
+}
+
+func TestParseTaskPlanRejectsArgumentsTheToolWouldReject(t *testing.T) {
+	for _, arguments := range []string{
+		`{}`,
+		`{"plan":null}`,
+		`{"plan":[{"step":"alias is not accepted"}]}`,
+		`{"plan":[{"content":""}]}`,
+		`{"plan":[{"content":"valid"},{"content":""}]}`,
+		`{"plan":[{"id":4,"content":"valid"}]}`,
+	} {
+		if plan, ok := parseTaskPlan(arguments); ok {
+			t.Fatalf("parseTaskPlan(%s) = %#v, true; want rejected", arguments, plan)
+		}
+	}
+}

internal/cli/app.go

@@ -368,6 +368,8 @@ func runWithDeps(args []string, stdout io.Writer, stderr io.Writer, deps appDeps
 	case "exec":
 		// Forward leading --add-dir occurrences so exec's own parser collects them.
 		return runExec(append(addDirFlagArgs(addDirs), args[1:]...), stdout, stderr, deps)
+	case "completions":
+		return runCompletions(args[1:], stdout, stderr)
 	case "daemon":
 		return runDaemon(args[1:], stdout, stderr, deps)
 	case "config":
@@ -1157,6 +1159,7 @@ Usage:
 
 Commands:
   exec       Run a one-shot prompt through the Go agent runtime
+  completions Generate shell completion scripts
   daemon     Manage the local background worker daemon (start/stop/status/run/attach)
   setup      Guide first-run provider setup
   config     Inspect resolved Go configuration without leaking secrets

internal/cli/completions.go

@@ -0,0 +1,404 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+)
+
+type completionNode struct {
+	names    []string
+	flags    []string
+	children []completionNode
+}
+
+type completionContext struct {
+	path        string
+	candidates  []string
+	transitions map[string]string
+}
+
+var completionRoot = completionNode{
+	flags: []string{"-h", "--help", "-v", "--version", "-p", "--prompt", "--add-dir", "--theme", "--skip-permissions-unsafe"},
+	children: []completionNode{
+		{names: []string{"exec"}, flags: []string{
+			"-h", "--help", "-f", "--file", "--image", "--add-dir", "--mode", "-m", "--model",
+			"--use-spec", "--spec-model", "--spec-reasoning-effort", "--max-turns", "--exec-profile",
+			"--auto", "--enabled-tools", "--disabled-tools", "--list-tools", "--profile", "-r",
+			"--reasoning-effort", "-C", "--cwd", "-w", "--worktree", "--worktree-dir", "-i",
+			"--input-format", "-o", "--output-format", "--prompt", "--resume", "--fork",
+			"--calling-session-id", "--calling-tool-use-id", "--tag", "--depth", "--session-title",
+			"--init-session-id", "--skip-permissions-unsafe", "--allow-escalation", "--self-correct",
+			"--notify", "--no-notify", "--no-completion-gate",
+		}},
+		{
+			names:    []string{"completions"},
+			flags:    []string{"-h", "--help"},
+			children: leafNodes("bash", "zsh", "fish", "powershell", "elvish"),
+		},
+		{names: []string{"daemon"}, children: leafNodes("start", "stop", "status", "run", "attach", "serve-remote", "link")},
+		{names: []string{"setup"}},
+		{names: []string{"config"}},
+		{names: []string{"models"}, children: []completionNode{{names: []string{"list", "ls"}}}},
+		{names: []string{"providers"}, children: []completionNode{
+			{names: []string{"current"}}, {names: []string{"list"}}, {names: []string{"catalog"}},
+			{names: []string{"add"}}, {names: []string{"check"}}, {names: []string{"use"}},
+			{names: []string{"remove", "rm"}}, {names: []string{"rename"}}, {names: []string{"setup"}},
+			{names: []string{"detect"}}, {names: []string{"models"}},
+		}},
+		{names: []string{"doctor"}},
+		{names: []string{"context"}},
+		{names: []string{"repo-map", "repomap"}},
+		{names: []string{"search", "find"}},
+		{names: []string{"sessions", "session"}, children: leafNodes("list", "children", "lineage", "tree", "rewind-plan", "rewind", "compact-plan")},
+		{names: []string{"spec"}, children: leafNodes("show", "approve", "reject")},
+		{names: []string{"init"}},
+		{names: []string{"specialists", "specialist"}, children: []completionNode{
+			{names: []string{"list"}}, {names: []string{"show"}}, {names: []string{"create"}},
+			{names: []string{"delete", "rm"}}, {names: []string{"edit"}}, {names: []string{"path"}},
+		}},
+		{names: []string{"plugins", "plugin"}, children: []completionNode{
+			{names: []string{"list"}}, {names: []string{"add"}}, {names: []string{"remove", "rm"}},
+		}},
+		{names: []string{"backends", "backend"}, children: leafNodes("doctor")},
+		{names: []string{"skills", "skill"}, children: []completionNode{
+			{names: []string{"list"}}, {names: []string{"add"}}, {names: []string{"info"}}, {names: []string{"remove", "rm"}},
+		}},
+		{names: []string{"tools", "tool"}, children: leafNodes("make", "list")},
+		{names: []string{"hooks"}, children: []completionNode{
+			{names: []string{"list"}}, {names: []string{"add"}}, {names: []string{"remove", "rm"}},
+			{names: []string{"enable"}}, {names: []string{"disable"}},
+		}},
+		{names: []string{"mcp"}, children: []completionNode{
+			{names: []string{"add"}}, {names: []string{"remove", "rm"}}, {names: []string{"enable"}},
+			{names: []string{"disable"}}, {names: []string{"check"}}, {names: []string{"list"}},
+			{names: []string{"permissions"}, children: leafNodes("list", "revoke", "clear")},
+			{names: []string{"tools"}, children: leafNodes("list")},
+			{names: []string{"oauth"}, children: leafNodes("login", "logout", "status")},
+		}},
+		{names: []string{"auth"}, children: leafNodes("openrouter", "chatgpt", "login", "logout", "status", "refresh")},
+		{names: []string{"sandbox"}, children: []completionNode{
+			{names: []string{"policy"}}, {names: []string{"setup"}}, {names: []string{"check"}},
+			{names: []string{"grants"}, children: leafNodes("list", "allow", "deny", "revoke", "clear")},
+		}},
+		{names: []string{"update"}},
+		{names: []string{"upgrade"}},
+		{names: []string{"worktrees", "worktree"}, children: leafNodes("prepare")},
+		{names: []string{"verify"}},
+		{names: []string{"trust"}, children: leafNodes("list", "remove")},
+		{names: []string{"eval"}, children: leafNodes("validate", "run", "bench")},
+		{names: []string{"changes", "change"}, children: []completionNode{
+			{names: []string{"inspect", "status"}}, {names: []string{"commit"}}, {names: []string{"push"}},
+			{names: []string{"pr", "pull-request"}},
+		}},
+		{names: []string{"usage"}, children: leafNodes("report")},
+		{names: []string{"cron"}, children: leafNodes("add", "list", "rm", "pause", "resume", "run")},
+		{names: []string{"repo-info", "repoinfo"}},
+		{names: []string{"serve"}},
+		{names: []string{"acp"}},
+		{names: []string{"help"}},
+		{names: []string{"version"}},
+	},
+}
+
+func leafNodes(names ...string) []completionNode {
+	nodes := make([]completionNode, 0, len(names))
+	for _, name := range names {
+		nodes = append(nodes, completionNode{names: []string{name}})
+	}
+	return nodes
+}
+
+func runCompletions(args []string, stdout io.Writer, stderr io.Writer) int {
+	if len(args) == 1 && (args[0] == "-h" || args[0] == "--help" || args[0] == "help") {
+		if err := writeCompletionsHelp(stdout); err != nil {
+			return exitCrash
+		}
+		return exitSuccess
+	}
+	if len(args) == 0 {
+		return writeExecUsageError(stderr, "shell required. Use `zero completions <bash|zsh|fish|powershell|elvish>`.")
+	}
+	if len(args) != 1 {
+		return writeExecUsageError(stderr, fmt.Sprintf("unexpected completions argument %q", args[1]))
+	}
+
+	contexts := completionContexts(completionRoot)
+	var err error
+	switch strings.ToLower(strings.TrimSpace(args[0])) {
+	case "bash":
+		err = writeBashCompletions(stdout, contexts)
+	case "zsh":
+		err = writeZshCompletions(stdout, contexts)
+	case "fish":
+		err = writeFishCompletions(stdout, contexts)
+	case "powershell":
+		err = writePowerShellCompletions(stdout, contexts)
+	case "elvish":
+		err = writeElvishCompletions(stdout, contexts)
+	default:
+		return writeExecUsageError(stderr, fmt.Sprintf("unsupported shell %q; expected bash, zsh, fish, powershell, or elvish", args[0]))
+	}
+	if err != nil {
+		return exitCrash
+	}
+	return exitSuccess
+}
+
+func writeCompletionsHelp(w io.Writer) error {
+	_, err := fmt.Fprint(w, `Generate shell completion scripts.
+
+Usage:
+  zero completions <shell>
+
+Arguments:
+  <shell>  Target shell: bash, zsh, fish, powershell, or elvish
+
+Examples:
+  source <(zero completions bash)
+  source <(zero completions zsh)
+  zero completions fish > ~/.config/fish/completions/zero.fish
+  zero completions powershell >> $PROFILE
+  eval (zero completions elvish | slurp)
+
+Flags:
+  -h, --help  Show this help
+`)
+	return err
+}
+
+func completionContexts(root completionNode) []completionContext {
+	contexts := []completionContext{}
+	var visit func(completionNode, []string)
+	visit = func(node completionNode, paths []string) {
+		candidates := append([]string{}, node.flags...)
+		transitions := map[string]string{}
+		for _, child := range node.children {
+			candidates = append(candidates, child.names...)
+			for _, path := range paths {
+				for _, name := range child.names {
+					childPath := strings.TrimSpace(path + " " + name)
+					transitions[path+"|"+name] = childPath
+				}
+			}
+		}
+		candidates = uniqueStrings(candidates)
+		for _, path := range paths {
+			contexts = append(contexts, completionContext{path: path, candidates: candidates, transitions: transitions})
+		}
+		for _, child := range node.children {
+			childPaths := make([]string, 0, len(paths)*len(child.names))
+			for _, path := range paths {
+				for _, name := range child.names {
+					childPaths = append(childPaths, strings.TrimSpace(path+" "+name))
+				}
+			}
+			visit(child, childPaths)
+		}
+	}
+	visit(root, []string{""})
+	sort.SliceStable(contexts, func(i, j int) bool { return contexts[i].path < contexts[j].path })
+	return contexts
+}
+
+func uniqueStrings(values []string) []string {
+	seen := map[string]bool{}
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		if value == "" || seen[value] {
+			continue
+		}
+		seen[value] = true
+		result = append(result, value)
+	}
+	return result
+}
+
+func allTransitions(contexts []completionContext) map[string]string {
+	transitions := map[string]string{}
+	for _, context := range contexts {
+		for key, value := range context.transitions {
+			transitions[key] = value
+		}
+	}
+	return transitions
+}
+
+func sortedTransitionKeys(transitions map[string]string) []string {
+	keys := make([]string, 0, len(transitions))
+	for key := range transitions {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func shellWords(values []string) string {
+	return strings.Join(values, " ")
+}
+
+func writeBashCompletions(w io.Writer, contexts []completionContext) error {
+	if _, err := fmt.Fprintln(w, "# bash completion for zero\n_zero() {\n  local cur context token i candidates\n  cur=\"${COMP_WORDS[COMP_CWORD]}\"\n  context=\"\""); err != nil {
+		return err
+	}
+	if err := writePOSIXContextLoop(w, contexts, "  for ((i = 1; i < COMP_CWORD; i++)); do", "    token=\"${COMP_WORDS[i]}\"", "  done"); err != nil {
+		return err
+	}
+	if err := writePOSIXCandidateCase(w, contexts, "  "); err != nil {
+		return err
+	}
+	_, err := fmt.Fprintln(w, "  COMPREPLY=( $(compgen -W \"$candidates\" -- \"$cur\") )\n}\ncomplete -F _zero zero")
+	return err
+}
+
+func writeZshCompletions(w io.Writer, contexts []completionContext) error {
+	if _, err := fmt.Fprintln(w, "#compdef zero\n_zero() {\n  local context token i\n  local -a candidates\n  context=\"\""); err != nil {
+		return err
+	}
+	if err := writePOSIXContextLoop(w, contexts, "  for ((i = 2; i < CURRENT; i++)); do", "    token=\"${words[i]}\"", "  done"); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintln(w, "  case \"$context\" in"); err != nil {
+		return err
+	}
+	for _, context := range contexts {
+		if _, err := fmt.Fprintf(w, "    %q) candidates=(%s) ;;\n", context.path, quotedWords(context.candidates)); err != nil {
+			return err
+		}
+	}
+	_, err := fmt.Fprintln(w, "  esac\n  compadd -- \"${candidates[@]}\"\n}\ncompdef _zero zero")
+	return err
+}
+
+func writePOSIXContextLoop(w io.Writer, contexts []completionContext, start string, token string, end string) error {
+	if _, err := fmt.Fprintln(w, start); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintln(w, token); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintln(w, "    case \"$context|$token\" in"); err != nil {
+		return err
+	}
+	transitions := allTransitions(contexts)
+	for _, key := range sortedTransitionKeys(transitions) {
+		if _, err := fmt.Fprintf(w, "      %q) context=%q ;;\n", key, transitions[key]); err != nil {
+			return err
+		}
+	}
+	if _, err := fmt.Fprintln(w, "    esac"); err != nil {
+		return err
+	}
+	_, err := fmt.Fprintln(w, end)
+	return err
+}
+
+func writePOSIXCandidateCase(w io.Writer, contexts []completionContext, indent string) error {
+	if _, err := fmt.Fprintln(w, indent+"case \"$context\" in"); err != nil {
+		return err
+	}
+	for _, context := range contexts {
+		if _, err := fmt.Fprintf(w, "%s  %q) candidates=%q ;;\n", indent, context.path, shellWords(context.candidates)); err != nil {
+			return err
+		}
+	}
+	_, err := fmt.Fprintln(w, indent+"esac")
+	return err
+}
+
+func quotedWords(values []string) string {
+	quoted := make([]string, 0, len(values))
+	for _, value := range values {
+		quoted = append(quoted, fmt.Sprintf("%q", value))
+	}
+	return strings.Join(quoted, " ")
+}
+
+func writeFishCompletions(w io.Writer, contexts []completionContext) error {
+	if _, err := fmt.Fprintln(w, "# fish completion for zero\nfunction __zero_completion_context\n    set -l context ''\n    set -l tokens (commandline -opc)"); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintln(w, "    for token in $tokens[2..-1]\n        switch \"$context|$token\""); err != nil {
+		return err
+	}
+	transitions := allTransitions(contexts)
+	for _, key := range sortedTransitionKeys(transitions) {
+		if _, err := fmt.Fprintf(w, "            case %q\n                set context %q\n", key, transitions[key]); err != nil {
+			return err
+		}
+	}
+	if _, err := fmt.Fprintln(w, "        end\n    end\n    if test -z \"$context\"\n        echo __root__\n    else\n        echo \"$context\"\n    end\nend"); err != nil {
+		return err
+	}
+	for _, context := range contexts {
+		path := context.path
+		if path == "" {
+			path = "__root__"
+		}
+		if _, err := fmt.Fprintf(w, "complete -c zero -f -n 'test (__zero_completion_context) = %q' -a %q\n", path, shellWords(context.candidates)); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func writePowerShellCompletions(w io.Writer, contexts []completionContext) error {
+	if _, err := fmt.Fprintln(w, "# PowerShell completion for zero\nRegister-ArgumentCompleter -Native -CommandName zero -ScriptBlock {\n    param($wordToComplete, $commandAst, $cursorPosition)\n    $context = ''\n    $elements = @($commandAst.CommandElements)\n    $limit = $elements.Count\n    if ($wordToComplete -ne '' -and $limit -gt 1) { $limit-- }\n    for ($i = 1; $i -lt $limit; $i++) {\n        $token = $elements[$i].Extent.Text\n        switch (\"$context|$token\") {"); err != nil {
+		return err
+	}
+	transitions := allTransitions(contexts)
+	for _, key := range sortedTransitionKeys(transitions) {
+		if _, err := fmt.Fprintf(w, "            '%s' { $context = '%s'; break }\n", key, transitions[key]); err != nil {
+			return err
+		}
+	}
+	if _, err := fmt.Fprintln(w, "        }\n    }\n    $candidates = switch ($context) {"); err != nil {
+		return err
+	}
+	for _, context := range contexts {
+		if _, err := fmt.Fprintf(w, "        '%s' { @(%s) }\n", context.path, powershellWords(context.candidates)); err != nil {
+			return err
+		}
+	}
+	_, err := fmt.Fprintln(w, "    }\n    $candidates | Where-Object { $_ -like \"$wordToComplete*\" } | ForEach-Object {\n        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)\n    }\n}")
+	return err
+}
+
+func powershellWords(values []string) string {
+	quoted := make([]string, 0, len(values))
+	for _, value := range values {
+		quoted = append(quoted, "'"+strings.ReplaceAll(value, "'", "''")+"'")
+	}
+	return strings.Join(quoted, ", ")
+}
+
+func writeElvishCompletions(w io.Writer, contexts []completionContext) error {
+	if _, err := fmt.Fprintln(w, "# Elvish completion for zero\nset edit:completion:arg-completer[zero] = {|@args|\n    var context = ''\n    for token $args[1..-1] {"); err != nil {
+		return err
+	}
+	transitions := allTransitions(contexts)
+	for index, key := range sortedTransitionKeys(transitions) {
+		keyword := "if"
+		if index > 0 {
+			keyword = "} elif"
+		}
+		if _, err := fmt.Fprintf(w, "        %s (eq $context'|'$token %q) {\n            set context = %q\n", keyword, key, transitions[key]); err != nil {
+			return err
+		}
+	}
+	if _, err := fmt.Fprintln(w, "        }\n    }"); err != nil {
+		return err
+	}
+	for index, context := range contexts {
+		keyword := "if"
+		if index > 0 {
+			keyword = "} elif"
+		}
+		if _, err := fmt.Fprintf(w, "    %s (eq $context %q) {\n        put %s\n", keyword, context.path, shellWords(context.candidates)); err != nil {
+			return err
+		}
+	}
+	_, err := fmt.Fprintln(w, "    }\n}")
+	return err
+}

internal/cli/completions_test.go

@@ -0,0 +1,175 @@
+package cli
+
+import (
+	"bytes"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+func TestCompletionsHelpAndRootHelp(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	if code := runWithDeps([]string{"completions", "--help"}, &stdout, &stderr, appDeps{}); code != exitSuccess {
+		t.Fatalf("completion help exit code = %d, want %d: %s", code, exitSuccess, stderr.String())
+	}
+	for _, want := range []string{
+		"zero completions <shell>",
+		"bash, zsh, fish, powershell, or elvish",
+		"source <(zero completions bash)",
+		"~/.config/fish/completions/zero.fish",
+		"eval (zero completions elvish | slurp)",
+	} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Errorf("completion help missing %q:\n%s", want, stdout.String())
+		}
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := runWithDeps([]string{"--help"}, &stdout, &stderr, appDeps{}); code != exitSuccess {
+		t.Fatalf("root help exit code = %d, want %d: %s", code, exitSuccess, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "completions Generate shell completion scripts") {
+		t.Fatalf("root help does not list completions command:\n%s", stdout.String())
+	}
+}
+
+func TestCompletionsRejectsMissingUnknownAndExtraShellArguments(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "missing", args: []string{"completions"}, want: "shell required"},
+		{name: "unknown", args: []string{"completions", "nu"}, want: "unsupported shell"},
+		{name: "extra", args: []string{"completions", "bash", "extra"}, want: "unexpected completions argument"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			if code := runWithDeps(test.args, &stdout, &stderr, appDeps{}); code != exitUsage {
+				t.Fatalf("exit code = %d, want %d: %s", code, exitUsage, stderr.String())
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q, want empty", stdout.String())
+			}
+			if !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("stderr = %q, want substring %q", stderr.String(), test.want)
+			}
+		})
+	}
+}
+
+func TestCompletionsGeneratesEverySupportedShell(t *testing.T) {
+	tests := []struct {
+		shell       string
+		marker      string
+		syntaxShell string
+	}{
+		{shell: "bash", marker: "complete -F _zero zero", syntaxShell: "bash"},
+		{shell: "zsh", marker: "#compdef zero", syntaxShell: "zsh"},
+		{shell: "fish", marker: "complete -c zero"},
+		{shell: "powershell", marker: "Register-ArgumentCompleter -Native -CommandName zero"},
+		{shell: "elvish", marker: "edit:completion:arg-completer[zero]"},
+	}
+	for _, test := range tests {
+		t.Run(test.shell, func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			if code := runWithDeps([]string{"completions", test.shell}, &stdout, &stderr, appDeps{}); code != exitSuccess {
+				t.Fatalf("exit code = %d, want %d: %s", code, exitSuccess, stderr.String())
+			}
+			if !strings.Contains(stdout.String(), test.marker) {
+				t.Fatalf("%s completion missing marker %q:\n%s", test.shell, test.marker, stdout.String())
+			}
+			for _, want := range []string{"daemon", "mcp oauth", "sandbox grants", "--output-format"} {
+				if !strings.Contains(stdout.String(), want) {
+					t.Errorf("%s completion missing %q", test.shell, want)
+				}
+			}
+			script := stdout.String()
+			switch test.shell {
+			case "fish":
+				assertBalancedFishBlocks(t, script)
+			case "powershell", "elvish":
+				assertBalancedBraces(t, script)
+			}
+			if test.syntaxShell != "" {
+				assertNativeShellSyntax(t, test.syntaxShell, script)
+			}
+		})
+	}
+}
+
+func assertBalancedBraces(t *testing.T, script string) {
+	t.Helper()
+	if opens, closes := strings.Count(script, "{"), strings.Count(script, "}"); opens != closes {
+		t.Errorf("unbalanced braces: %d opening, %d closing", opens, closes)
+	}
+}
+
+func assertBalancedFishBlocks(t *testing.T, script string) {
+	t.Helper()
+	depth := 0
+	for _, line := range strings.Split(script, "\n") {
+		fields := strings.Fields(line)
+		if len(fields) == 0 {
+			continue
+		}
+		switch fields[0] {
+		case "function", "for", "switch", "if":
+			depth++
+		case "end":
+			depth--
+			if depth < 0 {
+				t.Fatal("fish completion closes a block before one is opened")
+			}
+		}
+	}
+	if depth != 0 {
+		t.Errorf("fish completion has %d unclosed blocks", depth)
+	}
+}
+
+func assertNativeShellSyntax(t *testing.T, shell, script string) {
+	t.Helper()
+	path, err := exec.LookPath(shell)
+	if err != nil {
+		t.Skipf("%s is not installed", shell)
+	}
+	command := exec.Command(path, "-n")
+	command.Stdin = strings.NewReader(script)
+	if output, err := command.CombinedOutput(); err != nil {
+		t.Fatalf("%s syntax check failed: %v\n%s", shell, err, output)
+	}
+}
+
+func TestCompletionTreeCoversAliasesNestingAndCommonFlags(t *testing.T) {
+	contexts := completionContexts(completionRoot)
+	byPath := make(map[string][]string, len(contexts))
+	for _, context := range contexts {
+		byPath[context.path] = context.candidates
+	}
+
+	assertCandidates(t, byPath[""], "sessions", "session", "plugins", "plugin", "worktrees", "worktree", "--add-dir", "--theme", "-p", "--prompt")
+	assertCandidates(t, byPath["exec"], "--model", "--cwd", "--worktree", "--output-format", "--resume", "--skip-permissions-unsafe")
+	assertCandidates(t, byPath["daemon"], "start", "stop", "status", "run", "attach")
+	assertCandidates(t, byPath["mcp oauth"], "login", "logout", "status")
+	assertCandidates(t, byPath["sandbox grants"], "list", "allow", "deny", "revoke", "clear")
+	assertCandidates(t, byPath["completions"], "bash", "zsh", "fish", "powershell", "elvish")
+}
+
+func assertCandidates(t *testing.T, got []string, wants ...string) {
+	t.Helper()
+	set := make(map[string]bool, len(got))
+	for _, candidate := range got {
+		set[candidate] = true
+	}
+	for _, want := range wants {
+		if !set[want] {
+			t.Errorf("candidates %v do not contain %q", got, want)
+		}
+	}
+}

internal/trace/emit.go

@@ -137,6 +137,27 @@ func WriteNDJSON(w io.Writer, t *TurnTrace) error {
 			return err
 		}
 	}
+	for _, event := range t.TaskStates {
+		if err := enc.Encode(map[string]any{
+			"type":                 "task_state",
+			"revision":             event.Revision,
+			"status":               event.Status,
+			"plan_pending":         event.PlanPending,
+			"plan_in_progress":     event.PlanInProgress,
+			"plan_completed":       event.PlanCompleted,
+			"plan_failed":          event.PlanFailed,
+			"tools_succeeded":      event.ToolsSucceeded,
+			"tools_failed":         event.ToolsFailed,
+			"verification_passed":  event.VerificationPassed,
+			"verification_failed":  event.VerificationFailed,
+			"verification_outcome": event.VerificationOutcome,
+			"changed_file_count":   event.ChangedFileCount,
+			"completion_decision":  event.CompletionDecision,
+			"plan_parity":          event.PlanParity,
+		}); err != nil {
+			return err
+		}
+	}
 	return nil
 }
 
@@ -206,6 +227,15 @@ func WriteText(w io.Writer, t *TurnTrace) error {
 				event.Truncated, event.Reason, event.SpillCreated)
 		}
 	}
+	if len(t.TaskStates) > 0 {
+		latest := t.TaskStates[len(t.TaskStates)-1]
+		write("task state: revision=%d status=%s plan=%d/%d/%d/%d tools=%d/%d verification=%d/%d(%s) files=%d plan_parity=%s completion=%s\n",
+			latest.Revision, latest.Status, latest.PlanPending, latest.PlanInProgress,
+			latest.PlanCompleted, latest.PlanFailed, latest.ToolsSucceeded,
+			latest.ToolsFailed, latest.VerificationPassed, latest.VerificationFailed,
+			latest.VerificationOutcome, latest.ChangedFileCount, latest.PlanParity,
+			latest.CompletionDecision)
+	}
 	return firstErr
 }
 

internal/trace/parse.go

@@ -132,6 +132,26 @@ func ReadNDJSON(r io.Reader) (*TurnTrace, error) {
 				Reason:                  stringField(obj, "reason"),
 				SpillCreated:            boolField(obj, "spill_created"),
 			})
+		case "task_state":
+			if !sawTraceHeader {
+				return nil, errors.New("parse trace: not a valid NDJSON trace (no type:trace header)")
+			}
+			t.TaskStates = append(t.TaskStates, TaskStateEvent{
+				Revision:            int(parseInt64(obj["revision"])),
+				Status:              stringField(obj, "status"),
+				PlanPending:         int(parseInt64(obj["plan_pending"])),
+				PlanInProgress:      int(parseInt64(obj["plan_in_progress"])),
+				PlanCompleted:       int(parseInt64(obj["plan_completed"])),
+				PlanFailed:          int(parseInt64(obj["plan_failed"])),
+				ToolsSucceeded:      int(parseInt64(obj["tools_succeeded"])),
+				ToolsFailed:         int(parseInt64(obj["tools_failed"])),
+				VerificationPassed:  int(parseInt64(obj["verification_passed"])),
+				VerificationFailed:  int(parseInt64(obj["verification_failed"])),
+				VerificationOutcome: stringField(obj, "verification_outcome"),
+				ChangedFileCount:    int(parseInt64(obj["changed_file_count"])),
+				CompletionDecision:  stringField(obj, "completion_decision"),
+				PlanParity:          stringField(obj, "plan_parity"),
+			})
 		default:
 			// Unknown event type: tolerate (forward-compat) but only after a
 			// header has been seen.
@@ -152,8 +172,8 @@ func ReadNDJSON(r io.Reader) (*TurnTrace, error) {
 	if !sawTraceHeader {
 		return nil, errors.New("parse trace: non-empty input had no type:trace header")
 	}
-	if len(t.Spans) == 0 && len(t.Counters) == 0 && len(t.PrefixHashes) == 0 && len(t.OutputBudgets) == 0 {
-		return nil, errors.New("parse trace: header present but no spans, counters, or prefix hashes recovered (corrupt or truncated)")
+	if len(t.Spans) == 0 && len(t.Counters) == 0 && len(t.PrefixHashes) == 0 && len(t.OutputBudgets) == 0 && len(t.TaskStates) == 0 {
+		return nil, errors.New("parse trace: header present but no events recovered (corrupt or truncated)")
 	}
 	return t, nil
 }

internal/trace/recorder.go

@@ -29,6 +29,10 @@ type Recorder struct {
 	firstActionStamped  bool
 }
 
+// maxTaskStateEvents bounds trace growth in pathological long runs. Once full,
+// the latest aggregate replaces the tail so final state is never lost.
+const maxTaskStateEvents = 128
+
 // NewRecorder returns a ready recorder. sessionID correlates with the agent
 // session (Options.SessionID); runID is a per-Run sequence; profile is an
 // optional label (e.g. "cold", "warm") for benchmark runs.
@@ -203,6 +207,24 @@ func (r *Recorder) EmitOutputBudget(event OutputBudgetEvent) {
 	r.tr.OutputBudgets = append(r.tr.OutputBudgets, event)
 }
 
+// EmitTaskState records one content-free structured task snapshot. Calls retain
+// event order so revisions can be replayed alongside the tool and turn stream.
+func (r *Recorder) EmitTaskState(event TaskStateEvent) {
+	if r == nil {
+		return
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.finished {
+		return
+	}
+	if len(r.tr.TaskStates) < maxTaskStateEvents {
+		r.tr.TaskStates = append(r.tr.TaskStates, event)
+		return
+	}
+	r.tr.TaskStates[len(r.tr.TaskStates)-1] = event
+}
+
 // Finish stamps CompletedAt, derives each span's parent (by interval
 // containment) and exclusive time, and returns a snapshot of the trace. Calling
 // Finish more than once returns the same snapshot.
@@ -223,6 +245,7 @@ func (r *Recorder) Finish() *TurnTrace {
 	snap.Counters = append([]Counter(nil), r.tr.Counters...)
 	snap.PrefixHashes = append([]PrefixHash(nil), r.tr.PrefixHashes...)
 	snap.OutputBudgets = append([]OutputBudgetEvent(nil), r.tr.OutputBudgets...)
+	snap.TaskStates = append([]TaskStateEvent(nil), r.tr.TaskStates...)
 	return &snap
 }
 

internal/trace/task_state_test.go

@@ -0,0 +1,66 @@
+package trace
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestTaskStateTraceRoundTripContainsNoTaskContent(t *testing.T) {
+	recorder := NewRecorder("session", "run", "")
+	recorder.Start()
+	event := TaskStateEvent{
+		Revision:            4,
+		Status:              "active",
+		PlanPending:         2,
+		PlanCompleted:       1,
+		ToolsSucceeded:      3,
+		ToolsFailed:         1,
+		VerificationPassed:  1,
+		VerificationOutcome: "passed",
+		ChangedFileCount:    2,
+		PlanParity:          "match",
+	}
+	recorder.EmitTaskState(event)
+
+	var output bytes.Buffer
+	if err := WriteNDJSON(&output, recorder.Finish()); err != nil {
+		t.Fatalf("WriteNDJSON: %v", err)
+	}
+	if strings.Contains(output.String(), "secret objective") || strings.Contains(output.String(), "private.go") {
+		t.Fatalf("task content leaked into trace: %s", output.String())
+	}
+	if strings.Contains(output.String(), "objective_hash") {
+		t.Fatalf("trace contains a confirmable objective fingerprint: %s", output.String())
+	}
+	parsed, err := ReadNDJSON(strings.NewReader(output.String()))
+	if err != nil {
+		t.Fatalf("ReadNDJSON: %v", err)
+	}
+	if len(parsed.TaskStates) != 1 || parsed.TaskStates[0] != event {
+		t.Fatalf("unexpected round trip: %#v", parsed.TaskStates)
+	}
+}
+
+func TestTaskStateIsDocumentedAsOptionalTraceEvent(t *testing.T) {
+	for _, key := range OptionalEventKeys() {
+		if key == "task_state" {
+			return
+		}
+	}
+	t.Fatal("task_state missing from OptionalEventKeys")
+}
+
+func TestTaskStateTraceIsBoundedAndRetainsLatestSnapshot(t *testing.T) {
+	recorder := NewRecorder("session", "run", "")
+	for revision := 1; revision <= maxTaskStateEvents+20; revision++ {
+		recorder.EmitTaskState(TaskStateEvent{Revision: revision})
+	}
+	events := recorder.Finish().TaskStates
+	if len(events) != maxTaskStateEvents {
+		t.Fatalf("task state events = %d, want cap %d", len(events), maxTaskStateEvents)
+	}
+	if got := events[len(events)-1].Revision; got != maxTaskStateEvents+20 {
+		t.Fatalf("latest revision = %d, want %d", got, maxTaskStateEvents+20)
+	}
+}

internal/trace/trace.go

@@ -103,6 +103,27 @@ type OutputBudgetEvent struct {
 	SpillCreated            bool   `json:"spill_created"`
 }
 
+// TaskStateEvent is a content-free snapshot of the run's structured task
+// projection. Objective text, plan content, tool output, file paths, and
+// confirmable content fingerprints are deliberately excluded so tracing cannot
+// become a secret-bearing side channel.
+type TaskStateEvent struct {
+	Revision            int    `json:"revision"`
+	Status              string `json:"status"`
+	PlanPending         int    `json:"plan_pending"`
+	PlanInProgress      int    `json:"plan_in_progress"`
+	PlanCompleted       int    `json:"plan_completed"`
+	PlanFailed          int    `json:"plan_failed"`
+	ToolsSucceeded      int    `json:"tools_succeeded"`
+	ToolsFailed         int    `json:"tools_failed"`
+	VerificationPassed  int    `json:"verification_passed"`
+	VerificationFailed  int    `json:"verification_failed"`
+	VerificationOutcome string `json:"verification_outcome,omitempty"`
+	ChangedFileCount    int    `json:"changed_file_count"`
+	CompletionDecision  string `json:"completion_decision,omitempty"`
+	PlanParity          string `json:"plan_parity"`
+}
+
 // TurnTrace is the finished record for one agent.Run. It is the value
 // emitters serialize; it is not mutated after Finish returns a snapshot.
 type TurnTrace struct {
@@ -118,6 +139,7 @@ type TurnTrace struct {
 	Counters            []Counter           `json:"counters"`
 	PrefixHashes        []PrefixHash        `json:"prefix_hashes,omitempty"`
 	OutputBudgets       []OutputBudgetEvent `json:"output_budgets,omitempty"`
+	TaskStates          []TaskStateEvent    `json:"task_states,omitempty"`
 }
 
 // PrefixHash is one fingerprint of the prompt prefix emitted by an agent run.
@@ -280,5 +302,6 @@ func OptionalEventKeys() []string {
 		"counter:" + CounterPrefixDrift,
 		"counter:" + CounterPostureEscalations,
 		"event:prefix_hash",
+		"task_state",
 	}
 }