Skip to the content
docs

Enhanced sessions

Cloudfield was named Aether until November 2026. The commands, paths and hostnames in this guide still use that name. View this guide on GitHub.

Browse guides / Enhanced sessions

A session normally shows the agent's own terminal UI. This is Standard mode. In Enhanced mode, Cloudfield drives the agent over the Agent Client Protocol (ACP), a JSON protocol on the agent's stdin and stdout. The dashboard then shows the agent's messages, tool calls, diffs and permission prompts as native controls in a Chat view, instead of a terminal. Read Agents first to install and sign in to an agent. Other terms are in the glossary.

Which agents

Agent How it serves ACP How it runs without asking
claude adapter claude-agent-acp session mode bypassPermissions
codex adapter codex-acp session mode agent-full-access
pi adapter pi-acp pi never asks
omp omp acp --auto-approve the --auto-approve flag
opencode opencode acp {"permission":"allow"} in OPENCODE_CONFIG_CONTENT
copilot copilot --acp --allow-all the --allow-all flag, which the session cannot take back
gemini gemini --acp session mode yolo
cursor agent --force acp the --force flag
custom the definition's --acp command the definition's --acp-mode

antigravity has no Enhanced mode (Agents).

Like Standard, an Enhanced session acts without asking by default. You can switch the session to a mode that asks (Claude Code, Codex and Gemini offer one).

claude, codex and pi need their adapter installed: aether agent add <name> --enhanced installs the agent and its adapter (Enhanced adapters).

Choose Enhanced

Set up on the Agents page, or onboarding's Agent step, shows both modes before anything installs. Enhanced shows messages, tool activity, file changes and approvals as controls. It runs through an adapter, so some agent-specific commands and screens are missing, and it starts a few seconds slower. Enhanced sessions of Claude Code, OpenCode and omp report their cost to Insights and budgets; Standard sessions report none. Both modes act without asking by default.

The dashboard remembers the mode you last chose for each agent, in Set up, in New session or in the Default mode select on the Agents page, and New session starts on it. A launch from New session saves the agent, mode and model on the server, so every device starts from them (Saved launch choices). For an agent with no remembered mode, New session starts on Enhanced when the agent's Enhanced mode is installed, and on Standard otherwise; aether session and the connector do so whenever no mode is named. New session lists Enhanced first and marks it Recommended. Before an agent's Enhanced mode is installed, Set up suggests Enhanced for Codex, oh-my-pi, OpenCode, Copilot, Gemini and Cursor, and Standard for the rest; it suggests Standard for Claude Code because its adapter runs on the Claude Agent SDK. Once it is installed, Set up starts on Enhanced.

Launch an Enhanced session

CODE
aether session "fix the flaky login test" --agent codex --mode enhanced
aether session "fix the flaky login test" --agent claude --mode enhanced --model opus --effort high

--mode takes standard, enhanced or background on aether session and aether template save. The task is the session's first prompt. An agent with no ACP command is refused:

CODE
scheduler: harness "custom" has no command for mode "acp"

--model is set after the session opens, so the launch itself still succeeds. If the agent rejects it, the session runs on the agent's default model, or the one it already had, and says so: the session's model becomes that one, refused_model names the refused one, model_error holds the reason, and the Session view shows a Model not set error notice, such as The agent refused "claude-fable-5-2", so the session runs on the agent's default model: ... Invalid value for config option model: claude-fable-5-2 from a Claude Code that predates the model. A Background session driven over ACP ends instead, with model not set: <the agent's error>. Standard sessions, and Claude Code's Background sessions, pass the model to the CLI, which fails the turn with its own error, for example Claude Code 2.1.287 does not support this model; version 2.1.290 or newer is required. Run 'claude update'. A model you pick later from the composer menu becomes the session's recorded model and survives a reopen, a server restart and a switch to Standard. A model id Cloudfield cannot store (whitespace, a leading -, or over 128 bytes) shows a Model not recorded notice.

