Feature: declarative hooks for workflow automation #117

Problem

Keen has no way to automatically react to tool or session events. Users must repeatedly ask the model to run formatters, tests, or policy checks by hand.

Proposal

Add declarative hooks that run external shell commands on lifecycle events.

MVP events

• before_tool / after_tool
• after_write
• turn_end
• session_end

Example hook

hooks:                                                                                                                                                   
  - event: after_write                                                                                                                                   
    pattern: "*.go"                                                                                                                                      
    command: ["gofmt", "-w", "{{file}}"]                                                                                                                 
    timeout: 30s                                                                                                                                         
    on_error: fail  # warn | ignore                                                                                                                      
    stdout: capture                                                                                                                                      

Requirements

• External commands only; no in-process plugins.
• Templating for {{file}}, {{tool}}, {{session_id}}, etc.
• Timeout and output bounds.
• Configurable fail-open vs fail-closed behavior.
• before_tool hooks can block a tool call with a reason.
• Commands are subject to the existing permission system.
• Deduplicate (event, file) per turn; avoid recursive hooks.
• Add /hooks list and /hooks dry-run for inspection.

Use cases to document

1. Auto-format on save (gofmt, prettier, rustfmt, black).
2. Run focused tests after relevant file changes.
3. Reject writes that fail a policy check.
4. Regenerate artifacts after source changes.

Alternatives considered

• Prompt engineering: unreliable.
• Built-in formatters/test runners: too much surface.
• MCP file-watching hooks: cannot react to Keen-internal events or block tool calls.

Context

• Flagged during OMP analysis as a high-value workflow feature.
• Currently on the Tier 3 roadmap in `ROADMAP.md