Sentinels observe event patterns

When a coding agent runs, it produces a stream of events: codons start and complete, files change, tools run, costs accumulate. Sometimes you want something watching that stream while the agent works – checking quality, tracking cost, narrating progress – without adding instructions to the agent's prompt or interrupting its run. That is what a sentinel does. A sentinel is a separate observation agent attached to a codon, the unit of work in a hank. It watches the event stream, makes its own LLM calls when a pattern it cares about appears, and writes a report for a later consumer.

The important boundary is in the name: observation is separate from action. A sentinel never edits the agent's files, never sends instructions back, and never blocks the run. This page builds up how that works: why sentinels exist instead of hooks, what one is and is not, how it decides to fire, how its lifecycle fits around a codon, and the design rules that keep observation safe. The configuration details come from the pinned 0.10.0 schema; the sentinel configuration reference carries the full field-by-field contract.

Why not hooks?#

A hook usually means a callback at a fixed lifecycle point. That model works when the question is "run this at codon start," but it is a poor fit for "when these event types appear together, under these conditions, produce a report." A sentinel watches patterns in the event stream and can combine event types with conditions, so its rule is declarative: when X, then Y, then Z. The shape of a sentinel's work, end to end, is:

pseudocode:
sentinel: trigger(event-pattern) → accumulate(strategy) → fire(llm) → write(output-file)

A sentinel is also configured separately from the main workflow. A codon attaches a file reference or an inline configuration in its sentinels array, so you can add or remove an observer without changing the codon's prompt or agent logic. That separation is what makes observers cheap to experiment with: a cost watcher, a code reviewer, or a narrator can sit alongside the main agent, and changing how you monitor the work never changes the agent's task. The 0.10.0 contract described here is the version pinned by docs.lock.

The output format is deliberately narrow. In 0.10.0, a sentinel writes text or jsonl; the old json format was removed in 0.5.5.

