Proposed specificationSource-located exemplarH1 H3

Hooks and event bus

Extend behavior at named events.

JOIN POINTnamed_lifecycle_eventRECORD STATUSCandidate · v0.1.0

UML class view

The proposed contract drawn as participant roles, received calls, and numbered dependencies.

Object interactions

The same roles and calls as a class collaboration and a numbered message sequence.

Object interaction diagram for Hooks and event bus, showing role collaboration and a numbered message sequence — FIG. P16 / OBJECT INTERACTIONS
Open full SVG Download PDF

Pointcut

Where the mechanism applies. All four dimensions belong to the proposed match, not just its vocabulary.

Context: Harness lifecycle emits named events or hook points.
Trigger: A model, tool, turn, or agent event is published.
Structure: Event schema, registration, handler ordering, and interception result.
Effect: Registered handlers observe or transform behavior at the declared point.

Protected contract

The obligation that clients, operators, and auditors should be able to rely on.

Requires: Event names and payload schemas are stable within a run.
Ensures: Handler order and whether a result may be modified are explicit.
Invariant: A handler cannot create an undetected recursive event storm.
Violation: Handler failure and reentrancy have defined isolation or propagation behavior.

Negative control

A direct logging statement is not an extensible hook.

Variation & lifecycle

The hot spot is admitted only where the protected semantics survive.

Permitted variation

Hook registry, event bus, observer, middleware, and priority.

Test obligation

Test order, reentrancy, exception, unsubscribe, and conflicting handlers.

Evolution question

Did events move from ad hoc callbacks to a typed lifecycle vocabulary?

Prompt + code design

An illustrative prompt and a small design sketch for the proposed contract. Names and APIs are invented; this is not a repository excerpt.

PROMPT SKETCH

Emit named lifecycle events with stable payload schemas. Run handlers in declared order, state whether a handler may modify the event, and make the final decision inspectable.

CODE DESIGN / PYTHON

def emit(bus, event):
    current = event
    for handler in bus.handlers(event.kind):
        outcome = handler(current)
        if outcome is None:
            continue
        if not handler.may_modify:
            raise ImmutableEvent(handler.name)
        current = outcome
    bus.record(event.kind, current)
    return current

Illustrative design sketch. Hook order and mutation rights are part of the contract, not documentation trivia. This example is a teaching aid, not implementation evidence or a conformance claim.

Detection & matching

The frozen rule that retrieves this record, the canonical source exemplar, and the control that should stay unmatched.

Join point: named_lifecycle_event
Source locator: See the source record.
Lexical cue: (?i)\b(?:event[_-]?bus|hooks?[_-]?(?:manager|registry|system)|register[_-]?hook|subscribe)\bFrozen expression, v0.1.0. A match is a retrieval cue, not a confirmed implementation.
Aliases: None
Canonical exemplar: microsoft/agent-frameworkpython/packages/core/agent_framework/_agent_hooks.py:3Support: python/packages/core/tests/core/test_agent_hooks.py:189
Negative control: A direct logging statement is not an extensible hook.

Scope-anchored review. pohe-agent analyze <repo> --pattern P16 anchors the cue to its enclosing declaration and checks a separate operational signature for all four pointcut dimensions. Missing roles and negative-control risks remain visible; a structural match is not E2/E3. Calibration report ↗

Repository files

Up to five public files retrieved by the frozen cue and pinned to the audited commit. A match is a place to inspect, not a confirmed implementation.

01microsoft/agent-frameworkpython/packages/core/agent_framework/_agent_hooks.py:3CANONICAL SOURCE 02aaif-goose/goosecrates/goose/src/acp/provider.rs:777RETRIEVAL CUE 03affaan-m/ECCskills/taste-application/scripts/falapi.py:263RETRIEVAL CUE 04agno-agi/agnolibs/agno/agno/os/event_streams/base.py:21RETRIEVAL CUE 05anomalyco/opencodepackages/cli/src/acp/catalog.ts:67RETRIEVAL CUE

Evidence & provenance

Each layer answers a different question. Do not substitute retrieval for review.

Source-located exemplar

A concrete source anchor is available for this proposed record. It is one exemplar, not evidence that all repositories—or every contract field—conform.

Review boundary: this candidate and its specification come from an AI-assisted study. Independent human validation remains open.

ANY-EVIDENCE FAMILY COVERAGE31/36

86.1% of repository families in the frozen panel have at least one current cue, historical cue, or canonical source layer. This is not confirmed prevalence.

Current lexical-cue repositories: 34 / 41

Canonical source anchormicrosoft/agent-framework 71e56792f5dbpython/packages/core/agent_framework/_agent_hooks.py:3

Supporting surfacepython/packages/core/tests/core/test_agent_hooks.py:189

Named hook lifecycle and enforcement middleware.

Exploratory retrieval cue Regex / v0.1.0

This expression is a discovery instrument only. A match is a retrieval cue—not a confirmed implementation, pointcut match, or contract proof.