Agent commands

An agent runs these commands from anywhere in its sandbox. Each one talks to a server the runner starts on the loopback interface for that run. They work only inside a Spotlight run.

spotlight handover --next <where> [--note <text>]
spotlight reply --to <handle> [--body <text>] [--resolve]
spotlight trace --task <id> [--out <path>]
spotlight history --station <key> [--line <key>] [--fingerprint <fp>] [--outcome <word>] [--since <date>] [--last <n>] [--out <dir>]
spotlight recall "<words>" | <handle>
spotlight remember --kind <kind> --body <text> [--path <path>]... [--reach <reach>] [--supersedes <handle>]
spotlight candidate --name <name> --hypothesis <text | @file> <station.json | ->
spotlight cause --task <task> --cause config|task|judge|check|infra --evidence <text | @file> [--suggestion <text | @file>]
spotlight tools
spotlight tools search "<words>" [--limit <n>]
spotlight tools describe <tool>
spotlight <tool> [--<input> <value>...] [--json <object> | --json -]

In a search's agent run, reply, recall and remember are refused with a search may not <answer a remark, recall what the team remembers or propose a memory>: it studies the station's history and proposes station configs, nothing more.

The tools Spotlight itself gives are listed in Built-in tools and skills. Why agents talk back through a command line gives the reasons.

EnvironmentCopy Anchor Link

The runner sets these in the harness's environment. Every other SPOTLIGHT_ variable is removed from it.

Without SPOTLIGHT_HANDOVER_URL and SPOTLIGHT_HANDOVER_TOKEN, each command fails:

Common behaviourCopy Anchor Link

spotlight handoverCopy Anchor Link

spotlight handover --next <where> [--note <text>]

Says where the task goes when the run ends. The run carries on until the agent's turn ends.

--next takes one of the values the run is offered: the keys of the stations a run at the current station may pass to, in line order, then review, then done where the current station ends the line. When each is offered, and what it does to the task, is in Handover.

Running handover again replaces the earlier choice. The last accepted one counts.

spotlight handover --next code-review --note "Added retries to the webhook client."
spotlight handover --next review < question.md

Without a handoverCopy Anchor Link

If the agent never runs handover, the runner reads /workspace/.spotlight/outcome.json when the harness exits:

{ "next": "code-review", "note": "Added retries to the webhook client." }

The file is ignored when it is missing, is not JSON, or has an empty next. A file an earlier run left is removed when a run starts. With neither a handover nor the file, the task goes to a person. See Handover.

spotlight replyCopy Anchor Link

spotlight reply --to <handle> [--body <text>] [--resolve]

Answers a remark on the task's pull request. The run's briefing lists the open remarks and their handles, such as c12.

spotlight reply --to c12 --body "Renamed, thanks." --resolve
spotlight reply --to c14 < answer.md

spotlight traceCopy Anchor Link

spotlight trace --task <id> [--out <path>]

Writes a task's trace to a file as indented JSON.

On success it prints one line: Wrote the trace to <path>, the number of nodes, the number of faults, the time the trace spans, and advice to search the file rather than load it whole.

spotlight historyCopy Anchor Link

spotlight history --station <key> [--line <key>] [--fingerprint <fp>] [--outcome <word>] [--since <date>] [--last <n>] [--out <dir>]

Writes a station's recent runs to files: the config each ran with, its journal, its outcome and its file changes. Only stations on the lines of the run's own team are read. Runs are the station's ended task runs, newest first.

The runs are written to <out>/<station>/. Anything already in that folder is removed first.

index.md shows a fingerprint by its first 12 characters, and none for a run with no recorded config.

On success it prints three lines: Wrote the history to <folder>, the number of runs and configs, and a grep -r command to search the folder. In a search's run, a line before the last reads <n> candidates proposed so far, under <folder>/candidates.

In a search's runCopy Anchor Link

In a search's agent run, only the searched station is read; any other is answered as a station no line has. The runs of the search's held-out tasks are left out, and every run of the searched tasks is written, beyond --last if need be. The folder also holds:

The candidate named seed is the live config the search started from, replayed on the searched tasks. A candidate's runs are its replay's runs on the searched tasks, one per task run of the set and copy.

Outcome wordsCopy Anchor Link

--outcome keeps a run when the word is one of these parts of its outcome. A run with no recorded outcome never matches. With --outcome, the latest 500 ended runs are searched, and --last of the matches are kept.

Station outcomes says what each part means.

spotlight history --station implementation
spotlight history --line delivery --station implementation --outcome sent-back --last 10

spotlight recallCopy Anchor Link

spotlight recall "<words>"
spotlight recall <handle>

Reads what the run's team remembers, beyond the memories its briefing lists. Only memories that stand in the run's own team are read, never proposed, rejected or retired ones, and never another team's.

