Could a gate consume a workflow input on resume?

[markuswondrak]

Gate verdicts currently come exclusively from an interactive terminal prompt.

GateStep.execute() currently checks sys.stdin.isatty():

• On a TTY, it prompts for a verdict.
• Without a TTY, it returns PAUSED.

One use case that is not directly represented by the gate today is an approval
verdict delivered through another channel—for example, a web UI, Slack, a PR
check, or an API. In that flow, the workflow run pauses and exits, an external
system collects the verdict, and the run is later resumed without a terminal.

The existing workflow primitives can support this use case, but the composition
is more indirect than it may need to be. There may be room to let the gate
consume the resume-time input itself while preserving its current behavior by
default.

This differs from earlier proposals:

• It is not an automatically selected branch based on a condition ([Feature]: New gate-on-condition step kind (auto-fire on condition) #2593).
• It does not skip the gate in CI using if and ci_mode; that removes the
  approval checkpoint.
• It does not require a gate-specific CLI option such as --gate-answer or
  --gate-script ([Feature]: Document a test harness for scripting gate verdicts non-interactively #2594 and feat(workflows): add --gate-script for non-interactive gate testing #2667).

What works today

The behavior can be composed from existing primitives using a workflow input,
a switch, a nested gate, and resume-time inputs (#2812):

inputs:
  spec_verdict:
    type: string
    default: pending

steps:
  - id: review-spec
    type: switch
    expression: "{{ inputs.spec_verdict }}"
    cases:
      approve: []
      reject:
        - id: rejected
          type: shell
          run: "echo 'rejected' >&2; exit 1"
    default:
      - id: await-approval
        type: gate
        message: "Awaiting out-of-band approval."
        options: [approve, reject]

The initial non-interactive run pauses at await-approval. The --json output
surfaces the gate message and options (#2964), allowing an external system to
render the approval request. After a human decides, that system can continue
the workflow with:

specify workflow resume <run_id> --input spec_verdict=approve

This works, but the gate's decision semantics are bypassed. Its message and
options still provide useful metadata, but its own output.choice and
on_reject behavior do not participate. The external verdict is instead
interpreted by a parallel switch, and rejection behavior must be recreated in
another step.

Possible improvement: bind a gate verdict to a workflow input

Allow a gate to name a declared workflow input that may provide its verdict:

inputs:
  spec_verdict:
    type: string
    default: ""

steps:
  - id: review-spec
    type: gate
    message: "Approve the specification?"
    options: [approve, reject]
    on_reject: abort
    verdict_input: spec_verdict

The external approval flow then becomes:

specify workflow resume <run_id> --input spec_verdict=approve

The resumed gate would consume spec_verdict, record approve in
output.choice, and apply its existing gate semantics. No parallel switch or
gate-specific CLI option would be needed.

Suggested behavior:

• If verdict_input is absent, preserve today's behavior exactly.
• If the referenced input is unset or empty, prompt on a TTY and pause without
  a TTY, as today.
• If it contains a verdict, match it against options case-insensitively.
• If it does not match an option, fail with a clear validation error rather
  than silently pausing or selecting a fallback.
• Store a matched verdict in output.choice.
• Apply the existing on_reject behavior for reject or abort.
• Continue using the existing resume --input validation and merge behavior.
• Keep the existing --json gate representation.

Internally, this could remain a small gate-specific resolver or be implemented
behind an input-provider seam—for example, a terminal provider plus a workflow
input provider. The requested public behavior is the workflow-input binding;
the internal abstraction can stay as small as the current implementation
requires.

Why this fits the existing-primitives direction

This reuses capabilities already shipped:

• Resume-time workflow inputs from [Feature]: Allow workflow resume to accept updated workflow inputs #2812.
• Structured gate metadata from [Feature]: surface gate detail in the workflow run/resume --json outcome #2964.
• Existing gate options, output.choice, and on_reject semantics.

It adds no new gate-specific CLI argument or verdict-file format. The only new
surface would be an optional gate field connecting two existing primitives:
workflow inputs and gate decisions.

Questions

1. Is the terminal-only verdict source in GateStep intentional, or is it an
   implementation constraint that could be relaxed?
2. Would an optional verdict_input field fit the project's preference for
   composing existing workflow primitives?
3. If the field is acceptable, should an unset value retain the current
   TTY-or-pause behavior described above?

[mnriem]

Thanks for the thorough write-up — the framing against #2593/#2594/#2667 and the "compose existing primitives" lens is exactly right, and it makes this easy to reason about.

Answering your three questions directly:

1. Is the terminal-only verdict source intentional?
It's an implementation constraint, not a deliberate restriction. GateStep.execute() only knows about sys.stdin.isatty() today, but it already receives the full StepContext — including context.inputs. On resume --input, the engine merges the supplied values into the run's inputs and rebuilds the context before re-executing the paused gate, so the resume-time verdict is already sitting in context.inputs by the time the gate runs again. Nothing structural prevents the gate from reading it; the seam just isn't wired up.

2. Does an optional verdict_input fit the project's direction?
Yes. This is the kind of change we prefer: one optional field that connects two already-shipped primitives (resume-time inputs from #2812, gate decisions/--json metadata from #2964) with no new CLI argument and no verdict-file format. It also keeps the gate as the single source of decision semantics (output.choice, on_reject), rather than forcing the parallel-switch workaround that recreates rejection behavior elsewhere. Writing a full custom step type would mean re-implementing options, on_reject (abort/skip/retry), show_file rendering (including its control-char/ANSI-escape stripping), validate(), and the exact --json output shape — which defeats the point of reusing gate semantics.

3. Should an unset value retain today's TTY-or-pause behavior?
Yes — that should be the contract:

• verdict_input absent → today's behavior, unchanged.
• Referenced input unset/empty → prompt on a TTY, pause without one (as today).
• Input holds a value → match against options case-insensitively, store in output.choice, apply existing on_reject.
• Value doesn't match any option → fail with a clear validation error (not a silent pause or fallback).

One wrinkle worth pinning down: on_reject: retry.
retry pauses so the next resume re-executes the gate. But a bound verdict_input still holds the previous reject value on that next resume, so a naive read would re-consume it and loop indefinitely. We'd want explicit "consume-once" semantics here — e.g. a matched verdict is only consumed when the input is non-empty and the input must be re-supplied (or cleared) for the retried gate to proceed, otherwise it falls back to prompt/pause. Worth deciding this behavior up front since it's the one place the input-binding and the existing gate control flow interact non-trivially.

If that semantics question lands where I think it will, this looks like a small, backward-compatible addition to GateStep plus validation and tests. Happy to review a PR along these lines!

[markuswondrak]

Thank you very much for your response!

Does this meet your expectations? #3725