Clarify autonomy tier messages in plain language

Author: Patel230

cmd/autonomy_tiers.go

@@ -48,18 +48,19 @@ func nextAutonomyTier(level engine.AutonomyLevel) engine.AutonomyLevel {
 	return containerAutonomyTiers[(autonomyTierIndex(level)+1)%len(containerAutonomyTiers)]
 }
 
-func autonomyTierHint(level engine.AutonomyLevel) string {
+// autonomyTierDescription is plain-language copy shown when the user changes tier (ctrl+L).
+func autonomyTierDescription(level engine.AutonomyLevel) string {
 	switch level {
 	case engine.AutonomyBasic:
-		return "read & search only"
+		return "Read and search the codebase only. File changes and terminal commands need your approval."
 	case engine.AutonomySemi:
-		return "edits auto · shell asks"
+		return "Read and edit files automatically. Terminal commands need your approval."
 	case engine.AutonomyFull:
-		return "shell auto · risky asks"
+		return "Read, edit, and run most terminal commands in the container. Risky commands still need your approval."
 	case engine.AutonomyYOLO:
-		return "minimal prompts"
+		return "Almost no approval prompts. Use only when you fully trust this session."
 	default:
-		return ""
+		return "Read and edit files automatically. Terminal commands need your approval."
 	}
 }
 
@@ -87,11 +88,12 @@ func renderAutonomyTierLabel(level engine.AutonomyLevel) string {
 }
 
 func formatAutonomyTierMessage(level engine.AutonomyLevel) string {
-	name := renderAutonomyTierLabel(level)
-	if hint := autonomyTierHint(level); hint != "" {
-		return fmt.Sprintf("Autonomy → %s (%s)", name, hint)
-	}
-	return fmt.Sprintf("Autonomy → %s", name)
+	return fmt.Sprintf("Autonomy %s — %s", renderAutonomyTierLabel(level), autonomyTierDescription(level))
+}
+
+func formatSandboxReadyAutonomyMessage(level engine.AutonomyLevel) string {
+	return fmt.Sprintf("Sandbox ready. Default tier %s — %s Press ctrl+L to switch Inspect · Edit · Run · Trust.",
+		renderAutonomyTierLabel(level), autonomyTierDescription(level))
 }
 
 func autonomyLevelForTierName(name string) engine.AutonomyLevel {

cmd/autonomy_tiers_copy_test.go

@@ -0,0 +1,41 @@
+package cmd
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/engine"
+)
+
+func TestAutonomyTierDescriptions_PlainLanguage(t *testing.T) {
+	cases := []struct {
+		level engine.AutonomyLevel
+		need  []string
+	}{
+		{engine.AutonomyBasic, []string{"Read and search", "need your approval"}},
+		{engine.AutonomySemi, []string{"edit files automatically", "Terminal commands need your approval"}},
+		{engine.AutonomyFull, []string{"most terminal commands", "Risky commands still"}},
+		{engine.AutonomyYOLO, []string{"Almost no approval", "fully trust"}},
+	}
+	for _, tc := range cases {
+		desc := autonomyTierDescription(tc.level)
+		for _, fragment := range tc.need {
+			if !strings.Contains(desc, fragment) {
+				t.Fatalf("level %v description %q missing %q", tc.level, desc, fragment)
+			}
+		}
+	}
+}
+
+func TestFormatAutonomyTierMessage_NoArrowJargon(t *testing.T) {
+	msg := formatAutonomyTierMessage(engine.AutonomyFull)
+	if strings.Contains(msg, "→") {
+		t.Fatalf("expected no arrow jargon, got %q", msg)
+	}
+	if strings.Contains(msg, "shell auto") {
+		t.Fatalf("expected plain language, got %q", msg)
+	}
+	if !strings.Contains(msg, "Run") {
+		t.Fatalf("expected tier name in message, got %q", msg)
+	}
+}

cmd/chat.go

@@ -667,7 +667,7 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, nil
 		case tea.KeyCtrlL:
 			if m.containerEnabled && !m.containerReady {
-				m.messages = append(m.messages, displayMsg{role: "system", content: "Autonomy tiers unlock when the container is ready."})
+				m.messages = append(m.messages, displayMsg{role: "system", content: "Autonomy tiers (Inspect · Edit · Run · Trust) unlock when the container is ready."})
 				m.viewDirty = true
 				m.updateViewportContent()
 				return m, nil
@@ -1108,7 +1108,7 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if m.session.Autonomy == 0 {
 				m.session.Autonomy = DefaultContainerAutonomy
 			}
-			m.messages = append(m.messages, displayMsg{role: "system", content: "Sandbox ready · default autonomy " + renderAutonomyTierLabel(m.session.Autonomy) + " (ctrl+L to change)"})
+			m.messages = append(m.messages, displayMsg{role: "system", content: formatSandboxReadyAutonomyMessage(m.session.Autonomy)})
 			m.invalidateConnStatus()
 		}
 		if msg.err != nil {