Review points

Pause agent work for a person before continuing.

Human input requests let package-backed tools ask for approval, a choice, a reason, a missing value, or an explicit resume signal while ExecWarden stores the request, answer, followup action, and audit context.

When to Use Human Input

Use human input when a tool has enough context to pause, show a concrete question, and continue after a person answers. Approval is one kind of human input: it decides whether a risky followup action may run. Generic input covers the other cases where the package needs a missing value, a reason, a selected option, or a deliberate resume signal.

Approval-shaped request	Use approve/reject when the person is deciding whether a risky provider call should proceed. The selected followup action is the exact action the answer can allow.
Free text request	Use free text when the package needs a reason, ticket id, release note, or other short value before it can continue.
Choice request	Use single choice for one selected path. A selected choice can run a same-package followup action with fixed parameters.
Resume request	Use resume when the package only needs a person to acknowledge that work may continue.

Lifecycle

1. Stage or preview	The package action computes the proposed change, question, or missing input before making an irreversible provider call.
2. Return request	The action returns `userInputRequest` with a title, summary, input kind, and optional same-package followup.
3. Store and show	ExecWarden stores the request under the workspace, shows it to the relevant review surfaces, and returns a pending response to the caller.
4. Answer	A person submits the approval, rejection, text, choice, or resume answer. Approval-shaped answers can satisfy approval policy for the selected followup action.
5. Continue	ExecWarden wakes the source session. If the answer selected a followup, the gateway runs that same-package followup with the stored parameters and answer data.

Package Contract

return {
  ok: true,
  userInputRequest: {
    title: "Review production change",
    summary: "Terminate instance i-123 in us-east-1?",
    input: {
      kind: "single_choice",
      choices: [
        {
          id: "approve",
          label: "Terminate",
          style: "danger",
          followup: {
            capability: "pkg:aws-admin:instances.terminate.commit",
            params: { instanceId: "i-123", region: "us-east-1" }
          }
        },
        { id: "reject", label: "Cancel" }
      ]
    }
  }
};

Followups are deliberately narrow: they must target the same package namespace and still pass the source policy. Multi-choice answers are stored, but they do not execute followups in the first slice because batch semantics need a separate product shape.

Trust Boundary

What ExecWarden enforces	The gateway stores the request, scopes it to the workspace, records the answer, checks followup policy, resumes the source session, and logs the decision path.
What the package must do	Package authors must stage dangerous mutations through this request/answer/followup lifecycle instead of calling the provider before the person answers.
Custom package trust	Workspace-authored packages are still code that can call declared providers with package-local secrets. ExecWarden does not currently provide a public package marketplace, third-party package review, signing, or provenance checks.

Where It Appears

Approvals UI/API	Single-choice requests with exactly `approve` and `reject` choice ids are projected into existing approval surfaces.
Generic input API	Other request shapes are listed and answered through `/v1/user-input-requests`.
MCP clients	Generic input returns `pending_user_input`. Approval-shaped input returns `pending_approval`.
Workflows	Workflow runs and owned agent sessions can wait while a package-backed tool is pending human input, then continue after the answer/followup completes.
Next question	Use Approvals & Policy for approve/reject semantics, or Workflows when a repeatable run must wait for the answer.