fix(sandbox): clarify scoped permission prompts

internal/sandbox/engine_test.go

@@ -2,6 +2,7 @@ package sandbox
 
 import (
 	"context"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -485,6 +486,28 @@ func TestEngineDeniesOutOfWorkspacePaths(t *testing.T) {
 	}
 }
 
+func TestEnginePromptsForOutOfWorkspaceReadWithReadSpecificReason(t *testing.T) {
+	root := t.TempDir()
+	outside := outsideDefaultTempPath(root, "external")
+	engine := NewEngine(EngineOptions{WorkspaceRoot: root, Policy: DefaultPolicy()})
+
+	decision := engine.Evaluate(context.Background(), Request{
+		ToolName:      "list_directory",
+		SideEffect:    SideEffectRead,
+		Permission:    PermissionAllow,
+		WorkspaceRoot: root,
+		Args:          map[string]any{"path": outside},
+	})
+
+	want := fmt.Sprintf("Reading %s requires access outside the workspace.", outside)
+	if decision.Action != ActionPrompt || decision.Block == nil || !decision.Block.Recoverable {
+		t.Fatalf("outside read decision = %#v, want recoverable prompt", decision)
+	}
+	if decision.Reason != want || decision.Block.Reason != want {
+		t.Fatalf("outside read reasons = decision %q, block %q; want %q", decision.Reason, decision.Block.Reason, want)
+	}
+}
+
 func TestEnginePrecheckReportsBlocksBeforeExecution(t *testing.T) {
 	root := t.TempDir()
 	outside := outsideDefaultTempPath(root, "escape.txt")

internal/sandbox/scope.go

@@ -203,11 +203,24 @@ func dedupeScopeRoots(roots []string) []string {
 // only on outside_workspace results. The returned block always carries
 // the caller's original requestedPath.
 func (s *Scope) validate(requestedPath string) *pathBlock {
-	return s.validateAgainstRoots(requestedPath, s.Roots())
+	return withOutsideWorkspaceAccessReason(s.validateAgainstRoots(requestedPath, s.Roots()), requestedPath, SideEffectWrite)
 }
 
 func (s *Scope) validateRead(requestedPath string) *pathBlock {
-	return s.validateAgainstRoots(requestedPath, s.ReadRoots())
+	return withOutsideWorkspaceAccessReason(s.validateAgainstRoots(requestedPath, s.ReadRoots()), requestedPath, SideEffectRead)
+}
+
+func withOutsideWorkspaceAccessReason(block *pathBlock, requestedPath string, sideEffect SideEffect) *pathBlock {
+	if block == nil || block.Code != BlockOutsideWorkspace || !strings.Contains(block.Reason, " is outside the workspace") {
+		return block
+	}
+	switch sideEffect {
+	case SideEffectRead:
+		block.Reason = fmt.Sprintf("Reading %s requires access outside the workspace.", requestedPath)
+	case SideEffectWrite, SideEffectOutOfWorkspace:
+		block.Reason = fmt.Sprintf("Writing to %s requires access outside the workspace. Use /add-dir or --add-dir to allow writes there.", requestedPath)
+	}
+	return block
 }
 
 func (s *Scope) validateAgainstRoots(requestedPath string, roots []string) *pathBlock {

internal/sandbox/scope_test.go

@@ -1,6 +1,7 @@
 package sandbox
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -279,6 +280,45 @@ func TestScopeValidateAllowsAnyRootButRelativeOnlyWorkspace(t *testing.T) {
 	}
 }
 
+func TestScopeValidateReadExplainsReadAccessOutsideWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	scope, err := NewScope(workspace, nil)
+	if err != nil {
+		t.Fatalf("NewScope: %v", err)
+	}
+
+	outside := outsideDefaultTempPath(workspace, "elsewhere.txt")
+	block := scope.validateRead(outside)
+	if block == nil {
+		t.Fatal("validateRead(outside workspace) = nil, want block")
+	}
+	want := fmt.Sprintf("Reading %s requires access outside the workspace.", outside)
+	if block.Reason != want {
+		t.Fatalf("block.Reason = %q, want %q", block.Reason, want)
+	}
+	if strings.Contains(block.Reason, "--add-dir") || strings.Contains(block.Reason, "writes") {
+		t.Fatalf("read block reason must not suggest write access: %q", block.Reason)
+	}
+}
+
+func TestScopeValidateWriteExplainsWriteAccessOutsideWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	scope, err := NewScope(workspace, nil)
+	if err != nil {
+		t.Fatalf("NewScope: %v", err)
+	}
+
+	outside := outsideDefaultTempPath(workspace, "elsewhere.txt")
+	block := scope.validate(outside)
+	if block == nil {
+		t.Fatal("validate(outside workspace) = nil, want block")
+	}
+	want := fmt.Sprintf("Writing to %s requires access outside the workspace. Use /add-dir or --add-dir to allow writes there.", outside)
+	if block.Reason != want {
+		t.Fatalf("block.Reason = %q, want %q", block.Reason, want)
+	}
+}
+
 func TestScopeValidateKeepsSymlinkTraversalProtection(t *testing.T) {
 	workspace := t.TempDir()
 	outside := outsideDefaultTempPath(workspace, "symlink-target")

internal/tui/model.go

@@ -2212,7 +2212,16 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			}
 			return m, nil
 		}
