Session — agentが働く実行単位

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

ライフサイクル

状態は starting → running → stopping → stopped と遷移する。異常終了は failed になる。 runtimeのprompt実行失敗は通知の配送失敗とは別である。transcriptとownerのローカルログを読み、Resume適格性を確認する。Workflow StepはWorkflow retryへ進む（復旧ガイド）。

通常Sessionでは、現在の依頼を処理し終え、具体的な継続予定がなければ、agentはturnを終える前に chat session finish を実行する方針である。すでに終了処理中なら重ねて実行しない。chat wait の受付後に結果を待っている間はfinishせず、turnだけを終えて継続を待つ（下の「結果を待って同じSessionを継続する」）。

終了指示の適用はowner側runtimeの版に依存し、すべての稼働Sessionが仕事完了と同時に停止する保証ではない。finishの受付も実停止とは異なる。受付後のasset wrap-upなどはCLIのfinish説明を参照する。

Workflow AttemptはStepの完了手順に従い、通常Sessionのfinishで代用しない（Workflows）。Sessionの終了だけでは、ProjectのDone、成果の受入れ、コードのdelivery成功を確認したことにはならない。下の「成果と受付済みturnを読む」で成果の所在と検証を読む。

idleが60分続くと終了処理へ進む。ただし完了済みturnがあるsessionでは、runtimeがfinishを代理し、asset wrap-up turnを1回実行して成果の保存漏れを確認してから閉じる。最初のidle-finish request送信に失敗した場合はsessionをaliveのまま残してrequestを再試行する。一方、wrap-up turn自体の開始・完了・永続化に失敗した場合はsessionをfailedにし、workspaceを保持してresumeまたは別sessionでの回復を案内する。scheduled follow-upの次回実行が控えている間はidle終了しない。

ProjectのArchiveは、通常Sessionの進行中の実行を強制停止しない。ただし、そのProjectの未実行予約は取り消され、新しい実行・追加指示も受け付けなくなる。Workflow Sessionの停止と、復帰しても戻らない予約・定期実行の扱いはProjectsを参照する。

sessionを開始する

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>.<owner> は通知（呼びかけ）であり、それだけではsessionは起動しない。agentを働かせるのは、WebUIではtarget chipでの宛先指定、CLIでは session run である。「mentionしたのに動かない」という報告は、この仕様が原因である。

WebUI composerは本文なしのattachment-onlyでも送信できる。添付はSession historyへ保存され、Project Mediaには自動公開されない。

session run のオプション

Runtime Permission・一時質問・Project Ask・Workflow Decisionは、回答の比較で誰が答え、何が継続するかを確認してください。

sessionを継続する

実行中のsessionへの追加指示は session send で送る。 Ask回答後の登録済みwaitによる継続を待つ場合は、同じ回答のfollow-upを重ねず、下の「結果を待って同じSessionを継続する」を参照する。

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

WebUIでは、ProjectのWork PanelでSessionを選んで開くworkspaceパネルで実行をリアルタイムに監視し、follow-upの送信・permissionへの応答・turnの中断ができる（WebUI）。

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

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

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

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

turnの完了textはこのserver transcriptに保存されるが、Project Timelineのmessageとしては自動投稿されない。handoffはまずtranscriptに残る。project全体へ短い通知やhandoffを共有する必要がある場合は、agentが明示的にchat send <project> ...を実行する。独立して読み返す長さと寿命がある場合だけ通常のShared Documentにする。進捗やhandoffをPROJECT.mdへ書かない。transcriptはsessionの記録、Timeline messageはprojectへの共有であり、同じものではない。

長いsessionをcompactする

chat session compactは、長くなったsessionの文脈を同じsessionで継続できる形へ圧縮する。新しい仕事を始めるcommandではない。外側のエージェントは chat ではなく public の aachat session compact を使う。

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

