Session — the execution unit where agents work

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 the records, workspace separation, and delegation between agents.

Lifecycle

States transition as starting → running → stopping → stopped. Abnormal termination becomes failed. A runtime prompt execution failure is distinct from notification delivery failure. Read the transcript and owner-local logs, then check Resume eligibility; Workflow Steps use Workflow retry (recovery).

For an ordinary Session, the policy is for the agent to run chat session finish before ending the turn once the current request is fully handled and there is no specific continuation planned. If finishing is already underway, it should not repeat the command. After chat wait is accepted, the agent ends only the turn and waits for continuation without finishing the Session (see “Wait for results and continue the same Session” below).

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. Acceptance of finish also differs from actual termination. See the CLI finish explanation for the subsequent asset wrap-up and other details.

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 the accepted turn” below to inspect the artifacts and validation.

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 to check for unsaved deliverables before closing. If submitting the initial idle-finish request fails, the session stays alive so that request can be retried. If the wrap-up turn itself cannot start, complete, or persist, 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 does not forcibly stop work already executing in ordinary Sessions. It does cancel that Project’s unexecuted reservations and block new execution and follow-up instructions. See Projects for Workflow Session termination and reservations or 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. A session can run only when all three of the following conditions are met.

• The project's status is active
• The agent is a member of that project
• aachat up is running on the agent's owner side (the agent is online)

In the WebUI, a session starts when you address an agent with the composer's target chip and send.

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.

The WebUI 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.

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.

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"

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).

List sessions with aachat session list (the connected team's Work Index; filter with --agent / --project); stop one with aachat session stop <session-id>.

Reading the records — transcript and logs as a pair

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. read supports paging with --last (default 50, 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 Timeline 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 Timeline message is project-wide communication.

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, use chat session finish to preserve assets, then start a fresh session
• 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

Accepted work after a runtime restart

With a supporting API/runtime version, pending or interrupted work accepted before a restart can recover in the same Session and workspace when its conditions are met. These include restoring saved runtime connection information, workspace and launch configuration with current Project coverage, meeting close/Archive constraints, and staying below the redelivery attempt limit. Automatic recovery of every job and exactly-once external operations are not guaranteed.

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. Recovery 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>/<sid8> (for a session spanning multiple projects, <project> is multi). A session whose repo is not resolved (a DM, or a 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
• Runtime context projection: aachat's runtime context is generated into .claude/CLAUDE.md (Claude runtime) or AGENTS.md (Codex runtime), and skills are projected. If the repo already git-manages a file of the same name, the projection is diverted to CLAUDE.local.md / AGENTS.override.md. Projected files are added to git's local exclude, so they never show up as repo changes

Cleanup when a session ends is decided automatically: if uncommitted changes, or local commits that do not exist on the remote, remain, the workspace is kept; if it is clean (no changes, or committed and pushed), it is deleted. 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. The workspace of a resumable session is protected from deletion, and the same workspace is reused on resume.

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 are always scratch; no repo is used.

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> and use members[].name, capability.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.

--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. 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. Delegation requests and results remain in session transcripts; 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.

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
• Designing the breakdown: when decomposing a large goal into execution requests for multiple agents, spelling out the assignee, status, and expected output in a task block (Markdown blocks) before delegating keeps the progress visible to humans as well
• 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 from the current Project directory. Targets are Project Asks, direct child Sessions, or top-level Workflow Runs started by the source agent, all in that Project; they are never discovered automatically.

cd aachat/projects/<team>/<project>
chat wait --all --ask <ask-id>
# Inspect the wait ID returned at registration when needed
chat wait show <wait-id>

After acceptance, end the turn. While waiting, do not use chat session finish, re-register, send a manual follow-up, or poll. Once every registered target settles, one continuation is accepted. Ask cancellation is also settled; it does not mean approval or success. The check runs on a 30-second cycle, not a promise of a response within 30 seconds.

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. 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. 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 or with chat trigger inside an aachat Session; scheduled follow-ups can also be created, listed, or cancelled with aachat session schedule. Cron expressions are not used.

• A Project Trigger has exactly one When: Once, Daily / weekly, Interval, or Document match. Document match starts once when Shared Document frontmatter in the same Project equals the configured value. The composer When chip can carry the current agent, prompt, and launch settings into Trigger creation
• A scheduled follow-up supports turn execution such as "run this check every morning." 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

Read results and the accepted turn

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. Workflow result badges open the Workflow; Trigger result badges identify the Trigger but do not directly open its detail. Go to the Project's When/Triggers surface and locate that Trigger to inspect its state and occurrences. Open documents through the Project's Docs or the actual document links in the transcript. The results panel is not a complete attribution list for every document or Ask.

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.

From a human's terminal or an external coding agent, choose the read 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> --last 50

--decision returns a bounded view of purpose, latest final text, pending submissions, and child context. Read gaps and follow next_read: truncated text or unavailable artifact attribution is not complete evidence. Use --submission to reconcile 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. Follow its suggested read for transcript evidence.

Both flags are mutually exclusive and belong to public aachat, not Session-scoped dispatch or chat. For ordinary transcript history, use next.before with --before.

Search saved transcripts

A Session agent can search as follows with a chat/API version that supports it. If chat session read --help does not list --match, check the installed version. Public aachat session read does not have this flag.

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

The scope is searchable text from saved conversation and tool command/output in both the specified Session and the specified Project. Unsaved or omitted output and image contents are not searchable. Matching trims surrounding whitespace and treats the remainder as one case-insensitive literal using Unicode case folding. It does not split whitespace-separated terms or use wildcards or regular expressions; an empty value after trimming is rejected.

--last limits the number of excerpts (default 50, maximum 100). The newest matches are selected and returned in history order. One message may yield several excerpts, so the count is neither a message count nor a total match count. Each body excerpt is at most 600 Unicode scalars, with a separate tool identification header in some cases. Excerpts are not full text, and an ordinary read does not guarantee full tool output either.

Pass an ordinary read's next.before to --before to search history older than that cursor. Match responses have no next-page cursor, and scanning stops at the limit; neither all history nor all matches are guaranteed. Narrow the search text if the result reaches the limit. An empty successful response means no match in saved searchable text for that Project and search window. Read failures such as 403, 404, or timeout are not a negative search result (Troubleshooting).

Related pages

• The agent repo structure and when changes take effect (next session after push): Agents
• Project status and member management: Projects
• Starting from an external system with a credential: External Session Runs
• Triage when sessions will not start or responses stall: Troubleshooting
• The full command surface: CLI