-		promptRow := permissionTranscriptRow(permissionEventFromRequest(msg.request))
+		promptEvent := permissionEventFromRequest(msg.request)
+		promptRow := permissionTranscriptRow(promptEvent)
+		// The focused modal owns the actionable reason while the decision is
+		// pending. Keep only structured block context in the transcript row so
+		// the same explanation is not shown immediately above the card.
+		if promptEvent.Block == nil {
+			promptRow.detail = ""
+		} else {
+			promptRow.detail = permissionBlockDetail(promptEvent)
+		}
 		promptRow.runID = msg.runID
 		m.transcript = appendTranscriptRow(m.transcript, promptRow)
 		m.pendingPermission = &pendingPermissionPrompt{

internal/tui/model_test.go

@@ -1606,6 +1606,9 @@ func TestPermissionRequestShowsFocusedPrompt(t *testing.T) {
 	if strings.Contains(view, "risk:") || strings.Contains(view, "risk=") {
 		t.Fatalf("focused permission prompt must not render risk labels, got %q", view)
 	}
+	if count := strings.Count(view, request.Reason); count != 1 {
+		t.Fatalf("focused permission reason rendered %d times, want once:\n%s", count, view)
+	}
 }
 
 func TestPermissionPromptChoicesResolveDecision(t *testing.T) {
@@ -1720,6 +1723,34 @@ func TestPermissionRowRendersSandboxBlocks(t *testing.T) {
 	}
 }
 
+func TestPermissionRowRendersIdenticalEventAndBlockReasonOnce(t *testing.T) {
+	const reason = "Reading /home/dev/.nvm requires access outside the workspace."
+	event := agent.PermissionEvent{
+		ToolCallID:     "call_read",
+		ToolName:       "list_directory",
+		Action:         agent.PermissionActionDeny,
+		DecisionAction: agent.PermissionDecisionDeny,
+		SideEffect:     "read",
+		Reason:         reason,
+		Scope:          "/home/dev/.nvm",
+		Block: &sandbox.Block{
+			Code:   sandbox.BlockOutsideWorkspace,
+			Path:   "/home/dev/.nvm",
+			Reason: reason,
+		},
+	}
+
+	row := permissionTranscriptRow(event)
+	if count := strings.Count(event.Reason+"\n"+row.detail, reason); count != 1 {
+		t.Fatalf("permission reason represented %d times, want once: detail=%q", count, row.detail)
+	}
+	for _, want := range []string{"denied by user", "outside workspace", "path: /home/dev/.nvm"} {
+		if !strings.Contains(row.detail, want) {
+			t.Fatalf("permission detail missing %q: %q", want, row.detail)
+		}
+	}
+}
+
 func TestAppendTranscriptRowDedupesRuntimeRowsByID(t *testing.T) {
 	event := agent.PermissionEvent{
 		ToolCallID: "call_1",

internal/tui/permission_prompt_test.go

@@ -126,6 +126,29 @@ func TestPermissionPromptMapsEscalatedSandboxReason(t *testing.T) {
 	}
 }
 
+func TestPermissionPromptWrapsLongReasonWithoutTruncating(t *testing.T) {
+	request := agent.PermissionRequest{
+		ToolName:   "list_directory",
+		SideEffect: "read",
+		Reason:     "Reading /home/dev/projects/a-very-long-directory-name/with/nested/configuration requires access outside the workspace.",
+		AvailableDecisions: []agent.PermissionDecisionAction{
+			agent.PermissionDecisionAllow,
+			agent.PermissionDecisionDeny,
+		},
+	}
+
+	card, _ := renderFocusedPermissionPrompt(request, 0, false, "", 60)
+	got := plainRender(t, card)
+	for _, want := range []string{"Reading", "/home/dev/projects", "requires access outside the workspace."} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("permission card truncated reason; missing %q:\n%s", want, got)
+		}
+	}
+	if strings.Contains(got, "…") {
+		t.Fatalf("permission card must wrap the decision reason instead of truncating it:\n%s", got)
+	}
+}
+
 func TestPermissionOptionsExposePersistentCommandPrefixApproval(t *testing.T) {
 	request := agent.PermissionRequest{
 		ToolName:      "bash",

internal/tui/rendering.go

@@ -1131,7 +1131,13 @@ func renderFocusedPermissionPrompt(request agent.PermissionRequest, cursor int,
 	}
 	lines := []string{top, body}
 	if reason := permissionDisplayReason(request.Reason); reason != "" {
-		lines = append(lines, fill(zeroTheme.muted).Render(reason))
+		reasonWidth := width
+		if widthTier(width) != tierTiny {
+			reasonWidth = maxInt(1, width-4)
+		}
+		for _, line := range wrapPlainText(reason, reasonWidth) {
+			lines = append(lines, fill(zeroTheme.muted).Render(line))
+		}
 	}
 	// Surface exactly what the grant covers (file/dir/host) so "always" is a
 	// clear, bounded choice rather than a blind tool-wide yes.

internal/tui/transcript.go

@@ -398,8 +398,10 @@ func permissionDetailText(event agent.PermissionEvent) string {
 	if event.GrantMatched {
 		parts = append(parts, "approved by saved permission")
 	}
-	if event.Reason != "" {
-		parts = append(parts, permissionDisplayReason(event.Reason))
+	if event.Action == agent.PermissionActionPrompt {
+		if reason := permissionDisplayReason(event.Reason); reason != "" {
+			parts = append(parts, reason)
+		}
 	}
 	if event.Block != nil {
 		parts = append(parts, permissionBlockDetail(event))
@@ -438,7 +440,9 @@ func permissionBlockDetail(event agent.PermissionEvent) string {
 	if path := strings.TrimSpace(event.Block.Path); path != "" {
 		parts = append(parts, "path: "+path)
 	}
-	if reason := permissionDisplayReason(event.Block.Reason); reason != "" {
+	reason := permissionDisplayReason(event.Block.Reason)
+	eventReason := permissionDisplayReason(event.Reason)
+	if reason != "" && reason != eventReason {
 		parts = append(parts, reason)
 	}
 	return strings.Join(parts, "  ")