feat: add escalation support with clarify command

Author: ppiankov

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.23.0] - 2026-03-22
+
+### Added
+- Escalation support: parse clarification questions from VectorCourt verdicts
+- `SubmitClarification()` client method for POST /v1/cases/:id/clarify
+- `vectorpad clarify <case-id>` CLI command: interactive or `--json` pipe mode
+- CLI submit output shows escalation questions with impact level and defaults
+- TUI verdict summary shows clarification hint with case ID
+
 ## [0.22.0] - 2026-03-21
 
 ### Added

cmd/vectorpad/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bufio"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -58,6 +59,8 @@ func run(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer) int
 			return runPrecedent(args[2:], stdin, stdout, stderr)
 		case "outcome":
 			return runOutcome(args[2:], stdout, stderr)
+		case "clarify":
+			return runClarify(args[2:], stdin, stdout, stderr)
 		}
 	}
 
@@ -848,6 +851,22 @@ func runSubmit(args []string, stdin io.Reader, stdout io.Writer, stderr io.Write
 		}
 	}
 
+	// Check for escalation questions.
+	escalation, caseID := tui.ParseEscalation(raw)
+	if escalation != nil && escalation.Mode == "human_clarification" && len(escalation.Questions) > 0 {
+		_, _ = fmt.Fprintf(stderr, "\n⚠ clarification needed (%d questions):\n", len(escalation.Questions))
+		for i, q := range escalation.Questions {
+			_, _ = fmt.Fprintf(stderr, "  %d. [%s] %s\n", i+1, q.ImpactOnVerdict, q.Question)
+			if q.Context != "" {
+				_, _ = fmt.Fprintf(stderr, "     %s\n", q.Context)
+			}
+			if q.DefaultIfUnanswered != "" {
+				_, _ = fmt.Fprintf(stderr, "     default: %s\n", q.DefaultIfUnanswered)
+			}
+		}
+		_, _ = fmt.Fprintf(stderr, "\nrun: vectorpad clarify %s\n", caseID)
+	}
+
 	// Pretty-print the response.
 	var formatted []byte
 	var pretty json.RawMessage