--effort is set after the model, through the agent's thought_level session option, so the first turn already runs at it. Copilot reads --reasoning-effort on copilot --acp itself, so its Enhanced sessions get the flag instead. If the agent rejects the effort or advertises no effort option, the Chat view shows an Effort not set error notice, and a Background session driven over ACP fails rather than run at the default. An effort you pick later from the composer menu becomes the session's recorded effort and survives a reopen and a switch to Standard, like the model.

The session's sandbox is the same as a Standard session's, with the same image, home, retention, Pause and Close. The agent's ACP server runs beside a login shell, and the Terminal tab is that shell: use it to log the agent in or inspect the checkout (terminal.md).

The Chat view

An Enhanced session opens on Chat: one timeline, newest at the bottom.

  • Your messages are bubbles on the right. Everything the agent writes to you renders Markdown under them; its last message is the answer, with the turn's outcome ("Finished in 12s") and Copy the reply.
  • The work between two of its messages, its thoughts, tool calls, plan, subagents and answered requests, folds into one header ("Read 2 files, ran 1 command and edited 1 file"). Click it for one step per call, and click a call for its command, output, diff, or input and result. Files the agent read are chips that open in Files.
  • While the agent works, the newest header stays open and says what it is doing, with the seconds since it began. While it waits on you it reads "Waiting for your approval: <command>" or "Waiting for your answer". Once the agent writes again, or the turn ends, the steps fold away, unless you opened or closed them yourself or a subagent still runs. When a turn ends with no request, the session says Waiting for your reply, and the header's Reply focuses the composer.
  • Notices, a turn that was cancelled or stopped, and messages between agents show inline. Hide from Session, under Agent messages in Details, turns agent messages off.
  • Scrolling near the top loads older items. A failed load shows the server's error with Retry.
  • Esc in an empty composer moves focus to the timeline. Esc again leaves the session.

A success or failure report from the agent does not close the session: the timeline shows Done or Failed, and you can keep sending messages. Close ends the session and starts the container retention period (default seven days).

The Multiplayer strip under the view switch shows who controls the session and who watches, with Take control and Release. Control works as in a Standard session (Session control).

The composer

Enter sends and Shift+Enter adds a line. On a touch screen, Enter adds a line and the button sends. The button changes with the turn:

Button When What the message does
Send no turn is running starts a turn
Steer a turn runs and the agent supports steering joins the running turn
Queue a turn runs and you hold Mod+Shift, or the agent cannot steer runs after this turn
Interrupt a turn runs and the box is empty stops the turn and cancels its requests
Resume the session is paused resumes it

Enter never interrupts. Mod+Shift+Enter always queues. / lists the agent's commands and @ completes a path in the session's checkout. The menus under the box set the agent's mode, model and effort. The footer shows context window use, such as 43%, and turns amber from 90%; click it for the breakdown, and for Compact when the agent has a /compact command.

An unsent message stays with its session across pages, mode switches and reconnects. Reloading the page discards it.

Steering, answering, interrupting and changing options need control of the session. The owner's desktop tab takes it when it first shows Chat and nobody holds it. Without control you still get Send, and the message waits for the controller as in a Standard session (Messages and notes).

Attach files adds files to the composer, at most eight: images up to 8 MiB, other files up to 64 MiB. Images go to the agent as image content and other files as a path in the container. If the agent does not advertise image support, remove the image before sending.

Permissions and input

A new session starts in the agent's no-prompt setting, so a request arrives after you switch to a mode that asks, from an agent whose own configuration still asks, or for a check the agent never skips. Claude Code in bypassPermissions still asks for an explicit ask rule in its settings, a tool that needs a person, and its own safety checks, at every permission tier. Answer here, with aether answer, or with a connector's aether_decide_approval. Each request marks the session Needs you and docks above the composer, one at a time (1 of N). The composer stays shut until you answer. Interrupt stops the turn and cancels the request instead.

