Session — agentが働く実行単位

sessionはagentが実際に働く実行単位である。ユーザーまたは別のagentが依頼を出すとsessionが起動し、agentはownerのマシン上のcoding agentの上で動く（trust-boundary.md）。このページはsessionのライフサイクル、操作、記録の読み方、workspaceの分離、agent間の委任を示す。

ライフサイクル

状態は starting → running → stopping → stopped と遷移する。異常終了は failed になる。idleが60分続くと自動停止する。

sessionを開始する

bash

aachat session run <agent> --project <project> "依頼内容"

agentは指定したprojectのmemberとして解決される。sessionを実行できる条件は次の3つがすべて満たされていることである。

projectのstatusが active である
agentがそのprojectのmemberである
agentのowner側で aachat up が稼働している（agentがonline）

WebUIでは、composerの target chip でagentを宛先に指定して送信するとsessionが起動する。

@mentionはsessionの実行トリガーではない。 メッセージ本文の @<agent> は通知（呼びかけ）であり、それだけではsessionは起動しない。agentを働かせるのは、WebUIではtarget chipでの宛先指定、CLIでは session run である。「mentionしたのに動かない」という報告は、この仕様が原因である。

`session run` のオプション

オプション	意味
`--repo <owner/repo>`	このsessionのworkspace repositoryを上書きする
`--mode <MODE>`	このsessionのACP launch mode（例: `bypassPermissions`）
`--attach <PATH>`	画像・動画・PDFを添付する。添付先はSession historyであり、Project Mediaには公開されない
`--stdin`	依頼文をstdinから読む（message引数と排他）

sessionを継続する

実行中のsessionへの追加指示は session send で送る。

bash

aachat session send <session-id> --project <project> "追加指示"

オプション	意味
`--cancel-current-turn`	実行中のturnを中断してから、このメッセージを実行する
`--attach <PATH>`	`run` と同じ。Session history行きで、Project Media非公開
`--stdin`	メッセージをstdinから読む

WebUIでは、Timelineのsessionカードから開くworkspaceパネルで実行をリアルタイムに監視し、follow-upの送信・permissionへの応答・turnの中断ができる（webui.md）。

sessionの一覧は aachat session list（--agent / --project で絞り込み）、停止は aachat session stop <session-id> で行う。

記録を読む — transcriptとログの対

sessionの記録は2種類あり、内容と保存場所が異なる。対で使い分ける。

コマンド	読むもの	保存場所
`aachat session read <session-id> --project <project>`	会話のtranscript（依頼・応答・経過）	server
`aachat session logs <session-id>`	runtimeのstderrログ（起動・実行エラー）	ローカル（`~/aachat/.run/logs/`）

会話の内容と成果を確認するなら read、起動失敗や実行エラーの原因を調べるなら logs を使う。read は --last（既定50・最大100）と --before でページングできる。logs は --from-start で先頭から読める。

workspaceの分離と作られ方

sessionごとに独立したworkspaceが ~/aachat/.run/workspaces/<agent>--<sid8>（sid8はsession IDの先頭8文字）に作られる。session開始時にruntimeが次の内容を準備する。

workspace repo: repoが解決されたsessionでは、そのrepoがworkspaceのrootにcheckoutされる。branchはaachat管理の aachat-sessions/<project>/<agent>/<sid8>（複数projectをまたぐsessionは <project> が multi）。repoが解決されないsession（DM、repo未設定のteam）はrepoなしの空workspace（scratch）になる
agent repo: agent自身のrepoが aachat/agents/<agent名>/ にworktreeとして展開される。sessionからは環境変数 AA_AGENT_DIR でこの場所を参照できる
runtime文脈の投影: .claude/CLAUDE.md（Claude runtime）または AGENTS.md（Codex runtime）にaachatのruntime contextが生成され、skillが投影される。repoが同名ファイルを既にgit管理している場合は CLAUDE.local.md / AGENTS.override.md に退避される。投影物はgitのローカルexcludeに入り、repoの変更としては見えない

sessionが終わったときの後始末は自動で判定される: 未コミットの変更、またはremoteに存在しないローカルコミットが残っていればworkspaceは保持され、クリーン（変更なし、またはコミット済みかつpush済み）なら削除される。この保持判定はgit workspaceにのみ適用される。repoなしのscratch workspaceは中身に関係なくsession終了時に削除されるため、残したい成果物はShared Documents・media等のprojectサーフェスに置いてからsessionを終える。resume可能なsessionのworkspaceは削除対象から保護され、resume時は同じworkspaceが再利用される。

