fix(agent): safe variable-only interpolation for expandPrompt

Replace unquoted heredoc shell expansion with quoted heredoc plus
explicit per-variable plain-text substitution.

- Always emit <<'DELIMITER' so prompt content is never shell-evaluated
- When expandPrompt: true, scan prompt for ${VAR} / $VAR tokens and
  emit safe bash string replacements using a helper _p variable
- Backticks, $(...), globs, and all other shell syntax pass through
  to the agent literally
- Add Field descriptions to prompt and expandPrompt for --schema output

Fixes accidental execution of shell expressions in agent prompts.

Author: Tom Brandenburg

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "flowsh-cli"
-version = "0.4.0"
+version = "0.4.2"
 description = "Generate Bash harness scripts from workflow YAML files."
 readme = "README.md"
 requires-python = ">=3.11"

src/flowsh_cli/__init__.py

@@ -3,7 +3,7 @@
 from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
 from flowsh_cli.render import harness_path, render_harness
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "Workflow",

src/flowsh_cli/models.py

@@ -73,7 +73,14 @@ def validate_run(cls, value: str) -> str:
 
 class AgentStep(BaseStep):
     type: Literal["agent"]
-    prompt: str
+    prompt: str = Field(
+        description=(
+            "The prompt text sent to the agent. "
+            "May contain markdown, code fences, backticks, $(...), and other shell syntax freely — "
+            "the prompt is never passed through a shell. "
+            "Use expandPrompt: true to substitute ${VAR} / $VAR tokens from vars steps."
+        )
+    )
     agent: str | None = None
     model: str | None = None
     command: str | None = None
@@ -84,7 +91,17 @@ class AgentStep(BaseStep):
             "dangerously-skip-permissions",
         ),
     )
-    expandPrompt: bool = False
+    expandPrompt: bool = Field(
+        default=False,
+        description=(
+            "When true, substitutes ${VAR} and $VAR tokens from vars steps into the prompt "
+            "at runtime using safe plain-text replacement. "
+            "Shell expressions such as $(cmd), `cmd`, $((expr)), and globs are NOT evaluated — "
+            "they pass through to the agent literally. "
+            "Only uppercase variable names matching [A-Z_][A-Z0-9_]* found in the prompt text "
+            "are replaced. All other shell syntax in the prompt is safe to use."
+        ),
+    )
 
     @model_validator(mode="before")
     @classmethod

src/flowsh_cli/render.py

@@ -257,16 +257,25 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
         )
     elif isinstance(step, AgentStep):
         delimiter = heredoc_delimiter("PROMPT", step.prompt)
-        heredoc = f"<<{delimiter}" if step.expandPrompt else f"<<'{delimiter}'"
         lines.extend(
             [
                 "  local prompt",
-                f"  prompt=$(cat {heredoc}",
+                f"  prompt=$(cat <<'{delimiter}'",
                 *step.prompt.splitlines(),
                 delimiter,
                 "  )",
             ]
         )
+        if step.expandPrompt:
+            braced = re.findall(r"\$\{([A-Z_][A-Z0-9_]*)\}", step.prompt)
+            bare = re.findall(r"\$([A-Z_][A-Z0-9_]*)(?!\w)", step.prompt)
+            seen: dict[str, None] = {}
+            for var in braced + bare:
+                seen[var] = None
+            for var in seen:
+                lines.append(f'  _p=\'${{{var}}}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
+                lines.append(f'  _p=\'${var}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
+
         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 '')}")

tests/test_workflow_to_harness.py

@@ -557,23 +557,27 @@ def test_render_harness_quotes_agent_prompt_heredoc_by_default() -> None:
     assert "prompt=$(cat <<PROMPT_EOF" not in script
 
 
-def test_render_harness_unquotes_agent_prompt_heredoc_when_expand_prompt_enabled() -> None:
+def test_render_harness_safe_variable_substitution_when_expand_prompt_enabled() -> None:
     workflow = Workflow(
         id="wf_prompt_expand",
         name="Prompt Expand",
         steps=[
             AgentStep(
                 type="agent",
-                prompt="Work on issue $ISSUE_NUMBER.",
+                prompt="Work on issue ${ISSUE_NUMBER}.",
                 expandPrompt=True,
             )
         ],
     )
 
     script = render_harness(workflow)
 
-    assert "prompt=$(cat <<PROMPT_EOF" in script
-    assert "prompt=$(cat <<'PROMPT_EOF'" not in script
+    # Always uses quoted heredoc - no shell expansion of the raw prompt
+    assert "prompt=$(cat <<'PROMPT_EOF'" in script
+    assert "prompt=$(cat <<PROMPT_EOF" not in script
+    # Safe substitution lines emitted for the declared variable
+    assert '_p=\'${ISSUE_NUMBER}\'; prompt="${prompt//"$_p"/"$ISSUE_NUMBER"}"' in script
+    assert '_p=\'$ISSUE_NUMBER\'; prompt="${prompt//"$_p"/"$ISSUE_NUMBER"}"' in script
 
 
 def test_render_harness_disambiguates_duplicate_step_function_names(tmp_path: Path) -> None: