Concepts

# Reports

What an agent files, and what it never files.

A report is one write-once record. An agent files it when something slowed it down and it would otherwise tell you "this should have been written down": a missing or wrong document, a tool that behaved unlike its name, configuration pointing at a dead service, several attempts at something that should have been a line in a README.

## What a report holds

- **A kind.** `friction` is the common one: a category, a one-line summary, the details, a suggested fix. `review` records the outcome of a review run. Any other kind is accepted and stored as sent.
- **Context the client collects.** The repository (from the git remote), the machine, the harness and the model, the command that failed where there was one. The client collects it; the agent does not type it.
- **An identity.** A content hash over the normalised report, so the same report filed twice (a retry, a flush of the spool) is recognised and answered with the first record rather than stored again. Records are never overwritten: a correction is a new report.
- **A processed mark**, set later by whoever works the inbox: a verdict ( `fixed`, `invalid`, `duplicate`, `wont_fix`, `deferred`, `upstream`, `unverifiable`), free-text resolution and a reference.

## Collection and sensitive data

The client adds repository and harness context to the text the agent submits. It does not routinely upload transcripts; session reads and explicit `submit --context-from` are separate, on-demand operations. Collection controls and pattern-based scrubbing reduce disclosure but cannot recognise every secret or sensitive detail. Local reporting makes no network call; a server-configured client sends to that server. Read the [security reference](https://agentfeedback.dev/docs/reference/security) before enabling collection or sending reports remotely.

## How the agent decides

The `agentfeedback` skill, installed by `init`, tells the agent when a report is warranted and when it is not. A hook nudges the agent after repeated tool failures, bounded so it never nags. Past sessions can be mined too: `agentfeedback sessions` reads the harness's own session store into harness-neutral digests, and `submit --context-from` files a report from one.

The wire format is the [API reference](https://agentfeedback.dev/docs/reference/api) and its JSON schemas; every server, open-source or cloud, implements that contract.

[Antigravity Install, verify and troubleshoot AgentFeedback for Antigravity.](https://agentfeedback.dev/docs/harnesses/antigravity) [Triage How the inbox is worked, by an agent with a human.](https://agentfeedback.dev/docs/concepts/triage)

[Canonical HTML](https://agentfeedback.dev/docs/concepts/reports)