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 work. 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.

Observation is separate from action, and the boundary is precise. A sentinel never edits the agent's files and never sends instructions back to the agent. While a codon runs, it does not block the main agent; the one place sentinel work can hold up the run is the codon boundary, where queued observation finishes before the next codon starts (we walk through that in the lifecycle section). 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 field-by-field configuration contract lives in the sentinel configuration reference; the schemas behind it are pinned by docs.lock, the resolved artifact record for this documentation build.

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 output format is deliberately narrow: a sentinel writes text or jsonl.

What a sentinel is (and isn't)#

A sentinel is a parallel observation agent, not a logging hook. It observes events from the main workflow and fires a report: it 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 does not block the main agent's execution. It is 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's required structural fields are id (a kebab-case string), name, trigger, execution, and model. That is not the whole requirement: the schema also demands at least one of userPromptFile or userPromptText, and a config carrying only the five structural fields fails validation and never loads. Attachment happens in hank.json, on the codon – there is no root-level sentinels setting. The fragment below shows the structural fields and how a codon attaches a sentinel by file reference; the complete observer configuration later in this page supplies the user prompt:

{
  "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, and it covers config loading only: a missing, unparseable, or schema-invalid config file or reference fails the codon when the flag is set. A sentinel skipped for other reasons – a model absent from the provider registry, an unconfigured or unhealthy provider, or a per-sentinel instantiation error – is only logged, and the codon runs without it even with the flag set. 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: file references in a sentinel config, and the config's own prompt and schema file references, 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 own directory.

Finally, a sentinel is not an agent session with filesystem tools. It sees only the event data its prompt template interpolates, which is the subject of the next section.

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.

Omitted llmParams fields fall back to temperature 0, maxOutputTokens 8192 and maxRetries 2; the strip above gives each field's accepted bounds.

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

**Status:** Success

**Cost:** $<cost>

**Duration:** 117,863 ms (~1m 58s)

---

## Verification Limitations

Artifact existence, row coverage, and correctness **cannot be verified** from this input. No file-update events were provided. The absence of file-update events does not indicate missing files.

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 the prompt: prompt text and it.events are the inputs to the model, not a filesystem workspace. Sentinel prompts are Eta templates rendered with a context of it.events (up to 1,000 triggering events), it.codon, and it.world.currentTime. Only it.codon.id is the observed codon's runtime id; it.codon.name and it.codon.description come from the sentinel's own configuration, it.codon.startTime is the time the sentinels were loaded for that codon, and it.world.currentTime is when the trigger was queued. A prompt without an it.events interpolation receives no event data at all – the sweep example below shows what that looks like in a real capture. For the full set of trigger operators and strategies, use the sentinel configuration reference.

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 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:

One payload note for the table above: the base shape marks assistant.action's toolName and toolUseId optional, but when action is "tool_use" the runtime's wire validator requires a non-empty toolUseId and a present toolName; for thinking and message actions both may be absent. toolUseId is the key that joins the action to tool.result.toolUseId and file.updated.source.toolUseId.

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 worked example: it is attached to the run's final codon, and when that codon's codon.completed arrives, it fires immediately with the one received event and writes a 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

Captured: 2026-09-04 · runtime: hankweave@0.10.0 (the later, Eta-templated run of this fixture).

The sweep observer does not receive the earlier codon's completion, because sentinel sets are attached per codon. A second capture from the same fixture shows the event ordering directly – the final codon.completed event followed by sentinel.triggered and sentinel.output:

{"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}}

Captured: 2026-09-04 · runtime: hankweave@0.10.0 (the first, untemplated run of this fixture).

These are two different captured runs of the same fixture, not one run. The sentinel.output content in the second 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 the previous section is not a formality; without the interpolation, the sentinel fires on an empty picture. The templated report is likewise not evidence that the observer inspected every earlier codon or the whole filesystem: it summarizes the single codon.completed event its prompt rendered. The fixture also confirms that sentinels belong on a codon: a root-level sentinels array fails validation with Unrecognized field(s) at hank root: sentinels. 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 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. 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. For WebSocket visibility, reportToWebsocket.outputs: false suppresses sentinel.output emission and reportToWebsocket.errors: false suppresses sentinel.error emission, each enabled unless explicitly false, and the output file is written independently of the outputs switch. The lifecycle and triggers keys are accepted by the schema but have no implemented suppression gate: sentinel.loaded, sentinel.unloaded, and sentinel.triggered are emitted whenever the lifecycle operation or trigger occurs. The output-file, error-handling, and WebSocket reporting contracts are:

The strip's schema text for maxConsecutiveFailures needs scope: it is compared only for a regular error of a non-conversational immediate sentinel. A debounce, count, or timeWindow sentinel logs the error and keeps going, and a fatal corruption error increments the counter but is never compared with the threshold. The sentinel configuration reference owns the full unload policy.

The runtime also bounds queued sentinel work, dropping the oldest queued trigger under pressure; the exact thresholds and the failure categories, consecutive-failure behavior, and scoped environment keys are owned by the sentinel configuration reference.