---
tags: [Agents, Watchers, Architecture]
---

# The file changed. Why didn't the agent wake up?

Issue #1499 asked for an agent that notices events by itself. Picture a Host
waiting quietly while `notes.md` changes. The tempting answer was to add a
`before_iteration` hook that checks the file. I followed that path through the
code and found the catch: every iteration begins *after* somebody calls
`agent.input()`. While the Host is idle, the hook never runs. There is no turn
to attach the file change to.

The Host already had two ways to start a turn without a person typing in the
UI. Its scheduler starts a turn when the clock fires; its inbox consumer starts
one when a chat message arrives. Both eventually call `input_handler()`. That
was the useful discovery. The missing piece was a common way to record an
observed event before asking the agent to do anything with it.

We first separated the two jobs. A small background poll records a file change
or timer firing in a durable queue. A worker then reads the event and hands its
envelope to `input_handler()` as a user message in a stable session. The agent
can be busy for minutes; observation does not have to wait for its answer.

Then a second event arrived while that turn was still running. Starting a
competing turn would fight the same session. Leaving it until the answer was
finished would make the Agent reason from stale state. The existing
`before_iteration` and `after_iteration` hooks provided the precise boundary:
claim the event before the next model decision, or request one more iteration
when it arrives during a final model call. That small piece is now a copyable
`watch_events` plugin. The Host only supplies the durable queue callback.

A restart exposed the harder edge. Suppose the agent's answer reaches the
session log, then the process dies before the queue records completion. Blindly
retrying would give the agent the same event twice and might repeat a tool's
side effect. Recovery now checks the saved session for that event ID before it
starts another turn. It cannot promise exactly-once external side effects after
an uncertain crash, but it can avoid repeating a turn whose completion is
already in the Host's own record.

The lesson was about where to put the boundary. A plugin helps an agent
*during* a turn; a watcher must also make an idle turn possible. The queue
makes that handoff survive a restart and gives the operator a place to see
what happened. Neither part needs to pretend it owns the other's lifetime.

The focused watcher and plugin suite passed 17 cases, including an event
arriving during a tool batch, one arriving during a final model call, a lost
queue acknowledgement, and the copied plugin loading outside the package.
The merged PR's Python 3.10–3.13 CI matrix passed. A different kind of watch,
registered by an Agent to resume its original conversation days later, still
needs the session-owned runtime planned in #1788.