If the agent refuses its no-prompt mode, the Chat view shows a Mode not set error notice, such as The agent refused mode "bypassPermissions", so the session runs in "default": ... Mode bypassPermissions is not available in this session, and the agent asks as that mode does. Claude Code's adapter refuses bypassPermissions when its settings or managed policy set permissions.disableBypassPermissionsMode to "disable".

  • The card names what the agent wants ("Claude Code wants to run a command") and shows the command, or the files it changes with their diffs.
  • When the agent offers allow once and allow always, How long chooses between Just once (the default) and Always, and Allow answers with that option; Reject sits beside it. Other option sets keep the agent's own buttons, allow once filled.
  • Keys 1 to 4 pick an option while the card has focus, shown on each button, and 1 never picks an allow-always option.
  • A form question shows its fields. A link request shows the URL with Copy link and Open.
  • An answered request stays in the timeline as one line, such as "Allowed once · run go test".
  • A subagent's request is the session's request, answered the same way.
  • From the CLI, aether sessions <session-id> lists pending requests and aether answer <session-id> <request-id> <option-id> answers one: allow once or reject once, never always.
  • Answering needs permission to steer the session and control of it. The first answer wins. Cancelling the turn answers every pending request cancelled.
  • A Default session's sudo command is a request too, in Standard sessions as well. It shows under Needs you in the session's details, not in the dock: Approve runs it once as root, Deny refuses it. Only the session's owner or an admin may approve, and neither needs control (Sudo in a Default session).

A message sent during a turn waits for it to end (Queued), or joins it with Steer. If the agent refuses it, the message reads not_sent with the agent's error. If the connection closes first, the transcript shows Message not delivered: agent connection closed and the message is not resent.

Status

A turn start marks the session working. A turn end parks it as waiting, like a Standard session whose agent reports its turns. The reason tells you how it ended:

Reason State Cause
turn ended without a report waiting The turn ended normally with no outcome report
agent reported success finished The session shows Finished: review (failure-handling.md)
needs input: <question> needs-you The agent ran aether-internal report --outcome needs-input and ended its turn
blocked: <summary> needs-you The agent reported an external blocker
the summary of a waiting report waiting-agents, waiting-ci or waiting-tools The agent waits on its own agents, CI or a process
the summary of an answered report answered The agent replied with nothing pending. It never needs you
turn cancelled waiting You or the agent cancelled the turn
turn interrupted needs-you The connection that ran the turn ended first, as after a server restart. Send a message to continue
turn ended: <stop reason> needs-you Any other ACP stop reason, such as max_tokens or refusal. Send a message to continue
enhanced turn failed: <error> failed The agent failed the prompt but stayed connected
enhanced session ended: <cause> disconnected The adapter exited. Reopening the session clears it
enhanced session failed: <error> disconnected The adapter could not start or open the session, or the agent lost its session twice within 5 minutes

Background work

Claude Code can end a turn while a background subagent, a workflow or a command started with run_in_background keeps running. The Enhanced session stays working until they finish, and when one finishes and Claude Code starts a follow-up turn on its own, the Chat view shows it as an autonomous turn. The session reason reads working in background: <n> tasks, or waiting-agents or waiting-tools between turns.

  • Claude Code runs the main agent's Agent calls in the background: the call returns at once and its subagent's card follows the task until it reports. A reload reads up to 5,000 earlier items to keep the card of a subagent that still runs; past that, scroll up to load its launch.
  • A shell such as a dev server does not hold the session, because it may never end.
  • Stop cancels an autonomous turn and parks the session with turn cancelled. The tasks keep running in Claude Code.
  • A task that never ends keeps the session working until you press Stop, as long as the agent sends something within three times --stall-threshold.
  • Other agents report no background tasks. Output they send with no prompt open is logged under their last turn and changes no state.

Mail

