feat(engine,policy): human-in-the-loop approvals (issue #106)

Add Policy.spec.hitl configuration and pause gated tool calls at checkpoints
with approve, reject, edit, and switch decisions. Non-interactive runs exit
interrupted; resume via --decision or --auto-approve. Emit approval.requested
and approval.resolved trace events with actor attribution and edit diffs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: leo-aa88

internal/cli/hitl.go

@@ -0,0 +1,137 @@
+package cli
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/policy"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/runtime"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/spec"
+	"github.com/mattn/go-isatty"
+)
+
+// EnvHitlActor overrides the actor recorded on approval trace events.
+const EnvHitlActor = "AGENTCTL_HITL_ACTOR"
+
+func hitlActorFromEnv() string {
+	if v := strings.TrimSpace(os.Getenv(EnvHitlActor)); v != "" {
+		return v
+	}
+	if u := strings.TrimSpace(os.Getenv("USER")); u != "" {
+		return u
+	}
+	return "operator"
+}
+
+func applyHitlRunOptions(opts *runtime.WorkflowRunOptions, autoApprove bool, decision string, editJSON string, switchTarget string) error {
+	opts.AutoApprove = autoApprove || envAutoApproveEnabled()
+	opts.HitlActor = hitlActorFromEnv()
+	decision = strings.TrimSpace(decision)
+	if decision == "" {
+		return nil
+	}
+	kind, err := spec.ParseHitlDecisionKind(decision)
+	if err != nil {
+		return err
+	}
+	hd := &runtime.HitlDecisionOptions{Kind: string(kind)}
+	switch kind {
+	case spec.HitlDecisionEdit:
+		if strings.TrimSpace(editJSON) == "" {
+			return fmt.Errorf("run: --decision edit requires --decision-edit-json")
+		}
+		var m map[string]any
+		if err := json.Unmarshal([]byte(editJSON), &m); err != nil {
+			return fmt.Errorf("run: --decision-edit-json: %w", err)
+		}
+		hd.EditedWith = m
+	case spec.HitlDecisionSwitch:
+		hd.SwitchTarget = strings.TrimSpace(switchTarget)
+		if hd.SwitchTarget == "" {
+			return fmt.Errorf("run: --decision switch requires --decision-switch-target")
+		}
+	}
+	opts.HitlDecision = hd
+	return nil
+}
+
+func maybePromptHitlDecision(in io.Reader, out io.Writer, gate policy.HitlGate) (*policy.HitlDecisionInput, error) {
+	if !isatty.IsTerminal(os.Stdin.Fd()) {
+		return nil, nil
+	}
+	actor := hitlActorFromEnv()
+	display := policy.RedactHitlArgs(gate.With, gate.Review.RedactKeys)
+	fmt.Fprintf(out, "\n%s\n", gate.Review.Description)
+	fmt.Fprintf(out, "Tool: %s\nArguments: %v\n", gate.Uses, display)
+	fmt.Fprintf(out, "Allowed decisions: %v\n", gate.Review.AllowedDecisions)
+	if len(gate.Review.SwitchTargets) > 0 {
+		fmt.Fprintf(out, "Switch targets: %v\n", gate.Review.SwitchTargets)
+	}
+	for {
+		fmt.Fprintf(out, "Decision [approve/reject/edit/switch]: ")
+		line, err := readLine(in)
+		if err != nil {
+			return nil, err
+		}
+		kind, err := spec.ParseHitlDecisionKind(line)
+		if err != nil {
+			fmt.Fprintf(out, "Unknown decision %q\n", line)
+			continue
+		}
+		if !decisionAllowed(kind, gate.Review.AllowedDecisions) {
+			fmt.Fprintf(out, "Decision %q is not allowed for this call\n", kind)
+			continue
+		}
+		dec := &policy.HitlDecisionInput{Kind: kind, Actor: actor}
+		switch kind {
+		case spec.HitlDecisionEdit:
+			fmt.Fprintf(out, "Edited args JSON: ")
+			editLine, err := readLine(in)
+			if err != nil {
+				return nil, err
+			}
+			var m map[string]any
+			if err := json.Unmarshal([]byte(editLine), &m); err != nil {
+				fmt.Fprintf(out, "Invalid JSON: %v\n", err)
+				continue
+			}
+			if err := policy.ValidateHitlEdit(gate.With, m, gate.Review); err != nil {
+				fmt.Fprintf(out, "%v\n", err)
+				continue
+			}
+			dec.EditedWith = m
+		case spec.HitlDecisionSwitch:
+			fmt.Fprintf(out, "Switch target operation: ")
+			target, err := readLine(in)
+			if err != nil {
+				return nil, err
+			}
+			dec.SwitchTarget = target
+		}
+		return dec, nil
+	}
+}
+
+func decisionAllowed(kind spec.HitlDecisionKind, allowed []spec.HitlDecisionKind) bool {
+	for _, a := range allowed {
+		if a == kind {
+			return true
+		}
+	}
+	return false
+}
+
+func readLine(r io.Reader) (string, error) {
+	sc := bufio.NewScanner(r)
+	if !sc.Scan() {
+		if err := sc.Err(); err != nil {
+			return "", err
+		}
+		return "", fmt.Errorf("run: unexpected EOF reading hitl decision")
+	}
+	return strings.TrimSpace(sc.Text()), nil
+}