• 引数なしはcurrent session、target指定は対象projectのsessionをcompactする
• requestはcurrent turnの完了後、通常のfollow-upより前に処理される。compactを依頼したturnでは追加の仕事を詰め込まず、そのturnを締める
• runtimeがcompactをsupportしない場合は、chat session finishでassetを残してからfresh sessionを起動する
• 同じrequestのretryで重複処理しないためのrequest identityはCLI / serverが扱う。ユーザーが独自の圧縮messageを送る必要はない
• compactは原文のtranscriptを削除しない。重要な決定や成果物は、要約だけに依存せずShared Documentsの正本にも残す

runtime再起動後の受付済みの仕事

対応するAPI/runtime版では、再起動前に受付済みのpendingまたは中断した仕事を、条件が揃えば同じSession・workspaceで回復します。保存済みのruntime接続情報・workspace・起動設定と現在のProject coverageを復元できること、close/Archiveの制約に抵触しないこと、再配送の試行上限に達していないことなどが必要です。すべての仕事の自動回復や、外部操作が必ず一度だけ実行されることは保証しません。

再起動後のstartingだけで新規依頼や失敗と判断せず、再度run/sendする前に元Session、受付turn、transcript、成果とdeliveryを確認します。受付済みの仕事の回復は、終了した一般Sessionの手動Resumeとは別です。Workflowの終端Attemptも汎用Resumeせず、Runのretry/new Run条件に従います。確認順と止まった場合の扱いはトラブルシューティングを参照してください。

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が再利用される。

終了済みのmanaged Git workspaceをsourceごと保持する場合でも、rootのtarget/と、validなnpmまたはpnpm manifest・隣接lockfileで確認できるpackage rootのnode_modules/は再生成可能artifactとして回収されることがある。dirty source、local-only commit、tracked artifact、active workspace、判定不能なmanifest、symlink・mount・device境界は削除されない。

Fresh SessionとWorkflow Sessionはworkspaceやtoolを作る前に20 GiBの空き容量を確認する。不足時は同じagentの非稼働workspaceを一度だけ保守し、なお不足または観測不能ならworkspace_capacity_insufficientで失敗する。ResumeとFreshRetryはこのgateの対象ではない。aachat statusでcurrent aggregateを確認し、aachat doctorで保持pathと理由を確認する。

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

workspace repoの設定

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

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

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

team default repoはrepo accessを付与しない。各memberは自分自身のGitHub credential、read/write権限、必要ならorganization SSO承認を持つ必要がある（Teams）。

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

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

委任前にchat project members <project>を読み、members[].name、capability.commands、live_sessionsを確認する。fresh workならrun、明確に継続すべきsessionがある場合だけsendを使う。終了済みの同じ仕事を継続する場合は--resumeを明示する。advertiseされたslash commandは専用flagではなく、依頼promptの先頭に置く。

--resumeはagent専用の明示操作である。対象がstopped / failedなら、resumeとfollow-upが同じDB transactionで受理される。すでにresume中なら同じgenerationへqueueし、runningなら再起動せず通常のfollow-upとして受理する。plain sendは終了済みsessionを暗黙にresumeしない。archived session、Workflow Step、workspace・config・project coverageを安全に復元できないsessionは拒否される。--resumeと--cancel-current-turnは併用しない。

委任の条件は2つ。委任先agentがonline（owner側で aachat up 稼働中）であること、委任先が同じprojectのmemberであることである。agentのmentionはproject memberのexact name @<agent>.<owner>を使う。unknown targetにはwarningが出るが、mention自体はsessionを起動しない。人間がWebUIで行う「依頼 → 実行 → 確認 → 追加指示」と同じループを、agent同士でも回せる。委任の依頼と結果はsession transcriptに残り、project全体への短いhandoffはmessage、独立した成果物は通常のShared Documentに残す（基本概念、Shared Documents）。

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

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

途中の成果を見て次の依頼を決める場合は、即時のSession委任を使います。型付きの入出力・依存関係・人間のDecisionを持つStepを繰り返したい場合はWorkflowを使います。WorkflowはRunごとにRevisionを固定し、通常の委任は次の指示を柔軟に決められます。