Messages from other sessions and people (coordination.md) reach an Enhanced session without hooks. When mail arrives and the session has no turn running, the server sends the agent one prompt telling it to run aether-internal inbox and acknowledge the batch, ending with End this turn with exactly one report as your last action: aether_report, or /usr/local/bin/aether-internal report where you have no aether_report tool. A message steered into a running turn carries no such line. Messages that arrive together share one prompt, and each set of new unread messages starts at most one turn, even a turn the agent refuses. A session that opens afterwards gets the prompt again.

Report reminder

A turn that ends normally (end_turn) without an outcome report gets one more prompt from the server: Report your state with aether_report or aether-internal report (answered, waiting, needs-input, blocked, success or failure) before ending the turn., naming only the outcomes the session's role may use. It appears in the Session view as a message. The turn it starts is never reminded, so an agent that still does not report parks with turn ended without a report. A subsession's parent then gets the last message of the reminded turn, not the reminder's.

No reminder follows a turn that was cancelled, interrupted, failed or stopped on another stop reason, or one that background tasks or a request waiting on you hold. A message you sent during the turn starts the next turn instead. A session a member controls gets none: the next prompt is theirs. The reminder also waits on the same admission as a mail prompt: a protected session, a subsession a member controls, and a paused or switching session get none. Background sessions get none either: their turn end finishes the session.

The reminder is a prompt, not a hook, so it works the same for every agent. Claude Code's ACP adapter does forward _meta.claudeCode.options.settings, where a Stop hook could live, but that setting replaces the adapter's own settings and reaches only Claude Code.

The prompt waits while a session is protected, a member controls a subsession, or the session is paused or switching modes. Lifting protection, releasing control or Resume offers the mail that arrived meanwhile at once; otherwise the server retries a waiting prompt at least every 30 seconds.

Restarts and failures

The agent's ACP server runs under a keeper: a process in the session sandbox, started from the staged server binary as aether-internal acp-keeper, that owns the adapter's stdin and stdout and serves them on a socket in /run/aether-acp/. The server attaches to the keeper with a short-lived aether-internal acp-keeper attach exec and a token only the server holds. The keeper and that exec run as root, out of the agent's reach; the adapter runs as the session's user, as before (security).

A server restart or update (systemctl restart aether-server, aether server update, a boot trial or a rollback) leaves the keeper and the agent running. Terminals started with aether-internal terminal run under a keeper of their own and keep their output, input and exit status through it (terminal.md). The next server process reattaches and adopts the conversation: the turn in flight keeps streaming, an open permission request or question stays open under the same id, background tasks and commands the agent's shell tool started keep running, and nothing is sent to the agent twice. A turn that ended while no server was attached still ends before what the agent sent after it, such as a background task's follow-up turn. A message queued behind the turn is sent again once the server is back, unless it already reached the agent; one queued for a paused session waits until the session resumes. An answer, cancel or message sent while the new server is still recovering sessions waits for recovery, up to 30 seconds, instead of failing with the Enhanced agent is not running. The log records no notice for an adoption. A stopped server detaches cleanly. A killed one can, rarely, record twice the agent output it logged in the instant before it died. A server killed after it recorded a new turn but before the turn's prompt reached the keeper ends that turn with Turn interrupted: Cloudfield's server restarted before this turn's prompt reached the agent. Send it again.

The server cannot reattach when the keeper or the agent exited, when the agent wrote more than 32 MiB while no server read it, when the keeper speaks another protocol version, or when the server stopped before the agent's conversation opened. An agent counts as exited 5 seconds after its process ends, even if a command it started still holds its output open. The server then logs Agent restarted with the reason, stops the keeper and the agent, and restores the conversation in a fresh one, as Reopen after Close, a failed Close and Retry Enhanced always do. A turn cut off that way ends with a Turn interrupted notice, its pending permission requests are dropped, and the session parks with turn interrupted. Queued messages read Not sent: send them again. Background tasks end with the old adapter, including commands the agent's own shell tool left running, and the log notes Background work interrupted. Commands in a terminal started with aether-internal terminal keep running, and the terminal stays usable (terminal.md). A conversation that cannot be restored starts a new one and says Started a new agent conversation. When another process attaches to the keeper, which only a second server on the same data directory or root in the container can do, the server logs Agent connection taken over and restores the conversation the same way.

