feat: pass RALPH_NAME env var to context and check scripts

Context and check scripts can now read $RALPH_NAME to dynamically
resolve per-ralph state (e.g. context/workspace/ralphs/$RALPH_NAME/).
The env var is set when running a named ralph and omitted for ad-hoc
prompts. run_command() gains an env parameter that merges with the
parent environment so scripts keep PATH etc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/ralphify/_runner.py

@@ -7,6 +7,7 @@
 
 from __future__ import annotations
 
+import os
 import shlex
 import subprocess
 from dataclasses import dataclass
@@ -31,6 +32,7 @@ def run_command(
     command: str | None,
     cwd: Path,
     timeout: int,
+    env: dict[str, str] | None = None,
 ) -> RunResult:
     """Run a script or shell command and return the result.
 
@@ -39,20 +41,27 @@ def run_command(
     Pipes, redirections, and ``&&`` chaining are not supported in
     commands — use a ``run.*`` script for complex logic.
 
+    When *env* is set, the given variables are merged on top of the
+    current process environment so scripts keep ``PATH`` etc.  When
+    ``None`` (default), ``subprocess.run`` inherits the parent env.
+
     On timeout, returns ``exit_code=-1`` and ``timed_out=True``.
     """
     if script:
         cmd = [str(script)]
     else:
         cmd = shlex.split(command)
 
