[Phase 4] Workspace Hooks: CLI Commands for Hook Management

[frankbria]

Summary

Add CLI commands for listing, testing, and managing workspace hooks.

Parent issue: #392

Scope

New CLI subcommands in cli/app.py

1. cf hooks list — show configured hooks for current workspace

   • Display hook name, script preview (first 80 chars), timeout
   • Indicate which hooks are configured vs. not set

2. cf hooks test <hook-name> — dry-run a specific hook

   • Execute the hook with current workspace context
   • Show stdout/stderr/exit code
   • Useful for validating hook scripts before relying on them

3. cf hooks show <hook-name> — display full hook script and config

Changes to existing commands

4. cf status — show hook summary (N hooks configured) in workspace status output

Acceptance Criteria

• cf hooks list displays all configured hooks with preview
• cf hooks test before_task executes the hook and shows results
• cf hooks show after_init displays the full script
• cf status includes hook count in workspace summary
• CLI integration tests for all new commands

Dependencies

• Depends on [Phase 4] Workspace Hooks: Configuration Schema and Parser #393 (config schema) and [Phase 4] Workspace Hooks: Execution Engine with Timeout and Error Handling #394 (execution engine)

[traycerai]

Plan

Observations

The CLI uses Typer with a sub-app pattern: each domain lives in its own codeframe/cli/<domain>_commands.py file, defines a <domain>_app = typer.Typer(...), and gets registered in app.py via app.add_typer(...). The EnvironmentConfig dataclass in codeframe/core/config.py drives .codeframe/config.yaml and is the natural home for hook config. No codeframe/core/hooks.py or hooks_commands.py exists yet — this ticket creates both from scratch.

Approach

Since #393 (config schema) and #394 (execution engine) are dependencies, this plan covers all three layers in sequence: extend EnvironmentConfig with a hook schema, create a codeframe/core/hooks.py execution engine, then build codeframe/cli/hooks_commands.py and wire it into app.py. Finally, update the status command to surface hook count. This keeps every layer minimal and consistent with existing patterns.

---

Implementation Plan

