Episode 30 Prelude — Adequate Observability and the Agent Event Runtime
2026-06-01Episode 30 Prelude
Adequate Observability and the Agent Event Runtime
Opening#
🧠: This prelude is about a threshold. We are not only creating another folder of hooks. We are naming the layer that lets the house see itself.
Right now, the system has many capable hands. Claude hooks, Codex hooks, Gemini hooks, Copilot hooks, and now Hermes hooks each capture pieces of agent labor. They write JSONL. They preserve tool calls, prompts, permission moments, plans, failures, corrections, and session stops. That is already valuable. But it is still too manual. You have to enter a session folder, inspect raw files, and ask another agent to interpret what happened.
That is not yet adequate observability. It is evidence, but not yet a living observatory.
The hinge#
The next step is implied by the current shape: the hooks should stop being the main architecture. They should become adapters.
Each hook folder remains useful, but only as the first sensory nerve for a specific CLI. The common layer should be a generic package that receives those raw signals, normalizes them, stores them, traces them, and lets humans or agents subscribe to them.
My first name for that layer was agent-event-runtime. Codex independently landed on the same top recommendation. Claude Code preferred the shorter agent-events, while keeping agent-event-runtime as the stronger runtime-shaped umbrella. That agreement matters: both agents said the noun should be events, not hooks. Hooks are the mechanism. Events are the language. Observability is the purpose.
Naming recommendation#
The safest package name is either agent-events or agent-event-runtime.
I would use agent-event-runtime if the folder is expected to contain the executable CLI, schema, ledger, timeline, and subscription machinery. It says: this is not only a vocabulary; it is a runtime that receives, emits, stores, and serves events.
I would use agent-events if you want the most minimal, generic package name, with runtime, ledger, trace, and bus as internal modules.
I would not name the core iris-hooking or miadi-agent-hooks. Those names are meaningful, but they overfit the generic layer. Iris can name the observer surface. Miadi can name the orchestration integration. But the common package should be able to receive Claude, Codex, Gemini, Copilot, Hermes, and future agents without requiring them to enter the cosmology first.
🌸: Iris watches. Miadi orchestrates. Coaia reflects. But the common tongue they share should be events.
Package layers#
I think this begins as one package with internal layers, not many packages immediately.
Layer zero is adapters. The current bash scripts stay, but they become thin. Their job is to capture the native payload and call a shared emitter.
Layer one is the schema. This is the most important step: a canonical event envelope with fields like schema version, event id, session id, agent, source, event type, timestamp, trace id, span id, parent span id, and payload.
Layer two is the ledger. At first, this can still be append-only JSONL under the session data root. Later it can add SQLite indexes for query. The key shift is that the ledger stores normalized events, not only each agent’s private dialect.
Layer three is tracing and timeline reconstruction. This is where plans, tool calls, tool results, corrective feedback, redirections, permissions, and stops become a readable story: what was proposed, what was accepted, what changed, what failed, and what needs response.
Layer four is subscription. Start simple: filtered reads and tailing over the append-only ledger. Do not jump immediately to Kafka, NATS, or Redis unless a real remote subscriber demands it. The first subscriber can be Iris, another agent, or a human-facing watch command.
Layer five is integration. Miadi and Coaia consume the normalized stream, not the hook folders directly. Miadi can route and govern. Coaia can remember and reflect. Tushell can preserve knowledge and provenance.
The minimal event vocabulary#
The first vocabulary can be small:
agent.session.started. agent.prompt.submitted. agent.tool.proposed. agent.tool.completed. agent.permission.requested. agent.plan.proposed. agent.feedback.corrective. agent.redirection.accepted. agent.turn.stopped. agent.session.ended.
This is enough to reconstruct a post-work timeline and enough to power subscriptions.
The next practical move#
The next move should not be to rewrite everything. It should be to define the envelope and a shared emitter. Then update one hook suite, probably Hermes hooks or Codex hooks, to emit both its current raw JSONL and the new canonical event JSONL.
That gives us a reversible test. If it works, the other hook folders migrate one by one. If it fails, no session capture is lost.
The test question is simple: can a person or another agent subscribe to a session and answer, without opening raw JSONL by hand: What happened? What is being created? What changed? What should I do next?
If yes, we have crossed from capture into observability.
Closing#
This is Episode 30’s seed: adequate observability is not a dashboard first. It is a shared event language, a ledger, and a subscription path. The bash hooks are the first version of the nerves. The package is the nervous system. The event runtime is how the house begins to feel its own work while the work is still alive.
Asking the wheel…