Given words, it searches the bodies of the team's standing memories and prints at most ten, the best match first. Words are matched by their English stem, so retry finds retries. Each is printed as:

M-12 · rejected approach · line, in acme/api at src/uploads
  Retrying uploads from a queue needs a worker we do not run.
  From a run on task <task id>, approved by Ada Lovelace on 2026-09-21

The last line says where the memory came from:

<name> is someone when the person is not known. With no match it prints The team remembers nothing about "<words>". Try other words.

Every memory a recall returns is recorded against the run, and shows under "Given to the agent" in "Remembered" on its Run page; the recall itself is a spotlight.recall span in the task's trace.

Given a handle, such as M-12 or m-12, it prints that one memory in full: its kind, whether it stands or was retired, its body, where it applies, the steps and notes it rests on, the spotlight trace command for its task, the memory it replaced, and, once retired, why and what replaced it.

spotlight recall upload retries
spotlight recall M-12

spotlight rememberCopy Anchor Link

spotlight remember --kind <kind> --body <text> [--path <path>]... [--reach <reach>] [--supersedes <handle>]

Proposes a memory from inside the run. It rests on the step the agent ran the command from; where that step can't be found, on the last thing the agent said. It waits in the inbox beside the run, with anything drafted from the run, until a teammate approves, edits or rejects it, and is kept only once approved. A memory from a task that came from outside the team cannot be approved together with other memories. Proposing the same memory twice from one run keeps one.

On success it prints Proposed <kind> for the <reach>: <body>, and that the memory waits for a person's approval.

spotlight remember --kind rationale --body "Uploads retry in the request, not from a queue." --path src/uploads
spotlight remember --kind correction --supersedes M-7 < correction.md

spotlight candidateCopy Anchor Link

spotlight candidate --name <name> --hypothesis <text | @file> <station.json | ->

Proposes a station config from a search's agent run. The file holds the station block as JSON, in the shape of one entry of a line's stations; - reads it from standard input. Spotlight checks it, then replays it on the search's searched tasks. Only a search's runs may propose a candidate.

The block may change only the station's prompt, harness, model, effort, profile, skills, tools, decisions, memories and description, from the block the search started from. Proposing the same name again from the same run answers with the candidate it proposed.

On success it prints:

Proposed <name> as candidate <id>.
Spotlight replays it as <replay id>; its results show in spotlight history once the replay ends.

A refused block prints Spotlight refused the candidate:, one line per problem as <path>: <message>, a warning marked (<severity>, not why it was refused), and Fix the station block and propose it again. A refused proposal does not count toward the iteration's candidates, but an iteration may try at most three times as many as it may propose.

Other problems with the block are those of a replay candidate, at their path under station.

spotlight candidate --name terse-prompt --hypothesis @why.md station.json

spotlight causeCopy Anchor Link

spotlight cause --task <task> --cause config|task|judge|check|infra --evidence <text | @file> [--suggestion <text | @file>]

Records why a failing task failed, from the agent run of a search's reflection. Only the tasks its briefing lists take a cause. Recording a task's cause again replaces the one before.

On success it prints:

Recorded <cause> as the cause for task <task>, whose replay run <run> failed.
Recording another cause for the task replaces this one.

spotlight cause --task a17c4e02-9b3d-4f61-8e5a-0c2d7b9f4a13 --cause judge --evidence @evidence.md --suggestion "Drop the rubric line that asks for tests."

spotlight toolsCopy Anchor Link

spotlight tools

Lists the tools the run was given, up to 30 of them. Each entry is the tool's signature, its description, and a line for each input that has a description. For a tool acme.comment with a required input issue and an optional piped input body:

spotlight acme comment --issue <string> [--body <string> (or piped in)] [--json <object> | --json -]
  <description>
    --issue  <input description>

A tool that requires approval lists [--intent <string>] after its own inputs, and its description ends with the reason a person approves it and Say what you want to do with --intent; the person reads it first.

A run given more than 30 tools prints a summary instead: how many tools it was given, each integration's name with its number of tools, and the search and describe commands. Spotlight's own tools are counted under Spotlight, and catalog tools under the Spotlight catalog.

This run was given 214 tools, too many to list:
  Linear  195
  Petstore  19

Find one with: spotlight tools search "<words>"
Read one with: spotlight tools describe <tool>

A run given no tools prints This run was given no tools.

spotlight tools searchCopy Anchor Link

spotlight tools search "<words>" [--limit <n>]

Ranks the run's tools by how well they match the words, and prints the best first. The search runs in the command over the run's tool list. Nothing is sent anywhere.

The words and every tool's name, integration and description are split into lower case words at spaces, punctuation and changes of case, so linear.issueCreate and linear.issue-create both read as linear issue create. Each word of the search scores against each of the three:

