[FEATURE] Workflows: a deterministic shell/command step (no agent needed to run one command)

Status Open
Maintainer reply None cached
Activity 0 comments · opened Oct 1, 2026

Problem. A dynamic workflow can chain subagents deterministically (pipeline(), parallel()), but the script itself has "No direct filesystem or shell access from the workflow itself | Agents read, write, and run commands" (docs: Orchestrate subagents at scale with dynamic workflows, Behavior and limits). So any stage that is a plain command, such as running a test gate, invoking an external agent CLI, or posting a result, must be wrapped in an agent() whose only job is to run that one command.

That wrapper:

  • spends model tokens and latency on a step with no judgment in it;
  • can paraphrase, retry, or skip the command, so a deterministic step becomes non-deterministic;
  • attributes the step to the wrapper's model, not to what actually ran.

Use case. An AI-native SDLC pipeline: design (subagent) -> design review (an external model via its CLI) -> implement (subagent) -> gate (make test) -> review. Today the only fully deterministic way to run this is a separate shell orchestrator, outside Claude Code, that the main session polls. That orchestrator loses /workflows progress, resume, and permission evaluation.

Proposal. Add a run(cmd, {cwd, timeout, env}) primitive, or agent() with a command: mode, that:

  • executes through the session's normal Bash permission evaluation (allow/deny rules, PreToolUse hooks, sandbox);
  • returns {exitCode, stdout, stderr} (bounded) to the script;
  • is cached and replayed on resume exactly like a completed agent() call.

Determinism rules (no Date.now()) are unchanged, because the command's result is a recorded value.

Alternatives considered.

  • A one-tool Haiku agent() wrapper: costs tokens, and its output is not guaranteed verbatim.
  • Hooks: a hook cannot spawn an agent or return a result to a script.
  • A separate orchestrator process: loses resume, progress and permission parity.

View original on GitHub ↗