1つのsessionのworkspace repoは1つ。複数のrepoにまたがる仕事は、repoごとのsessionに分けてprojectレベルで調整する。同じrepoに対して複数のsessionが並行して走っても、それぞれが独立したworkspaceで作業するため、作業中のファイルが直接衝突することはない。変更の統合はgit / PRの通常フローで行う。

workspace repoの設定

repoの解決順は sessionでの指定 > projectの設定 > teamのデフォルト である。

設定場所	設定方法
session（1回限りの上書き）	CLI `session run --repo <owner/repo>`、WebUIはcomposerの Repo chip
projectの設定	projectの設定で repository（`owner/repo`）とworking branchを指定する
teamのデフォルト	team作成時（WebUI「Create Team」/ `aachat team create --repo`）またはteam設定のrepositoryで指定する

sessionでの上書きは、projectの設定またはteamのデフォルトのどちらかと一致している必要がある。一致しない owner/repo は拒否される（任意のrepoを指せる仕組みではない）。DMのsessionは常にscratchで、repoは使われない。

なおWebUIサイドバーの「Repository」ツリー（GitHub App接続）はこの設定とは別系統である（webui.md）。aachat init のrepo接続（connected-repo.md）もworkspace repoの設定ではない。

委任 — agentが別のagentのsessionを動かす

session内で動いているagentは、chat コマンドで別のagentのsessionを起動・監視・継続できる。chat はsession内のagent専用であり、session外（人間・外部agent）は aachat を使う。

操作	コマンド
別agentのsessionを起動する	`chat session run --agent <agent> --project <project> "依頼内容"`
経過・結果を読む	`chat session read <session-id> --project <project>`
追加指示を送る	`chat session send <session-id> --project <project> "追加指示"`

委任の条件は2つ。委任先agentがonline（owner側で aachat up 稼働中）であること、委任先が同じprojectのmemberであることである。人間がWebUIで行う「依頼 → 実行 → 確認 → 追加指示」と同じループを、agent同士でも回せる。引き継ぎの成果物はShared Documentsに残す（concepts.md、shared-documents.md）。

委任で起動されたsessionには、起動元のsession（source session）との系譜（lineage）が記録される。どの依頼からどのsessionが生まれたかを後から辿れるため、agent間で仕事が渡っても経緯は追跡できる。

オーケストレーションのパターン

複数agentの協働は、この委任コマンドの組み合わせで実現する。専用のオーケストレーション機構は別にない。

runとsendの使い分け: chat session run は新しい仕事を新しいsessionとして開始する（相手のsessionが動いている必要はない）。chat session send は既に実行中のsessionへの追加指示専用で、停止済みのsessionには送れない
完了待ち: blockする待機コマンドはない。orchestrator役のagentは chat session read <session-id> でworkerのtranscriptを読み、進捗・完了を確認する
分解の設計: 大きなGoalを複数agentへの実行依頼に分解するときは、task ブロック（markdown-blocks.md）で担当・status・期待Outputを明示してから委任すると、人間からも進行が見える
委任の深さやfan-out数に実装上の上限はない。深い連鎖は経緯が追いにくくなるため、成果はprojectのShared Documentsに集約する

人間がWebUIから複数agentを動かす場合、composerの宛先（target chip）は1メッセージにつき1 agentである。複数agentへは依頼を分けて送るか、orchestrator役のagentに委任を任せる。

スケジュール実行

sessionの自動実行には2つの独立した機構がある。どちらもWebUIから設定し、CLIには設定コマンドがない。cron式はなく、時刻・間隔・条件で指定する。

機構	対象	繰り返し	設定場所
scheduled start（run trigger）	新しいsessionを条件成立時に起動	なし（1回限り）	composerの When chip（「後で始める」）
scheduled follow-up	実行中・待機中のsessionへfollow-up turnを送る	あり（1分〜1日の間隔）	sessionスレッドcomposerの Schedule ボタン

scheduled start の条件は2種類: 指定時刻になったら（After）、または指定した共有ドキュメントのフィールドが指定値に一致したら（DocumentMatch。例: あるdocのstatusが approved になったら起動）。条件なしの即時開始は通常の session run を使う
scheduled follow-up は「毎朝この確認をさせる」のような繰り返しのturn実行に使う。次の実行が控えている間は、idle 60分の自動停止は働かずsessionは待機し続ける。繰り返しを終えるにはfollow-upを削除するか、sessionを終了する