[Phase 4] Workspace Hooks: Template Variable Rendering

[frankbria]

Summary

Add template variable rendering to hook scripts so they can reference task/workspace context dynamically.

Parent issue: #392

Scope

Add to core/hooks.py

1. Template rendering function:

   def render_hook_template(script: str, context: dict[str, str]) -> str

2. Supported variables:

   • {{task_id}} — current task ID
   • {{task_title}} — current task title
   • {{task_status}} — current task status
   • {{workspace_path}} — absolute workspace path
   • {{batch_id}} — batch ID (if in batch execution, else empty)
   • {{engine}} — execution engine (react/plan)

3. Rendering rules (following Symphony's strict approach):

   • Unknown variables raise an error (strict mode)
   • Empty/None values render as empty string
   • No nested template evaluation

4. Integrate rendering into run_hook() before shell execution

Acceptance Criteria

• All 6 template variables render correctly
• Unknown variables raise TemplateRenderError
• None values render as empty string
• Unit tests for all variable substitutions and error cases

Dependencies

• Depends on [Phase 4] Workspace Hooks: Execution Engine with Timeout and Error Handling #394 (hook execution engine)

[traycerai]

Plan

Observations

• codeframe/core/hooks.py does not exist yet — it must be created from scratch.
• The project already uses jinja2>=3.1.6 (in pyproject.toml) but the ticket calls for a custom {{...}}-style strict renderer, not Jinja2 (which uses the same delimiters — using plain re-based substitution is more appropriate and aligns with the "no nested evaluation" rule).
• Custom exceptions follow a per-module pattern (e.g., InvalidTransitionError in file:codeframe/core/state_machine.py, CycleDetectedError in file:codeframe/core/dependency_graph.py).
• Task model in file:codeframe/core/models.py has: id, title, status; Project model has workspace_path. batch_id and engine are runtime/execution-level values passed via context dict.
• Tests for core/ live under tests/core/ and follow pytest with pytest.mark.unit and parametrize patterns (see file:tests/debug/test_template.py and file:tests/lib/test_sdk_hooks.py as style references).

Approach

Create codeframe/core/hooks.py with TemplateRenderError, render_hook_template(), and run_hook(). Template rendering uses re.sub scanning for {{...}} tokens: known keys substitute (or render as "" for None), unknown keys raise TemplateRenderError. Then add tests/core/test_hooks.py covering all variables, error cases, and run_hook() integration.

---

Implementation Steps

1. Create codeframe/core/hooks.py

TemplateRenderError exception class

Define TemplateRenderError(Exception) at module level, following the same pattern as InvalidTransitionError in file:codeframe/core/state_machine.py:

• Accept variable_name: str in __init__
• Message: "Unknown template variable: '{{<variable_name>}}'"

SUPPORTED_VARIABLES constant

Define a module-level frozenset (or tuple) of the 6 supported variable names:
task_id, task_title, task_status, workspace_path, batch_id, engine

render_hook_template(script: str, context: dict[str, str]) -> str

• Use re.findall or re.sub with pattern r'\{\{(\w+)\}\}' to scan for all {{variable}} tokens
• For each matched variable name:
  • If not in SUPPORTED_VARIABLES → raise TemplateRenderError(variable_name)
  • If key is in context and value is None → substitute with ""
  • If key is in context with a value → substitute with str(value)
  • If key is in SUPPORTED_VARIABLES but not in context → substitute with "" (treat as missing/empty)
• Perform a single-pass substitution via re.sub with a replacement callable to avoid double-scanning
• Do not re-evaluate the rendered string (no nested template evaluation)
• Return the fully substituted string

run_hook(script: str, context: dict[str, str]) -> subprocess.CompletedProcess

• Call render_hook_template(script, context) to get the rendered command string
• Use subprocess.run with shell=True, capture_output=True, text=True (following the same pattern as file:codeframe/core/executor.py's _execute_shell_command)
• Return the CompletedProcess result; callers are responsible for checking returncode
• Let TemplateRenderError propagate up naturally (do not catch it here)

---

2. Create tests/core/test_hooks.py

Structure following the style in file:tests/lib/test_sdk_hooks.py and file:tests/debug/test_template.py:

render_hook_template tests — all 6 variable substitutions

Use @pytest.mark.parametrize for happy-path cases:

Template	Context	Expected output
"task: {{task_id}}"	{"task_id": "42"}	"task: 42"
"{{task_title}}"	{"task_title": "Fix bug"}	"Fix bug"
"status={{task_status}}"	{"task_status": "IN_PROGRESS"}	"status=IN_PROGRESS"
"cd {{workspace_path}}"	{"workspace_path": "/home/app"}	"cd /home/app"
"batch={{batch_id}}"	{"batch_id": "b-99"}	"batch=b-99"
"engine={{engine}}"	{"engine": "react"}	"engine=react"

None-value rendering tests

• A context value of None renders as "" (empty string)
• A variable in SUPPORTED_VARIABLES absent from context dict renders as ""

Unknown variable error tests

• "{{unknown_var}}" with any context raises TemplateRenderError
• Verify the exception message contains the variable name

No nested evaluation test

• A script rendered to contain {{task_id}} (e.g., via a value that itself contains braces) does not undergo a second pass of substitution

run_hook integration tests

• Mock subprocess.run (using unittest.mock.patch) to assert:
  • render_hook_template is called before subprocess.run
  • The rendered script (not the original) is passed to subprocess.run
• Assert TemplateRenderError propagates before subprocess.run is called if an unknown variable is in the script

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `codeframe/core/hooks.py` does **not exist yet** — it must be created from scratch.
- The project already uses `jinja2>=3.1.6` (in `pyproject.toml`) but the ticket calls for a custom `{{...}}`-style strict renderer, not Jinja2 (which uses the same delimiters — using plain `re`-based substitution is more appropriate and aligns with the "no nested evaluation" rule).
- Custom exceptions follow a per-module pattern (e.g., `InvalidTransitionError` in `file:codeframe/core/state_machine.py`, `CycleDetectedError` in `file:codeframe/core/dependency_graph.py`).
- `Task` model in `file:codeframe/core/models.py` has: `id`, `title`, `status`; `Project` model has `workspace_path`. `batch_id` and `engine` are runtime/execution-level values passed via context dict.
- Tests for `core/` live under `tests/core/` and follow `pytest` with `pytest.mark.unit` and parametrize patterns (see `file:tests/debug/test_template.py` and `file:tests/lib/test_sdk_hooks.py` as style references).

## Approach

Create `codeframe/core/hooks.py` with `TemplateRenderError`, `render_hook_template()`, and `run_hook()`. Template rendering uses `re.sub` scanning for `{{...}}` tokens: known keys substitute (or render as `""` for `None`), unknown keys raise `TemplateRenderError`. Then add `tests/core/test_hooks.py` covering all variables, error cases, and `run_hook()` integration.

---

## Implementation Steps

### 1. Create `codeframe/core/hooks.py`

**`TemplateRenderError` exception class**

Define `TemplateRenderError(Exception)` at module level, following the same pattern as `InvalidTransitionError` in `file:codeframe/core/state_machine.py`:
- Accept `variable_name: str` in `__init__`
- Message: `"Unknown template variable: '{{<variable_name>}}'"`

**`SUPPORTED_VARIABLES` constant**

Define a module-level `frozenset` (or tuple) of the 6 supported variable names:
`task_id`, `task_title`, `task_status`, `workspace_path`, `batch_id`, `engine`

**`render_hook_template(script: str, context: dict[str, str]) -> str`**

- Use `re.findall` or `re.sub` with pattern `r'\{\{(\w+)\}\}'` to scan for all `{{variable}}` tokens
- For each matched variable name:
  - If not in `SUPPORTED_VARIABLES` → raise `TemplateRenderError(variable_name)`
  - If key is in `context` and value is `None` → substitute with `""`
  - If key is in `context` with a value → substitute with `str(value)`
  - If key is in `SUPPORTED_VARIABLES` but not in `context` → substitute with `""` (treat as missing/empty)
- Perform a single-pass substitution via `re.sub` with a replacement callable to avoid double-scanning
- Do **not** re-evaluate the rendered string (no nested template evaluation)
- Return the fully substituted string

**`run_hook(script: str, context: dict[str, str]) -> subprocess.CompletedProcess`**

- Call `render_hook_template(script, context)` to get the rendered command string
- Use `subprocess.run` with `shell=True`, `capture_output=True`, `text=True` (following the same pattern as `file:codeframe/core/executor.py`'s `_execute_shell_command`)
- Return the `CompletedProcess` result; callers are responsible for checking `returncode`
- Let `TemplateRenderError` propagate up naturally (do not catch it here)

---

### 2. Create `tests/core/test_hooks.py`

Structure following the style in `file:tests/lib/test_sdk_hooks.py` and `file:tests/debug/test_template.py`:

**`render_hook_template` tests — all 6 variable substitutions**

Use `@pytest.mark.parametrize` for happy-path cases:

| Template | Context | Expected output |
|---|---|---|
| `"task: {{task_id}}"` | `{"task_id": "42"}` | `"task: 42"` |
| `"{{task_title}}"` | `{"task_title": "Fix bug"}` | `"Fix bug"` |
| `"status={{task_status}}"` | `{"task_status": "IN_PROGRESS"}` | `"status=IN_PROGRESS"` |
| `"cd {{workspace_path}}"` | `{"workspace_path": "/home/app"}` | `"cd /home/app"` |
| `"batch={{batch_id}}"` | `{"batch_id": "b-99"}` | `"batch=b-99"` |
| `"engine={{engine}}"` | `{"engine": "react"}` | `"engine=react"` |

**`None`-value rendering tests**

- A context value of `None` renders as `""` (empty string)
- A variable in `SUPPORTED_VARIABLES` absent from `context` dict renders as `""`

**Unknown variable error tests**

- `"{{unknown_var}}"` with any context raises `TemplateRenderError`
- Verify the exception message contains the variable name

**No nested evaluation test**

- A script rendered to contain `{{task_id}}` (e.g., via a value that itself contains braces) does **not** undergo a second pass of substitution

**`run_hook` integration tests**

- Mock `subprocess.run` (using `unittest.mock.patch`) to assert:
  - `render_hook_template` is called before `subprocess.run`
  - The rendered script (not the original) is passed to `subprocess.run`
- Assert `TemplateRenderError` propagates before `subprocess.run` is called if an unknown variable is in the script

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[frankbria]

Implemented in PR #438 (merged). All hook system components (config schema, execution engine, template rendering, runtime integration, CLI commands) were delivered as a single PR implementing the parent issue #392.