feat(agent): add PermissionModePlan for interactive read-only planning

internal/agent/loop.go

@@ -898,12 +898,13 @@
 		}, nil
 	}
 	tool, toolFound := registry.Get(call.Name)
-	if permissionMode == PermissionModeSpecDraft && toolFound && !ToolAdvertised(tool, permissionMode) {
+	if (permissionMode == PermissionModeSpecDraft || permissionMode == PermissionModePlan) && toolFound && !ToolAdvertised(tool, permissionMode) {
+		modeName := string(permissionMode)
 		return ToolResult{
 			ToolCallID:   call.ID,
 			Name:         call.Name,
 			Status:       tools.StatusError,
-			Output:       `Error: Tool "` + call.Name + `" is not available in spec-draft mode.`,
+			Output:       `Error: Tool "` + call.Name + `" is not available in ` + modeName + ` mode.`,
 			DenialReason: DenialFiltered,
 		}, nil
 	}
@@ -2691,7 +2692,7 @@
 	// (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.)
 	eager := make([]zeroruntime.ToolDefinition, 0, len(visible))
 	loadedTail := make([]zeroruntime.ToolDefinition, 0)
 	var hiddenTools []tools.Tool
 	for _, tool := range visible {
@@ -2857,6 +2858,9 @@
 	if permissionMode == PermissionModeSpecDraft {
 		return toolAdvertisedInSpecDraft(tool)
 	}
+	if permissionMode == PermissionModePlan {
+		return toolAdvertisedInPlan(tool)
+	}
 	if permissionMode == PermissionModeAuto {
 		return tool.Safety().Permission == tools.PermissionAllow || tool.Safety().AdvertiseInAuto
 	}
@@ -2889,6 +2893,18 @@
 	return safety.SideEffect == tools.SideEffectRead && safety.Permission == tools.PermissionAllow
 }
 
+// toolAdvertisedInPlan mirrors toolAdvertisedInSpecDraft: the agent may only
+// read the workspace, ask the user, and shape the plan with update_plan. No
+// mutating tool is advertised, so plan mode stays strictly read-only.
+func toolAdvertisedInPlan(tool tools.Tool) bool {
+	switch tool.Name() {
+	case "ask_user", "update_plan":
+		return true
+	}
+	safety := tool.Safety()
+	return safety.SideEffect == tools.SideEffectRead && safety.Permission == tools.PermissionAllow
+}
+
 func stopReasonFromToolResult(result ToolResult) StopReason {
 	if result.Meta == nil {
 		return ""

internal/agent/loop_test.go

@@ -725,9 +725,6 @@ func TestRunReportsTruncationFinishReason(t *testing.T) {
 	if result.FinishReason != zeroruntime.FinishReasonLength {
 		t.Fatalf("FinishReason = %q, want %q", result.FinishReason, zeroruntime.FinishReasonLength)
 	}
-	if !result.Truncated() {
-		t.Fatal("Truncated() = false, want true for a length-capped response")
-	}
 	if result.TruncationNotice() == "" {
 		t.Fatal("TruncationNotice() empty for a truncated response")
 	}
@@ -745,7 +742,7 @@ func TestRunNormalCompletionIsNotTruncated(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if result.Truncated() || result.TruncationNotice() != "" {
+	if result.TruncationNotice() != "" {
 		t.Fatalf("normal completion reported as truncated: reason=%q", result.FinishReason)
 	}
 }
@@ -3166,6 +3163,121 @@ func TestSpecDraftDeniesBashToolCalls(t *testing.T) {
 	}
 }
 
+func TestPlanModeAdvertisesOnlySafeTools(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	for _, tool := range tools.CoreTools(root) {
+		registry.Register(tool)
+	}
+	provider := &mockProvider{
+		turns: [][]zeroruntime.StreamEvent{{
+			{Type: zeroruntime.StreamEventText, Content: "done"},
+			{Type: zeroruntime.StreamEventDone},
+		}},
+	}
+
+	_, err := Run(context.Background(), "plan", provider, Options{
+		Registry:       registry,
+		PermissionMode: PermissionModePlan,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	names := map[string]bool{}
+	for _, definition := range provider.requests[0].Tools {
+		names[definition.Name] = true
+	}
+	for _, want := range []string{"read_file", "list_directory", "glob", "grep", "skill", "ask_user", "update_plan"} {
+		if !names[want] {
+			t.Fatalf("plan mode tools missing %q from %#v", want, names)
+		}
+	}
+	for _, denied := range []string{"write_file", "edit_file", "apply_patch", "bash", "web_fetch"} {
+		if names[denied] {
+			t.Fatalf("plan mode advertised denied tool %q in %#v", denied, names)
+		}
+	}
+}
+
+func TestPlanModeDeniesHiddenToolCalls(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewWriteFileTool(root))
+	provider := providerCallingWriteFileThenAnswer("done")
+
+	result, err := Run(context.Background(), "plan", provider, Options{
+		Registry:       registry,
+		PermissionMode: PermissionModePlan,
+		MaxTurns:       2,
+	})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("expected final answer after denial, got %q", result.FinalAnswer)
+	}
+	var denied string
+	for _, message := range result.Messages {
+		if message.Role == zeroruntime.MessageRoleTool {
+			denied = message.Content
+			break
+		}
+	}
+	if !strings.Contains(denied, "not available in plan mode") {
+		t.Fatalf("expected plan mode denial, got %q", denied)
+	}
+	if _, err := os.Stat(filepath.Join(root, "notes.txt")); !os.IsNotExist(err) {
+		t.Fatalf("write_file should not have written notes.txt, stat err=%v", err)
+	}
+}
+
+func TestPlanModeDeniesBashToolCalls(t *testing.T) {
+	root := t.TempDir()
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewBashTool(root))
+	provider := &mockProvider{
+		turns: [][]zeroruntime.StreamEvent{
+			{
+				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "bash"},
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"command":"printf ran > ran.txt"}`},
+				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-1"},
+				{Type: zeroruntime.StreamEventDone},
+			},
+			{
+				{Type: zeroruntime.StreamEventText, Content: "done"},
+				{Type: zeroruntime.StreamEventDone},
+			},
+		},
+	}
+
+	result, err := Run(context.Background(), "plan", provider, Options{
+		Registry:       registry,
+		PermissionMode: PermissionModePlan,
+		MaxTurns:       2,
+	})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("expected final answer after denial, got %q", result.FinalAnswer)
+	}
+	var denied string
+	for _, message := range result.Messages {
+		if message.Role == zeroruntime.MessageRoleTool {
+			denied = message.Content
+			break
+		}
+	}
+	if !strings.Contains(denied, "not available in plan mode") {
+		t.Fatalf("expected plan mode bash denial, got %q", denied)
+	}
+	if _, err := os.Stat(filepath.Join(root, "ran.txt")); !os.IsNotExist(err) {
+		t.Fatalf("bash should not have written ran.txt, stat err=%v", err)
+	}
+}
+
 func TestRunStopsWhenSubmitSpecReturnsReviewControl(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()

internal/agent/types.go

@@ -24,6 +24,12 @@ const (
 	PermissionModeAsk       PermissionMode = "ask"
 	PermissionModeUnsafe    PermissionMode = "unsafe"
 	PermissionModeSpecDraft PermissionMode = "spec-draft"
+	// PermissionModePlan is an interactive, read-only planning mode toggled from
+	// the TUI with /plan. It applies to the CURRENT session (unlike spec-draft,
+	// which drafts in a separate session): the agent may inspect the workspace
+	// and shape the plan with update_plan/ask_user, but no mutating tool is
+	// advertised, so it cannot write files, run shell, or implement while planning.
+	PermissionModePlan PermissionMode = "plan"
 	// PermissionModeMemberAuto is a headless mode for swarm/specialist MEMBERS: it
 	// advertises the in-workspace mutators a member needs to build (write/edit +
 	// shell) on top of the Auto set, while the sandbox engine still gates them at
@@ -331,13 +337,6 @@ type Result struct {
 	IncompleteReason string
 }
 
-// Truncated reports whether the final response ended abnormally (cut off at the
-// output token cap or withheld by a content filter) rather than completing
-// naturally. Callers can use it to warn the user that FinalAnswer is incomplete.
-func (result Result) Truncated() bool {
-	return result.FinishReason != ""
-}
-
 // TruncationNotice returns a user-facing warning when the final response was
 // truncated, or "" for a normal completion. Shared by the CLI and TUI so the
 // wording stays consistent.