A session sandbox keeps the server binary it was created with. A session whose container a server without keepers created runs its adapter without one, and every restart restores its conversation as above until the container is recreated. Reopen, Retry Enhanced, Pause and resume reuse the container; a new session, or an account switch at a usage limit, gets a new container with a keeper. When a new keeper fails to start and Cloudfield cannot stop it, the session fails with Enhanced agent failed and the keeper that failed to start could not be stopped, instead of running the adapter without a keeper beside one the keeper may have started. Rolling the server back to a build without keepers stops each keeper with its agent and restores the conversation as above.

Restoration depends on the agent's own saved conversation and login. Check the checkout before you retry interrupted work.

Claude's adapter keeps running when its Claude Code process dies, but drops the conversation and answers every later prompt with Session not found. Cloudfield shows that prompt's Prompt failed notice, then Agent conversation lost, and restores the conversation in a fresh adapter as above. Send the failed message again. If the agent loses the conversation again within 5 minutes, Cloudfield stops the adapter and the session parks with enhanced session failed: the agent lost its conversation again within 5 minutes: ....

If the agent refuses a turn with Authentication required, Cloudfield shows Sign-in refused, or Agent signed out when the login file cannot sign the agent in, restarts the adapter in the same container so it reads the account's login again, and restores the conversation. Agent mail is offered again by itself. A session whose agent reported an outcome that is still waiting for its turn to end is not restarted. The session parks with the agent's error followed by what to do, one of:

CODE
enhanced turn failed: ... Authentication required ...; Ada's Claude Code login is signed out. Sign in, then send the message again: dashboard Agents page, or aether agent login claude
enhanced turn failed: ... Authentication required ...; Cloudfield restarted the agent to reread Ada's login: send the message again. Refused again? Sign in: dashboard Agents page, or aether agent login claude
enhanced turn failed: ... Authentication required ...; a restart did not help. Start a new session, or if Ada's Claude Code login is signed out, sign in: dashboard Agents page, or aether agent login claude

The first is a login file that cannot sign the agent in; the notice quotes what it lacks. The second is a refusal the file does not explain, which a restart fixes when only the agent's copy of the login was stale. The third is a second refusal within 5 minutes: either this sandbox's copy of the login is stale, which a new session's sandbox does not share, or the login is signed out. The owner named is the owner of the account the session runs on. A refusal after the login file changed restarts the agent once more inside those 5 minutes, so a message sent after signing in reaches an agent that has read the new login. A session Cloudfield does not restart the agent of (a Background one, or one whose agent reported an outcome) ends its reason with <owner>'s <agent> login may be signed out. Sign in: ..., and so does a session whose agent refuses to open its conversation. See harnesses.md for where else a signed-out login shows.

Each time it starts or restarts an adapter, Cloudfield checks that your home still belongs to the session's user with owner rwx. A root command in any of your sessions can change that and lock every agent on the home out of its login and its ~/.local/bin. Cloudfield gives the home back and shows Home restored with the owner and mode it found (security.md). An agent that stays connected and is never refused gets no restore, so its tools keep failing: run sudo chown "$(id -u):$(id -g)" "$HOME" && sudo chmod u+rwx "$HOME" in that session's Terminal tab, which runs as the session's user; a Default session's sudo waits for your approval. If restoring fails, the session parks with enhanced session failed: the agent cannot read its home: ..., naming the home, its owner and mode, and the error.

If the adapter fails to start or exits, the container and login shell stay available. The log shows the real error and the end of the adapter's stderr, and the session parks:

CODE
enhanced session failed: open the agent conversation: acphost: session/new: {"code":-32000,"message":"Authentication required"}
enhanced session ended: the agent's ACP server exited with code 1; stderr: ...