internal/cli/hitl_load.go

@@ -0,0 +1,42 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/policy"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state"
+)
+
+type checkpointHitlPayload struct {
+	PendingHitl *pendingHitlJSON `json:"pendingHitl,omitempty"`
+}
+
+type pendingHitlJSON struct {
+	StepID string                    `json:"stepId"`
+	Uses   string                    `json:"uses"`
+	With   map[string]any            `json:"with"`
+	Review policy.ResolvedHitlReview `json:"review"`
+}
+
+// loadPendingHitlGate reads the latest interrupted checkpoint for a run awaiting HITL input.
+func loadPendingHitlGate(ctx context.Context, st state.RuntimeStore, runID string) (*policy.HitlGate, error) {
+	cp, err := st.GetLatestCheckpoint(ctx, runID)
+	if err != nil {
+		return nil, err
+	}
+	var payload checkpointHitlPayload
+	if err := json.Unmarshal([]byte(cp.ContextJSON), &payload); err != nil {
+		return nil, fmt.Errorf("unmarshal checkpoint: %w", err)
+	}
+	if payload.PendingHitl == nil {
+		return nil, nil
+	}
+	p := payload.PendingHitl
+	return &policy.HitlGate{
+		Uses:   p.Uses,
+		With:   p.With,
+		Review: p.Review,
+	}, nil
+}

internal/cli/run.go

@@ -14,15 +14,21 @@ import (
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/runtime"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/runtime/local"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/spec"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
+	"github.com/mattn/go-isatty"
 	"github.com/spf13/cobra"
 )
 
 func newRunCmd() *cobra.Command {
 	var inputFile string
 	var inputPairs []string
 	var approves []string
+	var autoApprove bool
+	var decision string
+	var decisionEditJSON string
+	var decisionSwitchTarget string
 	var resumeRunID string
 
 	cmd := &cobra.Command{
@@ -37,6 +43,8 @@ Workflow input is built from optional --input-file (JSON object) plus repeated -
 --approve using the full uses string (e.g. tool.helper.echo).
 
 Resume an interrupted or incomplete run with --resume <run-id> (no workflow argument).
+When a run pauses for human approval, resume with --decision and related flags, or use
+--auto-approve / AGENTCTL_AUTO_APPROVE=1 for non-interactive approval.
 
 Examples:
   agentctl run workflow/demo --input topic=hello
@@ -71,12 +79,16 @@ Exit codes (section 11.2):
 					return NewExitError(ExitValidationError, err)
 				}
 			}
-			return runRun(cmd, wfName, resumeRunID, inputFile, inputPairs, approves)
+			return runRun(cmd, wfName, resumeRunID, inputFile, inputPairs, approves, autoApprove, decision, decisionEditJSON, decisionSwitchTarget)
 		},
 	}
 	cmd.Flags().StringVar(&inputFile, "input-file", "", "path to JSON file with workflow input object")
 	cmd.Flags().StringArrayVar(&inputPairs, "input", nil, "workflow input as key=value (repeatable; values are strings)")
 	cmd.Flags().StringArrayVar(&approves, "approve", nil, "approve a policy-gated tool uses string (repeatable)")
+	cmd.Flags().BoolVar(&autoApprove, "auto-approve", false, "auto-approve human-in-the-loop gates (or set AGENTCTL_AUTO_APPROVE=1)")
+	cmd.Flags().StringVar(&decision, "decision", "", "HITL decision when resuming: approve, reject, edit, or switch")
+	cmd.Flags().StringVar(&decisionEditJSON, "decision-edit-json", "", "JSON object of edited tool args when --decision edit")
+	cmd.Flags().StringVar(&decisionSwitchTarget, "decision-switch-target", "", "target operation when --decision switch")
 	cmd.Flags().StringVar(&resumeRunID, "resume", "", "resume an interrupted or incomplete run by id")
 	return cmd
 }
