Report fields: what an agent sends to Little Spaces

Every field of a Little Spaces report and of its asks, with the limits Little Spaces enforces, plus an example report an agent sends with spaces report.

A report is a JSON object that an agent sends with spaces report or the MCP tool report_activity. Agents connected with hooks are given a ready-made command, so you only need this page to check what a field means or why a report was refused. Little Spaces refuses a report with a field it doesn’t know, and says which field to fix.

Example

A report sent by hand looks like this, with the values in angle brackets filled in:

sh ~/.local/share/little-spaces/install.sh report - <<'JSON'
{"project":"<project name>","runId":"<this session's run ID>","app":"Claude Code","eventId":"<new unique ID>","kind":"progress","summary":"<what happened, in one or two sentences>"}
JSON

The command a session is given when it starts sends the same JSON. It also names the sign-in to use, and fills in the project fields its hooks send, so the report joins the session’s run.

Report

Field	Required	Limits and meaning
project	No	A readable project name, 1 to 120 characters. Without one, the report goes to Unassigned. Projects appear by themselves; no setup is needed.
repository	No	The repository being worked on: a repository root URL or a standard git SSH remote, without credentials, at most 2,000 characters.
projectId	No	A stable project identity when there is no repository, such as a domain. 1 to 160 characters.
runId	Yes	The session’s stable ID, 1 to 160 characters. Every report from one run stays in one workstream. Start separate work with a new run ID.
eventId	Yes	A new unique ID for each report, 1 to 160 characters. Reuse it, with identical content, only to retry that report.
app	Yes	The app’s name, 1 to 120 characters.
kind	No	started, progress (the default), finding, output, blocked or finished. blocked means waiting on something other than you.
summary	Yes	What happened, 1 to 4,000 characters.
next	No	What happens next, in one line of at most 300 characters.
needsYou	No	One ask, or a list of 1 to 6. See asks.
supersedes	No	Up to 20 keys of the agent’s open asks in this run that this report retires. A key with nothing open is ignored.
withdrawsAsk	No	true to withdraw every open ask of the agent’s in this run.
answeredHere	No	1 to 6 items saying you answered asks in the session. See answered here.
references	No	Up to 20 links (HTTP or HTTPS, without credentials, each at most 2,000 characters), such as the pull requests or issues the report is about.
topicHint	No	A name for the piece of work, at most 100 characters and eight words. A new run with the same name joins that workstream.
parentRunId	No	The run that started this one, 1 to 160 characters, so the Map can show which sessions work for which.
threadUrl	No	A link to the conversation, HTTP or HTTPS.
occurredAt	No	When it happened, in Unix milliseconds, for a report sent late.

Asks

Each item of needsYou:

Field	Required	Limits and meaning
type	Yes	question, approval, review or merge.
ask	Yes	One line saying exactly what the agent needs, 1 to 300 characters.
recommendation	No	For a question or approval: what the agent recommends and why, at most 500 characters.
options	No	Questions only: 2 to 6 answers, each different and at most 120 characters.
key	No	1 to 40 lowercase letters, digits and hyphens, unique in the report. In a list, every ask but at most one needs a key.
stopped	No	Only when the agent truly can’t go on: why, at most 200 characters.
holdsUp	No	Up to 5 names of work that waits on the answer, each at most 80 characters.

A stopped or holdsUp value of no, none, n/a, - or blank, in any case, is dropped as if it were left out.

Answered here

Each item of answeredHere:

Field	Required	Limits and meaning
key	No	The key of the open question or approval you answered. Leave it out for the run’s open ask without a key.
answer	Yes	Your reply, in one line, 1 to 200 characters.

Each key may appear once, and at most one item goes without a key. Review and merge asks, and keys with nothing open, are ignored.

Answers

Your answers in Little Spaces are at most 2,000 characters. An agent fetches them with spaces answers or the MCP tool get_answers, and only the agent identity that asked can read them. Each call returns at most 50 answers, oldest first, and repeats each one until the agent acknowledges it.