Agent Hooks

A local agent reports what it is doing back to NEXUS by posting to the app's local hook endpoints. Those posts are what fills the live activity feed beside the Room, and what lets a session's own account of its work sit alongside the terminal output NEXUS parses on its own.

Attribution — which agent an event belongs to — is the whole contract on this page.

Quick facts

What decides attribution	The per-agent credential presented with the request, and nothing else
Attribution from the request body	Not accepted
Default agent when attribution is absent	None — there is no fallback
Credential missing, or only the shared launch credential	Refused, 401
Body is valid JSON but not a JSON object	Refused, 400
Provisioning	Issued automatically when that agent's session starts

The credential decides the agent

Every hook post must present the credential issued to the specific agent it is reporting for. That credential is the sole basis for attribution: NEXUS records the event against the agent the credential belongs to, and nothing in the request body can name, override, or hint at a different one.

There is deliberately no second path. A request that presents no credential at all, or that presents only the shared launch credential — the one that identifies the launch rather than any individual agent — is refused. It is not attributed to a default agent, not attributed to whichever agent seems most likely, and not recorded as an unattributed event to be sorted out later. A hook post either arrives with proof of which agent it speaks for, or it does not arrive.

Treat a per-agent credential the way you would treat any bearer token: it belongs in a file with owner-only permissions, never in an environment variable, and never in shared history. See Paths & Credentials for the naming rule that keeps it out of a commit.

Refusals

Condition	Outcome
Presents that agent's own credential	Accepted, and attributed to that agent
Presents only the shared launch credential	401 — refused, attributed to nobody
Presents no credential	401 — refused, attributed to nobody
Body is valid JSON but not a JSON object — an array, a string, a number	400 — refused

A 401 here is a configuration fact, not a transient failure: replaying the same request unchanged will fail identically. Retry logic should surface it rather than loop on it.

Every refusal is recorded locally, so a misconfigured integration is diagnosable instead of silently dropping data. If activity you expect is missing from the feed, the refusal that discarded it is the first thing to look for — an integration posting without the right credential looks exactly like an idle agent from the outside.

Breaking change: body-based attribution is gone

Earlier builds accepted an agent identifier carried in the request body, and would attribute a post that presented only the shared launch credential. Both behaviours have been removed. An integration built against either one will now be refused with 401 and will contribute nothing to the activity feed.

To migrate an integration you wrote yourself:

1. Present the credential belonging to the agent the post is reporting for, on every request.
2. Remove the agent-identifying field from the request body. It no longer selects an agent, and leaving it in place does not keep a request attributed.
3. Post a JSON object. A body that parses as valid JSON but is not an object is refused with 400.
4. Handle 401 as an error worth reporting, not one worth retrying.

Existing agents upgrade themselves

Agents provisioned before this change need no manual repair. The per-agent credential is issued the next time that agent's session starts, and posting works from that point on. There is nothing to re-create, re-provision, or re-register, and no configuration file to hand-edit.

Where to go next

• Paths & Credentials — how local credential files are named, where they live, and why a token never travels in the environment.
• Running & Monitoring — the live status vocabulary a running agent reports, and what NEXUS refuses to infer.
• The Room — where hook events surface as a live feed.