Agents, tasks and results

An agent is a named worker inside a session: it runs a certified runner, Claude Code or Codex CLI (runners), on the session’s own machine, with your key. A session has a primary agent (usually main) and may have more. Each agent has a queue of the instructions you send it; the commands address an instruction as a task (<task> below), and what a task produces is its results.

Each section gives the app form first. In an agent’s window, / commands fill in this session and this agent; from a terminal, name them.

Start and find agents

In the app: n on the home screen starts an agent session, /agents lists the agents of this session, and /agent status shows this agent. From a terminal:

ks run --agent --agent-name main
ks agent list --session <session>
ks agent status main --session <session>
ks agent history main --session <session>

ks run --agent creates the session and its primary agent, binds your key and starts the machine. ks agent create <name> gives a session that has none its primary agent. An agent is renamed with ks agent rename and removed through a plan with ks agent remove.

A new agent name starts with a letter and uses only letters, digits, dashes and underscores, up to 48 characters. ks run --agent, ks agent create, ks agent rename and the app check a new name before sending anything, so a name the service would refuse stops at once with a usage error (exit code 2).

What the agent is doing

The activity word is the agent’s supervisor’s own report, never inferred:

Activity	Meaning
`starting`	Supervised and waiting for its first instruction; it reads `ready` after that instruction, when its runner has started
`ready`	Idle, waiting for the next instruction
`working`	Running an instruction
`waiting_provider`	Waiting on the model provider
`running_tool`	Running a tool
`waiting_approval`	Waiting for you to decide a permission request
`waiting_advice`	Waiting for an adviser’s reply
`paused`, `stopped`	The session is saved and parked, or the agent was stopped
`failed`, `recovery_required`	Its runner stopped and what it was doing is not known: it is not ready, and a person decides what happens next (`/queue`)
`removed`	The agent was removed from its session
`unknown`	Nothing current has been reported

A heartbeat means the connection is alive, not that a model is working.

Instructions and the queue

Instructions run one at a time, in the order they were accepted. In the app, type an instruction and press Enter; every Enter is a new message. /queue shows what is waiting, /tasks lists this agent’s tasks, and /task show <task> gives one in full. From a terminal:

ks agent tell main "Run the tests and fix what fails" --session <session>
ks agent ask main "@reviewer Is this change safe?" --session <session>
ks agent queue show main --session <session>
ks task list --session <session>
ks task show <task> --session <session>

ks agent tell queues an instruction from outside any window; the same words sent twice are one submission, so a retried send never runs twice. Change the wording to send a second one.

Rearrange what is still pending against the queue you looked at:

/task move <task> --before <task> (or --after <task>);
/task replace <task> --text "..." cancels one with its content kept and puts a new one in its place;
/agent queue cancel --preview, then --confirm <queue revision>, cancels pending instructions in bulk.

Stop the work in flight

Esc in the app interrupts the instruction in flight: it is asked to stop at a safe boundary.
/task cancel <task> (ks task cancel <task>) ends one instruction: work that has not started is stopped outright; running work is asked to stop and reads cancelling until its end is observed, then cancelled. The instructions queued behind it stay held.
/stop --confirm <agent> (ks agent stop <agent>) asks the instruction in flight to stop and holds the queue. You confirm by naming the agent. The session keeps running, and billing, until you pause it.

When the queue is held

A failed or unresolved instruction holds the instructions behind it, because they may have been written expecting its result. Nothing starts until you decide. In the app:

/queue
/agent queue resume --finding "the failure is understood"
/agent queue hold --finding "leave it held"

From a terminal, the same with the agent and session named: ks agent queue resume main --session <session> --finding "...".

queue resume continues the held instructions; the failed one is never restarted. /task resume <task> --checkpoint <checkpoint> runs a blocked instruction again as a new attempt from a checkpoint you name, and /task reconcile records that an attempt’s outcome could not be established.

Results

In the app: /results, /result show <result>, /diff <result>, /result download <result> --out report.md and /apply <result> --confirm <digest>. From a terminal:

ks result list --session <session>
ks result show <result>
ks result diff <result>
ks result download <result> --out report.md
ks result apply <result>

Every result is verified against its recorded sha256 on receipt and again before it is served; a download is checked for size and digest before it is placed, and never replaces a file you have unless you pass --force.
Each attempt also records a changeset: what it changed against the base it started from. /diff shows it and /apply applies it only onto that base, all or nothing, confirmed by its digest (from a terminal, it asks).
An agent’s own “done” is a report, not a verdict: a task reads finished, never verified. Independent checks are Cruise’s job.

Files in the workspace

/file list and /file show (ks file list, ks file show) read a session’s workspace without a shell. Agent sessions have no shell: the agent works through its runner and your permission requests.