feat(prompt): inject RuntimeStatusSuffix into first-turn agent prompt

Adds a RuntimeStatusSuffix constant to the prompt package and appends
it to the composed prompt on the first turn of each worker run. The
suffix instructs the agent how to signal blocked or needs-human-review
status via the .sortie/status file, per the A2O protocol.

- Add exported RuntimeStatusSuffix constant in internal/prompt/turn.go
- Restructure first-turn guard in RunWorkerAttempt to nest the tool
  advertisement check inside an outer turnNumber==1 block, then
  unconditionally append the status suffix (ordering: template output
  → tool advertisement → status suffix)
- Fix orchestrator_test.go first-turn prompt assertion to use
  strings.HasPrefix instead of exact equality, since the suffix is
  now appended after the template output
- Add TestRuntimeStatusSuffixInjection with four subtests covering
  first-turn inclusion, ordering after tool advertisement, omission on
  continuation turns, and injection when the template renders empty

Closes #231

Author: serghei-dev

internal/orchestrator/orchestrator_test.go

@@ -2200,14 +2200,14 @@ func TestOrchestratorDynamicConfigReload(t *testing.T) {
 
 		if v, ok := capturedPrompts.Load("P-1"); !ok {
 			t.Error("no prompt captured for P-1")
-		} else if got, ok := v.(string); !ok || got != "do P-1" {
-			t.Errorf("prompt for P-1 = %q, want %q", got, "do P-1")
+		} else if got, ok := v.(string); !ok || !strings.HasPrefix(got, "do P-1") {
+			t.Errorf("prompt for P-1 = %q, want prefix %q", got, "do P-1")
 		}
 
 		if v, ok := capturedPrompts.Load("P-2"); !ok {
 			t.Error("no prompt captured for P-2")
-		} else if got, ok := v.(string); !ok || got != "review P-2" {
-			t.Errorf("prompt for P-2 = %q, want %q", got, "review P-2")
+		} else if got, ok := v.(string); !ok || !strings.HasPrefix(got, "review P-2") {
+			t.Errorf("prompt for P-2 = %q, want prefix %q", got, "review P-2")
 		}
 	})
 

internal/orchestrator/worker.go

@@ -544,8 +544,11 @@ func RunWorkerAttempt(ctx context.Context, issue domain.Issue, attempt *int, dep
 			return
 		}
 
-		if turnNumber == 1 && deps.ToolRegistry != nil && deps.ToolRegistry.Len() > 0 {
-			rendered += "\n\n" + buildToolAdvertisement(deps.ToolRegistry, cfg.Tracker.Project)
+		if turnNumber == 1 {
+			if deps.ToolRegistry != nil && deps.ToolRegistry.Len() > 0 {
+				rendered += "\n\n" + buildToolAdvertisement(deps.ToolRegistry, cfg.Tracker.Project)
+			}
+			rendered += "\n\n" + prompt.RuntimeStatusSuffix
 		}
 
 		logger.Info("turn started", slog.Int("turn_number", turnNumber), slog.Int("max_turns", maxTurns))

internal/orchestrator/worker_test.go

@@ -2891,3 +2891,231 @@ func TestRunWorkerAttempt_A2OStatusSignal(t *testing.T) {
 		}
 	})
 }
