feat(ergon): hook lifecycle + model wire types (BRO-997)

[broomva]

Summary

Second slice of ergon per spec §12 work order. Lands the eight-event hook lifecycle and the wire types those hooks observe.

• model.rs — provider-agnostic wire types (Message with block-structured content, ContentBlock enum, ToolCall, ToolResult, ToolDefinition, ModelRequest, ModelResponse, Usage)
• hook.rs — Hook trait with 8 events (workflow_start/end, step_start/end, pre/post_inference, pre/post_tool_use), HookCtx<'a>, three outcome enums (HookOutcome, ToolHookOutcome, InferenceHookOutcome), and HookRegistry builder.
• 18 new unit tests (43 total in ergon, up from 25)
• All clippy + fmt clean, workspace check passes

Spec: core/life/docs/superpowers/specs/2026-05-05-ergon-v0.1.md (§3.7, §3.8)
Linear: BRO-997. Umbrella: BRO-994.

Why two modules in one PR

The Hook trait references ModelRequest, ModelResponse, ToolCall, ToolResult directly. Three options for where those types live:

Option	Cost
Re-export from praxis_core / arcan_provider	Couples ergon to those crates, defeats Layer-2 framing
Placeholder types refactored in BRO-998	Churns hook signatures the moment step.rs lands
Ergon owns the wire types ← this PR	Hook contract is provider-independent forever

Ergon owning the wire types is what makes step.rs a translator (not a coupling) — it converts between ergon's shapes and arcan_provider / praxis_core::Tool at the boundary.

Spec deviation: hook event defaults

Spec §3.7 only defaulted on_workflow_start to Continue; the other 7 events were abstract. This PR defaults all 8 events to Ok(_::Continue).

Rationale: a real-world hook (e.g. `NousScoreHook`) only cares about one event. Forcing eight no-op implementations on every hook is boilerplate without safety — the same `Continue` ships either way. The original spec choice was a compile-time push to "force the implementer to think about each event" — ergonomically counterproductive once you have more than two hooks. Documented in CHANGELOG and `crates/ergon/ergon/CLAUDE.md`.

Test plan

• `cargo fmt --all -- --check` — clean
• `cargo clippy -p ergon --all-targets -- -D warnings` — clean
• `cargo clippy --workspace -- -D warnings -A clippy::too_many_arguments` — clean
• `cargo test -p ergon --all-targets` — 43 passed; 0 failed
• `cargo check --workspace` — no regression
• CI: format / lint / test-linux / test-macos / msrv all green

What's next (BRO-998, separate PR)

`step.rs` will:

1. Use these wire types as the inner contract
2. Add substrate dependencies (`arcan-provider`, `praxis-core`, `lago-journal`, `life-vigil`) for the autonomous loop body
3. Land the three default sinks (`LagoSink`, `VigilSink`, `LifegwSink`)
4. Implement `StepCtx::run_inference_streaming` with full hook firing per spec §5

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Hook lifecycle system enabling interception and modification of agent behavior at key points
  • Wire-type definitions for model interaction, including messages, tools, requests, and responses

• Documentation

  • Updated CHANGELOG and module documentation with expanded feature descriptions
  • Added 18 new unit tests (43 total), improving test coverage

[linear]

BRO-997 Ergon §12.3 — Land `hook.rs` (Hook trait, HookCtx, outcomes, HookRegistry)

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

This PR lands two foundational ergon modules: a Hook trait system with eight lifecycle events and a HookRegistry for managing hook invocations, plus a Model module defining provider-agnostic wire-format types (MessageRole, ContentBlock, Message, ToolDefinition, ToolCall, ToolResult, ModelRequest, Usage, ModelResponse) with builder helpers. Both modules are exported in lib.rs and documented in CHANGELOG.md and CLAUDE.md.

Changes

Hook & Model Foundation

Layer / File(s)	Summary
Data Shapes crates/ergon/ergon/src/hook.rs crates/ergon/ergon/src/model.rs	Hook defines HookCtx, HookOutcome, ToolHookOutcome, InferenceHookOutcome. Model defines MessageRole, ContentBlock, Message, ToolDefinition, ToolCall, ToolResult, ModelRequest, Usage, ModelResponse with serde tagging and non-exhaustive stability.
Core Implementations crates/ergon/ergon/src/hook.rs crates/ergon/ergon/src/model.rs	Hook trait specifies eight lifecycle events (on_start, on_input, on_pre_inference, on_post_inference, on_pre_tool_use, on_post_tool_use, on_output, on_end) with default Continue outcomes; HookRegistry collects hooks in order via with() and with_arc() builders. Model types include constructors (::new), helpers (user_text, assistant_text, extract_tool_calls, text), and field accessors.
API Surface & Exports crates/ergon/ergon/src/lib.rs	Two new public modules declared (hook, model); re-exports Hook, HookCtx, HookOutcome, ToolHookOutcome, InferenceHookOutcome, HookRegistry and model wire types (ContentBlock, Message, MessageRole, ModelRequest, ModelResponse, ToolCall, ToolDefinition, ToolResult, Usage).
Documentation & Status CHANGELOG.md crates/ergon/ergon/CLAUDE.md	Changelog entry expanded to detail hook lifecycle, wire types, and 18 new unit tests (43 total). CLAUDE.md marks model.rs and hook.rs as Done (BRO-997), documents step.rs as Not yet landed, and introduces Spec deviations section covering license.workspace and hook event defaults.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• Ergon §12.3 — Land hook.rs (Hook trait, HookCtx, outcomes, HookRegistry) #1141: This PR directly implements the Hook trait, HookCtx, HookOutcome/ToolHookOutcome/InferenceHookOutcome variants, HookRegistry, and lifecycle events that land hook.rs as specified in that issue.
• Ergon §12.6 — Land four auto-hooks (attestation.rs, budget.rs, score.rs, capability.rs) #1144: This PR provides the Hook trait, HookCtx, HookOutcome enums, HookRegistry, and lib.rs re-exports that form the public API and registry infrastructure required to implement the four Life-specific hook variants described in that issue.

Poem

🐰 *ears twitch with joy*

Hooks now loop through agent life,
From start to end, they guide the strife,
Models talk in tongues so pure,
Wire-format, generic, sure.
Registries await the call,
Foundations built, we've landed all! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: introducing hook lifecycle system with eight events and provider-agnostic model wire types for the ergon crate.
Docstring Coverage	✅ Passed	Docstring coverage is 85.51% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/bro-997-ergon-hook-lifecycle

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}