+    merged_env = {**os.environ, **env} if env else None
+
     try:
         result = subprocess.run(
             cmd,
             capture_output=True,
             text=True,
             cwd=cwd,
             timeout=timeout,
+            env=merged_env,
         )
         return RunResult(
             success=result.returncode == 0,

src/ralphify/checks.py

@@ -118,18 +118,23 @@ def discover_enabled_checks(root: Path, ralph_dir: Path | None = None) -> list[C
     return discover_enabled(root, ralph_dir, discover_checks, discover_checks_local)
 
 
-def run_check(check: Check, project_root: Path) -> CheckResult:
+def run_check(check: Check, project_root: Path, ralph_name: str | None = None) -> CheckResult:
     """Run a single check and return the result.
 
     The check's script or command executes with *project_root* as the
     working directory.  On timeout, ``exit_code`` is ``-1`` and
     ``timed_out`` is ``True``.
+
+    When *ralph_name* is set, a ``RALPH_NAME`` environment variable is
+    passed to the subprocess so scripts can read per-ralph state.
     """
+    env = {"RALPH_NAME": ralph_name} if ralph_name else None
     r = run_command(
         script=check.script,
         command=check.command,
         cwd=project_root,
         timeout=check.timeout,
+        env=env,
     )
     return CheckResult(
         check=check,
@@ -140,7 +145,7 @@ def run_check(check: Check, project_root: Path) -> CheckResult:
     )
 
 
-def run_all_checks(checks: list[Check], project_root: Path) -> list[CheckResult]:
+def run_all_checks(checks: list[Check], project_root: Path, ralph_name: str | None = None) -> list[CheckResult]:
     """Run every check sequentially and return all results.
 
     Checks execute in the order given (the engine sorts alphabetically by
@@ -150,8 +155,11 @@ def run_all_checks(checks: list[Check], project_root: Path) -> list[CheckResult]
     The engine passes the results to :func:`format_check_failures`, which
     formats them as markdown for injection into the next iteration's prompt.
     This is what drives the self-healing feedback loop.
+
+    When *ralph_name* is set, it is forwarded to each check subprocess
+    as the ``RALPH_NAME`` environment variable.
     """
-    return [run_check(check, project_root) for check in checks]
+    return [run_check(check, project_root, ralph_name) for check in checks]
 
 
 def format_check_failures(results: list[CheckResult]) -> str:

src/ralphify/contexts.py

@@ -91,22 +91,27 @@ def discover_enabled_contexts(root: Path, ralph_dir: Path | None = None) -> list
     return discover_enabled(root, ralph_dir, discover_contexts, discover_contexts_local)
 
 
-def run_context(context: Context, project_root: Path) -> ContextResult:
+def run_context(context: Context, project_root: Path, ralph_name: str | None = None) -> ContextResult:
     """Run a single context and return the result.
 
     Static-only contexts (no script or command) return immediately with
     ``success=True`` and empty output.  The static content is combined
     with command output later during prompt resolution.
+
+    When *ralph_name* is set, a ``RALPH_NAME`` environment variable is
+    passed to the subprocess so scripts can read per-ralph state.
     """
     if not context.script and not context.command:
         # Static-only context, no command to run
         return ContextResult(context=context, output="", success=True)
 
+    env = {"RALPH_NAME": ralph_name} if ralph_name else None
     r = run_command(
         script=context.script,
         command=context.command,
         cwd=project_root,
         timeout=context.timeout,
+        env=env,
     )
     return ContextResult(
         context=context,
@@ -116,14 +121,17 @@ def run_context(context: Context, project_root: Path) -> ContextResult:
     )
 
 
-def run_all_contexts(contexts: list[Context], project_root: Path) -> list[ContextResult]:
+def run_all_contexts(contexts: list[Context], project_root: Path, ralph_name: str | None = None) -> list[ContextResult]:
     """Run every context sequentially and return all results.
 
     Each context's command (or script) executes with *project_root* as the
     working directory.  Static-only contexts return immediately.  Results
     are passed to :func:`resolve_contexts` for prompt injection.
+
+    When *ralph_name* is set, it is forwarded to each context subprocess
+    as the ``RALPH_NAME`` environment variable.
     """
-    return [run_context(ctx, project_root) for ctx in contexts]
+    return [run_context(ctx, project_root, ralph_name) for ctx in contexts]
 
 
 def resolve_contexts(prompt: str, results: list[ContextResult]) -> str:

src/ralphify/engine.py

@@ -231,6 +231,7 @@ def _run_checks_phase(
     project_root: Path,
     state: RunState,
     emit: _BoundEmitter,
+    ralph_name: str | None = None,
 ) -> str:
     """Execute all checks, emit per-check and summary events.
 
@@ -241,7 +242,7 @@ def _run_checks_phase(
 
     emit(EventType.CHECKS_STARTED, {"iteration": iteration, "count": len(enabled_checks)})
 
-    check_results = run_all_checks(enabled_checks, project_root)
+    check_results = run_all_checks(enabled_checks, project_root, ralph_name)
 
     # Build per-result data once; reused for both per-check and summary events.
     results_data: list[dict] = []
@@ -287,7 +288,7 @@ def _run_iteration(
     context_results: list[ContextResult] = []
     if primitives.contexts:
         context_results = run_all_contexts(
-            primitives.contexts, config.project_root,
+            primitives.contexts, config.project_root, config.ralph_name,
         )
         emit(EventType.CONTEXTS_RESOLVED, {"iteration": iteration, "count": len(primitives.contexts)})
 
@@ -307,7 +308,7 @@ def _run_iteration(
 
     if primitives.checks:
         check_failures_text = _run_checks_phase(
-            primitives.checks, config.project_root, state, emit,
+            primitives.checks, config.project_root, state, emit, config.ralph_name,
         )
 
     return check_failures_text, True

tests/test_checks.py

@@ -365,6 +365,27 @@ def test_combines_stdout_and_stderr(self, mock_run):
         assert "out" in result.output
         assert "err" in result.output
 
+    @patch(_MOCK_SUBPROCESS)
+    def test_ralph_name_passed_as_env(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        check = self._make_check()
+        run_check(check, Path("/project"), ralph_name="docs")
+
+        passed_env = mock_run.call_args.kwargs["env"]
+        assert passed_env["RALPH_NAME"] == "docs"
+
+    @patch(_MOCK_SUBPROCESS)
+    def test_ralph_name_none_no_env(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        check = self._make_check()
+        run_check(check, Path("/project"), ralph_name=None)
+
+        assert mock_run.call_args.kwargs["env"] is None
+
 
 class TestRunAllChecks:
     @patch(_MOCK_SUBPROCESS)

tests/test_contexts.py

@@ -281,6 +281,27 @@ def test_combines_stdout_and_stderr(self, mock_run):
         assert "out" in result.output
         assert "err" in result.output
 
+    @patch(_MOCK_SUBPROCESS)
+    def test_ralph_name_passed_as_env(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        ctx = self._make_context()
+        run_context(ctx, Path("/project"), ralph_name="docs")
+
+        passed_env = mock_run.call_args.kwargs["env"]
+        assert passed_env["RALPH_NAME"] == "docs"
+
+    @patch(_MOCK_SUBPROCESS)
+    def test_ralph_name_none_no_env(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        ctx = self._make_context()
+        run_context(ctx, Path("/project"), ralph_name=None)
+
+        assert mock_run.call_args.kwargs["env"] is None
+
 
 class TestRunAllContexts:
     @patch(_MOCK_SUBPROCESS)

tests/test_engine.py

@@ -529,3 +529,53 @@ def test_no_ralph_name_returns_none(self):
             ralph_file="RALPH.md",
         )
         assert _resolve_ralph_dir(config) is None
+
+
+class TestRalphNameEnv:
+    """Tests that ralph_name flows to context and check subprocesses."""
+
+    @patch(_MOCK_SUBPROCESS, side_effect=_ok)
+    def test_ralph_name_passed_to_context_scripts(self, mock_run, tmp_path):
+        """When ralph_name is set, context scripts receive RALPH_NAME env var."""
+        # Create a context with a command
+        ctx_dir = tmp_path / ".ralphify" / "contexts" / "test-ctx"
+        ctx_dir.mkdir(parents=True)
+        (ctx_dir / "CONTEXT.md").write_text("---\ncommand: echo hi\n---\n")
+
+        config = _make_config(tmp_path, ralph_name="docs", max_iterations=1)
+        state = _make_state()
+        run_loop(config, state, NullEmitter())
+
+        # Find the context subprocess call (first call before the agent call)
+        context_call = mock_run.call_args_list[0]
+        assert context_call.kwargs["env"]["RALPH_NAME"] == "docs"
+
+    @patch(_MOCK_SUBPROCESS, side_effect=_ok)
+    def test_ralph_name_passed_to_check_scripts(self, mock_run, tmp_path):
+        """When ralph_name is set, check scripts receive RALPH_NAME env var."""
+        # Create a check with a command
+        check_dir = tmp_path / ".ralphify" / "checks" / "test-chk"
+        check_dir.mkdir(parents=True)
+        (check_dir / "CHECK.md").write_text("---\ncommand: echo ok\n---\n")
+
+        config = _make_config(tmp_path, ralph_name="docs", max_iterations=1)
+        state = _make_state()
+        run_loop(config, state, NullEmitter())
+
+        # The check call is after the agent call
+        check_call = mock_run.call_args_list[-1]
+        assert check_call.kwargs["env"]["RALPH_NAME"] == "docs"
+
+    @patch(_MOCK_SUBPROCESS, side_effect=_ok)
+    def test_no_ralph_name_no_env(self, mock_run, tmp_path):
+        """When ralph_name is None, no custom env is passed."""
+        ctx_dir = tmp_path / ".ralphify" / "contexts" / "test-ctx"
+        ctx_dir.mkdir(parents=True)
+        (ctx_dir / "CONTEXT.md").write_text("---\ncommand: echo hi\n---\n")
+
+        config = _make_config(tmp_path, ralph_name=None, max_iterations=1)
+        state = _make_state()
+        run_loop(config, state, NullEmitter())
+
+        context_call = mock_run.call_args_list[0]
+        assert context_call.kwargs["env"] is None

tests/test_runner.py

@@ -1,3 +1,4 @@
+import os
 import subprocess
 from pathlib import Path
 from unittest.mock import patch
@@ -88,3 +89,25 @@ def test_combines_stdout_and_stderr(self, mock_run):
 
         assert "out" in result.output
         assert "err" in result.output
+
+    @patch(_MOCK_SUBPROCESS)
+    def test_env_merged_with_parent(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        run_command(script=None, command="echo", cwd=Path("/project"), timeout=60, env={"RALPH_NAME": "docs"})
+
+        passed_env = mock_run.call_args.kwargs["env"]
+        assert passed_env["RALPH_NAME"] == "docs"
+        # Parent env vars (like PATH) should be preserved
+        assert "PATH" in passed_env
+
+    @patch(_MOCK_SUBPROCESS)
+    def test_env_none_inherits_parent(self, mock_run):
+        mock_run.return_value = subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="", stderr=""
+        )
+        run_command(script=None, command="echo", cwd=Path("/project"), timeout=60, env=None)
+
+        # env=None means subprocess.run inherits parent env
+        assert mock_run.call_args.kwargs["env"] is None