Session — the execution unit where agents work

If something is not working, start aachat support for guided diagnosis, repair, and verification. It requires a terminal and the selected CLI: Claude Code by default, or Codex with aachat support --provider codex. Share the symptom and any Session ID or failure code after it starts; do not put secrets in command arguments.

A session is the execution unit in which an agent actually works. When a user or another agent sends a request, a session starts, and the agent runs on top of the coding agent on the owner's machine (Trust Boundary). This page covers the session lifecycle, operations, how to read results and records, workspace separation, and delegation between agents.

Lifecycle

States transition as starting → running → stopping → stopped. Abnormal termination becomes failed. In the WebUI, when a Session becomes failed, a Session failed: <agent> notification appears for 10 seconds, and Open session opens that Session.

If the runtime cannot run a turn, the Session becomes failed immediately and its workspace is preserved. The message says that the result could not be confirmed, nothing is replayed automatically, and you should confirm the runtime has stopped and review the saved history before continuing in a new Session. A runtime prompt execution failure is distinct from notification delivery failure. Start aachat support; the support agent reads the transcript and owner-local logs, then checks Resume eligibility; Workflow Steps use Workflow retry (recovery).

Finishing a Session

In a conversation with the human user, the agent ends only the turn after a completed answer and keeps the same Session open for follow-up. It does not add a question asking whether to continue, polling, or a wait tool call. For a current request that is not a conversation with the human user, such as a child Session task or a non-interactive Trigger task, the agent runs chat session finish when the request's purpose has been achieved. This distinction depends on the current request, not the presence of a parent Session or how it started. Delivering an intermediate result, such as a specification, does not by itself end the Session.

An ordinary Session can also finish when the user instructs it to end. If successfully registered waits are the only work still pending, it can finish only if it owes no unfinished final result to a parent Session and has no specific contract requiring it to stay open. Having no remaining work does not meet this wait condition. Unfinished child Sessions and Workflow Attempts end only the turn while waiting. Registered waits can continue the same Session after it closes (see “Wait for results and continue the same Session” below).

After the current turn, finish runs one asset wrap-up turn that checks for unsaved deliverables, then closes the Session. Acceptance of finish is not the same as actual termination. Application of this instruction depends on the owner-side runtime version; it does not guarantee that every running Session stops immediately when its work is done (CLI).

In the WebUI, the Session owner can request the same finish with the Finish button in the composer. It appears when the Session is running, has started, and its turn is active or idle. No instruction text is needed; after you press it, the button shows Finishing… and then Stopping…. It is disabled while pending follow-ups are visible (Finish is available after pending follow-ups are processed or removed.). To stop without waiting for wrap-up, use Force stop session in the Session header details (owner only, while running or stopping).

A Workflow Attempt follows its Step completion procedure; ordinary Session finish is not a substitute (Workflows). A Session ending does not by itself establish that the Project is Done, its deliverables are accepted, or code delivery succeeded. Use “Read results and records” below to inspect the artifacts and validation.

While a background shell started by Claude remains active, its turn stays open and the final report is saved in the same response. Follow-up input waits in the queue until the turn completes. Cancelling the turn through an interrupt also requests that background shells started in that turn stop. The Agent must stop long-running processes it no longer needs, such as dev servers and watchers.

For every Runtime, 60 minutes without inbound runtime activity during an executing turn cancels the turn and marks the Session failed with a reason. A pending permission request awaiting a human response extends the deadline; delivering that response to the Runtime allows another 60 minutes. If cancellation receives no response within 10 seconds, the connection closes.

Idle auto-finish

After 60 idle minutes, a session enters its finish path. When it has a completed turn, the runtime performs finish on its behalf and runs one asset wrap-up turn before closing. If submitting the initial idle-finish request fails, the session stays alive and the request is retried. If the wrap-up turn itself cannot start, complete, or be saved, the session becomes failed, preserves its workspace, and instructs the user to resume it or start another session. Idle finish is disabled while a scheduled follow-up has a next run pending.

Archiving a Project asks every in-progress Session that covers the Project to stop, ordinary Sessions and Workflow Sessions alike (a close that interrupts the running turn). The status does not become archived until every Session is confirmed stopped. Unexecuted reservations are cancelled, and new execution and follow-up instructions are refused. Archive is rejected while a Session also covers another Project. See Projects for reservations and recurring work that are not restored automatically.

Starting a session

aachat session run <agent> --project <project> "request text"

The agent is resolved as a member of the specified project. Accepting a start requires the following conditions.

• The project's status is active
• The agent is a member of that project

Execution requires aachat up to be running on the agent owner's side with the runtime connected. If the other start conditions are met, the Session is accepted even while offline, waits in starting, and starts automatically when the runtime connects. Waiting for the connection has no timeout; do not start the same work again.

In the WebUI, a session starts when you address an agent with the composer's target chip and send. The composer also accepts an attachment-only request with no message text. The attachment is stored in Session history and is not automatically published to Project Media.

