Reports

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 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 and its JSON schemas; every server, open-source or cloud, implements that contract.