Fix the cause (for a login, run the agent's login command in the Terminal tab). Then choose Retry Enhanced in the Chat view, or pause and resume the session, to start a fresh ACP server. Open in Standard switches the session when the agent can switch. Otherwise it starts a new Standard session with the same task and closes this one without merging, after asking.

A turn that fails on the account's usage limit does not park with enhanced turn failed:. The session moves to another account (usage fallback): its container is replaced by one on the new account, the log gets a Continued on <B>'s account notice, and the session is prompted to continue. The session must be restorable there, or the session parks with enhanced session failed: <error>. With no account to move to, the session parks with a Usage limit reached on <A>'s account; ... reason that says why (Usage limit mid-session).

Switching a running agent

A running Standard or Enhanced session can move to the other mode in the same container, keeping the agent's conversation:

CODE
aether session switch <session-id> --mode enhanced
aether session switch <session-id> --mode standard

In the dashboard, More → Switch to Enhanced… (or Switch to Standard…) does the same after a confirmation. It needs permission to steer the session. While someone controls the session only that session can switch, so the CLI switches only a session nobody controls.

Only Claude Code and oh-my-pi can switch. Any other agent, and any agent whose command a definition overrides, is refused:

CODE
scheduler: this agent cannot move a running session between Standard and Enhanced: codex

A Background session cannot switch:

CODE
scheduler: invalid session state transition: a background session cannot switch modes

A Standard session must have reported its session, which happens on its first turn, or the switch is refused with the agent has not reported its session yet; it does on its first turn. Switching to Enhanced needs the adapter installed, or it is refused with the agent's ACP server is not installed; install it with Enhanced selected on the Agents page. The dashboard menu says why it cannot switch: Enhanced adapter not installed · Set up, or Available after the agent's first turn.

The container, checkout, shell tabs, control lease and conversation carry over. A turn in progress is interrupted, pending permission requests are dropped, the login shell is replaced, and turns taken in Standard mode are not in the Session timeline. A Switched to Standard or Switched from Standard notice marks the gap. Anything the agent started that outlives it, such as a dev server, keeps running.

A failed switch puts the previous mode back and shows the real error, for example:

CODE
switch to Standard: the agent's terminal exited with code 1 as it started; the Terminal tab shows its output

While the switch runs, messages are refused and read not_sent. Pause, Close and Kill wait for it, for about two minutes at most.

Background sessions

A Background session of codex, omp, opencode, copilot, gemini or cursor uses the agent's ACP server when it is installed. Every other agent, and these six without the server, use the agent's headless command line. Claude Code keeps claude -p.

The Chat view of such a session has no composer ("Background sessions take no input."). The task is the only prompt. A permission request that still arrives is answered with allow_once, or the first allow_* option if there is none, and never with allow_always.

When the turn ends, the session finishes like any Background session: commit, publish and completed or failed, with the reason agent exited; results committed or agent exited 1: <cause>. Mail does not wake a Background session. A server restart mid-turn resumes the session and prompts the agent to continue.

Instructions and the session log

Every session gets the agent instructions and the team memory brief. Claude Code takes them as a system prompt. Other agents get them with the task, or after the first message when there is no task, so compaction can drop them; the report reminder repeats the reporting rule when it matters. The session's timeline records session instructions: system prompt or session instructions: first message when the session opens.

The conversation is stored at <data-dir>/transcripts/<run_id>.items.jsonl with no size or age limit, and is deleted with the session. Anything an agent or tool prints, a secret included, can be in it (privacy.md).

Limits

  • Enhanced mode does not isolate the agent from its tools. They share one container, so a build that runs out of memory can end the agent.
  • Codex subagents do not nest in the timeline yet.
  • Only Claude Code reports background tasks and autonomous turns.
  • Antigravity has no Enhanced mode.
  • An interrupted turn is not resumed on its own. Send a message to continue.
  • A mode switch discards the turn in progress.

Next: Teams.