An @mention is not a session execution trigger. The exact @<agent>.<owner> in a message body is a notification (a call-out) and does not start a session on its own. What makes an agent work is target chip addressing in the WebUI, and session run in the CLI. Reports of "I mentioned the agent but nothing ran" are caused by this specification.

session run options

For runtime Permission, a temporary question, a Project Ask, or a Workflow Decision, use the response comparison to choose who answers and what continues.

Startup receipt (chat session run)

When an agent inside a Session starts another Session with chat session run, the response waits up to 40 seconds for the new Session to leave starting. In the CLI's JSON output, data.startup.state is one of the following.

chat workflow run returns one data.startups[] element per Step Session it started, and each element's startup has the same shape (Workflows).

Continuing a session

Send additional instructions to a running session with session send. When waiting for a registered Ask continuation, do not send the same answer again as a follow-up; see “Wait for results and continue the same Session” below.

aachat session send <session-id> --project <project> "follow-up instruction"

Follow-ups sent while a turn is running are queued and run in order.

In the WebUI, the workspace panel opened by selecting a Session in the Project Work Panel lets you monitor execution in real time, send follow-ups, respond to permissions, and cancel turns (WebUI). When a stopped or failed Session can be resumed, Restart session is shown.

Edit, remove, or run queued follow-ups now

When a Session has queued follow-ups, a Queued follow-ups section (N queued) appears above the Session composer. Each item has these actions.