What a sentinel is (and isn't)#

A sentinel is a parallel observation agent, not a logging hook. It watches events from the main workflow, makes its own LLM calls when a pattern matches, and writes to its own output files – a full parallel execution framework in miniature. What it does not do matters just as much: it runs no tools, sends no instructions back to the main agent, and never blocks the main agent's execution. Think of it as a note-taker, not an editor.

That boundary defines the safe data flow, which is one way: the main agent edits files X and Y, the sentinel watches and writes analysis to file A, and the agent or a later codon reads file A. Do not route a sentinel's output into a file that the main agent is editing; concurrent-edit protection can report a hash mismatch when another process changes that file.

Required configuration and attachment#

A sentinel needs five fields: id, name, trigger, execution, and model. The ID is a kebab-case string. Attachment happens in hank.json, on the codon – there is no root-level sentinels setting. The minimal config below shows the required fields, and the hank fragment shows how a codon attaches a sentinel by file reference:

{
  "id": "quality-observer",
  "name": "Quality Observer",
  "trigger": { "type": "event", "on": ["codon.completed"] },
  "execution": { "strategy": "immediate" },
  "model": "anthropic/claude-haiku-4-5"
}

{
  "hank": [
    {
      "id": "step-two",
      "sentinels": [
        { "sentinelConfig": "sentinels/sweep-observer.json" }
      ]
    }
  ]
}

The wrapper accepts either a sentinel config file path, as above, or an inline config object. Its optional settings can include failCodonIfNotLoaded, outputPaths, and reportToWebsocket. failCodonIfNotLoaded defaults to false: if loading fails, the runtime skips the sentinel; when it is true, the codon fails instead. The full field list, including prompt, output, and error-handling options, is:

Two load-time behaviors are worth knowing before you rely on a sentinel. First, model validation: a full model ID containing /, such as anthropic/claude-haiku-4-5, is checked against the provider registry at load, and if it is absent the sentinel is skipped with an info-level log. A model without / is not registry-checked at load; it loads but fails on its first LLM call with No LLM provider available. Use a registry <provider>/<model> ID for a sentinel that must fire. Second, path rules: at 0.10.0, file references in a sentinel config and in its prompt or schema fields are strict portable relative POSIX paths. They cannot climb above the hank root or traverse a symlink, and for a file-based config, prompt and schema references resolve from that config's directory.

Finally, a sentinel is not an agent session with filesystem tools. It sees event data only when its Eta prompt – the template engine used for sentinel prompts – interpolates the template context. The context contains events (up to 1,000), the current codon (id, name, description, startTime), and world.currentTime. A prompt without an it.events interpolation receives no event data at all.

How a sentinel decides to fire#

Two configuration objects control firing. A trigger selects events and optional conditions; an execution strategy decides when matching events become one LLM call. The captures and schema strips below show the contracts for triggers, strategies, prompts, model parameters, structured output, and conversational mode, all pinned from the schema and linked in the sentinel configuration reference. The first capture is a real sentinel log, included because it demonstrates the model-ID behavior from the previous section: haiku passes validation but fails at firing with No LLM provider available, pi/google/gemini-2.5-flash is not found in the registry, and google/gemini-2.5-flash fires, writing to the managed sentinel path shown in the log header.

# ./.hankweave/sentinels/outputs/quality-observer/quality-observer.log

---
Yes, it contains exactly the line `hello from hankweave` and nothing else.

With the mechanics in view, here is a complete event-observer configuration. It fires on codon.completed for one codon, uses immediate execution, and asks the model to summarize only status, failure reasons, and budget fields present in the event. Note the prompt's explicit instruction that artifact contents are not available – the config encodes the observation boundary rather than leaving the model to guess.

{
  "id": "quality-observer",
  "name": "Quality Observer",
  "description": "Observes the validate-and-repair completion event. Reports only status and budget fields present in that event; cannot read or verify output artifacts.",
  "trigger": {
    "type": "event",
    "on": [
      "codon.completed"
    ],
    "conditions": [
      {
        "operator": "equals",
        "path": "codonId",
        "value": "validate-and-repair"
      }
    ]
  },
  "execution": {
    "strategy": "immediate"
  },
  "model": "anthropic/claude-haiku-4-5",
  "userPromptText": "The codon `validate-and-repair` completed. Here are the triggering completion events:\n\n<%= JSON.stringify(it.events, null, 1) %>\n\nSummarize only status, failure reasons and budget fields actually present. These completion events do not provide file contents or file.updated events. State explicitly that artifact existence, row coverage and correctness cannot be verified from this input. Never treat missing file-update events as proof of missing files. Observe and report only.",
  "output": {
    "format": "text",
    "file": "quality-observer.log"
  }
}

The captured report from that observer shows both the value and the limit of the separation. The observer summarizes completion status and budget fields, then states plainly that artifact existence, coverage, and correctness cannot be verified from its input:

---
# Codon Completion Summary: `validate-and-repair`

**Status:** Success

**Cost:** $<cost>

**Duration:** 197.8 seconds

**Exit Status:** Success

---

...

- **Artifact existence cannot be verified** — no file.updated events provided
- **Row coverage cannot be verified** — no file contents or update events provided
- **Correctness cannot be verified** — no file contents or update events provided

To check those properties, use a rig – a setup or checker that reads artifacts – or a codon that reads them; a sentinel completion log is not proof. The same rule applies to a prompt file: prompt text and it.events are the inputs to the model, not a filesystem workspace. For the full set of trigger operators and strategies, use the reference page rather than assuming that a lifecycle callback has access to files.

The sentinel lifecycle across a codon#

Each codon has its own set of sentinels, and loading the next codon's set unloads the previous one. Within a codon, the lifecycle is easiest to reason about as four states: Loaded → Active → Completing → Unloaded. The figure shows both the ASCII and mermaid renderings of the same state machine:

↗ Enlarge

sentinel lifecycle:
  load config → Loaded
       ↓
  observe routed events and queue matching work → Active
       ↓
  agent exits → Completing (drain sentinel work)
       ↓
  capture final state and cost → Unloaded → next codon

During codon execution, sentinel work is fire-and-forget. Event emission does not wait for a sentinel, so the main agent continues while the sentinel evaluates its queue. The runtime routes server-state and agentic-backbone events – runtime status and agent/tool activity – to sentinels. Connection-state events such as server.ready, pong, and history.batch are excluded, and so are sentinel events themselves, which prevents a sentinel from observing its own reports. The sentinel event types, with their payloads, are:

At the codon boundary, the agent's exit moves the codon to completing-sentinels. This is the blocking part of the lifecycle: debounce timers fire, count buffers flush, time-window work is processed, and queued LLM calls finish. After the runtime emits codon.completed, it performs a second drain for sentinels watching that event, so a sentinel conditioned on codon.completed completes before the next codon starts. Final sentinel states and costs are captured after that second drain, then the sentinels are unloaded.

Two consequences follow. The cost carried by the codon.completed event itself does not include sentinel work triggered by that event. And in replay mode, which reuses recorded codon output, sentinels are intentionally skipped because they make real, nondeterministic LLM calls. For reference, the routable event categories a sentinel can trigger on are:

The five sentinel event types – sentinel.loaded, sentinel.unloaded, sentinel.triggered, sentinel.output, and sentinel.error – are journaled and broadcast to WebSocket clients, but, as noted above, are not routed back to sentinels.

Designing with sentinels#

Start with who will use the report. A sentinel that writes a file the main agent is also editing can cause concurrent-edit protection to reject the edit, so give the observer its own report file and ask the agent or a later codon to read it. Both contributions stay available without two processes editing the same file.

That separation also makes observers swappable. Keep the event trigger and template shape, then change the prompt for a laziness check, mock detection, data-hygiene review, or shell-error watch. The sweep observer in fixtures/sentinel-sweep/ is a working example: it is attached to the run's final codon, and when that codon's codon.completed arrives, it fires immediately with one received event and writes the single end-of-run sweep report:

---
# Sweep Report

1. Received 1 event of type `codon.completed`.

2. Codon `step-two` completed successfully with a cost of $<cost> and duration of <ms>ms.

3. Sweep: clean

The sweep observer does not receive the earlier codon's completion, because sentinel sets are attached per codon. The captured event sequence shows the ordering directly: the final codon.completed event is followed by sentinel.triggered and sentinel.output, and those sentinel events are journaled but not fed back into sentinels.

{"id":"<id>","timestamp":"<ts>","type":"codon.completed","data":{"codonId":"step-one","success":true,"cost":"<n>","duration":"<n>","exitStatus":{"type":"success"}}}
{"id":"<id>","timestamp":"<ts>","type":"codon.completed","data":{"codonId":"step-two","success":true,"cost":"<n>","duration":"<n>","exitStatus":{"type":"success"}}}
{"id":"<id>","timestamp":"<ts>","type":"sentinel.triggered","data":{"sentinelId":"sweep-observer","codonId":"step-two","triggerNumber":1,"strategy":"immediate","eventCount":1,"queueSize":0}}
{"id":"<id>","timestamp":"<ts>","type":"sentinel.output","data":{"sentinelId":"sweep-observer","codonId":"step-two","triggerNumber":1,"outputType":"text","content":"I don't see any events in your message. You've described a scenario involving codon completion events and asked me to write a sweep report, but no actual event data has been provided for me to analyze.\n\nTo write the three-line report you've requested, I would need to see the events themselves. Could you please share:\n\n- The event log or event stream from the two-codon run\n- Details about each `codon.completed` event (success/failure status, costs if applicable)\n\nOnce you provide the events, I can generate:\n1. Count of codon.completed events and their success status\n2. Total cost calculation\n3. Sweep status assessment\n\nPlease paste the events and I'll write your report.","cost":"<n>","tokens":{"input":102,"output":158},"eventCount":1}}

That capture carries a second lesson. The sentinel.output content shows the model reporting that it received no events – because the first version of the sweep prompt did not interpolate it.events. The template context rule from earlier is not a formality; without the interpolation, the sentinel fires on an empty picture. The fixture also confirms that sentinels belong on a codon: a root-level sentinels array is rejected. See the sentinel configuration reference for the full sweep pattern and codon settings.

For output files, the two-line rule is:

• a bare filename such as quality-observer.log resolves to the managed directory <execution>/.hankweave/sentinels/outputs/<sentinel-id>/, where <execution> is the run's execution directory;
• a path containing /, including ./quality-observer.log, resolves relative to agentRoot, the configured agent workspace, when present.

The configured output path is independent of an external -o directory. The full output, lastValueFile, format, and codon-level settings.outputPaths contract is in the sentinel configuration reference.

Error handling and guardrails#

The design rules above lead to a practical division of labor. Use a sentinel for a check that fits in a paragraph: "don't use any," "every function needs a docstring," or "stay on task." Use a separate codon when the review needs architecture, related files, or trade-off reasoning. If a sentinel's finding must affect execution, have it write an output file and reference that file in a later codon's prompt or rig – the codon boundary is what separates observation from action.

Sentinels are optional infrastructure, not a prerequisite for an effective hank; the documentation pilots explicitly ran without them. Model selection has its own two-plane behavior – codon self-test versus provider health-check – and sentinel key overrides belong with authentication and model selection.

The runtime manages sentinels through SentinelManager. Conversational sentinel history persists under .hankweave/sentinels/history/; configured output files follow the output-path rule above. The reportToWebsocket setting controls visibility of lifecycle, error, output, and trigger events. The output-file, error-handling, and WebSocket reporting contracts are:

The runtime also bounds queued work: at most 100 pending triggers and 10,000 queued events. When a cap is reached, the oldest queued trigger is dropped and an info-level log records the action. For the exact failure categories, consecutive-failure behavior, scoped keys, and reporting switches, use the sentinel configuration reference.