# MAESTRO タスク実行アーキテクチャ

この文書は、MAESTROでタスク依頼を受け付けてから、Worker、Piece、Movement、LLM、ツール、承認、再試行、通知、UI反映を経て完了するまでの現行処理を示す。機能追加やリファクタリング時の影響確認に使用する。

## 文書の扱い

- 実装を正とし、処理経路を変更したPRではこの文書も更新する。
- 通常経路だけでなく、ASK、承認待ち、サブタスク待ち、再試行、キャンセル、失敗を維持する。
- 図中の名称は主要なファイル、関数、状態名に対応させる。
- 特定機能の将来設計は含めず、現行コードの動作だけを記載する。

## 調査対象コミット

- 基準ブランチ: `origin/main`
- PR #935実装コミット: `a86fea5523d9f8245cd42c53e3c1c167ccb26388`
- 最終照合HEAD: `2ba26737742464f9ef7ccfd4459012e00175fd88`
- 対象変更: PR #935「systemプロンプト静的化 + 動的コンテキスト末尾注入」
- 調査日: 2026-07-24

## 主要な実装境界

| 境界 | 主なファイル・関数 |
|---|---|
| タスク作成 | src/bridge/local-tasks-crud-api.ts |
| コメント・interjection・ASK再開 | src/bridge/local-tasks-comments-api.ts |
| 継続・キャンセル | src/bridge/local-tasks-control-api.ts |
| Tool承認 | src/bridge/local-tasks-tool-requests-api.ts |
| Package承認 | src/bridge/local-tasks-package-requests-api.ts |
| Job永続化・claim・再開 | src/db/repositories/jobs.ts |
| Worker実行・終了処理 | src/worker.ts |
| Piece・Movement制御 | src/engine/piece-runner.ts |
| Agent iteration | src/engine/agent-loop.ts |
| LLM stream | src/engine/agent-loop/llm-iteration.ts、src/engine/llm-stream.ts |
| Tool dispatch | src/engine/agent-loop/tool-dispatcher.ts、tool-execution.ts |
| チャット表示 | ui/src/components/chat/ChatPane.tsx、ChatMessageFeed.tsx |
| 承認UI | ui/src/components/chat/ToolRequestApproval.tsx、PackageRequestApproval.tsx |
| 通知・監査 | src/notifications/*、src/progress/*、ui/src/components/activity/* |

## 1. タスク依頼から完了までの全体フロー

```mermaid
flowchart TD
    U[ユーザー / 外部クライアント]
    UI[React UI<br/>CreateTaskDialog / ChatComposer]
    API_CREATE[POST /api/local/tasks]
    API_COMMENT[POST /api/local/tasks/:id/comments]
    API_CONTINUE[POST /api/local/tasks/:id/continue]
    OTHER[Scheduler / A2A / Reflection / Subtask]

    U --> UI
    UI --> API_CREATE
    UI --> API_COMMENT
    UI --> API_CONTINUE

    API_CREATE --> VALIDATE[入力・可視性・Space・LLM選択・添付検証]
    VALIDATE --> CLASSIFY[Piece選択 / Grounded固定 / LLM Router]
    CLASSIFY --> TASKDB[(local_tasks / comments)]
    CLASSIFY --> WORKSPACE[Space解決<br/>persistent/ephemeral workspace・runtime dir]
    WORKSPACE --> JOBDB[(jobs: queued)]

    API_COMMENT --> WRITE_GATE[Task write gate]
    WRITE_GATE --> PREV{最新Job状態}
    PREV -->|running / dispatching / waiting_subtasks| INTERJECT[interjection comment保存<br/>既存Jobへ次iterationで投入]
    PREV -->|tool/package approval待ち| CONFLICT[409: 承認を先に要求]
    PREV -->|queued / retry| REUSE[既存pending Jobを再利用]
    PREV -->|ASK待ち・終端・Jobなし| FOLLOWUP[resumeMovement/askCount継承<br/>Job作成]
    REUSE --> JOBDB
    FOLLOWUP --> JOBDB

    API_CONTINUE --> CONTINUE_GATE[所有権・Piece存在・前Job終端確認]
    CONTINUE_GATE --> HANDOFF[continuedFromJobIdとhandoff comment<br/>新Jobは transcript replay で前会話を引き継ぐ]
    HANDOFF --> JOBDB

    OTHER --> JOBDB

    JOBDB --> POLL[Worker.processNext polling]
    POLL --> CLAIM[retry期限優先→queued<br/>worker/model/profile適合<br/>issue lockなし]
    CLAIM --> RUNNING[原子的にstatus=running<br/>worker_id設定]
    RUNNING --> EXEC[Worker.executeJob]

    EXEC --> PREP[workspace / reporter / Space / Piece / model / MCP / browser / context準備]
    PREP --> RUNPIECE[runPiece]
    RUNPIECE --> MOVEMENT[Movement loop]
    MOVEMENT --> RESULT{PieceRunResult}

    RESULT -->|completed| SUCCESS[succeeded<br/>workspace commit・最終結果]
    RESULT -->|waiting_human: ASK| ASKWAIT[waiting_human<br/>回答コメントで再開]
    RESULT -->|waiting_human: tool_request| TOOLWAIT[waiting_human<br/>承認APIで再開]
    RESULT -->|waiting_human: package_request| PKGWAIT[waiting_human<br/>承認・install後に再開]
    RESULT -->|waiting_subtasks| SUBWAIT[子Job完了待ち<br/>全完了で親queued]
    RESULT -->|cancelled| CANCELLED[cancelled<br/>子Job取消]
    RESULT -->|error / aborted| RETRY{再試行可能か}
    RETRY -->|yes| RETRYDB[retry + next_retry_at]
    RETRY -->|fatal / 上限| FAILED[failed]

    ASKWAIT --> API_COMMENT
    TOOLWAIT --> APPROVE_TOOL[tool request decide API]
    APPROVE_TOOL -->|approve/deny| JOBDB
    PKGWAIT --> APPROVE_PKG[package request decide API]
    APPROVE_PKG -->|approve/deny| JOBDB
    SUBWAIT --> JOBDB
    RETRYDB --> POLL

    SUCCESS --> EVENTS[Audit / events.jsonl / activity / metrics]
    ASKWAIT --> EVENTS
    TOOLWAIT --> EVENTS
    PKGWAIT --> EVENTS
    SUBWAIT --> EVENTS
    CANCELLED --> EVENTS
    FAILED --> EVENTS
    EVENTS --> NOTIFY[Push / Webhook / Notification projection]
    EVENTS --> UIREFRESH[REST polling + SSE stream]
    UIREFRESH --> UI
```

## 2. WorkerとPiece実行

```mermaid
flowchart TD
    A[Worker.processNext]
    A --> B[claimNextRetryJob または claimNextJob]
    B --> C[runJobTracked]
    C --> D[executeJob]
    D --> E[issue lock取得 / running監査 / Push]
    E --> F{Reflection Jobか}
    F -->|yes| FR[Reflection専用経路]
    F -->|no| G[prepareJobWorkspace]
    G --> H[Space・folderContext・runtimeDir解決]
    H --> I[Piece読込・定義検証]
    I --> J{worker/model適合}
    J -->|不一致| JQ[queuedへ戻す]
    J -->|適合| K{required MCP tokenあり}
    K -->|不足| KH[waiting_human: mcp_auth_required]
    K -->|OK| L[LLM client生成]
    L --> M[Tool Policy・SSH・grant・package解決]
    M --> N[Mission / conversation / provenance / browser / skill context]
    N --> O[runPiece]
    O --> P[EventLogger・Conversation・ContextManager初期化]
    P --> P2{continuedFromJobIdあり<br/>= Continue経由}
    P2 -->|yes| REPLAY[transcript.jsonl を loadFrom → allReplayableThreads<br/>全スレッドを古い順に連結（system行が境界）<br/>掃除はスレッド毎・重複call_idは付け替え<br/>transition保持は最終スレッドかつ同一pieceのときだけ<br/>seedContinuation で新会話の頭に再生]
    P2 -->|no| Q
    REPLAY --> Q[開始Movement選択<br/>resume > override > piece start]
    Q --> R[loop/revisit/cancel guard]
    R --> S[prepareMovementContext]
    S --> T[executeMovement]
    T --> U[MovementResult mapping]
    U --> V{next}
    V -->|別Movement| Q
    V -->|COMPLETE / ASK / WAIT / ABORT| W[PieceRunResult]
    W --> X[handlePieceResult]
    X --> Y[DB状態・コメント・監査・通知・親子Job処理]
    Y --> Z[heartbeat/guard停止・metrics・unlock]
```

`prepareMovementContext`では、Workspace Tool Policyを唯一のtool/edit/SSH権限源とし、タスク内承認済みtoolをunionする。task instructionへ、Movement feedback、follow-up notice、subtask resume notice、checklist、lessonsを加える。

transcript（`runs/{taskId}/transcript.jsonl`）はタスクのruntime directoryに置く正規化された会話記録で、通常はturnを追記し、Continuation seedやprompt guardによる整形時には全体を再構築する。**transcript replayが走るのはContinue経由（`continuedFromJobId`あり）のみ**。コメントやASK回答による新Jobではreplayせず、コメント文脈をtask instructionへ含める。この場合に再利用可能なのは条件が一致する静的接頭辞までで、実際の再利用量は保証しない。replayの整形規則は`Conversation.replayableTurns`を参照。

## 3. Movement・LLM・ツール内部

```mermaid
flowchart TD
    M0[executeMovement] --> M1[prepareMovement]
    M1 --> TOOLS[getToolDefs + complete<br/>遷移先があるPieceではtransitionも追加]
    M1 --> STATIC[static preamble構築<br/>AGENTS・Memory・Skills・tool説明]
    M1 --> DYNAMIC[dynamic context構築<br/>時刻・files・Mission・handoff・console]
    M1 --> GUIDE[Movement guidance + task instruction]
    M1 --> SEED[プロンプト要素をConversationへ順序どおり配置]
    STATIC --> SEED
    DYNAMIC --> SEED
    GUIDE --> SEED
    SEED --> DCFG{delegate許可かつ<br/>再帰深度上限未満}
    DCFG -->|yes| DINJECT[runDelegateをtoolCtxへ注入]
    DCFG -->|no| LOOP[iteration loop]
    DINJECT --> LOOP
    TOOLS --> REQUEST[LLM request入力<br/>toolsはConversationの外で保持]

    LOOP --> CANCEL{cancel/deadline signal}
    CANCEL -->|yes| MCANCEL[cancel result]
    CANCEL -->|no| INJECT[未処理interjectionをuser messageへ追加]
    INJECT --> WATCH[watchdog / loop guard]
    WATCH --> PGUARD[prompt guard<br/>estimate・dedup・compact・summarize]
    PGUARD -->|overflow復旧不能| ABORT[context overflow result]
    PGUARD -->|変更あり| REWRITE[Conversation.rewrite<br/>正規化後transcriptを再構築]
    PGUARD -->|変更なし| LLM[runLlmIteration]
    REWRITE --> LLM
    REQUEST --> LLM
    LLM --> CLIENT_GUARD[LLM client側の<br/>最終token上限検査]
    CLIENT_GUARD --> STREAM[OpenAI-compatible streaming<br/>text/tool deltas/usage/retry/thinking/backend]
    STREAM --> ERR{LLM error}
    ERR -->|recoverable| LOOP
    ERR -->|terminal| LERR[llm error result]
    ERR -->|no error| CALLS{tool callsあり}

    CALLS -->|なし| TEXT[text-only warning/retry]
    TEXT --> LOOP
    CALLS -->|あり| SPLIT[regular と transition/completeを分類]
    SPLIT --> TLOOP[重複tool loop判定]
    TLOOP -->|上限| TABORT[tool loop abort]
    TLOOP --> DISPATCH[dispatchRegularToolCalls]
    DISPATCH --> PAR{read-only parallel可能か}
    PAR -->|yes| PEXEC[Promise.all]
    PAR -->|no| SEXEC[sequential]
    PEXEC --> TOOL[executeRegularToolCallCached]
    SEXEC --> TOOL
    TOOL --> AUTH[tool存在・引数・権限・sandbox・cache]
    AUTH --> TOOL_KIND{delegateか}
    TOOL_KIND -->|yes| DELEGATE[runDelegateSubAgent<br/>隔離した子ConversationでexecuteMovement]
    TOOL_KIND -->|no| IMPL[各tool execute]
    DELEGATE --> TResult[tool_resultをconversation・UI・eventへ記録]
    IMPL --> TResult

    TResult --> WAIT{待機フラグ}
    WAIT -->|browser| WB[waiting_human]
    WAIT -->|tool request| WT[waiting_human tool_request]
    WAIT -->|package request| WP[waiting_human package_request]
    WAIT -->|subtask| WS[waiting_subtasks]
    WAIT -->|なし| TERM{complete / transition winner}
    TERM -->|complete success + pending child| WS
    TERM -->|complete| COMPLETE[completed / needs_user_input / abort mapping]
    TERM -->|transition valid| TRANS[next Movement]
    TERM -->|invalid| RET[tool_result errorを追加してiteration再試行]
    TERM -->|none| LOOP
```

`tools`はConversationへ格納されない。`prepareMovement`が`messages`と並ぶ別の戻り値として返し、`runLlmIteration`へ渡す。`delegate`は通常tool dispatchの一種だが、実行前に`runDelegate`を`toolCtx`へ注入し、呼び出された場合は隔離した子Conversationで再帰的に`executeMovement`を実行する。

### 3.1 LLMリクエストのキャッシュ境界

PR #935以降は、単にプロンプトの内容を分割するだけでなく、LLMへ渡す`tools`と`messages`の順序を次の形に固定する。図中の「キャッシュ再利用可能」は、同一モデル・同一チャットテンプレート・同一Pieceなど、先行要素がバイト一致し、バックエンド側に対象キャッシュが残っている場合を表す。再利用量そのものを保証するものではない。

```mermaid
flowchart TD
    REGULAR[Workspace Tool Policyで解決した<br/>regular tools] --> TOOLS[tools配列を構築]
    TRANSITION[transition<br/>遷移先がある場合のみ<br/>enumはPiece全体の和集合] --> TOOLS
    COMPLETE[complete] --> TOOLS
    TOOLS --> TOOLS_STABLE[同一Piece内でtools配列を<br/>バイト単位で安定化]

    STATIC[static preamble<br/>共通ルール・tool概要・AGENTS・Memory Index<br/>Skills Index・Working Directory] --> SYSTEM[先頭の単一system message]
    FIRST_GUIDANCE[開始Movement guidance] --> SYSTEM
    SYSTEM --> REPLAY{Continueかつ<br/>再生可能transcriptあり}
    REPLAY -->|yes| PRIOR[過去の非system turnを順番に再生]
    REPLAY -->|no| NO_PRIOR[過去turnなし]
    PRIOR --> USER[末尾の単一user message]
    NO_PRIOR --> USER
    DYNAMIC[dynamic context<br/>日時・Mission・files・console<br/>handoffは再生可能turnがないContinue時のみ] --> USER
    INSTRUCTION[task instruction] --> USER
    USER --> MESSAGES[messages配列完成]

    TOOLS_STABLE --> REQUEST[LLM request]
    MESSAGES --> REQUEST
    TOOLS_STABLE -. キャッシュの先行条件 .-> SYSTEM
    SYSTEM -. 同一なら静的接頭辞を再利用 .-> PRIOR
    PRIOR -. 過去requestと一致する範囲を再利用 .-> USER
    USER -. ここから新規評価 .-> GENERATE[生成開始]
```

実際のメッセージ列は次の形になる。`dynamic context`と`task instruction`は、厳密なrole交互制約を持つモデルでも扱えるよう、別々の`user` messageではなく一つに結合する。

```text
tools = [regular tools..., transition（遷移先がある場合）, complete]

messages = [
  system(static preamble + 開始Movement guidance),
  ...replayable prior turns,                    // Continue時のみ
  user(dynamic context + task instruction),
]
```

Movement 2以降のguidance、interjection、watchdog警告などは、既存会話の末尾へ`user` messageとして追加する。先頭へ挿入しないため、そこまでのキャッシュ済み接頭辞を壊さない。

### 3.2 初回・遷移・再開経路ごとのプロンプト構築

```mermaid
flowchart TD
    START[Job開始] --> KIND{開始・再開の種類}

    KIND -->|新規Job| NEW[Conversation.seed]
    NEW --> NEW_MESSAGES["system: static + 開始guidance<br/>user: dynamic + instruction"]
    NEW_MESSAGES --> NEW_CACHE[過去turnの再利用なし]

    KIND -->|同一Job内のMovement遷移| MOVE[Conversation.enterMovement]
    MOVE --> MOVE_MESSAGES["既存messages末尾へ<br/>user: 次Movement guidance"]
    MOVE_MESSAGES --> MOVE_CACHE["toolsはPiece内で安定<br/>既存prefixをそのまま再利用可能"]

    KIND -->|同一PieceをContinue| SAME[loadFrom → replayableTurns<br/>keepTransitions=true]
    SAME --> SAME_MESSAGES["systemを新しく構築<br/>過去の非system turnを再生<br/>Error回答でないcompleteを除去<br/>handoffを省略して末尾へdynamic + instruction"]
    SAME_MESSAGES --> SAME_CACHE["static・tools・再生turnが一致する範囲を再利用可能"]

    KIND -->|別PieceをContinue| CROSS[loadFrom → replayableTurns<br/>keepTransitions=false]
    CROSS --> CROSS_MESSAGES["旧Pieceのtransitionを除去<br/>新Pieceのsystem・toolsを使用<br/>再生turnがあればhandoffを省略"]
    CROSS_MESSAGES --> CROSS_CACHE["Piece固有のguidance/toolsが変わるため<br/>同一Piece相当の再利用は保証しない"]

    KIND -->|コメント・ASK回答による新Job| COMMENT[transcript replayなし]
    COMMENT --> COMMENT_MESSAGES["system: static + 開始guidance<br/>user: dynamic + コメント文脈を含むinstruction"]
    COMMENT_MESSAGES --> COMMENT_CACHE["条件が一致する静的接頭辞のみ再利用可能<br/>再利用量は保証せず、過去turnも再生しない"]
```

### 3.3 transcript replayの整形

```mermaid
flowchart TD
    LOAD[transcript.jsonlをloadFrom] --> THREAD[system行を境界にスレッド分割<br/>全スレッドを古い順に連結<br/>掃除はスレッド毎・重複call_idは付け替え]
    THREAD --> DROP_SYSTEM[スレッド先頭のsystemを除外]
    DROP_SYSTEM --> COMPLETE_CHECK{assistantにcompleteがあるか}
    COMPLETE_CHECK -->|Errorで始まる結果あり| KEEP_COMPLETE[拒否された中間completeを保持]
    COMPLETE_CHECK -->|結果なし、またはError以外| DROP_COMPLETE[completeを除外]
    DROP_COMPLETE --> DROP_COEMITTED[同じassistant messageで<br/>同時出力されたtransitionも除外]
    COMPLETE_CHECK -->|completeなし| TRANSITION_CHECK{transitionか}
    KEEP_COMPLETE --> TRANSITION_CHECK
    DROP_COEMITTED --> VALIDATE
    TRANSITION_CHECK -->|回答済みtransition かつ keepTransitions=true<br/>（最終スレッドかつ同一PieceのContinue）| KEEP_TRANSITION[call/resultペアを保持]
    TRANSITION_CHECK -->|keepTransitions=false<br/>（別PieceのContinue、および古いスレッドでは一括除去）| DROP_TRANSITION[除外]
    TRANSITION_CHECK -->|通常tool call| KEEP_REGULAR[call/resultペアを保持]
    KEEP_TRANSITION --> VALIDATE[未回答call・孤立result・空assistantを除外]
    DROP_TRANSITION --> VALIDATE
    KEEP_REGULAR --> VALIDATE
    VALIDATE --> SEED_CONTINUATION[seedContinuation]
```

判定基準は厳密には「成功済みか」ではなく、対応するtool resultが`Error`で始まるかである。`Error`回答された`complete`は、その後も会話が続いた中間履歴として保持する。結果がない、または`Error`以外の`complete`は除外し、同じassistant messageで同時出力された`transition`も一緒に除外する。

transcriptはタスクのruntime directoryに置く会話記録で、コメント追いメッセージのJobは新しいスレッド（先頭はsystem）を追記するため複数スレッドが蓄積し得る。replayは蓄積された全スレッドを古い順に連結して使う（`Conversation.allReplayableThreads`。issue #1343。以前は最後の再生可能スレッドだけを採っていたが、質問への回答で前の話が落ちる形で表に出たため既定から外した。経緯は docs/design/2026-07-26-transcript-last-thread-replay.html の冒頭の注記）。掃除（`replayableTurns`）はスレッド毎にかける——まとめてかけると、別スレッドが同じ`tool_call`のidを使い回したときに対応付けが狂い、終了済みの`complete`が生き残る。連結後にスレッドをまたいで重なったidは決定的に付け替える（`gen_call_{n}`はジョブ毎に1番から振り直されるため実際に重なる）。`keepTransitions`は最終スレッドにだけ当てる——その値の元になる`samePieceContinuation`は直前のジョブ1件から決まる判断で、古いスレッドがどのpieceで走ったかは記録に無いため。**最終スレッドが空でない限り**、この形でも連結前より再生量は増える（古いスレッドは以前は捨てていた）。例外は最終スレッドが空のとき——クラッシュや書き込み途中で切れてsystem行しか無いジョブがそれで、以前の`lastReplayableThread`は空スレッドを飛ばして1つ前を採っていたため、そこに`keepTransitions`が当たっていた。いまは1つ前が「古いスレッド」扱いになり遷移が落ちるので、この形では再生量が減る。遷移を落とす向きは安全側なので意図してそのままにしている。通常のturn追加では追記するが、`seedContinuation`と、prompt guardのdedup・compact・summarizeによってmessagesが変わった場合は、`Conversation.rewrite()`でファイル全体を再構築する。

### 3.4 キャッシュを維持するための変更時ルール

| 対象 | 維持すべき条件 | 変更時の影響 |
|---|---|---|
| `tools`配列 | Workspace Tool Policy、task内grant、動的tool module条件が不変なら、同一Piece内で名前、順序、schema、descriptionを安定させる | 1バイトでも変わるとllama.cppで全prompt cache missになり得る |
| transition | 遷移先があるPieceだけ追加し、enumはPiece全体の和集合にする | Movementごとの差分がtools配列に入ると全prompt cache missになり得る |
| static preamble | 日時、Mission、files、handoff、consoleを入れない | Jobごとの差分が先頭に入り、継続時の共有prefixを失う |
| system message | index 0の一つだけにする | 厳格なchat templateで拒否される可能性がある |
| dynamic context | task instructionと一つの末尾`user` messageに結合する | 連続した`user` roleに対応しないモデルで失敗し得る |
| Movement guidance | 2番目以降は会話末尾へ`user`として追記する | 先頭を書き換えると既存prefixを無効化する |
| 同一Piece transition | replay時に回答済みcall/resultを保持する | 中間履歴を削ると、その位置以降のcacheが分岐する |
| Error以外のcomplete | replayから除外し、同時出力transitionも除外する | 再生すると継続Jobが即時完了を模倣する可能性がある |

キャッシュ再利用量は`llm-stream`の`prompt_cache reused=... prompt=... pct=...`ログと、LLMイベントの`cachedPromptTokens`で確認する。構造を変更した場合は、単体テストだけでなく実バックエンドでMovement遷移直後とContinue直後の再利用率を測定する。

## 4. 待機・再開・通知・UI

```mermaid
sequenceDiagram
    participant Agent as Agent Loop
    participant Worker
    participant DB
    participant API
    participant UI as Chat UI
    participant Notify as Push/Webhook/Inbox

    Agent->>Worker: PieceRunResult(waiting_human)
    Worker->>DB: status=waiting_human, waitReason, resumeMovement
    Worker->>Notify: waiting_human event
    UI->>API: task/tool/package request polling
    API->>DB: pending request取得
    API-->>UI: 承認カード / ASK表示

    alt ASK
        UI->>API: POST comment
        API->>DB: resumeMovementとaskCountを継承したJob作成
    else Tool Request
        UI->>API: approve / deny
        API->>DB: grantまたはdeny + parked Jobをqueuedへ戻す
    else Package Request
        UI->>API: approve / deny
        API->>DB: CAS決定、必要なら隔離install、parked Jobをqueuedへ戻す
    end

    DB-->>Worker: 次回pollでclaim
    Worker->>Agent: 同一Movementから再実行
    Agent->>Worker: completed / failed / cancelled
    Worker->>DB: 終端status・comment・audit・event
    Worker->>Notify: succeeded / failed
    DB-->>UI: task/comments/activity更新
```

チャットUIでは `ChatPane → ChatMessageFeed → ChatMessage` が永続コメントを表示し、`ChatComposerPanel`がTool RequestとPackage Requestの承認カードを表示する。`useJobStream`は生成中text、tool call、LLM状態、delegate streamを反映する。Activityは`ActivityTimeline`、短期通知はToast、要対応通知はNotification Bell/Centerが担う。

### 4.1 Auto Prompterの透明性境界

Auto Prompterが有効なJobでは、ツール実行前に固定済みPolicy Snapshotを評価し、追加指示、拒否、引数に結び付いた一回限りの承認を行う。発火結果は許可リスト形式のPolicy Eventとして記録し、チャットへ通知する。無効なJobではこの経路を短絡し、従来のツール実行経路を変えない。

Policy Eventは追跡可能性を支援するbest-effort監査であり、hidden chain-of-thought、生のツール引数、認証情報、prompt全文を保存しない。記録失敗だけを理由にエージェント処理を停止する保証型台帳でもない。

この機構はEU AI Actその他の法令への準拠を自己宣言しない。Article 50だけでchain-of-thought保存や一律5年保持が要求されるとは解釈せず、適用範囲、事業者の役割、保持期間は法務確認の対象とする。保持期間の設定は将来のCompliance Phaseで扱う。詳細は [EU AI Act透明性対応 設計付録](./auto-prompter-eu-ai-act-transparency-design.md) を参照する。

一次資料: [Regulation (EU) 2024/1689](https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng)、[European Commission: AI Act](https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai)