# Agent status and declared events

> Report progress from an identified agent session and distinguish an agent's claims from recorded command results.

Hansard's managed integration exposes `report_status` and `session_context`.
Status reporting works in Hansard launches and identified sessions opened
directly in supported agents. It does not depend on the selected model.
A standalone MCP connection can expose these tools, with
`capture_subagent_messages`, through `hansard mcp serve --status`, without
messaging or helper launches.

## Report progress

From an identified agent session:

```sh
hansard session report --state working --note "Checking the implementation"
```

States are `working`, `blocked`, `needs_review`, and `done`. Reports appear
on the project overview. They are agent declarations, not proof of success.

When the harness supplies a Hansard session token, pass it through
`--session-token` in the CLI or `session_token` in MCP. Claude Code and Codex
leave `session_token` out of MCP calls. Claude Code's hook supplies it, and
Codex identifies the calling thread with each request.

## Declare events and evidence

`report_status` accepts an `events` array. The CLI accepts the same array
through `--events`. Each event has a `kind` and optional `evidence` items:

```json
{
  "kind": "evidence",
  "evidence": [{ "type": "test", "ref": "parser-unit-tests", "result": "passed" }]
}
```

| Field              | Accepted values or limits                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Event kind         | `plan`, `decision`, `assumption`, `evidence`, `blocked`, `lesson`                                                     |
| Evidence type      | `command`, `test`, `commit`, `file`                                                                                   |
| Evidence reference | A tool-call identifier, name, commit hash, or relative path, up to 160 characters. No arguments or output.            |
| Evidence result    | `passed`, `failed`, `completed`, `interrupted`, `cancelled`, `present`, `created`, `modified`, `deleted`, or `exit:N` |
| Report size        | Up to four events, each with four evidence items. The one-line `note` supplies their summary, up to 240 characters.   |
| Retention          | Up to 128 events within 128 KiB, subject to the status record's 256 KiB limit.                                        |

Set `HANSARD_DECLARED_EVENTS=1` in the session-hook environment to request
event reporting in session-start instructions. These instructions are off by
default. The switch changes instructions only. Explicit reports remain available.

## Read declared evidence

The conversation timeline marks these rows **Declared**. It checks command
and test claims against recorded results in the loaded transcript pages.
A pass requires a recorded zero exit code. A missing or conflicting result
marks the claim **Unsupported**. Checks update as earlier pages load.
File and commit references remain unchecked.

Declared events never fill an observed runtime field. See
[Retained evidence in a conversation](https://www.hansard.dev/guides/stats/#retained-evidence-in-a-conversation)
for activity recorded by the runtime.

## Check hook failures

Session-start hooks provide the session identity and current project context.
Coordination hooks announce new unread messages and board posts. A hook stops
after 3.5 seconds, before its agent's five-second limit. On failure, it returns
an empty result so the agent continues.

Hansard records failures without hook input in `state/hook-failures.json`.
`hansard doctor` reports failures from the past seven days as **agent hooks**.
`hansard integrations sync` refreshes installed hooks. Restart the client
afterward. No conversation reimport is needed.