Lifecycle Hooks

Run project-defined logic on Kanbus lifecycle events with a first-class hook engine shared by Python and Rust.

One Engine, Every Boundary

Before/after hook phases are available across mutating and read operations.

Lifecycle hooks execute at normalized command boundaries: create, update, close, delete, comment, dependency edits, promote, localize, show, list, and ready.

Before-hooks on mutating operations are fail-closed by default. After-hooks are observer style: failures are surfaced as warnings without rolling back successful commands.

Project-Defined Integrations

Each hook is a command invocation with timeout, blocking mode, cwd, and per-hook env overrides.

hooks:
  enabled: true
  run_in_beads_mode: true
  default_timeout_ms: 5000
  before:
    issue.update:
      - id: validate-ticket
        command: ["./hooks/validate-ticket.sh"]
        timeout_ms: 1200
  after:
    issue.create:
      - id: notify-created
        command: ["./hooks/notify-created.sh"]
        env:
          WEBHOOK_URL: "https://example.invalid/hooks"
    issue.list:
      - id: planner-reminder
        command: ["./hooks/planning-reminder.sh"]

Unified With Policy Guidance

Policy as Code guidance now runs through the same lifecycle engine as a built-in hook provider.

Guardrails and custom hooks, same lifecycle model

Existing policy DSL semantics are preserved. The built-in provider emits policy guidance on post-operation events like create, update, close, delete, show, list, and ready.

--no-guidance and KANBUS_NO_GUIDANCE suppress policy guidance only. External project hooks continue to run unless hooks are globally disabled.

Operator UX

Inspect and validate hooks directly from the CLI.

# Inspect configured hooks and built-in providers
kbs hooks list

# Validate event bindings, IDs, command paths, and cwd values
kbs hooks validate

# Disable all hooks for one command
kbs --no-hooks list

# Disable all hooks for a session
KANBUS_NO_HOOKS=1 kbs list