Events, waits, and wakeups
An event gives the runtime something to handle. A wait records what an agent expects before it can continue. A wake lets the runtime reconsider or resume work. These are separate parts of the same workflow.
For example, an agent fixing a build can start CI, record a wait for that run, and pause. A CI notification can wake it. The agent must still inspect the run's status and decide whether the original objective is satisfied.
Sources of new work and evidence
An operator message can start or redirect work. A command result can resume work that was waiting for a test. A timer can make a scheduled check due. An external callback can announce a change outside Holon. Agents can also enqueue their own follow-up work.
These inputs retain their origins. A timer firing is not a new human request; a webhook does not replace the operator's scope. Scheduling urgency and instruction authority remain separate.
Registering a wait
The agent uses a wait operation to identify the expected condition: a task result, a timer, an external object, or operator input. For task and timer waits, the resource is the actual runtime handle. For an external wait, it identifies the outside object, such as a pull request or CI run.
Registering a wait does not subscribe an external service, start a timer, or make a task run. Those resources must exist separately. It also does not mean the agent must always yield: if the requested task result is already available, the runtime can return it for use in the same turn.
An explicit wait can resume its matching continuation while the WorkItem still has an independent business blocker. That resumption does not remove the blocker or authorize unrelated work. Cancellation, stop, and completion can also make an old continuation ineligible.
Wake hints and messages
External ingress has two delivery modes:
| Mode | What the agent receives |
|---|---|
wake_hint | A signal to recheck outside state. The callback payload is not delivered as a model-visible message. |
enqueue_message | A queued message containing the external payload, with its provenance preserved. |
Use a wake hint when the source of truth can be queried, such as CI status. Use a contentful message when the payload is needed for the work. In either case, receiving the notification is evidence of delivery, not proof that the external operation succeeded.
For callback setup and examples of both delivery modes, see Connect external events.
The agent's default ingress capability can be reused across objectives. Individual WorkItems record their own waits. There is no need to create and revoke a callback for each ordinary wait cycle.
Timers and fallback checks
A timer schedules a future wake; creating it does not pause the current turn.
If the current work must wait for that timer, the agent records a timer wait.
Repeating timers remain a scheduling responsibility until cancelled.
Cancelling an active timer atomically settles any unadmitted waits dependent on
it with reason timer_cancelled, preventing leaked wait registrations while
leaving the WorkItem explicitly blocked until new action occurs.
A fallback recheck deadline on a wait serves a different purpose: reconsider that specific wait if no matching wake arrives. It is not a substitute for an independently managed recurring schedule.
A complete CI continuation
The operator asks an agent to fix a build and verify CI. The agent records the objective and starts a run, then arranges a callback and waits. When a notification arrives, it checks the correct run and revision. If CI failed, it inspects the failure within the approved scope. If CI passed, it checks the remaining acceptance criteria before completing the objective.
No step requires the operator to keep a client window open while the daemon continues running. A stopped daemon or interrupted process is a separate recovery case; see Context continuity.
Access and authority
Callback URLs contain capability secrets. Possession allows the corresponding wake or enqueue action, so keep them out of public reports and source control. The URL does not grant the sender operator authority. Rotate or revoke it when access should end, rather than using revocation as routine wait cleanup.
Stopping an agent revokes its external triggers. Before reconnecting an integration, inspect the current capability and replace any revoked URL. See Connect external events for callback replacement and revocation.