From 7466b1751c4126735769a3304e1db80dab166a9e Mon Sep 17 00:00:00 2001
From: Peter Stone <thepeterstone@gmail.com>
Date: Fri, 6 Mar 2026 00:07:18 +0000
Subject: feat: blocked task state for agent questions via session resume
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When an agent needs user input it writes a question to
$CLAUDOMATOR_QUESTION_FILE and exits. The runner detects the file and
returns BlockedError; the pool transitions the task to BLOCKED and
stores the question JSON on the task record.

The user answers via POST /api/tasks/{id}/answer. The server looks up
the claude session_id from the most recent execution and submits a
resume execution (claude --resume <session-id> "<answer>"), freeing the
executor slot entirely while waiting.

Changes:
- task: add StateBlocked, transitions RUNNING→BLOCKED, BLOCKED→QUEUED
- storage: add session_id to executions, question_json to tasks;
  add GetLatestExecution and UpdateTaskQuestion methods
- executor: BlockedError type; ClaudeRunner pre-assigns --session-id,
  sets CLAUDOMATOR_QUESTION_FILE env var, detects question file on exit;
  buildArgs handles --resume mode; Pool.SubmitResume for resume path
- api: handleAnswerQuestion rewritten to create resume execution
- preamble: add question protocol instructions for agents
- web: BLOCKED state badge (indigo), question text + option buttons or
  free-text input with Submit on the task card footer

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 internal/api/server.go | 39 ++++++++++++++++++++++++++++++---------
 1 file changed, 30 insertions(+), 9 deletions(-)

(limited to 'internal/api/server.go')

diff --git a/internal/api/server.go b/internal/api/server.go
index bac98b6..5758347 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -112,31 +112,52 @@ func (s *Server) BroadcastQuestion(taskID, toolUseID string, questionData json.R
 func (s *Server) handleAnswerQuestion(w http.ResponseWriter, r *http.Request) {
 	taskID := r.PathValue("id")
 
-	if _, err := s.store.GetTask(taskID); err != nil {
+	tk, err := s.store.GetTask(taskID)
+	if err != nil {
 		writeJSON(w, http.StatusNotFound, map[string]string{"error": "task not found"})
 		return
 	}
+	if tk.State != task.StateBlocked {
+		writeJSON(w, http.StatusConflict, map[string]string{"error": "task is not blocked"})
+		return
+	}
 
 	var input struct {
-		QuestionID string `json:"question_id"`
-		Answer     string `json:"answer"`
+		Answer string `json:"answer"`
 	}
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
 		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid JSON: " + err.Error()})
 		return
 	}
-	if input.QuestionID == "" {
-		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "question_id is required"})
+	if input.Answer == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "answer is required"})
+		return
+	}
+
+	// Look up the session ID from the most recent execution.
+	latest, err := s.store.GetLatestExecution(taskID)
+	if err != nil || latest.SessionID == "" {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "no resumable session found"})
 		return
 	}
 
-	ok := s.pool.Questions.Answer(input.QuestionID, input.Answer)
-	if !ok {
-		writeJSON(w, http.StatusNotFound, map[string]string{"error": "no pending question with that ID"})
+	// Clear the question and transition to QUEUED.
+	s.store.UpdateTaskQuestion(taskID, "")
+	s.store.UpdateTaskState(taskID, task.StateQueued)
+
+	// Submit a resume execution.
+	resumeExec := &storage.Execution{
+		ID:              uuid.New().String(),
+		TaskID:          taskID,
+		ResumeSessionID: latest.SessionID,
+		ResumeAnswer:    input.Answer,
+	}
+	if err := s.pool.SubmitResume(r.Context(), tk, resumeExec); err != nil {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": err.Error()})
 		return
 	}
 
-	writeJSON(w, http.StatusOK, map[string]string{"status": "delivered"})
+	writeJSON(w, http.StatusOK, map[string]string{"status": "queued"})
 }
 
 func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
-- 
cgit v1.2.3