Use hook health to check whether agent callbacks are reaching Atomic and to locate failures that would otherwise be hidden by the hook's shell guard.
atomic agent status
atomic agent status --jsonThe human report shows each agent's most recent successful dispatch, its age
relative to the current time, and outstanding failing verbs. Session rows
attribute failures to a session and its parent. Existing plugin and git-shadow
errors are grouped from a bounded tail of .atomic/hook-errors.log.
Health is tracked per agent, session, and verb. A successful child cannot clear a parent's failure. A later successful dispatch of the same verb in the same session clears that session's current failure while retaining the earlier observations in the log. A successful dispatch may legitimately produce no new change when the working copy is unchanged.
| Field | Meaning |
|---|---|
hook_health |
Per-agent summary: last_fired, last_ok, last_error, verbs_recorded, and failing_verbs |
hook_sessions |
Session-level rows with agent, session_id, parent_session_id, and health.verbs |
hook_health_error |
Why the operational log could not be loaded; pending observations may still be reported |
hook_errors |
Grouped errors and recent entries from the bounded legacy error-log tail |
silent_agents |
Installed agents with no successful dispatch in the available operational log |
Each entry in health.verbs contains last_fired, outcome (ok or error),
an optional failure detail, and an optional last_ok. Failure summaries flatten
whitespace and truncate long details. Missing session IDs appear as null.
The hook-health fields are omitted when there are no observations. An empty
log gives no evidence that a freshly installed hook has failed. When the service
is unavailable and only pending observations are accessible, silent_agents
is omitted because the report is incomplete.
With jq installed, inspect one session's current outcomes:
atomic agent status --json \
| jq '.hook_sessions[]? | select(.session_id == "ses_child")'Native adapters retain the session ID and agent context from the payload.
Integration bridges can supply parent_session_id in raw_json, or explicitly
set ATOMIC_SESSION_ID and ATOMIC_PARENT_SESSION_ID for the hook process.
Typed agent receive also accepts a top-level parent_session_id and forwards
the resolved parent on its service request. Correlation is resolved in the
caller so it survives process boundaries.
If malformed input has no usable session ID, Atomic retains it as an unassigned diagnostic. It remains visible without being attributed to a different session.
Native hooks, typed receive, and the shared dispatch handler emit structured
Rust tracing observations. The existing local/reactor service layer appends
them transactionally to .atomic/atomic.redb, with event-ID deduplication and a
session index for paginated reads. Status projects health from these immutable
events. It no longer rewrites a shared hook-health.json snapshot.
Operational observations are local diagnostic data, independent of the running-turn provenance journal. Parsing failures and failures after a turn closes can therefore be logged without requiring a running turn.
During a service outage, each observation is spooled to its own immutable file
under .atomic/hook-log-pending/. Status can inspect these pending observations.
A successful append replays pending events into the database and removes their
spool files after commit. Retried events retain their original IDs and
observation times, so replay neither duplicates them nor makes an older failure
look newer than a later recovery.