@@ -1207,6 +1226,128 @@ complete -c vectorpad -n '__fish_use_subcommand' -a outcome -d 'Report outcome f
 complete -c vectorpad -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
 `
 
+func runClarify(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer) int {
+	jsonMode := false
+	var caseID string
+
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--json":
+			jsonMode = true
+		default:
+			if caseID == "" {
+				caseID = args[i]
+			}
+		}
+	}
+
+	if caseID == "" {
+		_, _ = fmt.Fprintln(stderr, "usage: vectorpad clarify <case-id> [--json]")
+		return 1
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		_, _ = fmt.Fprintf(stderr, "error: %v\n", err)
+		return 1
+	}
+	if cfg.VectorCourt.APIKey == "" {
+		_, _ = fmt.Fprintln(stderr, "error: no API key configured (run: vectorpad config set vectorcourt.api_key <key>)")
+		return 1
+	}
+
+	// JSON mode: read answers from stdin.
+	if jsonMode {
+		data, err := io.ReadAll(stdin)
+		if err != nil {
+			_, _ = fmt.Fprintf(stderr, "error: %v\n", err)
+			return 1
+		}
+		var req vectorcourt.ClarifyRequest
+		if err := json.Unmarshal(data, &req); err != nil {
+			_, _ = fmt.Fprintf(stderr, "error: invalid JSON: %v\n", err)
+			return 1
+		}
+
+		client := vectorcourt.NewClient(cfg.Endpoint(), cfg.VectorCourt.APIKey)
+		_, _ = fmt.Fprintln(stderr, "submitting clarification...")
+		raw, err := client.SubmitClarification(context.Background(), caseID, &req)
+		if err != nil {
+			_, _ = fmt.Fprintf(stderr, "error: %v\n", err)
+			return 1
+		}
+
+		var pretty json.RawMessage
+		if json.Unmarshal(raw, &pretty) == nil {
+			if f, err := json.MarshalIndent(pretty, "", "  "); err == nil {
+				_, _ = fmt.Fprintln(stdout, string(f))
+				return 0
+			}
+		}
+		_, _ = fmt.Fprintln(stdout, string(raw))
+		return 0
+	}
+
+	// Interactive mode: prompt for each answer.
+	f, ok := stdin.(*os.File)
+	if !ok || !isTerminal(f) {
+		_, _ = fmt.Fprintln(stderr, "error: interactive mode requires a terminal (use --json for pipe input)")
+		return 1
+	}
+
+	// Fetch the case to get pending questions.
+	// We don't have a "get case" endpoint, so prompt the user to provide question IDs.
+	_, _ = fmt.Fprintln(stderr, "Enter answers for case "+caseID)
+	_, _ = fmt.Fprintln(stderr, "Format: one answer per line as question_id=answer (empty line to submit)")
+	_, _ = fmt.Fprintln(stderr, "")
+
+	scanner := bufio.NewScanner(stdin)
+	var answers []vectorcourt.ClarificationAnswer
+	for {
+		_, _ = fmt.Fprint(stderr, "> ")
+		if !scanner.Scan() {
+			break
+		}
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			break
+		}
+		parts := strings.SplitN(line, "=", 2)
+		if len(parts) != 2 {
+			_, _ = fmt.Fprintln(stderr, "  invalid format, use: question_id=answer")
+			continue
+		}
+		answers = append(answers, vectorcourt.ClarificationAnswer{
+			QuestionID: strings.TrimSpace(parts[0]),
+			Answer:     strings.TrimSpace(parts[1]),
+			Confidence: "firm",
+		})
+	}
+
+	if len(answers) == 0 {
+		_, _ = fmt.Fprintln(stderr, "no answers provided")
+		return 1
+	}
+
+	client := vectorcourt.NewClient(cfg.Endpoint(), cfg.VectorCourt.APIKey)
+	_, _ = fmt.Fprintf(stderr, "submitting %d answers...\n", len(answers))
+	raw, err := client.SubmitClarification(context.Background(), caseID, &vectorcourt.ClarifyRequest{Answers: answers})
+	if err != nil {
+		_, _ = fmt.Fprintf(stderr, "error: %v\n", err)
+		return 1
+	}
+
+	var pretty json.RawMessage
+	if json.Unmarshal(raw, &pretty) == nil {
+		if f, err := json.MarshalIndent(pretty, "", "  "); err == nil {
+			_, _ = fmt.Fprintln(stdout, string(f))
+			return 0
+		}
+	}
+	_, _ = fmt.Fprintln(stdout, string(raw))
+	return 0
+}
+
 func isTerminal(f *os.File) bool {
 	info, err := f.Stat()
 	if err != nil {

internal/tui/launch.go

@@ -10,8 +10,8 @@ import (
 	"strings"
 
 	"github.com/ppiankov/vectorpad/internal/config"
-	"github.com/ppiankov/vectorpad/internal/vectorcourt"
 	"github.com/ppiankov/vectorpad/internal/stash"
+	"github.com/ppiankov/vectorpad/internal/vectorcourt"
 )
 
 // launchTarget represents a destination for the vector payload.
@@ -136,8 +136,10 @@ func stashVerdict(raw json.RawMessage, question string) {
 // formatVerdictSummary extracts a brief status line from the verdict JSON.
 func formatVerdictSummary(raw json.RawMessage, gate *vectorcourt.GateResult) string {
 	var envelope struct {
-		Verdict string `json:"verdict"`
-		Status  string `json:"status"`
+		Verdict    string                          `json:"verdict"`
+		Status     string                          `json:"status"`
+		CaseID     string                          `json:"case_id"`
+		Escalation *vectorcourt.EscalationDecision `json:"escalation,omitempty"`
 	}
 	if json.Unmarshal(raw, &envelope) == nil {
 		parts := []string{"vectorcourt"}
@@ -154,11 +156,26 @@ func formatVerdictSummary(raw json.RawMessage, gate *vectorcourt.GateResult) str
 		if gate != nil && gate.Tier != "" {
 			parts = append(parts, fmt.Sprintf("(tier: %s)", gate.Tier))
 		}
+		if envelope.Escalation != nil && envelope.Escalation.Mode == "human_clarification" {
+			parts = append(parts, fmt.Sprintf("⚠ %d questions — run: vectorpad clarify %s", len(envelope.Escalation.Questions), envelope.CaseID))
+		}
 		return strings.Join(parts, " — ")
 	}
 	return fmt.Sprintf("vectorcourt — verdict received (%d bytes)", len(raw))
 }
 
+// ParseEscalation extracts escalation data from the raw verdict JSON.
+func ParseEscalation(raw json.RawMessage) (*vectorcourt.EscalationDecision, string) {
+	var envelope struct {
+		CaseID     string                          `json:"case_id"`
+		Escalation *vectorcourt.EscalationDecision `json:"escalation,omitempty"`
+	}
+	if json.Unmarshal(raw, &envelope) == nil && envelope.Escalation != nil {
+		return envelope.Escalation, envelope.CaseID
+	}
+	return nil, ""
+}
+
 func (o *launchOverlay) show() {
 	o.visible = true
 	o.cursor = 0

internal/vectorcourt/client.go

@@ -294,6 +294,43 @@ func (c *Client) InstantPrecedents(ctx context.Context, query string, limit int)
 	return &result, nil
 }
 
+// SubmitClarification sends clarification answers and triggers re-deliberation.
+func (c *Client) SubmitClarification(ctx context.Context, caseID string, req *ClarifyRequest) (json.RawMessage, error) {
+	ctx, cancel := context.WithTimeout(ctx, consultTimeout)
+	defer cancel()
+
+	body, err := json.Marshal(req)
+	if err != nil {
+		return nil, fmt.Errorf("encode request: %w", err)
+	}
+
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.endpoint+"/v1/cases/"+caseID+"/clarify", bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	if c.apiKey != "" {
+		httpReq.Header.Set(authHeader, c.apiKey)
+	}
+
+	resp, err := c.http.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("clarify request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, parseAPIError(resp.StatusCode, respBody)
+	}
+
+	return json.RawMessage(respBody), nil
+}
+
 // GetPredictionDebt fetches the prediction debt health metric.
 func (c *Client) GetPredictionDebt(ctx context.Context) (*PredictionDebt, error) {
 	ctx, cancel := context.WithTimeout(ctx, accountTimeout)

internal/vectorcourt/types.go

@@ -132,6 +132,38 @@ type SparEvent struct {
 	Final     bool   `json:"final"`
 }
 
+// EscalationDecision is the council's escalation disposition from the verdict.
+type EscalationDecision struct {
+	Mode      string                  `json:"mode"` // auto_resolve, resolve_with_caveat, human_clarification, human_approval
+	Score     float64                 `json:"score"`
+	Triggers  []string                `json:"triggers,omitempty"`
+	Questions []ClarificationQuestion `json:"questions,omitempty"`
+}
+
+// ClarificationQuestion is a structured question the council asks the human.
+type ClarificationQuestion struct {
+	ID                  string `json:"id"`
+	Type                string `json:"type"` // constraint_missing, constraint_conflict, preference, stakes_confirm, approval, falsification
+	Question            string `json:"question"`
+	Context             string `json:"context"`
+	ConstraintField     string `json:"constraint_field,omitempty"`
+	DefaultIfUnanswered string `json:"default_if_unanswered,omitempty"`
+	ImpactOnVerdict     string `json:"impact_on_verdict"` // high, medium, low
+}
+
+// ClarificationAnswer captures the human's response to one clarification question.
+type ClarificationAnswer struct {
+	QuestionID string `json:"question_id"`
+	Answer     string `json:"answer"`
+	Confidence string `json:"confidence"` // firm, preferred, uncertain
+	Notes      string `json:"notes,omitempty"`
+}
+
+// ClarifyRequest is the JSON body for POST /v1/cases/:id/clarify.
+type ClarifyRequest struct {
+	Answers []ClarificationAnswer `json:"answers"`
+}
+
 // GateResult is the outcome of a preflight gate check.
 type GateResult struct {
 	Allowed  bool