@@ -165,7 +177,7 @@ func classifyRunError(err error) int {
 	}
 }
 
-func runRun(cmd *cobra.Command, wfName, resumeRunID, inputFile string, inputPairs, approves []string) error {
+func runRun(cmd *cobra.Command, wfName, resumeRunID, inputFile string, inputPairs, approves []string, autoApprove bool, decision, decisionEditJSON, decisionSwitchTarget string) error {
 	ctx := context.Background()
 	g := Globals()
 
@@ -203,33 +215,68 @@ func runRun(cmd *cobra.Command, wfName, resumeRunID, inputFile string, inputPair
 	defer func() { _ = st.Close() }()
 
 	rt := local.NewRuntime(root, st)
-	opts := runtime.WorkflowRunOptions{
-		EnvironmentName: strings.TrimSpace(g.Env),
-		Env:             env,
-		InputJSON:       inputJSON,
-		ApprovedActions: approves,
-		Resume:          resumeID != "",
-		RunID:           resumeID,
-	}
-	if !opts.Resume {
-		opts.WorkflowName = wfName
-	}
-	runID, runErr := rt.ExecuteWorkflow(ctx, opts)
 
-	outWfName := wfName
-	if opts.Resume && runID != "" {
-		if r, gerr := st.GetRun(ctx, runID); gerr == nil && r != nil {
-			outWfName = r.WorkflowName
+	for {
+		opts := runtime.WorkflowRunOptions{
+			EnvironmentName: strings.TrimSpace(g.Env),
+			Env:             env,
+			InputJSON:       inputJSON,
+			ApprovedActions: approves,
+			Resume:          resumeID != "",
+			RunID:           resumeID,
 		}
-	}
+		if err := applyHitlRunOptions(&opts, autoApprove, decision, decisionEditJSON, decisionSwitchTarget); err != nil {
+			return NewExitError(ExitValidationError, err)
+		}
+		if !opts.Resume {
+			opts.WorkflowName = wfName
+		}
+		runID, runErr := rt.ExecuteWorkflow(ctx, opts)
 
-	if werr := writeRunOutput(cmd, ctx, st, env, dsn, outWfName, runID, runErr, g); werr != nil {
-		return werr
-	}
-	if runErr != nil {
-		return NewExitError(classifyRunError(runErr), fmt.Errorf("run: %w", runErr))
+		outWfName := wfName
+		if opts.Resume && runID != "" {
+			if r, gerr := st.GetRun(ctx, runID); gerr == nil && r != nil {
+				outWfName = r.WorkflowName
+			}
+		}
+
+		if runErr == nil && runID != "" {
+			if r, gerr := st.GetRun(ctx, runID); gerr == nil && r != nil && r.Status == state.RunStatusInterrupted {
+				if opts.AutoApprove || strings.TrimSpace(decision) != "" {
+					resumeID = runID
+					continue
+				}
+				gate, gerr := loadPendingHitlGate(ctx, st, runID)
+				if gerr != nil {
+					return fmt.Errorf("run: load hitl gate: %w", gerr)
+				}
+				if gate != nil && isatty.IsTerminal(os.Stdin.Fd()) {
+					dec, perr := maybePromptHitlDecision(cmd.InOrStdin(), cmd.OutOrStdout(), *gate)
+					if perr != nil {
+						return perr
+					}
+					if dec != nil {
+						resumeID = runID
+						decision = string(dec.Kind)
+						if dec.Kind == spec.HitlDecisionEdit {
+							b, _ := json.Marshal(dec.EditedWith)
+							decisionEditJSON = string(b)
+						}
+						decisionSwitchTarget = dec.SwitchTarget
+						continue
+					}
+				}
+			}
+		}
+
+		if werr := writeRunOutput(cmd, ctx, st, env, dsn, outWfName, runID, runErr, g); werr != nil {
+			return werr
+		}
+		if runErr != nil {
+			return NewExitError(classifyRunError(runErr), fmt.Errorf("run: %w", runErr))
+		}
+		return nil
 	}
-	return nil
 }
 
 func writeRunOutput(cmd *cobra.Command, ctx context.Context, st *sqlite.Store, env, dsn, wfName, runID string, runErr error, g *Global) error {