Only the best match in each field counts. Points in the name count three times, in the integration's name twice, and in the description once. Where the search has two words or more and they appear together, in order, in a field, that field adds 8 points, weighted the same way. A tool that matches every word of the search scores a quarter more. Tools that match nothing are left out. Equal scores rank the tool with fewer words in its name first, then by name. Words of one letter in the search are ignored.

Each result is the tool's signature, the first line of its description (cut at 160 characters), and Needs a person's approval. for a tool that requires approval. The last line names the describe command for the best match.

spotlight linear issue-create --title <string> --team-id <string> [--json <object> | --json -]
  Create an issue.

Read one with: spotlight tools describe linear.issue-create

spotlight tools search "create issue"
spotlight tools search pets by status --limit 3

spotlight tools describeCopy Anchor Link

spotlight tools describe <tool>

Prints one tool the run was given, named as <integration>.<tool> or as two words, as in linear.issue-create or linear issue-create. In order, it prints:

The type marks an optional input, or one with a default, with ?. Each description becomes a /** */ comment above its input. Names that are not JavaScript identifiers are quoted, as in "team-id"?: string.

The example call gives every required input without a default, and --intent for a tool that requires approval. Each value is the schema's first examples entry, else its default, const or first enum value, else "…" for text, 0 for a number and true for a boolean. An object gives its required properties the same way, and a list holds one item. Where every input given is text, a number or a boolean, the call uses flags. Otherwise it gives every input as one object with --json.

linear.issue-create (from Linear)
Create an issue. Needs a person's approval before it runs: It posts publicly under the team's name. Using it asks them and does nothing else, so hand over and wait for their answer. Say what you want to do with --intent; the person reads it first.

Takes:
{
  /** What it is about */
  title: string;
  "team-id": string;
  labels?: string[];
  intent?: string;
}

For example:
spotlight linear issue-create --title "…" --team-id "…" --intent "…"

spotlight tools describe linear.issue-create
spotlight tools describe petstore find-pets-by-status

Learned outputCopy Anchor Link

After a call to an integration's tool succeeds, Spotlight records the shape of what it answered: field names and types, never values. It does this in the background, and never slows or fails the call. Each later successful call is merged into it. Every shape spotlight tools describe prints is learned.

Answers with (learned from earlier calls, may be incomplete):
{
  id: string;
  url?: string;
}

• The shape is kept per team and per tool. It is read when a run starts, so it shows in runs that start after a successful call.
• Redefining or removing the integration forgets it, and so does disbanding the team.

spotlight <tool>Copy Anchor Link

spotlight <integration> <tool> [--<input> <value>...] [--json <object> | --json -]
spotlight <integration>.<tool> [--<input> <value>...] [--json <object> | --json -]

Calls a tool the run was given. A tool named acme.comment is called as spotlight acme comment or spotlight acme.comment. Its flags are its inputs, by the names the tool gives them, as in --team_id or --petId. A built-in tool, such as pull-request, is called by its name alone, as in spotlight pull-request. See spotlight_integration for how an integration defines tools and their inputs.

--json <object> gives every input at once as one JSON object, keyed by input name, with each value in its JSON type. --json - or --json /dev/stdin reads the object from standard input. A flag given beside --json replaces that field of the object. When --json reads standard input, no piped input does: an input left out stays out, and naming one with - or /dev/stdin is refused.

Spotlight checks the inputs against the tool's schemas before it calls the host, and refuses a call that does not fit, saying where, as in linear.issue-create takes input, and input.teamId is not text. See Input schemas.

For a tool that requires approval, --intent <phrase> says what the agent wants to do, completing "Spotlight would like to …". It is optional, shown to the person who decides, and never passed to the tool. See What the agent wants.

The tool's result is printed to standard output. When the tool returns {"output": ...}, only the output is printed, as indented JSON with a string included, as in "https://linear.app/acme/issue/ENG-12". Who the tool acted as is recorded on the run and not printed. Any other result is printed as it came. Built-in tools answer with an object, as in {"url": "…"} from pull-request.

Other failures are the tool's own error as Spotlight reports it.

spotlight acme comment --issue <issue> --body "Deployed to staging."
git diff | spotlight acme comment --issue <issue>
spotlight petstore find-pets-by-status --status sold
spotlight linear issue-create --input '{"teamId": "<team id>", "title": "Flaky upload test"}'
spotlight linear issue-create --json '{"input": {"teamId": "<team id>", "title": "Flaky upload test"}}'
spotlight linear issue-create --json - < issue.json
spotlight acme comment --issue <issue> --body "Deployed to staging." \
  --intent "post the staging deploy on the issue, publicly under the team's name"