• Only the person who sent the item can change it (for an item sent by an Agent, that Agent's owner). Others are rejected with MessageMutationNotAllowed
• If the item already started or left the queue when you save, the UI shows This message is no longer queued. Check the current conversation and queue before choosing the next action. (QUEUED_FOLLOW_UP_NOT_QUEUED). Check the conversation and the queue before choosing the next action
• If someone else changed it first, the UI shows This queued message changed elsewhere. Review the latest version and try again. (QUEUED_FOLLOW_UP_CHANGED) with the latest version beside your draft. Review it, then save again
• If a Run now item contains input the runtime cannot accept (images, audio, resources, and so on), it is rejected with unsupported_input before the running turn is interrupted. The original item stays readable, and the current turn and Session keep running
• System notifications such as wait completion are not part of this queue and cannot be edited, removed, or run with Run now

Listing and stopping Sessions

List sessions with aachat session list (the connected team's Work Index; filter with --agent / --project; default 10, maximum 100); stop one with aachat session stop <session-id>. Free text in list rows, such as the body or failure reason, is truncated to a 100-character preview; read the full text through each row's read reference.

A Session belongs to the Project it was launched from. The Project Work Panel and Work Map lists, sidebar session signals, and lists filtered with --project show only Sessions launched from that Project. A Session launched from another Project that merely includes this Project in its coverage does not appear there, so look for it in its launch Project. A Workflow Run started directly by a Session with chat workflow run appears as a child row with a Workflow icon under that Session and links to the Run detail.

Read results and records

Copy as Markdown in an answer’s footer copies the original Markdown text after its last tool call. For answers without tools or without text after the last tool, it copies the full text currently loaded. Automatic continuations count as one merged answer and cannot be copied while running. Past answers remain copyable while a separate answer is running. Progress text and work history remain visible in the conversation.

Reading results

Open a Session from the Project Work Panel. Inspect its direct child Session tree to follow delegation, and read each child's final response and actual artifacts.

A link to a Session message opens the conversation at that message, including on narrow screens. A document link still opens the document even when it also carries a conversation position.

The result badges in the Session header show what the Session left behind, by kind: PR #N (up to 3), Pushed, Workflow, Trigger, HTML, Media, and Docs. Kinds with no results are hidden. The label list is in WebUI.

• When exactly one target can be opened, the badge opens it directly. For a Trigger, Project Triggers opens with that Trigger selected
• When there are several, a popup list opens (20 at a time; Show more loads the rest). Each row shows actions and up to two lines of explanation
• Documents and HTML pages badges show + when a new item was created and a pen when items were only updated
• Pushed opens the Code delivery panel, and PR #N opens the GitHub PR in a new tab
• Opening a same-Project Media result shows the Media detail inside the workspace, keeping your unsent draft and selected agent

The former standalone Results list and detail pages were removed. ID links using /results?result=<ID> open the result target or its Session. The old session_id, target, and used_by URL forms are no longer supported. The results view is not a complete attribution list for every document or Ask. Documents can also be opened from the Project's Docs or from actual document links in the transcript.

A stopped Session is an execution state. Check both repositories in Code Delivery, then read the submitted content and validation before accepting the outcome. Pin session / Unpin session in the header changes your personal pinned list; it does not keep execution running or guarantee workspace retention. Copy session reference copies a reference to the Session (aachat session: <title>).

A pin on a sidebar Project row means you have pinned a viewable ordinary Session whose home is that Project. This includes ended, old, and archived Sessions. The mark identifies the Project to open; it is not an unpin button. Changes from another tab or device may appear only on the next status refresh.

An agent inside a Session reads the conclusion, results, and repository state with:

chat session show <session-id> --project <team>/<project>
chat result list --session <session-id> --project <team>/<project>
chat result show <result-id> --project <team>/<project>

chat session show returns the latest completed response (latest_response), result cards (results), repository delivery state (repositories), and read references to the transcript and result lists (reads). chat result list can be narrowed with --with-summary (only with --session; results that have an explanation) and --include-excluded (also return excluded results).

Reporting and curating results (for agents)

For deliverables that exist apart from the reply, the agent reports those not recorded automatically (such as PRs and pushes) with chat result report --stdin. Right before returning a final answer with those deliverables, the agent curates its Session's results. Requests completed entirely in the reply do not need result reporting or curation.

• For deliverables that exist apart from the reply, explain the contribution in a one- to two-sentence summary. An existing result can gain or update its summary without re-registering receipts
• Set excluded:true to hide drafts, duplicates, and intermediates from ordinary lists; excluded:false restores them. null is invalid
• Excluding only tidies lists; it does not delete the body, references, receipts, or unsubmitted warnings

See CLI and Code Delivery for the full procedure.

Reading the records — transcript and logs as a pair

Tools called inside a Claude subagent appear inside the Agent row. Closed rows still show activity, failures, and cancellations in their children. If the parent is unavailable in the loaded message, the tool stays visible with Parent unavailable and its parent ID. Older records without parent IDs keep their flat display.

Tool summaries in chat session read / aachat session read include id="…" for Agent / Task and child tools, and parent="…" for children. IDs use JSON string escaping. When a short preview omits them, follow the returned detail_read to read the full text.

There are two kinds of session records, differing in content and storage location. Use them as a pair.

Use read to check conversation content and results; use logs to investigate startup failures and execution errors. aachat session read supports paging with --last (default 20, max 100) and --before. logs can read from the beginning with --from-start.

Turn completion text is stored in this server transcript but is not automatically posted as a Project Chat message. A handoff remains in the transcript first. When the project needs a short notification or handoff, the agent explicitly runs chat send <project> .... Use a normal Shared Document only when the handoff is substantial and independently worth rereading. Do not put progress or handoffs in PROJECT.md. A transcript is the session record; a Chat message is project-wide communication.

Reading from a human terminal or an outside agent

From a human's terminal or an external coding agent, choose the aachat session read view that answers your question:

aachat session read <session-id> --project <project> --team <team> --decision
aachat session read <session-id> --project <project> --team <team> --submission <turn-id>
aachat session read <session-id> --project <project> --team <team> --view children
aachat session read <session-id> --project <project> --team <team> --message <message-id> --full

• --decision returns a bounded view of purpose, latest final text, pending submissions, and child context. Read gaps and follow detail_read: truncated text or unavailable artifact attribution is not complete evidence
• --submission reconciles one accepted instruction. Take the exact turn_id from data.submission.turn_id in the original run/send receipt. It follows that submission's phase, not simply the latest turn. Runtime acknowledgement is not an independently observed start timestamp or a successful result
• --view pending|children|results|evidence returns one related collection (evidence requires --submission). Page collections with --limit and --cursor
• --message <id> and --result <id> read one item; add --full for the whole text

--decision and --submission are mutually exclusive. These flags belong to public aachat and are not available inside a Session (there, the error points to chat session show). For ordinary transcript history, run the returned next_page argv.

session.execution.runtime_wait describes a saved Runtime wait in this Project; --submission returns submission.runtime_wait only for the selected turn’s current recovery chain. Acceptance (accepted_at, runtime_acknowledged) is preserved and does not mean completion. An omitted wait does not guarantee progress or success. next_retry_at is a saved schedule, not an execution promise; an authentication reason alone does not establish that the owner must log in again. External MCP read_session without a section selector exposes the same session.execution.runtime_wait.

Reading and searching from inside a Session

An agent inside a Session reads transcripts with chat session read. Target IDs can be a full UUID or its first 8 or more characters.

chat session read <session-id> --project <team>/<project>
chat session read <session-id> --project <team>/<project> --match 'cargo test'
chat session read <session-id> --project <team>/<project> --message-id <message-id>

• --last sets how many items to return (default 50, maximum 100). Run the returned next_page for more
• Items whose text was shortened carry detail_read; --message-id reads the full transcript text of that message (tools remain summaries)
• --match searches saved text only within the specified Session, read through the specified Project. It trims surrounding whitespace and matches the remainder as one case-insensitive literal. It does not split on whitespace or use wildcards or regular expressions, and an empty value is rejected. Each match returns an excerpt of at most 600 characters. The newest matches, up to --last, are selected and returned in transcript order
• Continue a --match search with next_page as well. When scope.search_complete is true (next_page is null), the searched range is exhausted. An empty successful response means no match in saved searchable text. Read failures such as 403, 404, or timeout are not a negative search result (Troubleshooting)
• Commands in tool titles are searchable. Tool input payloads and output bodies, including saved output tails, are excluded from normal reads, detail reads, and searches with chat session read. Image contents are not searchable. No match does not establish that a tool succeeded or that no error occurred.
• The former --dialogue flag was removed; passing it fails as an unknown argument

Live view and saved tool output

Collapsed activity headers and individual rows share categories such as Read, Search, Edit, and Shell. The received kind takes priority; a small known-name mapping fills in unknown kinds. Unknown tool names remain visible, and unnamed tools appear as Tool. Compound shell commands are not parsed. Rows retain their specific titles; details provide the original tool name and retained input and results.

A Session's live view updates only while that Session's pane is visible. It shows text and tool summaries (kind, status, name, input, and the file paths touched); completed tools can also show the last 2,000 characters of supported text output. Open the tool details to read Output (last 2,000 characters) as plain text. Raw output in full and diff text are not shown. If the runtime is too old for the live view protocol, the pane shows Live view is unavailable with this version. with Retry and Update instructions (a link to Desktop). When updates cannot keep up, it shows Live updates could not keep up.; other failures show Could not update the live view. Retry rereads it.

Newly saved Session history keeps tool input, identifiers, status, and file paths, plus up to the last 2,000 Unicode characters of supported completed tool output. Output received only while a tool is running is not retained, and older history without this tail is not reconstructed. Size limits can also omit inputs, so full text is not guaranteed. History reads and searches cannot recover output that was not saved. This policy alone does not establish that all older history or data in other storage has been deleted (storage boundary).

Missing output proves neither that the tool returned an empty result nor that execution succeeded or failed. Reconcile the saved status and final response with the actual artifacts, and leave results you cannot verify explicitly unconfirmed. Do not rerun an operation solely to fill in missing output. Put confirmed results, judgments, sources, and remaining uncertainties needed for later decisions into independently readable artifacts such as Shared Documents, and point to them from the Session's final response. Select the necessary evidence and exclude secrets instead of copying raw output wholesale.

Running tools show elapsed time alongside their name, measured from the Launcher’s first receipt of that tool in the turn. Reopening, reloading, reconnecting, or expanding a child keeps the same starting point. Tools without a recorded start time and finished tools show no elapsed time. This is an observation time, not the runtime’s internal execution start.

Successful Codex file edits and Claude Edit/Write calls show available added and removed line counts, such as +12 −4, in both the live view and saved history. Counts describe one tool call, not the final Git diff or a Session total. Zero counts are shown; failed or unfinished calls, unavailable counts, and older history without counts show no count.

Compacting a long session

chat session compact compresses a long session's context so work can continue in that same session. It does not start new work. Outside agents use the public aachat session compact command instead of chat.

chat session compact
chat session compact <session-id> --project <project>
aachat session compact <session-id> --project <project>

• With no target it compacts the current session; a target requires its project
• The request runs after the current turn completes and before an ordinary follow-up. Do not pack more work into the turn that requests compaction; finish that turn
• If the runtime does not support compaction, preserve the handoff context and discuss switching Sessions with the user
• CLI / server request identity makes retries idempotent; do not send a home-grown compression prompt
• Compaction does not delete the original transcript. Keep important decisions and deliverables in canonical Shared Documents rather than relying on the summary alone

Runtime restarts and accepted work

When a runtime restarts, accepted requests that had not yet started executing are redelivered to the same Session, up to a bounded number of attempts. A turn that the agent had already accepted for execution is not rerun automatically after a restart, because its input may have reached the agent. Its input and a record of the missing result are kept. When a runtime prompt fails, the output received so far is saved and an interrupt is recorded so later inputs do not start.

A return to starting after restart alone does not mean a new request or failure. Before running or sending the work again, inspect the original Session, accepted turn, transcript, results, and delivery. For a turn that may already have run, check the history and any external side effects, then continue in a new Session. Automatic recovery of every job and exactly-once external operations are not guaranteed.

If the runtime's available settings changed when a Session restarts, aachat restores the previous settings where it can. Changed values appear in the composer as Some settings changed when this session restarted., and the Settings adjusted at restart list shows <option>: requested → actual or no longer available.

Handling of accepted work differs from manually resuming an ended ordinary Session. A terminal Workflow Attempt still follows Run retry/new Run rules, not generic Resume. See Troubleshooting for the check order and what to do if progress stops.

Workspace separation and how workspaces are created

Each session gets an independent workspace created at ~/aachat/.run/workspaces/<agent>--<sid8> (sid8 is the first 8 characters of the session ID). At session start, the runtime prepares the following.

• workspace repo: in a session whose repo is resolved, that repo is checked out at the workspace root. The branch is the aachat-managed aachat-sessions/<project>/<agent>/<session-id>. <project> and <agent> are converted to lowercase letters, digits, and - (for example, content-editor.kensaku63 becomes content-editor-kensaku63). For a session spanning multiple projects, <project> is multi. A session whose repo is not resolved (a DM or team with no repo configured) gets a repo-less empty workspace (scratch)
• agent repo: the agent's own repo is checked out as a worktree at aachat/agents/<agent-name>/. The session can locate it via the environment variable AA_AGENT_DIR
• Shared Project and team state: aachat/teams/<team>/projects/<project>/ holds the Project's PROJECT.md, documents, Database, Media, HTML, and Workflows; aachat/teams/<team>/ holds the Team Wiki; and aachat/contracts/ holds generated contracts
• Runtime context projection: aachat's runtime context is generated into .claude/CLAUDE.md (Claude runtime) or AGENTS.md (Codex runtime), and skills are projected. The runtime context contains the agent's role (identity.md), the full PROJECT.md of the Session's Project (a startup snapshot with its source path), the workspace layout, and the list of contracts. A missing PROJECT.md is stated; a read error or invalid UTF-8 fails startup. It is regenerated on resume but not refreshed mid-conversation, so read the source file for the latest content or another Project. If the repo already git-manages a file of the same name, the projection is diverted to CLAUDE.local.md / AGENTS.override.md. The Codex override also includes a snapshot of the tracked AGENTS.md from the current worktree, without modifying the original. Read failures, invalid UTF-8, and reserved aachat-runtime markers in that source fail startup. Source edits are reflected at the next runtime preparation, but an existing Codex thread is not guaranteed to reread instructions on resume. Projected files are added to git's local exclude, so they never show up as repo changes

Git ls-remote and fetch used to prepare the agent repo and the Session workspace are tried up to 4 times, but only for transient failures such as dropped connections, temporary DNS failures, and HTTP 5xx (waits of about 1, 2, and 4 seconds). The waits count toward each operation's 60-second deadline, and a stop request interrupts them. Authentication, permission, missing repositories or refs, and local corruption are not retried. A failed remote read does not fall back to stale tracking refs. Restoring a verified local checkpoint does not require this workspace fetch.

In a Claude runtime workspace, the generated .claude/settings.local.json always pins crossSessionInbound to refuse. Other Claude Code sessions on the same machine cannot inject turns into an aachat Session. To hand work to another agent, use aachat routes such as Project messages, delegation, and chat session send. Subagent communication inside the Session is unaffected.

Cleanup when a session ends is decided automatically. If uncommitted changes or unpublished local commits remain, the workspace is kept; if it is clean, it is deleted. HEAD counts as published when it is contained in its upstream, an explicit handoff target, or a locally known origin branch. Cleanup does not fetch; if refs are missing or reachability cannot be confirmed, the workspace is kept. This keep/delete decision applies only to git workspaces: a repo-less scratch workspace is deleted at session end regardless of its contents, so move anything worth keeping to a project surface (Shared Documents, media, etc.) before the session ends. On ordinary resume, an existing workspace is reused with its HEAD, index, and uncommitted changes intact. If it was reclaimed, aachat recreates it from the exact HEAD saved in a local checkpoint before cleanup. A name collision uses a separate local branch without changing the existing branch or worktree.

Older Sessions without a checkpoint are reconstructed from the published branch, or a verified Session-owned local branch when the remote branch is absent; this may differ from the previous HEAD. Startup stops if no trusted source is available. Checkpoints do not back up uncommitted changes or guarantee recovery on another host or after cache deletion. Runtime recovery still requires the original workspace and agent worktree.

An origin branch other than the configured target also counts as publication evidence for managed workspaces. This only proves the Git work is saved; it does not prove the requested PR or push was delivered correctly. If a tracking ref is missing, verify the repository, origin, publication branch and HEAD, synchronize that tracking ref, then retry. Dirty or untracked work and missing managed metadata are retained.

Even when an ended managed Git workspace keeps its source, regenerable artifacts may be reclaimed: root target/, and node_modules/ at package roots confirmed by a valid npm or pnpm manifest with an adjacent lockfile. Dirty source, local-only commits, tracked artifacts, active workspaces, unclassifiable manifests, and mount or device boundaries are not deleted. Scanning and deletion never follow symlinks, so a symlink is not a reason to keep a candidate, and pnpm-style node_modules/ built from symlinks is still reclaimed. Only the link itself is removed; a target outside the reclaimed candidate remains. A candidate root that is itself a symlink is not reclaimed.

Fresh Sessions and Workflow Sessions check for 20 GiB of free space before creating a workspace or tools. If space is short, they maintain inactive workspaces of the same agent once; if space is still short or cannot be observed, they fail with workspace_capacity_insufficient. Resume and FreshRetry are outside this gate. Start aachat support for guided diagnosis, repair, and verification. The support agent reads the current aggregate with aachat status and retained paths and reasons with aachat doctor, preserving local work before any cleanup.

One session has one workspace repo. Work that spans multiple repos is split into one session per repo and coordinated at the project level. Even when multiple sessions run in parallel against the same repo, each works in its own independent workspace, so in-progress files never collide directly. Changes are integrated through the normal git / PR flow.

Configuring the workspace repo

The repo resolution order is the session-level override > the project setting > the team default.

A session-level override must match either the project setting or the team default. An owner/repo that matches neither is rejected (this is not a mechanism for pointing at arbitrary repos). DM sessions also use the project repository setting or an allowed explicit session override. DMs do not automatically inherit the team default; without a repo setting, they use scratch.

Note that the WebUI sidebar's "Repository" tree (the GitHub App connection) is a separate system from this setting (WebUI). The aachat init repo connection (Connected Repo) is also not a workspace repo setting.

A team default repo does not grant repository access. Each member needs their own GitHub credential, read/write permission, and organization SSO authorization where required (Teams).

Delegation — an agent driving another agent's session

An agent running inside a session can start, monitor, and continue another agent's session with the chat command. chat is exclusively for agents inside a session; outside a session (humans, external agents), use aachat.

Before delegating, read chat project members <project> when needed and use items[].name, commands, and live_sessions to choose the target. Use run for fresh work; use send only when there is a clearly related session. To continue the same work in an ended session, explicitly add --resume. An advertised slash command is placed at the beginning of the request prompt; it is not a dedicated flag. Do not put model, effort, or mode in the request text; set --runtime and --config only when you need to change them.

--resume is an explicit agent-only operation. For a stopped or failed target, the resume and follow-up are accepted in the same database transaction. If a resume is already in progress, the follow-up is queued in that generation; if the target is running, it is accepted as an ordinary follow-up without restarting the session. Resume reuses the saved launch configuration when the runtime supports it. A plain send never resumes an ended session implicitly. Archived sessions, Workflow Steps, and sessions whose workspace, configuration, or project coverage cannot be safely restored are rejected. Do not combine --resume with --cancel-current-turn.

Delegation has two conditions: the delegate agent is online (aachat up running on its owner's side), and the delegate is a member of the same project. Agent mentions use the exact project-member name @<agent>.<owner>. An unknown target produces a warning, and a mention still does not start a session. The same loop humans run in the WebUI — request → execute → check → follow up — works between agents.

The delegated session leaves its results in its own transcript and does not chat session send a completion report back to the source. When the source needs the results, it reads the conclusion and results with chat session show, and reads chat session read when it needs the history and evidence. Use a message for a short project-wide handoff, and a normal Shared Document for an independent deliverable (Concepts, Shared Documents).

A session started by delegation records its lineage to the session that started it (the source session). Because which request spawned which session can be traced afterwards, the history stays traceable even as work passes between agents.

Target IDs for chat session show, chat session read, and chat wait can be a full UUID or its first 8 to 32 hex characters. If more than one target in the same Project matches, the command fails with ambiguous_id; pick one full ID from candidates and run it again. Commands that change state, such as chat session send, need the full UUID.

Picking delegated results from the list

When no wait continuation is coming, find targets with chat session list --project <project>.

• Each row's attention_reasons lists only mechanical reasons that need a person, in this order: permission_pending (a permission awaits a response), submission_pending (queued requests exist), and failure (failed). Check rows with non-empty attention_reasons for problems that affect your current work and responsibility
• Beyond those, pick only direct_child rows and rows whose execution.lifecycle is stopped with a latest response that changes the current decision
• Read only the selected rows through their returned detail_read. Reading the list is not itself evidence of integration

Orchestration patterns

Use immediate Session delegation when the next request depends on the work you are inspecting. Use a Workflow when you want repeatable Steps with typed inputs, outputs, dependencies, and human Decisions. A Workflow pins its Revision for each Run; ordinary delegation keeps the next instruction flexible.

• run versus send: chat session run starts new work as a new session. chat session send adds instructions in an existing session's context; add --resume only when continuing the same work in an ended session
• Waiting for completion: register explicit targets with chat wait as described below in “Wait for results and continue the same Session.” After acceptance, end the turn without polling. Read the results when continuation arrives
• There is no implementation limit on delegation depth or fan-out. Deep chains make the history hard to follow, so consolidate results in the project's Shared Documents

When a human drives multiple agents from the WebUI, the composer's target chip addresses one agent per message. To reach multiple agents, split the request into separate sends or entrust the delegation to an orchestrator agent.

Wait for results and continue the same Session

When a Session agent needs to use results in a later turn, register explicit target IDs with chat wait --all. Targets are direct child Sessions (--session), top-level Workflow Runs in that Project (--workflow), and Project Asks in that Project (--ask), 1 to 100 in total. Targets are never discovered automatically. A Workflow Step can wait on Project Asks it created and ordinary direct child Sessions of the same Agent and home Project. It cannot wait on Runs, other Steps, or Sessions of another Agent or home Project. Only one unresolved group is allowed. The Step stays running when only children remain unresolved, and shows waiting_for_decision while an Ask is unresolved. The original Step reads the results, continues its current and remaining tasks, and completes using the final completion instructions. If it waited within those instructions, it submits using the instructions already received.

chat wait --all --session <session-id> --workflow <run-id> --project <team>/<project>
chat wait --all --ask <ask-id> --project <team>/<project>
# Inspect the wait ID returned at registration when needed
chat wait show <wait-id>

Omitting --project uses the current directory's Project. To start one Workflow and wait on it, chat workflow run <slug> --input-file <path> --project <team>/<project> --wait starts the Run and registers the wait in one step. Neither command blocks.

Acceptance registers the wait; it does not mean the targets succeeded. After successful registration, an ordinary Session whose remaining work is covered by those waits may use chat session finish if it owes no unfinished final result to a parent and has no specific contract requiring it to stay open. Unfinished child Sessions and Workflow Attempts end only the turn. Unsettled waits survive closing; when all targets of each wait settle, one continuation is accepted for the same Session. In an ordinary Session, use separate waits for independent Asks and one shared wait only when all answers must be considered together. While waiting, do not re-register, send a manual follow-up, or poll. The check runs on a 30-second cycle, not a promise of a response within 30 seconds.

Create Asks, register waits, and finish necessary saves and reports before finish. Among Asks, only Project Asks can be wait targets; Session-scope Asks are cancelled when the Session ends. If finish returns session_pending_follow_ups, end the current turn, process the delivered content in the next turn, then reconsider whether to finish (recovery). After resuming, read the existing Ask's answer and revision before proceeding.

Each target settles as follows.

• Session: besides stopped / failed, a Session also settles when it is still running, has recorded a result, and has no active turn, auto-continuation, pending submission, scheduled follow-up, or open wait of its own. In that case the child Session stays open and accepts more instructions. Read the result; if more work is needed, send it with chat session send and register the wait again. While Claude is holding a background shell, its turn remains active, so recording a result alone does not settle the wait
• Ask: answered and cancelled are settled. Cancellation does not mean approval or success
• Workflow Run: settles when the Run becomes succeeded, attention_required, or cancelled

Find the wait and read its result

The following displays require a Web/API version that supports wait details and result notifications. If they are absent, check the registration receipt in the transcript and use the CLI read commands; absence alone proves neither an unregistered wait nor success.

A Session can be running while its list entry shows Awaiting results. Open that Session to find the wait panel above the composer. A single target is a row; expand a multiple-target group to see each Ask, Session, or Workflow name and state. Follow its link to the details. Deleted targets have a fallback name with a short ID and a disabled link. Couldn't load wait details. → Retry reloads these details; it does not resend an answer or continue the Session.

After all targets settle and continuation acceptance succeeds, the transcript stores a collapsible Wait completed system notification. If every target is settled but the notification is still absent after a check cycle, inspect whether the source Session is stopping or archived and whether its agent still has Project collaborator access. If the Project is not active (for example, Done), continuation is deferred until the Project is reopened. Expand a saved notification to inspect the names and states captured at settlement and follow the target links. Later renames or answer revisions do not rewrite this snapshot. Wait completed · Needs attention means a target is failed, attention_required, or cancelled. A stopped Session also does not by itself prove a successful deliverable.

Keep six checks separate: the answer was saved; every target settled; the target results succeeded; the system notification was saved; it was delivered to the agent; and the agent produced the next result using those inputs. Delivery pending / failed / cancelled describes notification delivery, separately from the target snapshot. Open a failed notification for its error and, when eligible, Retry delivery. It retries the same notification and turn; it does not rerun the targets. System notifications cannot be edited, removed, or sent with Run now like ordinary queued messages.

The agent receives target results with Read: commands and reads only the sources needed for its decision. The Web notification presents results and links, not raw commands to copy. chat wait show remains an optional read-only check. For retry conditions and Session failure, follow answer and continuation recovery.

See Projects for saving answers and distinguishing registered from unregistered waits. chat ask wait --timeout bounds a wait within the current turn; it does not register this continuation (CLI).

Runtime built-in subagents

A Task tool or similar subagent started by Claude Code / Codex is a runtime feature for exploration or parallel work inside the same session. It does not start a separate project-member agent session and does not gain independent project membership, transcript, or handoff ownership.

Use chat session run --agent ... when work belongs to a worker with another agent repo, owner, and project role. Use a runtime built-in subagent for temporary division of work inside the same session.

Scheduled execution

Automatic execution uses Project Triggers and scheduled follow-ups. Triggers are managed in the WebUI's Project Triggers or with chat trigger inside an aachat Session; scheduled follow-ups can also be created, listed, or cancelled with aachat session schedule create|list|cancel externally or chat session schedule create|list|cancel inside a Session. Cron expressions are not used.

• A Project Trigger has exactly one When: Once, Daily / weekly, Interval, Document match, or Webhook. Document match starts once when Shared Document frontmatter in the same Project equals the configured value. Webhook starts each time an authenticated external request is accepted. The Project composer's When chip can carry the current agent, prompt, and launch settings into Trigger creation. See Triggers
• A scheduled follow-up supports turn execution such as "check again ten minutes after this turn completes." Open the When chip in the session thread composer, choose under Send later how many minutes from now to send (1 to 1440, default 10), and check Repeat to repeat after the scheduled turn completes, waiting the selected duration each time. It is text-only; replies and attachments are not supported. While a next run is pending, the 60-minute idle auto-stop does not apply. Delete the follow-up or end the session to stop recurrence

Inside an Agent Session, use chat session schedule create self --after 10m "Check progress and continue". For another existing Session, replace self with its UUID and add --project <team/project>. Use --repeat-after 10m to repeat ten minutes after each scheduled turn completes. --after accepts one positive integer with s, m, h, or d (1 second to 30 days); --repeat-after accepts 1 minute to 24 hours. These are eligibility times: delivery waits until the Session is idle. Reservations never create or resume a Session.

Read or cancel with chat session schedule list self and chat session schedule cancel self <reservation-id>. The list includes creators and can_cancel; Agents can cancel their own reservations or Agent-created reservations targeting their own Session, with current Project access. Human-created reservations cannot be cancelled by Agents. After scheduling to self, end the current turn normally and keep the Session open: chat session finish ends the Session and cancels its reservations. Use the returned request_id with --request-id when retrying the same create request.

In progress on a scheduled follow-up means its delivery reservation is held; it does not confirm that execution has started. If the Runtime does not acknowledge delivery, an unaccepted reservation stays held until its 90-second lease expires and is reclaimed for retry. Delivery can take longer. Other turns on the same Session wait while the reservation is held, and Finish is rejected. Cancelling the reservation and stopping the Session remain available.

Cancelling a scheduled follow-up stops future runs for that follow-up; it does not stop work already accepted. In the WebUI, a confirmed cancellation removes the reservation from the thread. The notification distinguishes a new cancellation from one that was already cancelled or had otherwise ended. If the reservation is confirmed ended but the status of accepted work cannot be checked, the notification shows both facts as a warning.

Context for Sessions started by a Trigger

When a Project Trigger starts a new Session, the request that Session receives begins with a Trigger context: block. It contains:

• The starting Trigger's name and ID, its schedule, and which occurrence this Session runs
• The purpose written on the Trigger (Authored purpose, only when present)
• Recent history (Recent occurrences): the last 5 occurrences plus the latest accepted and latest failed ones. Each shows its state (accepted, skipped with a reason, or failed) and a Read: command (chat session show <id> --project ... or chat workflow status <run-id> --project ...)
• Under each accepted Session occurrence, what that Session left behind: the PR or push per repository, Shared Documents it created or updated, Project Asks and their status, child Sessions and their status, and Workflow and Trigger results. When there is none, it says no result observations, Project Asks, or child Sessions recorded

Session-scoped Asks are excluded. With no history, it says No earlier occurrences are recorded for this Trigger. If the block would exceed the request text limit, result lines are dropped and a more Session results omitted ... marker appears; read the earlier Session with its Read: command.

Runtime recovery

When Claude Code or Codex reaches a usage limit, the Session waits for recovery and keeps the same conversation, workspace, and Workflow attempt. Authentication failures also retry automatically; sign in in an external terminal if needed. The next attempt appears in the Session header. Usage-limit delays are 5 minutes, then 15 minutes, then 30 minutes thereafter. Temporary authentication failures during account switching wait 1 minute, then 2 minutes, then 15 minutes, then 30 minutes thereafter. Delays include 0–20% jitter. Automatic retries last at most 6 hours from the first wait in the same recovery episode. No new automatic attempt starts at or after the deadline; work already running is allowed to finish. Changing failure reasons, restarting or reconnecting the runtime, and reclaiming work do not reset the short delays or extend the deadline.

At the deadline, or when the next delay would reach beyond it, the Session enters Waiting for manual retry instead of failing. The conversation, workspace, Session/Attempt, and partial results are kept. Choose Stop to end recovery.

Retry requests one immediate attempt from the saved conversation. It does not reset the 6-hour window, and a failure after the deadline does not restart automatic retries. Repeated clicks or duplicate requests do not start parallel work. Reopening the page only reads its current state. If the device is offline, reconnect the runtime first. A resumed process reads the latest available credentials; the UI does not verify which provider account performed inference.

Billing restrictions and temporary provider rejections require a manual Retry for one attempt. For Codex, this includes structured rate-limit and server-overload errors, and exhausted retries with HTTP 429. No automatic attempt is scheduled for these rejections; Retry continues unfinished work in the same conversation and Workflow attempt. Safety check required means the saved history is unavailable, an operation is unresolved, or its result cannot be confirmed. Retry cannot bypass these conditions or resend the original request. During final wrap-up, Work results are saved; waiting to recover final wrap-up describes the remaining work; it does not declare the Workflow successful.

Related pages

• The agent repo structure, when changes take effect (next session after push), and Runtime defaults: Agents
• Project status and member management: Projects
• Starting from time, document conditions, or an external system: Triggers
• Submitting and recording PRs and pushes: Code Delivery
• Triage when sessions will not start or responses stall: Troubleshooting
• The full command surface: CLI