+
+// TestRuntimeStatusSuffixInjection verifies the first-turn-only injection of
+// prompt.RuntimeStatusSuffix into the prompt passed to RunTurn, including
+// ordering relative to tool advertisement and the absence of the suffix on
+// continuation turns.
+func TestRuntimeStatusSuffixInjection(t *testing.T) {
+	t.Parallel()
+
+	// writeSoftStop writes "blocked" to the .sortie/status file inside the
+	// given workspace path so the worker exits cleanly after one turn.
+	writeSoftStop := func(wsPath string) {
+		statusDir := filepath.Join(wsPath, ".sortie")
+		if err := os.MkdirAll(statusDir, 0o755); err == nil {
+			_ = os.WriteFile(filepath.Join(statusDir, "status"), []byte("blocked\n"), 0o644)
+		}
+	}
+
+	t.Run("first_turn_contains_suffix", func(t *testing.T) {
+		t.Parallel()
+
+		tmpDir := t.TempDir()
+		cfg := defaultWorkerConfig(tmpDir)
+		cfg.Agent.MaxTurns = 5
+
+		var wsPath atomic.Value
+		var capturedPrompt string
+		var mu sync.Mutex
+		ec := newExitCapture()
+
+		deps := WorkerDeps{
+			TrackerAdapter: &mockTrackerAdapter{},
+			AgentAdapter: &mockAgentAdapter{
+				startSessionFn: func(_ context.Context, params domain.StartSessionParams) (domain.Session, error) {
+					wsPath.Store(params.WorkspacePath)
+					return domain.Session{ID: "sess-1"}, nil
+				},
+				runTurnFn: func(_ context.Context, session domain.Session, params domain.RunTurnParams) (domain.TurnResult, error) {
+					mu.Lock()
+					capturedPrompt = params.Prompt
+					mu.Unlock()
+					if p, ok := wsPath.Load().(string); ok && p != "" {
+						writeSoftStop(p)
+					}
+					return domain.TurnResult{SessionID: session.ID, ExitReason: domain.EventTurnCompleted}, nil
+				},
+			},
+			ConfigFunc:         func() config.ServiceConfig { return cfg },
+			PromptTemplateFunc: func() *prompt.Template { return mustParseTemplate(t, "do work on {{ .issue.title }}") },
+			OnEvent:            func(_ string, _ domain.AgentEvent) {},
+			OnExit:             ec.onExit,
+			Logger:             discardLogger(),
+		}
+
+		RunWorkerAttempt(context.Background(), workerTestIssue(), nil, deps)
+
+		ec.waitResult(t)
+
+		mu.Lock()
+		p := capturedPrompt
+		mu.Unlock()
+
+		if !strings.Contains(p, prompt.RuntimeStatusSuffix) {
+			t.Errorf("first-turn prompt missing RuntimeStatusSuffix:\n%s", p)
+		}
+	})
+
+	t.Run("suffix_after_tool_advertisement", func(t *testing.T) {
+		t.Parallel()
+
+		tmpDir := t.TempDir()
+		cfg := defaultWorkerConfig(tmpDir)
+		cfg.Agent.MaxTurns = 5
+		cfg.Tracker.Project = "TESTPROJ"
+
+		var wsPath atomic.Value
+		var capturedPrompt string
+		var mu sync.Mutex
+		ec := newExitCapture()
+
+		reg := domain.NewToolRegistry()
+		reg.Register(&stubAgentTool{toolName: "tracker_api", desc: "Query issues"})
+
+		deps := WorkerDeps{
+			TrackerAdapter: &mockTrackerAdapter{},
+			AgentAdapter: &mockAgentAdapter{
+				startSessionFn: func(_ context.Context, params domain.StartSessionParams) (domain.Session, error) {
+					wsPath.Store(params.WorkspacePath)
+					return domain.Session{ID: "sess-1"}, nil
+				},
+				runTurnFn: func(_ context.Context, session domain.Session, params domain.RunTurnParams) (domain.TurnResult, error) {
+					mu.Lock()
+					capturedPrompt = params.Prompt
+					mu.Unlock()
+					if p, ok := wsPath.Load().(string); ok && p != "" {
+						writeSoftStop(p)
+					}
+					return domain.TurnResult{SessionID: session.ID, ExitReason: domain.EventTurnCompleted}, nil
+				},
+			},
+			ConfigFunc:         func() config.ServiceConfig { return cfg },
+			PromptTemplateFunc: func() *prompt.Template { return mustParseTemplate(t, "do work on {{ .issue.title }}") },
+			OnEvent:            func(_ string, _ domain.AgentEvent) {},
+			OnExit:             ec.onExit,
+			Logger:             discardLogger(),
+			ToolRegistry:       reg,
+		}
+
+		RunWorkerAttempt(context.Background(), workerTestIssue(), nil, deps)
+
+		ec.waitResult(t)
+
+		mu.Lock()
+		p := capturedPrompt
+		mu.Unlock()
+
+		toolIdx := strings.Index(p, "## Available Sortie tools")
+		if toolIdx < 0 {
+			t.Fatalf("first-turn prompt missing tool advertisement header:\n%s", p)
+		}
+		suffixIdx := strings.Index(p, prompt.RuntimeStatusSuffix)
+		if suffixIdx < 0 {
+			t.Fatalf("first-turn prompt missing RuntimeStatusSuffix:\n%s", p)
+		}
+		if suffixIdx <= toolIdx {
+			t.Errorf("RuntimeStatusSuffix (idx=%d) must appear after tool advertisement (idx=%d)", suffixIdx, toolIdx)
+		}
+	})
+
+	t.Run("continuation_turn_omits_suffix", func(t *testing.T) {
+		t.Parallel()
+
+		tmpDir := t.TempDir()
+		cfg := defaultWorkerConfig(tmpDir)
+		cfg.Agent.MaxTurns = 2
+
+		var prompts [2]string
+		var turnCounter atomic.Int64
+		var mu sync.Mutex
+		ec := newExitCapture()
+
+		deps := WorkerDeps{
+			TrackerAdapter: &mockTrackerAdapter{},
+			AgentAdapter: &mockAgentAdapter{
+				runTurnFn: func(_ context.Context, session domain.Session, params domain.RunTurnParams) (domain.TurnResult, error) {
+					n := turnCounter.Add(1)
+					mu.Lock()
+					if n <= 2 {
+						prompts[n-1] = params.Prompt
+					}
+					mu.Unlock()
+					return domain.TurnResult{SessionID: session.ID, ExitReason: domain.EventTurnCompleted}, nil
+				},
+			},
+			ConfigFunc:         func() config.ServiceConfig { return cfg },
+			PromptTemplateFunc: func() *prompt.Template { return mustParseTemplate(t, "turn={{ .run.turn_number }}") },
+			OnEvent:            func(_ string, _ domain.AgentEvent) {},
+			OnExit:             ec.onExit,
+			Logger:             discardLogger(),
+		}
+
+		RunWorkerAttempt(context.Background(), workerTestIssue(), nil, deps)
+
+		result := ec.waitResult(t)
+		if result.TurnsCompleted != 2 {
+			t.Fatalf("TurnsCompleted = %d, want 2", result.TurnsCompleted)
+		}
+
+		mu.Lock()
+		p1, p2 := prompts[0], prompts[1]
+		mu.Unlock()
+
+		if !strings.Contains(p1, prompt.RuntimeStatusSuffix) {
+			t.Errorf("turn 1 prompt missing RuntimeStatusSuffix:\n%s", p1)
+		}
+		if strings.Contains(p2, prompt.RuntimeStatusSuffix) {
+			t.Errorf("turn 2 prompt must not contain RuntimeStatusSuffix:\n%s", p2)
+		}
+	})
+
+	t.Run("empty_template_first_turn_contains_suffix", func(t *testing.T) {
+		t.Parallel()
+
+		tmpDir := t.TempDir()
+		cfg := defaultWorkerConfig(tmpDir)
+		cfg.Agent.MaxTurns = 5
+
+		var wsPath atomic.Value
+		var capturedPrompt string
+		var mu sync.Mutex
+		ec := newExitCapture()
+
+		deps := WorkerDeps{
+			TrackerAdapter: &mockTrackerAdapter{},
+			AgentAdapter: &mockAgentAdapter{
+				startSessionFn: func(_ context.Context, params domain.StartSessionParams) (domain.Session, error) {
+					wsPath.Store(params.WorkspacePath)
+					return domain.Session{ID: "sess-1"}, nil
+				},
+				runTurnFn: func(_ context.Context, session domain.Session, params domain.RunTurnParams) (domain.TurnResult, error) {
+					mu.Lock()
+					capturedPrompt = params.Prompt
+					mu.Unlock()
+					if p, ok := wsPath.Load().(string); ok && p != "" {
+						writeSoftStop(p)
+					}
+					return domain.TurnResult{SessionID: session.ID, ExitReason: domain.EventTurnCompleted}, nil
+				},
+			},
+			ConfigFunc:         func() config.ServiceConfig { return cfg },
+			PromptTemplateFunc: func() *prompt.Template { return mustParseTemplate(t, "") },
+			OnEvent:            func(_ string, _ domain.AgentEvent) {},
+			OnExit:             ec.onExit,
+			Logger:             discardLogger(),
+		}
+
+		RunWorkerAttempt(context.Background(), workerTestIssue(), nil, deps)
+
+		ec.waitResult(t)
+
+		mu.Lock()
+		p := capturedPrompt
+		mu.Unlock()
+
+		if !strings.Contains(p, prompt.RuntimeStatusSuffix) {
+			t.Errorf("first-turn prompt missing RuntimeStatusSuffix with empty template:\n%s", p)
+		}
+	})
+}

internal/prompt/turn.go

@@ -13,6 +13,22 @@ import (
 // such branching.
 const DefaultContinuationPrompt = "Continue working on this task. Review the current state of your work, check what remains to be done, and proceed with the next step. If you believe the task is complete, verify your changes and confirm completion."
 
+// RuntimeStatusSuffix is a fixed instruction string appended to the agent
+// prompt on the first turn of each worker run. It informs the agent of
+// the A2O status-signaling protocol for reporting blocked or
+// review-needed status via the .sortie/status file.
+//
+// Continuation turns omit this suffix because the instruction persists
+// in the agent's conversation history from turn 1.
+const RuntimeStatusSuffix = `If you determine that you cannot make further progress on this task without human
+intervention, or if your work is complete and requires human review, signal the
+orchestrator by running:
+
+    mkdir -p .sortie && echo "blocked" > .sortie/status
+
+Use "blocked" when you cannot proceed. Use "needs-human-review" when your work is
+complete and awaiting review. Do not write this file during normal productive work.`
+
 // BuildTurnPrompt returns the rendered prompt for a single turn within a
 // worker session. turnNumber 1 is the initial turn; turnNumber 2 and above
 // are continuation turns. If a continuation turn renders to empty output,