Background Agents & Jobs

Two different things share the word "background".

	Job	Background agent
What it is	A long-running command the agent started, such as a build, a test run, or a dev server	A whole conversation running in a detached process
Lives in	The current conversation	Its own process and process group
Survives the terminal closing	No	Yes
Managed with	/jobs	/agents, oasis-agent agents

Jobs

When the agent starts something long-running, a row appears under the prompt with a live timer:

›
  2 jobs ⚙ npm test 1m34s ⚙ vite dev 2m07s  ·  /jobs

Managing jobs

/jobs opens the list.

Key	Action
↑ ↓	Choose a job
↵	Show its output
k	Kill it
d	Detach it. It keeps running, the turn stops waiting

The cursor follows the job row, not a line number. A job finishing above the one you are about to kill will not slide a different one under your keypress.

/jobs works mid-turn, so you can inspect or kill a job while the model is still working.

Releasing a job mid-turn

Ctrl+B releases a foreground job the turn is waiting on, for when the model should have backgrounded something and did not. The job keeps running; find it in /jobs. With nothing waiting, Ctrl+B does what /background does.

Waiting without polling

The Monitor tool waits for a named line in a job's output rather than polling it. It is the right way to express "wait until the dev server says it is listening", and cheaper than repeated reads, and it does not burn turns.

Fieldbus sessions appear here

An EtherCAT live I/O session shows up in /jobs like any other job, so you can stop it yourself without the agent's cooperation. It holds physical outputs energised between turns, and if the model gets stuck you are not reduced to killing the process.

Background agents

A background agent is a whole conversation in a detached process. It outlives your terminal.

Dispatching one

# Stops at the first mutating tool and waits for you
oasis-agent --bg -p "port the modbus tests"

# Runs unattended inside the current directory
oasis-agent --bg --mode auto -p "run the test suite"

The command prints the conversation id and exits immediately. The work continues in its own session and process group.

The permission mode is fixed at dispatch, so choose how much rope it has with --mode.

Handing over the conversation you are in

From the REPL, /background moves the current conversation to a background agent. It keeps working if you leave, and your prompt becomes a new empty conversation.

Used from /agents on a conversation an agent is still working on, /background does the reverse: it lets go of that conversation and takes a fresh prompt, leaving the agent to run.

/bg and /handoff are the same command.

Tracking them

$ oasis-agent agents
ID                    STATE     UPDATED           TURNS  NAME
20260819-011449-bfd8  blocked   2026-08-19 01:14      1  port the modbus tests
                      ! needs approval: Bash

1 agent is stopped and waiting on you. `oasis-agent --resume <id>` to pick one up.

Flag	Effect
--all	Include finished and failed agents, not just live ones
--cwd <dir>	Only agents dispatched under this directory
--stop <id>	Stop one, so --resume can take the conversation over
--json	Print as a JSON array and exit. Needs no terminal

From the REPL, /agents lists background agents and saved conversations, and ↵ switches to one in place without leaving your session. /resume is the same command.

States

State	Meaning
running	Working now
blocked	Stopped and waiting on you, for an approval or a question
stopped	Ended, by --stop or on its own
failed	Ended with an error

An agent that meets something it may not do does not guess. It stops, saves state, and goes blocked.

Picking one up

oasis-agent --resume 20260819-011449-bfd8

A unique prefix of the id is enough. Resume it where there is someone to answer the question it stopped on.

Output files

Three files are left per agent:

File	Contents
<id>-agent.log	Prose output, as you would have seen it
<id>-agent.err	Diagnostics
<id>-agent.jsonl	The full event stream, one JSON object per line

The .jsonl file is the one to parse if you are wiring an agent into something else.

Which should I use?

You want	Use
The agent to run a build and keep working while it runs	A job. The agent does this itself
To keep working while a long conversation continues elsewhere	/background
To fire off work from a script and check on it later	oasis-agent --bg -p "…"
A conversation to survive an SSH disconnect	--bg, or /background before you leave
Structured events streamed to another program as they happen	Control Protocol