[Phase 4] Workspace Hooks: Integration with Runtime Task Lifecycle

[frankbria]

Summary

Wire the hook execution engine into CodeFrame's runtime so hooks fire at the correct lifecycle moments during task and batch execution.

Parent issue: #392

Scope

Changes to core/runtime.py

1. Load HooksConfig from workspace agents config at run start

2. Call hooks at lifecycle points:

   • after_init → after cf init completes workspace setup (in workspace.py)
   • before_task → in start_task_run(), after creating run but before agent launch
   • after_task_success → in complete_run(), after task transitions to DONE
   • after_task_failure → in fail_run(), after task transitions to FAILED
   • before_remove → not currently applicable (CodeFrame doesn't auto-remove workspaces), wire as future extension point

3. Failure handling:

   • before_task failure → abort the run, transition task to FAILED with hook error context
   • after_task_* failures → log warning, continue

Changes to core/conductor.py

4. Ensure batch execution calls hooks for each task in the batch

Changes to core/workspace.py

5. Call after_init hook after workspace initialization

Acceptance Criteria

• before_task hook runs before agent launch in single-task execution
• before_task hook failure aborts the run with clear error message
• after_task_success hook runs after successful completion
• after_task_failure hook runs after failure
• Hooks fire correctly during batch execution (per-task, not per-batch)
• after_init hook runs after cf init
• Integration tests: hook fires → task succeeds, hook fails → task aborted

Dependencies

• Depends on [Phase 4] Workspace Hooks: Execution Engine with Timeout and Error Handling #394 (execution engine) and [Phase 4] Workspace Hooks: Template Variable Rendering #395 (template rendering)

[traycerai]

Plan

Observations

The codebase has a clean, headless v2 core: runtime.py owns single-task lifecycle (start_task_run, complete_run, fail_run), conductor.py owns batch orchestration via _execute_serial, _execute_parallel, and _execute_single_task, and workspace.py owns init via create_or_load_workspace. The cf init command lives in file:codeframe/cli/app.py. The hook execution engine (HooksConfig, HookExecutor) and template rendering are being delivered by the upstream PRs #394/#395 — this issue's job is purely wiring those into the existing lifecycle points.

Approach

The plan introduces a thin _run_hook helper in runtime.py that calls the HookExecutor (from #394) using a HooksConfig loaded from AgentPreferences (already loaded per workspace). Each lifecycle point in runtime.py, conductor.py, and workspace.py is augmented with calls at the exact moments prescribed in the issue. The hook context dict provides task/workspace metadata needed by template rendering (#395).

---

Implementation Steps

1. Extend HooksConfig loading from workspace config

In file:codeframe/core/agents_config.py, add a hooks section to AgentPreferences to carry HooksConfig when #394 makes it available. The load_preferences function already walks AGENTS.md/CLAUDE.md; extend _parse_agents_md to also parse a ## Hooks section into a HooksConfig instance (using the data model from #394). Add a hooks: Optional[HooksConfig] field to AgentPreferences (defaulting to None).

Dependency: This step requires HooksConfig from #394 to be merged first.

---

2. Add _run_hook helper to runtime.py

In file:codeframe/core/runtime.py, add a private helper function _run_hook(workspace, hook_name, context_data) that:

1. Calls load_preferences(workspace.repo_path) from codeframe.core.agents_config to obtain the AgentPreferences, then reads .hooks.
2. If no hooks config is present, returns immediately (no-op).
3. Instantiates the HookExecutor from [Phase 4] Workspace Hooks: Execution Engine with Timeout and Error Handling #394 and calls executor.run(hook_name, context_data).
4. Returns a result object indicating success/failure.

Keep it synchronous (matching the existing runtime pattern — no async). Wrap execution in a try/except so callers can decide whether to propagate or swallow errors.

---

3. Wire before_task in start_task_run()

In file:codeframe/core/runtime.py, inside start_task_run(), after the run record is committed to the database (line ~121) but before emitting RUN_STARTED (line ~124):

• Call _run_hook(workspace, "before_task", {"task_id": task_id, "run_id": run_id, "workspace_id": workspace.id}).
• If the hook raises / returns a failure result:
  • Roll back the run record: delete the just-inserted row from the runs table.
  • Transition the task back to READY (reverting the IN_PROGRESS status set above).
  • Raise a HookError (a new lightweight exception, or RuntimeError) with a clear message like "before_task hook failed: <reason>; aborting run" — the caller in the CLI/conductor will catch this and surface it to the user.

---

4. Wire after_task_success in complete_run()

In file:codeframe/core/runtime.py, inside complete_run(), after tasks.update_status(workspace, run.task_id, TaskStatus.DONE) (line ~356) and after the RUN_COMPLETED event is emitted:

• Call _run_hook(workspace, "after_task_success", {"task_id": run.task_id, "run_id": run_id, "workspace_id": workspace.id}).
• On failure: log a warning via logger.warning(...) and continue — do not re-fail the run or transition the task status.

---

5. Wire after_task_failure in fail_run()

In file:codeframe/core/runtime.py, inside fail_run(), after tasks.update_status(workspace, run.task_id, TaskStatus.FAILED) (line ~419):

• Call _run_hook(workspace, "after_task_failure", {"task_id": run.task_id, "run_id": run_id, "reason": reason, "workspace_id": workspace.id}).
• On failure: log a warning via logger.warning(...) and continue.

---

6. Wire after_init in workspace.py

In file:codeframe/core/workspace.py, inside create_or_load_workspace(), only on the new-workspace path (after line ~509 where the Workspace object is constructed and returned from fresh init):

• Import load_preferences from codeframe.core.agents_config and the HookExecutor from [Phase 4] Workspace Hooks: Execution Engine with Timeout and Error Handling #394.
• Call the hook inline: _run_hook(workspace, "after_init", {"workspace_id": workspace.id, "repo_path": str(repo_path)}).
• On failure: log a warning — do not abort workspace creation; the workspace is already persisted.
• Do not trigger after_init when the workspace already existed (the already_existed branch in create_or_load_workspace).

Since workspace.py is currently a pure data-layer module with no hook awareness, keep the hook call minimal and guard it behind try/except to preserve the idempotent guarantee of create_or_load_workspace.

---

7. Ensure hooks fire per-task in batch execution (conductor.py)

The batch conductor calls _execute_task_subprocess() which runs cf work start <task_id> --execute as a subprocess. Since hooks are wired into start_task_run() / complete_run() / fail_run() in runtime.py, they will already fire correctly for each subprocess call — no changes needed in the subprocess path.

However, for the _execute_single_task() function in file:codeframe/core/conductor.py (used by parallel execution), verify that any direct in-process task execution (non-subprocess) also goes through start_task_run and complete_run/fail_run from runtime.py. If there are any direct status updates bypassing these functions, redirect them. Based on the current code, _execute_task_subprocess is the sole execution path for both serial and parallel, so no structural changes are required in conductor.py.

---

8. Add HOOK_FIRED and HOOK_FAILED event types to EventType

In file:codeframe/core/events.py, add two new constants to the EventType class:

HOOK_FIRED = "HOOK_FIRED"
HOOK_FAILED = "HOOK_FAILED"

Update _run_hook in runtime.py to emit HOOK_FIRED on success and HOOK_FAILED on failure using events.emit_for_workspace(), carrying {"hook_name": hook_name, ...context_data}. This integrates hook activity into the existing event log for observability.

---

9. Register before_remove as a no-op extension point

In file:codeframe/core/runtime.py, add a stub function fire_before_remove_hook(workspace) that calls _run_hook(workspace, "before_remove", {"workspace_id": workspace.id}). Document it as a future extension point (CodeFrame does not auto-remove workspaces currently). Do not wire it into any call site yet — this satisfies the spec's "wire as future extension point" requirement.

---

Sequence Diagram

sequenceDiagram
    participant CLI as cf init / cf work start
    participant WS as workspace.py
    participant RT as runtime.py
    participant HE as HookExecutor (#394)
    participant AG as execute_agent()

    CLI->>WS: create_or_load_workspace()
    WS->>HE: _run_hook("after_init", ctx)
    HE-->>WS: ok (warn on failure)
    WS-->>CLI: Workspace

    CLI->>RT: start_task_run(workspace, task_id)
    RT->>RT: create run record in DB
    RT->>HE: _run_hook("before_task", ctx)
    alt hook fails
        HE-->>RT: failure
        RT->>RT: rollback run, revert task to READY
        RT-->>CLI: raise HookError
    else hook passes
        HE-->>RT: ok
        RT-->>CLI: Run
    end

    CLI->>AG: execute_agent(workspace, run)
    AG->>RT: complete_run() or fail_run()

    RT->>HE: _run_hook("after_task_success"|"after_task_failure", ctx)
    HE-->>RT: ok or warn (never aborts)
    RT-->>AG: Run (updated)

Loading

---

Summary of File Changes

File	Change
file:codeframe/core/agents_config.py	Add hooks: Optional[HooksConfig] to AgentPreferences; parse ## Hooks section
file:codeframe/core/runtime.py	Add _run_hook() helper; wire before_task in start_task_run(), after_task_success in complete_run(), after_task_failure in fail_run(); add fire_before_remove_hook() stub
file:codeframe/core/workspace.py	Wire after_init hook in create_or_load_workspace() on new-workspace path only
file:codeframe/core/events.py	Add HOOK_FIRED and HOOK_FAILED event type constants
file:codeframe/core/conductor.py	No structural changes required (subprocess path already routes through runtime.py)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clean, headless v2 core: `runtime.py` owns single-task lifecycle (`start_task_run`, `complete_run`, `fail_run`), `conductor.py` owns batch orchestration via `_execute_serial`, `_execute_parallel`, and `_execute_single_task`, and `workspace.py` owns init via `create_or_load_workspace`. The `cf init` command lives in `file:codeframe/cli/app.py`. The hook execution engine (`HooksConfig`, `HookExecutor`) and template rendering are being delivered by the upstream PRs #394/#395 — this issue's job is purely wiring those into the existing lifecycle points.

## Approach

The plan introduces a thin `_run_hook` helper in `runtime.py` that calls the `HookExecutor` (from #394) using a `HooksConfig` loaded from `AgentPreferences` (already loaded per workspace). Each lifecycle point in `runtime.py`, `conductor.py`, and `workspace.py` is augmented with calls at the exact moments prescribed in the issue. The hook context dict provides task/workspace metadata needed by template rendering (#395).

---

## Implementation Steps

### 1. Extend `HooksConfig` loading from workspace config

In `file:codeframe/core/agents_config.py`, add a `hooks` section to `AgentPreferences` to carry `HooksConfig` when #394 makes it available. The `load_preferences` function already walks `AGENTS.md`/`CLAUDE.md`; extend `_parse_agents_md` to also parse a `## Hooks` section into a `HooksConfig` instance (using the data model from #394). Add a `hooks: Optional[HooksConfig]` field to `AgentPreferences` (defaulting to `None`).

> **Dependency**: This step requires `HooksConfig` from #394 to be merged first.

---

### 2. Add `_run_hook` helper to `runtime.py`

In `file:codeframe/core/runtime.py`, add a private helper function `_run_hook(workspace, hook_name, context_data)` that:

1. Calls `load_preferences(workspace.repo_path)` from `codeframe.core.agents_config` to obtain the `AgentPreferences`, then reads `.hooks`.
2. If no hooks config is present, returns immediately (no-op).
3. Instantiates the `HookExecutor` from #394 and calls `executor.run(hook_name, context_data)`.
4. Returns a result object indicating success/failure.

Keep it synchronous (matching the existing runtime pattern — no async). Wrap execution in a `try/except` so callers can decide whether to propagate or swallow errors.

---

### 3. Wire `before_task` in `start_task_run()`

In `file:codeframe/core/runtime.py`, inside `start_task_run()`, after the run record is committed to the database (line ~121) **but before** emitting `RUN_STARTED` (line ~124):

- Call `_run_hook(workspace, "before_task", {"task_id": task_id, "run_id": run_id, "workspace_id": workspace.id})`.
- If the hook raises / returns a failure result:
  - Roll back the run record: delete the just-inserted row from the `runs` table.
  - Transition the task back to `READY` (reverting the `IN_PROGRESS` status set above).
  - Raise a `HookError` (a new lightweight exception, or `RuntimeError`) with a clear message like `"before_task hook failed: <reason>; aborting run"` — the caller in the CLI/conductor will catch this and surface it to the user.

---

### 4. Wire `after_task_success` in `complete_run()`

In `file:codeframe/core/runtime.py`, inside `complete_run()`, **after** `tasks.update_status(workspace, run.task_id, TaskStatus.DONE)` (line ~356) and **after** the `RUN_COMPLETED` event is emitted:

- Call `_run_hook(workspace, "after_task_success", {"task_id": run.task_id, "run_id": run_id, "workspace_id": workspace.id})`.
- On failure: log a warning via `logger.warning(...)` and continue — do **not** re-fail the run or transition the task status.

---

### 5. Wire `after_task_failure` in `fail_run()`

In `file:codeframe/core/runtime.py`, inside `fail_run()`, **after** `tasks.update_status(workspace, run.task_id, TaskStatus.FAILED)` (line ~419):

- Call `_run_hook(workspace, "after_task_failure", {"task_id": run.task_id, "run_id": run_id, "reason": reason, "workspace_id": workspace.id})`.
- On failure: log a warning via `logger.warning(...)` and continue.

---

### 6. Wire `after_init` in `workspace.py`

In `file:codeframe/core/workspace.py`, inside `create_or_load_workspace()`, **only on the new-workspace path** (after line ~509 where the `Workspace` object is constructed and returned from fresh init):

- Import `load_preferences` from `codeframe.core.agents_config` and the `HookExecutor` from #394.
- Call the hook inline: `_run_hook(workspace, "after_init", {"workspace_id": workspace.id, "repo_path": str(repo_path)})`.
- On failure: log a warning — do not abort workspace creation; the workspace is already persisted.
- Do **not** trigger `after_init` when the workspace already existed (the `already_existed` branch in `create_or_load_workspace`).

> Since `workspace.py` is currently a pure data-layer module with no hook awareness, keep the hook call minimal and guard it behind `try/except` to preserve the idempotent guarantee of `create_or_load_workspace`.

---

### 7. Ensure hooks fire per-task in batch execution (`conductor.py`)

The batch conductor calls `_execute_task_subprocess()` which runs `cf work start <task_id> --execute` as a subprocess. Since hooks are wired into `start_task_run()` / `complete_run()` / `fail_run()` in `runtime.py`, they will **already fire correctly** for each subprocess call — no changes needed in the subprocess path.

However, for the `_execute_single_task()` function in `file:codeframe/core/conductor.py` (used by parallel execution), verify that any direct in-process task execution (non-subprocess) also goes through `start_task_run` and `complete_run`/`fail_run` from `runtime.py`. If there are any direct status updates bypassing these functions, redirect them. Based on the current code, `_execute_task_subprocess` is the sole execution path for both serial and parallel, so no structural changes are required in `conductor.py`.

---

### 8. Add `HOOK_FIRED` and `HOOK_FAILED` event types to `EventType`

In `file:codeframe/core/events.py`, add two new constants to the `EventType` class:

```
HOOK_FIRED = "HOOK_FIRED"
HOOK_FAILED = "HOOK_FAILED"
```

Update `_run_hook` in `runtime.py` to emit `HOOK_FIRED` on success and `HOOK_FAILED` on failure using `events.emit_for_workspace()`, carrying `{"hook_name": hook_name, ...context_data}`. This integrates hook activity into the existing event log for observability.

---

### 9. Register `before_remove` as a no-op extension point

In `file:codeframe/core/runtime.py`, add a stub function `fire_before_remove_hook(workspace)` that calls `_run_hook(workspace, "before_remove", {"workspace_id": workspace.id})`. Document it as a future extension point (CodeFrame does not auto-remove workspaces currently). Do not wire it into any call site yet — this satisfies the spec's "wire as future extension point" requirement.

---

## Sequence Diagram

```mermaid
sequenceDiagram
    participant CLI as cf init / cf work start
    participant WS as workspace.py
    participant RT as runtime.py
    participant HE as HookExecutor (#394)
    participant AG as execute_agent()

    CLI->>WS: create_or_load_workspace()
    WS->>HE: _run_hook("after_init", ctx)
    HE-->>WS: ok (warn on failure)
    WS-->>CLI: Workspace

    CLI->>RT: start_task_run(workspace, task_id)
    RT->>RT: create run record in DB
    RT->>HE: _run_hook("before_task", ctx)
    alt hook fails
        HE-->>RT: failure
        RT->>RT: rollback run, revert task to READY
        RT-->>CLI: raise HookError
    else hook passes
        HE-->>RT: ok
        RT-->>CLI: Run
    end

    CLI->>AG: execute_agent(workspace, run)
    AG->>RT: complete_run() or fail_run()

    RT->>HE: _run_hook("after_task_success"|"after_task_failure", ctx)
    HE-->>RT: ok or warn (never aborts)
    RT-->>AG: Run (updated)
```

---

## Summary of File Changes

| File | Change |
|---|---|
| `file:codeframe/core/agents_config.py` | Add `hooks: Optional[HooksConfig]` to `AgentPreferences`; parse `## Hooks` section |
| `file:codeframe/core/runtime.py` | Add `_run_hook()` helper; wire `before_task` in `start_task_run()`, `after_task_success` in `complete_run()`, `after_task_failure` in `fail_run()`; add `fire_before_remove_hook()` stub |
| `file:codeframe/core/workspace.py` | Wire `after_init` hook in `create_or_load_workspace()` on new-workspace path only |
| `file:codeframe/core/events.py` | Add `HOOK_FIRED` and `HOOK_FAILED` event type constants |
| `file:codeframe/core/conductor.py` | No structural changes required (subprocess path already routes through `runtime.py`) |

---

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.

[coderabbitai]

🔗 Related PRs

#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]
#369 - test: add CLI integration tests for ReactAgent runtime parameters [merged]
#387 - [Phase 2.5-F] Wire engine parameter through v2 API routes (#354) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[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.