Fix: capture agent output for later workflow steps (#32) (#56)

* Fix: capture agent output for later workflow steps (#32)

Agent steps currently discard their output after streaming it to the terminal, so later steps cannot inspect sentinel values like blocked status tags.

Changes:
- Add capture to AgentStep with shell-variable validation
- Render captured agent output into a shell variable while preserving uncaptured streaming behavior
- Add parser, schema, and runtime tests plus README coverage

Fixes #32

* Archive investigation for issue #32

* Fix: preserve captured agent failures (#32)

Author: tbrandenburg

.claude/PRPs/issues/completed/issue-32.md

@@ -0,0 +1,26 @@
+# Issue 32 Archive
+
+## Issue
+
+- #32: `[Important] capture: field on agent steps to expose output to subsequent steps`
+- Type: ENHANCEMENT
+
+## Investigation Summary
+
+Agent steps streamed their output to the terminal and discarded it, so later workflow steps could not inspect sentinel values such as blocked-status tags.
+
+## Implementation Plan
+
+- Add `capture: str | None = None` to `AgentStep` in `src/flowsh_cli/models.py`
+- Validate `capture` as an uppercase shell variable name
+- Render captured agent output into a shell variable in `src/flowsh_cli/render.py`
+- Add parser, schema, and end-to-end tests in `tests/test_workflow_to_harness.py`
+- Document `capture` in `README.md`
+
+## Validation
+
+- `make qa`
+
+## Notes
+
+The fix was implemented on branch `fix/issue-32-agent-capture`.

README.md

@@ -79,7 +79,7 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 |---|---|---|
 | `vars` | Execute shell commands and export their stdout into shell variables | Variable names must be uppercase shell identifiers. |
 | `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
-| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
+| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `capture`, `expandPrompt`, and `dangerouslySkipPermissions`. |
 | `for` | Iterate over newline-delimited values from a previous `vars` step | Flat iteration only; nested `for` steps are not supported. |
 | `while` | Re-evaluate a Bash condition before each iteration | Use for dynamic queues or other stateful loops that must keep discovering new work. |
 | `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
@@ -90,6 +90,8 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 
 `expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
 
+Set `capture: VARIABLE_NAME` on an `agent` step when you want the full OpenCode output stored in a shell variable for later `vars` or `bash` steps.
+
 Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to OpenCode. The YAML alias `dangerously-skip-permissions` is also accepted.
 
 ## Validation And Safety

src/flowsh_cli/models.py

@@ -94,6 +94,10 @@ class AgentStep(BaseStep):
     agent: str | None = None
     model: str | None = None
     command: str | None = None
+    capture: str | None = Field(
+        default=None,
+        description="Name of a shell variable that receives the full agent output for later steps.",
+    )
     dangerouslySkipPermissions: bool = Field(
         default=False,
         validation_alias=AliasChoices(
@@ -142,6 +146,13 @@ def validate_agent(cls, value: str | None) -> str | None:
             raise ValueError("must match ^[A-Za-z0-9_-]+$")
         return value
 
+    @field_validator("capture")
+    @classmethod
+    def validate_capture(cls, value: str | None) -> str | None:
+        if value is not None and not re.fullmatch(r"[A-Z_][A-Z0-9_]*", value):
+            raise ValueError("must match ^[A-Z_][A-Z0-9_]*$")
+        return value
+
 
 class VarsStep(BaseStep):
     type: Literal["vars"]

src/flowsh_cli/render.py

@@ -180,7 +180,8 @@ def render_harness(workflow: Workflow) -> str:
         '  local agent="${2:-}"',
         '  local model="${3:-}"',
         '  local command="${4:-}"',
-        '  local dangerously_skip_permissions="${5:-false}"',
+        '  local capture="${5:-}"',
+        '  local dangerously_skip_permissions="${6:-false}"',
         "",
         "  local cmd=(opencode run --format json)",
         '  if [[ -n "$agent" ]]; then',
@@ -206,7 +207,17 @@ def render_harness(workflow: Workflow) -> str:
         "    return 127",
         "  fi",
         "",
-        '  "${cmd[@]}" -- "$prompt"',
+        '  if [[ -n "$capture" ]]; then',
+        "    local output",
+        "    local status=0",
+        '    output="$("${cmd[@]}" -- "$prompt")"',
+        "    status=$?",
+        "    printf '%s\\n' \"$output\"",
+        '    printf -v "$capture" \'%s\' "$output"',
+        '    return "$status"',
+        "  else",
+        '    "${cmd[@]}" -- "$prompt"',
+        "  fi",
         "}",
         "",
         section(f"Starting workflow: {workflow.name}"),
@@ -376,10 +387,12 @@ def _render_step_body(step: Step, title: str) -> list[str]:
         lines.append(f"  local agent={bash_quote(step.agent or '')}")
         lines.append(f"  local model={bash_quote(step.model or '')}")
         lines.append(f"  local command={bash_quote(step.command or '')}")
+        lines.append(f"  local capture={bash_quote(step.capture or '')}")
         dangerous_skip_permissions = "true" if step.dangerouslySkipPermissions else "false"
         lines.append(f"  local dangerously_skip_permissions={dangerous_skip_permissions}")
         lines.append(
-            '  run_agent "$prompt" "$agent" "$model" "$command" "$dangerously_skip_permissions"'
+            '  run_agent "$prompt" "$agent" "$model" '
+            '"$command" "$capture" "$dangerously_skip_permissions"'
         )
     elif isinstance(step, ForStep):
         raise AssertionError("nested for steps are not supported")

tests/test_workflow_to_harness.py

@@ -154,6 +154,47 @@ def test_parse_workflows_accepts_agent_opencode_options(tmp_path: Path) -> None:
     assert step.dangerouslySkipPermissions is True
 
 
+def test_parse_workflows_accepts_agent_capture(tmp_path: Path) -> None:
+    workflow_file = tmp_path / "workflows.yml"
+    workflow_file.write_text(
+        """
+workflows:
+  - id: wf_agent_capture
+    name: Agent Capture
+    steps:
+      - type: agent
+        capture: IMPLEMENT_OUTPUT
+        prompt: Save the output.
+""".lstrip(),
+        encoding="utf-8",
+    )
+
+    step = parse_workflows(workflow_file)[0].steps[0]
+
+    assert isinstance(step, AgentStep)
+    assert step.capture == "IMPLEMENT_OUTPUT"
+
+
+@pytest.mark.parametrize("value", ["implement_output", "1OUTPUT", "OUTPUT-NAME"])
+def test_parse_workflows_rejects_invalid_agent_capture(tmp_path: Path, value: str) -> None:
+    workflow_file = tmp_path / "workflows.yml"
+    workflow_file.write_text(
+        f"""
+workflows:
+  - id: wf_agent_capture_invalid
+    name: Agent Capture Invalid
+    steps:
+      - type: agent
+        capture: {value}
+        prompt: Save the output.
+""".lstrip(),
+        encoding="utf-8",
+    )
+
+    with pytest.raises(WorkflowParseError, match="capture"):
+        parse_workflows(workflow_file)
+
+
 def test_parse_workflows_accepts_dangerous_skip_flag_alias(tmp_path: Path) -> None:
     workflow_file = tmp_path / "workflows.yml"
     workflow_file.write_text(
@@ -1092,6 +1133,7 @@ def test_cli_exposes_schema_without_workflow_argument() -> None:
     assert "model:" in result.output
     assert "command:" in result.output
     assert "dangerouslySkipPermissions:" in result.output
+    assert "capture:" in result.output
     assert "Each value is a shell command." in result.output
     assert "Name of a variable (defined by a preceding vars step)" in result.output
     assert "Name of the shell variable exported into each iteration body." in result.output
@@ -1903,6 +1945,153 @@ def test_generated_harness_invokes_opencode_with_all_agent_options(tmp_path: Pat
     assert '{"ok":true}' in executed.stdout
 
 
+def test_generated_harness_captures_agent_output_for_later_steps(tmp_path: Path) -> None:
+    workflow_file = tmp_path / "workflows.yml"
+    workflow_file.write_text(
+        """
+workflows:
+  - id: wf_agent_capture
+    name: Agent Capture
+    steps:
+      - type: agent
+        capture: IMPLEMENT_OUTPUT
+        prompt: |
+          Print a sentinel.
+      - type: bash
+        run: |
+          if echo "$IMPLEMENT_OUTPUT" | grep -qF '<implement-status>blocked</implement-status>'; then
+            printf 'blocked\\n'
+          fi
+""".lstrip(),
+        encoding="utf-8",
+    )
+    generated = subprocess.run(
+        [sys.executable, "-m", "flowsh_cli", str(workflow_file)],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+    )
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    fake_opencode = bin_dir / "opencode"
+    fake_opencode.write_text(
+        """#!/usr/bin/env bash
+printf '<implement-status>blocked</implement-status>\\n'
+""",
+        encoding="utf-8",
+    )
+    fake_opencode.chmod(0o700)
+
+    assert generated.returncode == 0, generated.stderr
+    executed = subprocess.run(
+        ["bash", str(tmp_path / "agent_capture.sh")],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+        env={**os.environ, "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}"},
+    )
+
+    assert executed.returncode == 0, executed.stderr
+    assert "blocked" in executed.stdout
+
+
+def test_generated_harness_preserves_agent_capture_failure_status(tmp_path: Path) -> None:
+    workflow_file = tmp_path / "workflows.yml"
+    workflow_file.write_text(
+        """
+workflows:
+  - id: wf_agent_capture_failure
+    name: Agent Capture Failure
+    steps:
+      - type: agent
+        name: Ask OpenCode
+        capture: IMPLEMENT_OUTPUT
+        prompt: |
+          Print a sentinel and fail.
+""".lstrip(),
+        encoding="utf-8",
+    )
+    generated = subprocess.run(
+        [sys.executable, "-m", "flowsh_cli", str(workflow_file)],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+    )
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    fake_opencode = bin_dir / "opencode"
+    fake_opencode.write_text(
+        """#!/usr/bin/env bash
+printf '<implement-status>blocked</implement-status>\n'
+exit 17
+""",
+        encoding="utf-8",
+    )
+    fake_opencode.chmod(0o700)
+
+    assert generated.returncode == 0, generated.stderr
+    executed = subprocess.run(
+        ["bash", str(tmp_path / "agent_capture_failure.sh")],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+        env={**os.environ, "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}"},
+    )
+
+    assert executed.returncode == 17, executed.stderr
+    assert "blocked" in executed.stdout
+
+
+def test_generated_harness_agent_without_capture_still_streams_output(tmp_path: Path) -> None:
+    workflow_file = tmp_path / "workflows.yml"
+    workflow_file.write_text(
+        """
+workflows:
+  - id: wf_agent_stream
+    name: Agent Stream
+    steps:
+      - type: agent
+        prompt: |
+          Stream the output.
+""".lstrip(),
+        encoding="utf-8",
+    )
+    generated = subprocess.run(
+        [sys.executable, "-m", "flowsh_cli", str(workflow_file)],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+    )
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    fake_opencode = bin_dir / "opencode"
+    fake_opencode.write_text(
+        """#!/usr/bin/env bash
+printf '<streamed-output>\\n'
+""",
+        encoding="utf-8",
+    )
+    fake_opencode.chmod(0o700)
+
+    assert generated.returncode == 0, generated.stderr
+    executed = subprocess.run(
+        ["bash", str(tmp_path / "agent_stream.sh")],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=tmp_path,
+        env={**os.environ, "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}"},
+    )
+
+    assert executed.returncode == 0, executed.stderr
+    assert "<streamed-output>" in executed.stdout
+
+
 def test_generated_harness_expands_agent_prompt_when_expand_prompt_enabled(tmp_path: Path) -> None:
     workflow_file = tmp_path / "workflows.yml"
     workflow_file.write_text(