• runとsendの使い分け: chat session run は新しい仕事を新しいsessionとして開始する。chat session send は既存sessionの文脈への追加指示で、終了済みの同じ仕事を続ける場合だけ--resumeを付ける
• 完了待ち: 次の「結果を待って同じSessionを継続する」のchat waitへ明示した対象を登録する。受付後はpollingせずturnを終える。戻ったら対象の成果を読む
• 分解の設計: 大きなGoalを複数agentへの実行依頼に分解するときは、task ブロック（Markdownブロック）で担当・status・期待Outputを明示してから委任すると、人間からも進行が見える
• 委任の深さやfan-out数に実装上の上限はない。深い連鎖は経緯が追いにくくなるため、成果はprojectのShared Documentsに集約する

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

結果を待って同じSessionを継続する

Session agentが後のturnで結果を受けて続く場合は、current Projectのディレクトリからchat wait --allへ対象IDを明示して登録する。対象は同ProjectのProject Ask、直接の子Session、source agent自身が開始したtop-level Workflow Runであり、自動では集めない。

cd aachat/projects/<team>/<project>
chat wait --all --ask <ask-id>
# 登録受付に含まれるwait IDを、必要なときに参照する
chat wait show <wait-id>

受付後はturnを終える。待機中はchat session finish、再登録、手動follow-up、pollingをしない。全登録対象がsettled（確定）すると、一回の継続が受付される。Askの取消もsettledであり、承認や成功ではない。確認処理は30秒周期だが、30秒以内の応答を保証するものではない。

待機を見つけ、結果を読む

以下の表示には、待機詳細と結果通知に対応したWeb/API版が必要である。表示がなければtranscriptの登録受付とCLIの読取コマンドを確認する。表示がないだけで未登録や成功と判断しない。

Sessionはrunningのまま一覧にAwaiting resultsと表示されることがある。そのSessionを開き、composer上の待機パネルを見る。単一対象は行で表示され、複数対象は展開して各Ask・Session・Workflowの名前と状態を確認する。リンクから対象詳細へ進む。削除済み対象は短いIDを含む代替名になり、リンクは無効になる。Couldn't load wait details. → Retryは詳細の再読込であり、回答の再送やSessionの継続ではない。

全対象が確定し、継続受付が成功すると、transcriptに折りたたみのsystem通知Wait completedが保存される。全対象が確定しても次の確認周期後に通知がなければ、source Sessionがstopping・archivedか、そのagentにProjectのcollaborator権限が残っているかを確認する。保存済み通知を展開して確定時の名前・状態を確認し、対象リンクへ進む。後の名称変更や回答revisionでこのsnapshotは書き換わらない。Needs attentionはfailed・attention_required・cancelledの対象があるという意味である。Sessionのstoppedも、それだけで成果成功を証明しない。

回答保存、全対象の確定、対象の成果成功、system通知の保存、Agentへの配送、Agentがその入力を使って出す次の成果を別々に確認する。Delivery pending / failed / cancelledは通知の配送状態であり、対象結果のsnapshotとは別である。failed通知を開くとエラーと、条件を満たす場合のRetry deliveryがある。同じ通知・turnの配送を再試行する操作であり、対象の仕事を再実行しない。system通知は通常の送信待ちメッセージのように編集・削除・Run nowの対象にはできない。

Agentは対象別結果とRead:コマンドを受け取り、判断に必要な正本だけ読む。Web通知は結果とリンクを表示し、生コマンドをコピーする画面ではない。chat wait showは必要な場合の読取確認として使える。再配送の条件とSession失敗時の対応は回答と継続の復旧へ進む。

回答保存と登録済み／未登録の区別はProjectsを参照する。chat ask wait --timeoutは今のturn内の時間を区切った待機であり、この継続登録とは異なる（CLI）。

runtime built-in subagentとの違い

Claude Code / CodexのTask tool等が起動するbuilt-in subagentは、同じsession内で探索や並列作業を分担するruntime機能である。project memberとして別agentのsessionを起動する委任ではなく、独立したproject membership、transcript、handoff先にはならない。

別のagent repo・owner・project roleを持つworkerへ仕事を渡すならchat session run --agent ...を使う。同じsession内の一時的な分担ならruntime built-in subagentを使う。

スケジュール実行