Step 1 — Extend EnvironmentConfig with a hook config schema (#393)

In file:codeframe/core/config.py:

• Add a HookConfig dataclass with the fields:
  • script: str — the shell command / script body to execute
  • timeout: int — seconds before the hook is killed (default 30)
• Add a WorkspaceHooksConfig dataclass with optional HookConfig fields for each named lifecycle point:
  • before_init, after_init, before_task, after_task
  • Each field defaults to None (hook not configured)
• Add a hooks: WorkspaceHooksConfig field to EnvironmentConfig, defaulting to an empty WorkspaceHooksConfig().
• Update EnvironmentConfig.from_dict to deserialise nested HookConfig objects within WorkspaceHooksConfig.
• Update EnvironmentConfig.to_dict to serialise them back correctly (the existing asdict call handles dataclasses recursively, so this should just work).

The resulting YAML shape under .codeframe/config.yaml will look like:

hooks:
  before_task:
    script: "echo pre-task"
    timeout: 30
  after_init:
    script: "./scripts/post_init.sh"
    timeout: 60

---

Step 2 — Create the hook execution engine (#394)

Create file:codeframe/core/hooks.py.

Key public API to expose:

Symbol	Purpose
HookResult dataclass	Holds hook_name, exit_code, stdout, stderr, duration_ms, timed_out: bool
run_hook(hook_cfg: HookConfig, workspace: Workspace, dry_run: bool) -> HookResult	Executes the shell script, captures output, enforces timeout
get_configured_hooks(env_cfg: EnvironmentConfig) -> dict[str, HookConfig]	Returns only the hooks that are not None
count_configured_hooks(env_cfg: EnvironmentConfig) -> int	Convenience count for the status command

Implementation notes for run_hook:

• Use subprocess.run with capture_output=True, timeout=hook_cfg.timeout, running the script via the shell (shell=True) in the workspace's repo_path as cwd.
• If dry_run=True, skip execution and return a HookResult with a sentinel exit_code=-1 and a stdout message indicating the dry-run, so the CLI can display it clearly.
• Catch subprocess.TimeoutExpired and set timed_out=True on the result.
• Catch other Exception and surface via stderr.

---

Step 3 — Create codeframe/cli/hooks_commands.py

Follow the exact pattern from file:codeframe/cli/env_commands.py:

hooks_app = typer.Typer(
    name="hooks",
    help="Workspace hook management",
    no_args_is_help=True,
)

3a — cf hooks list

@hooks_app.command("list")

• Load workspace via get_workspace(path), then load EnvironmentConfig via load_environment_config(path).
• Call get_configured_hooks(env_cfg) to get the active hooks dict.
• Define the canonical hook names list: ["before_init", "after_init", "before_task", "after_task"].
• Use a rich.table.Table with columns Hook, Status, Script preview, Timeout — consistent with the table style in env_commands.py.
• For each canonical hook name: show [green]configured[/green] or [dim]not set[/dim]; for configured ones, show the first 80 characters of script and the timeout.

3b — cf hooks test <hook-name>

@hooks_app.command("test")

• Accept hook_name: str = typer.Argument(...) and an optional --workspace / -w path option.
• Validate that hook_name is in the canonical list; exit with an error message if not.
• Load workspace and EnvironmentConfig; look up the hook; exit with error if not configured.
• Call run_hook(hook_cfg, workspace, dry_run=False).
• Print exit code, stdout, and stderr using console.print with appropriate colours (green for exit 0, red otherwise).
• Exit with code 1 if exit_code != 0 or timed_out is True.

3c — cf hooks show <hook-name>

@hooks_app.command("show")

• Accept hook_name: str = typer.Argument(...) and an optional --workspace / -w path option.
• Load workspace and EnvironmentConfig; look up the hook; exit with error if not configured.
• Use a rich.panel.Panel to display the full script text and timeout value — mirroring how env_commands.py uses Panel for the doctor report.

---

Step 4 — Register hooks_app in app.py

In file:codeframe/cli/app.py:

• Import hooks_app from codeframe.cli.hooks_commands alongside the other sub-app imports at the top of the file.
• Add app.add_typer(hooks_app, name="hooks") in the registration block alongside env_app, auth_app, etc.

---

Step 5 — Update cf status to include hook count

In the status command in file:codeframe/cli/app.py (around line 405, after the "Recent Activity" section):

• Add a Hooks section that:
  1. Calls load_environment_config(path) (lazily import it).
  2. Calls count_configured_hooks(env_cfg) if a config was found.
  3. Prints either N hooks configured (using count_configured_hooks) or [dim]No hooks configured[/dim].
• If no .codeframe/config.yaml exists, show [dim]No hooks configured[/dim] rather than erroring.

---

Flow diagram

sequenceDiagram
    participant User
    participant CLI as hooks_commands.py
    participant Core as codeframe/core/hooks.py
    participant Cfg as EnvironmentConfig (config.py)

    User->>CLI: cf hooks list
    CLI->>Cfg: load_environment_config(workspace_path)
    Cfg-->>CLI: EnvironmentConfig (with hooks)
    CLI->>Core: get_configured_hooks(env_cfg)
    Core-->>CLI: dict of configured HookConfig
    CLI-->>User: Rich table (hook name, status, preview, timeout)

    User->>CLI: cf hooks test before_task
    CLI->>Cfg: load_environment_config(workspace_path)
    CLI->>Core: run_hook(hook_cfg, workspace, dry_run=False)
    Core-->>CLI: HookResult (exit_code, stdout, stderr)
    CLI-->>User: stdout / stderr / exit code output

    User->>CLI: cf hooks show after_init
    CLI->>Cfg: load_environment_config(workspace_path)
    CLI-->>User: Rich panel (full script, timeout)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The CLI uses **Typer** with a sub-app pattern: each domain lives in its own `codeframe/cli/<domain>_commands.py` file, defines a `<domain>_app = typer.Typer(...)`, and gets registered in `app.py` via `app.add_typer(...)`. The `EnvironmentConfig` dataclass in `codeframe/core/config.py` drives `.codeframe/config.yaml` and is the natural home for hook config. No `codeframe/core/hooks.py` or `hooks_commands.py` exists yet — this ticket creates both from scratch.

## Approach

Since #393 (config schema) and #394 (execution engine) are dependencies, this plan covers all three layers in sequence: extend `EnvironmentConfig` with a hook schema, create a `codeframe/core/hooks.py` execution engine, then build `codeframe/cli/hooks_commands.py` and wire it into `app.py`. Finally, update the `status` command to surface hook count. This keeps every layer minimal and consistent with existing patterns.

---

## Implementation Plan

### Step 1 — Extend `EnvironmentConfig` with a hook config schema (`#393`)

In `file:codeframe/core/config.py`:

- Add a `HookConfig` dataclass with the fields:
  - `script: str` — the shell command / script body to execute
  - `timeout: int` — seconds before the hook is killed (default `30`)
- Add a `WorkspaceHooksConfig` dataclass with optional `HookConfig` fields for each named lifecycle point:
  - `before_init`, `after_init`, `before_task`, `after_task`
  - Each field defaults to `None` (hook not configured)
- Add a `hooks: WorkspaceHooksConfig` field to `EnvironmentConfig`, defaulting to an empty `WorkspaceHooksConfig()`.
- Update `EnvironmentConfig.from_dict` to deserialise nested `HookConfig` objects within `WorkspaceHooksConfig`.
- Update `EnvironmentConfig.to_dict` to serialise them back correctly (the existing `asdict` call handles dataclasses recursively, so this should just work).

The resulting YAML shape under `.codeframe/config.yaml` will look like:

```
hooks:
  before_task:
    script: "echo pre-task"
    timeout: 30
  after_init:
    script: "./scripts/post_init.sh"
    timeout: 60
```

---

### Step 2 — Create the hook execution engine (`#394`)

Create `file:codeframe/core/hooks.py`.

**Key public API to expose:**

| Symbol | Purpose |
|---|---|
| `HookResult` dataclass | Holds `hook_name`, `exit_code`, `stdout`, `stderr`, `duration_ms`, `timed_out: bool` |
| `run_hook(hook_cfg: HookConfig, workspace: Workspace, dry_run: bool) -> HookResult` | Executes the shell script, captures output, enforces timeout |
| `get_configured_hooks(env_cfg: EnvironmentConfig) -> dict[str, HookConfig]` | Returns only the hooks that are not `None` |
| `count_configured_hooks(env_cfg: EnvironmentConfig) -> int` | Convenience count for the `status` command |

**Implementation notes for `run_hook`:**

- Use `subprocess.run` with `capture_output=True`, `timeout=hook_cfg.timeout`, running the script via the shell (`shell=True`) in the workspace's `repo_path` as `cwd`.
- If `dry_run=True`, skip execution and return a `HookResult` with a sentinel `exit_code=-1` and a `stdout` message indicating the dry-run, so the CLI can display it clearly.
- Catch `subprocess.TimeoutExpired` and set `timed_out=True` on the result.
- Catch other `Exception` and surface via `stderr`.

---

### Step 3 — Create `codeframe/cli/hooks_commands.py`

Follow the exact pattern from `file:codeframe/cli/env_commands.py`:

```
hooks_app = typer.Typer(
    name="hooks",
    help="Workspace hook management",
    no_args_is_help=True,
)
```

#### 3a — `cf hooks list`

`@hooks_app.command("list")`

- Load workspace via `get_workspace(path)`, then load `EnvironmentConfig` via `load_environment_config(path)`.
- Call `get_configured_hooks(env_cfg)` to get the active hooks dict.
- Define the canonical hook names list: `["before_init", "after_init", "before_task", "after_task"]`.
- Use a `rich.table.Table` with columns **Hook**, **Status**, **Script preview**, **Timeout** — consistent with the table style in `env_commands.py`.
- For each canonical hook name: show `[green]configured[/green]` or `[dim]not set[/dim]`; for configured ones, show the first 80 characters of `script` and the `timeout`.

#### 3b — `cf hooks test <hook-name>`

`@hooks_app.command("test")`

- Accept `hook_name: str = typer.Argument(...)` and an optional `--workspace / -w` path option.
- Validate that `hook_name` is in the canonical list; exit with an error message if not.
- Load workspace and `EnvironmentConfig`; look up the hook; exit with error if not configured.
- Call `run_hook(hook_cfg, workspace, dry_run=False)`.
- Print exit code, stdout, and stderr using `console.print` with appropriate colours (green for exit 0, red otherwise).
- Exit with code `1` if `exit_code != 0` or `timed_out` is `True`.

#### 3c — `cf hooks show <hook-name>`

`@hooks_app.command("show")`

- Accept `hook_name: str = typer.Argument(...)` and an optional `--workspace / -w` path option.
- Load workspace and `EnvironmentConfig`; look up the hook; exit with error if not configured.
- Use a `rich.panel.Panel` to display the full `script` text and `timeout` value — mirroring how `env_commands.py` uses `Panel` for the doctor report.

---

### Step 4 — Register `hooks_app` in `app.py`

In `file:codeframe/cli/app.py`:

- Import `hooks_app` from `codeframe.cli.hooks_commands` alongside the other sub-app imports at the top of the file.
- Add `app.add_typer(hooks_app, name="hooks")` in the registration block alongside `env_app`, `auth_app`, etc.

---

### Step 5 — Update `cf status` to include hook count

In the `status` command in `file:codeframe/cli/app.py` (around line 405, after the "Recent Activity" section):

- Add a **Hooks** section that:
  1. Calls `load_environment_config(path)` (lazily import it).
  2. Calls `count_configured_hooks(env_cfg)` if a config was found.
  3. Prints either `N hooks configured` (using `count_configured_hooks`) or `[dim]No hooks configured[/dim]`.
- If no `.codeframe/config.yaml` exists, show `[dim]No hooks configured[/dim]` rather than erroring.

---

### Flow diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as hooks_commands.py
    participant Core as codeframe/core/hooks.py
    participant Cfg as EnvironmentConfig (config.py)

    User->>CLI: cf hooks list
    CLI->>Cfg: load_environment_config(workspace_path)
    Cfg-->>CLI: EnvironmentConfig (with hooks)
    CLI->>Core: get_configured_hooks(env_cfg)
    Core-->>CLI: dict of configured HookConfig
    CLI-->>User: Rich table (hook name, status, preview, timeout)

    User->>CLI: cf hooks test before_task
    CLI->>Cfg: load_environment_config(workspace_path)
    CLI->>Core: run_hook(hook_cfg, workspace, dry_run=False)
    Core-->>CLI: HookResult (exit_code, stdout, stderr)
    CLI-->>User: stdout / stderr / exit code output

    User->>CLI: cf hooks show after_init
    CLI->>Cfg: load_environment_config(workspace_path)
    CLI-->>User: Rich panel (full script, timeout)
```

---

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

#304 - test(cli): add comprehensive v2 CLI integration test suite [merged]
#317 - feat(cli): add interactive PRD generation via Socratic discovery [merged]
#369 - test: add CLI integration tests for ReactAgent runtime parameters [merged]
#382 - fix: return non-zero exit codes from work retry and batch run [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.