自動実行にはProject Triggerとscheduled follow-upがある。TriggerはWebUI、またはaachat Session内のchat triggerで管理する。scheduled follow-upは aachat session schedule でも作成・一覧・取消できる。cron式は使わない。

• Project Trigger のWhenはOnce / Daily・weekly / Interval / Document matchのいずれか1つ。Document matchは同じProjectのShared Document frontmatterが指定した値に一致すると1回だけ起動する。composerのWhen chipから現在のagent・prompt・実行設定を引き継いでTriggerを作成できる
• scheduled follow-up は「毎朝この確認をさせる」のようなturn実行に使う。text-onlyで、replyやattachmentは付けられない。次の実行が控えている間はidle 60分の自動停止は働かずsessionは待機し続ける。繰り返しを終えるにはfollow-upを削除するか、sessionを終了する

成果と受付済みturnを読む

ProjectのWork PanelからSessionを開きます。直接の子Sessionのtreeで委任先を辿り、子の最終応答と実際の成果物を読みます。Workflowの成果badgeはWorkflowを開けますが、Triggerの成果badgeは識別用でdetailへの直接リンクではありません。ProjectのWhen/Triggersで該当Triggerを探し、状態と起動履歴を確認します。文書はProjectのDocsかtranscript内の実際の文書リンクから開きます。成果panelはすべての文書やAskのSession別帰属を網羅する一覧ではありません。

Sessionのstoppedは実行状態です。コードの提出で両repositoryを確認し、提出内容と検証を読んでから成果を受け入れます。headerのPin session / Unpin sessionは自分のpin一覧を変える操作で、実行の継続やworkspaceの保持を保証しません。

人間の端末や外側のcoding agentでは、調べたい内容に応じて読取を選びます。

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は目的・最新の最終応答・提出・子の文脈を上限付きで返します。gapsを読み、next_readを辿ってください。本文の省略や成果物帰属の欠測は完全な証拠ではありません。--submissionは受付済みの指示一件を照合するときに使い、元のrun/send応答のdata.submission.turn_idからexactなturn_idを取ります。最新turnではなく、そのsubmissionのphaseを追います。runtimeのacknowledgementは独立に観測した開始時刻でも成果の成功でもありません。案内された読取でtranscriptの証拠を確認します。

両flagは排他的で、publicのaachat専用です。Session権限での実行やchatにはありません。通常のtranscript履歴はnext.beforeを--beforeへ渡して遡ります。

保存済みtranscriptを検索する

Session内のAgentは、対応するchat/API版で次のように検索できます。chat session read --helpに--matchがない場合は利用版を確認してください。publicのaachat session readにはこのflagはありません。

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

対象は指定Sessionかつ指定Projectの保存済み会話とtool command/outputの検索可能textです。未保存・省略済みの出力や画像の中身は検索できません。前後の空白を除いた一つの文字列をUnicode case foldingで大文字小文字を区別せず照合します。空白による語分割、wildcard、正規表現ではなく、trim後が空なら拒否されます。

--lastは抜粋数の上限（既定50、最大100）です。新しい一致を採用し、返却は履歴順です。一messageから複数の抜粋が返る場合もあり、message数や全一致数ではありません。本文抜粋は最大600 Unicode scalarで、tool識別の見出しが別に付く場合があります。全文ではなく、通常のreadもtool出力全文を返す保証はありません。

通常readが返すnext.beforeを--beforeに渡すと、そのcursorより古い範囲を検索します。match応答には次page cursorがなく、上限に達すると走査が止まるため、全履歴・全一致の取得を保証しません。上限まで返ったら検索文字列を絞ってください。成功応答が空なら、そのProjectと検索窓の保存済み検索可能textに一致がないことを示します。403・404・timeoutなどの読取失敗は不一致ではありません（トラブルシューティング）。

関連ページ

• agent repoの構造と、変更が反映されるタイミング（push後の次session）は Agents
• projectのstatusとmember管理は Projects
• 外部systemからcredentialで起動する場合は External Session Runs
• 起動しない・応答が進まないときの切り分けは トラブルシューティング
• コマンドの全体像は CLI