自動セッション継続

[mapserver2007]

precomact検知した時点で自動引き継ぎしたい

[mapserver2007]

Context Budget Red 中断・退避・再開 — 設計検討メモ

作成日: 2026-08-03
対象: agentic-workflow-foundation-kit のセッション管理 / Context Budget Auto-Handoff
ステータス: 設計検討（未実装）

---

TL;DR

要件	現行 kit	設計変更後
Red 到達後に新規チャットを自動で開く	不可（Cmd+N 必須）	依然 不可（Cursor Hook API 制約）
ターン完了まで待ってから Red	現状どおり	guard Hook で 次ツール前に中断可能
Red 直前のタスク退避	AI 任せ（handoff manifest）	Hook による決定論的退避（resume-point）
別チャットで Red 直前から再開	Step 粒度のみ（粗い）	Step 内サブタスク粒度まで可能

---

1. 背景と課題

1.1 現行の引き継ぎフロー

1. AI が [CONTEXT_BUDGET=RED] を出す
2. ユーザーが Cmd+N で新規チャットを開く
3. 新規チャットで短文を 1 通送る
4. session-bootstrap.sh が handoff-{session_id}.md を自動注入
5. 作業再開

参照: docs/CONTEXT_BUDGET.md, .cursor/hooks/README.md

1.2 現行設計の制約

制約	原因
Red 判定がターン末尾	stop Hook のみが Yellow/Red を評価
実行中に Red が出ない	afterShellExecution 等は観測のみ（判定なし）
バックグラウンド自動引き継ぎ不可	sessionStart は新規チャット作成時のみ発火。Hook にチャット起動 API なし
同一セッション継続は禁止	Lost in the Middle 防止（G-SESSION-RED-CONTINUE-001）

1.3 ユーザーが体感する問題

• 重いスキル実行中、最後まで走り切ってから Red 警告が来る
• Red 到達時点の「直前タスク」が構造化されず、再開位置が曖昧
• 新規チャットへの移行は ユーザー操作必須

---

2. 質問別の回答サマリ

2.1 バックグラウンド自動引き継ぎは可能か？

現行 Cursor IDE + kit の Hook だけでは不可。

• handoff 注入ポイントは sessionStart のみ
• stop Hook の followup_message（loop_limit: 5）は同一セッション継続用だが、Red 時は設計上禁止
• Cursor SDK / Cloud Agent による外部オーケストレーションは技術的に可能だが kit 標準外

現実的な緩和策:

• 重い処理を subagent dispatch に委譲（親コンテキスト保護）
• CHECKPOINT / Yellow で handoff 準備を前倒し
• preCompact 経路での途中通知（停止はしない）

2.2 実行途中で Red → ユーザー引き継ぎは可能か？

現行 kit: 不可（proxy Red の場合）。設計変更後: 可能。

中断の実現手段:

Hook	能力
preToolUse	permission: "deny" で次ツールをブロック
beforeShellExecution	同上（シェル特化）
subagentStart	新規 subagent 起動を拒否
preCompact	観測のみ（ブロック不可）

中断タイミング: 「次ツール呼び出しの直前」= 「直前タスク完了直後」。実行中ツールは完了まで待つ。

2.3 Red 直前まで戻して再開は可能か？

設計変更前提なら可能。 ただし「チャット履歴の完全復元」ではなく、決定論的退避 + 構造化再開ポイント として実現する。

再開粒度	実現可能性
ワークフロー Step 単位（Step ③ 途中など）	高
Step 内サブタスク（「7ファイル中3完了、次は auth.ts」）	中〜高
ツール呼び出し単位（中断シェルの続き）	低
会話 transcript の完全再現	不可

---

3. 現行 kit の再開資産（既存）

3.1 workflow-orchestrator

Red 時の定義:

• 即時中断 → タスクレポート最新化 → handoff manifest 書き出し
• 新ステップに進まない
• 未完了チェックは [ ] 維持、再開ポイントをレポート + handoff に記録

参照: .cursor/skills/workflow-orchestrator/SKILL.md

3.2 step envelope

• 終端状態: complete / incomplete / blocked / fatal
• incomplete / blocked / fatal は再開入力として保持
• パス: .cursor/.artifacts/{slug}--step{N}.md

参照: .cursor/skills/workflow-orchestrator/references/worker-dispatch.md

3.3 その他の退避機構

ファイル	役割
.cursor/.tracking/tracker-{session_id}.md	セッション追跡（キャンペーン SoT へのポインタ含む）
.cursor/.session/handoff-{session_id}.md	handoff manifest
.cursor/.session/pre-compact-{session_id}.md	compact 直前スナップショット
.cursor/.session/{session_id}.turns.jsonl	会話ログ（参照用、先頭 1000B/ターン）
docs/agent-tasks/reports/{report}.md	キャンペーン進行 SoT

3.4 足りないもの

1. Red 検知がターン末尾（guard Hook 未実装）
2. 退避が AI 任せ（劣化 AI が manifest を書くリスク）
3. 再開粒度が Step 止まり（Step 内進捗が弱い）

---

4. 提案アーキテクチャ（設計変更後）

4.1 目標フロー

[各ツール実行]
  → postToolUse Hook → resume-point 更新（決定論的）

[次ツール要求 + Red 閾値超過]
  → preToolUse guard → deny（中断）
  → guard が red-checkpoint + handoff 骨格を書く
  → stop Hook → Red followup_message
  → ユーザーに Cmd+N 案内

[新規チャット + 短文]
  → sessionStart → bootstrap
  → handoff + resume-point を additional_context 注入
  → orchestrator が resume-point から再開

4.2 新規コンポーネント

A. session-budget-guard.sh

登録先: preToolUse, beforeShellExecution, subagentStart

レベル	動作
Yellow	user_message のみ（継続可）
Red	次ツールを deny → agent loop 終了

Red 検知時に AI より先に 以下を書く:

• handoff-{session_id}.md（骨格 + resume-point ポインタ）
• red-checkpoint-{session_id}.json（中断瞬間の immutable snapshot）
• step envelope status: incomplete（workflow 再開用）

B. session-resume-tracker.sh

登録先: postToolUse, afterShellExecution

毎ツール完了後にローリング更新:

.cursor/.session/resume-point-{campaign_slug}.json

resume-point スキーマ（案）:

{
  "campaign_slug": "fix-auth-bug",
  "orig_session_id": "abc-123",
  "interrupted_at_unix": 1754234567,
  "trigger": "red_guard",
  "workflow_step": "step3",
  "orchestrator_phase": "implementation",
  "last_completed": {
    "tool": "Shell",
    "summary": "bin/quality-gate test (partial PASS)",
    "artifact_refs": [".cursor/.artifacts/fix-auth--step3.md"]
  },
  "next_action": {
    "description": "残り2テストファイルの修正",
    "inputs_to_read": [
      "docs/agent-tasks/reports/fix-auth.md",
      "src/auth.ts"
    ]
  },
  "git_snapshot": {
    "base_commit_sha": "...",
    "changed_files": ["src/auth.ts"]
  },
  "todo_progress": {
    "done": 3,
    "total": 7,
    "current_item": "tests/auth.test.ts"
  }
}

SoT 原則: tracker / task report = キャンペーン SoT。resume-point = 「最後に安全完了した地点」の機械記録。

C. handoff manifest 拡張

manifest.yaml > framework.handoff.manifest_required_sections に追加:

• 中断位置（Step / sub-step / ファイル / todo index）
• 完了済み作業（再実行不要リスト）
• 次に実行するアクション（1件）
• resume-point 参照

recovery_constraints に追加:

• 「完了済み作業」に列挙された項目は再実行しない
• 「次に実行するアクション」のみを最初の作業とする

D. bootstrap 注入拡張

session-bootstrap.sh が handoff に加え resume-point を additional_context に注入。

再開プロンプト例:

[CONTEXT_BUDGET_RESUME] campaign=fix-auth-bug, step=step3, resume from todo 4/7.
Read resume-point JSON + step envelope + task report.
Do NOT redo items in completed_work.

E. orchestrator 再開プロトocol 拡張

resume-point の状態	再開動作
workflow_step: step3 + envelope incomplete	Step ③ worker を同一入力 + resume-point で再 dispatch
sub-step 情報あり	worker prompt に resume_from を明示
envelope なし + resume-point のみ	親が resume-point から envelope を生成してから dispatch
実行中 subagent 中断	subagentStop で envelope 書き出し後、親が incomplete として再開

---

5. 再開精度と設計判断

5.1 ワークフロー Step 内再開（推奨・第一実装）

十分実用的。orchestrator + step envelope + task report で足りる。

• Red 前: postToolUse が resume-point を更新
• Red 後: 新チャットで「Step ③ の todo 4/7 から再開」

5.2 非 orchestrator の重いスキル（deep-thinking 等）

各スキルに checkpoint 契約を追加:

checkpoint:
  artifact: ".cursor/.artifacts/{slug}--checkpoint.md"
  update: "各 subagent 完了後"
  resume: "checkpoint を読んで中断フェーズから再開"

deep-thinking は A/B 並列のため、「Round 0 完了 → Red → 新チャットで Round 1 から」が現実的粒度。

5.3 実行中シェル / バックグラウンド subagent

ケース	対応
実行中シェル	完了を待つ → 結果を resume-point に記録 → 次ツールで deny
is_background: true subagent	subagentStart deny + 実行中は subagentStop で envelope 化
長時間 subagent	Step 開始前に Yellow で区切る（予防）

---

6. 実現できない部分（設計上の上限）

1. 中断されたコマンドの途中状態復元（プロセス / トランザクション / 未保存バッファ）
2. 旧チャットの in-context 履歴の完全復元（新セッションは外部化 artifact のみ）
3. ユーザー操作なしの新規チャット起動（Cmd+N + 短文は引き続き必要）
4. 100% 自動の「何を再実行しないか」判定（git diff + completed_work + 人間確認のハイブリッドが現実的）

---

7. 実装ロードマップ

Phase	内容	主な変更先	効果
P0	session-budget-guard.sh（Red deny）	hooks.json, manifest, templates	ターン末尾待ちを解消
P1	postToolUse による resume-point ローリング更新	新 Hook + state スキーマ	決定論的退避
P2	Red 時の red-checkpoint + handoff 骨格自動生成	guard Hook + manifest sections	AI 劣化に非依存の復旧
P3	bootstrap + orchestrator の Step 内再開	bootstrap.sh, workflow-orchestrator	「直前まで戻る」UX
P4	重いスキル各自の checkpoint 契約	deep-thinking 等 SKILL.md	非 orchestrator への拡張

変更経路: manifest.yaml / templates を編集 → bin/foundation-gate generate → 生成物を直接編集しない。

---

8. 関連ファイル（SoT 参照）

種類	パス
利用者ガイド	docs/CONTEXT_BUDGET.md
実装詳細	docs/references/context-budget-internals.md
Hook 技術詳細	.cursor/hooks/README.md
Hook 登録	.cursor/hooks.json
handoff 設定 SoT	manifest.yaml > framework.handoff
閾値 SoT	manifest.yaml > framework.budget_thresholds
orchestrator 再開	.cursor/skills/workflow-orchestrator/SKILL.md
worker 契約	.cursor/skills/workflow-orchestrator/references/worker-dispatch.md
統一設計書	.cursor/docs/AI_AGENT_UNIFIED_DESIGN.md
Cursor Hooks 公式	https://cursor.com/docs/hooks

---

9. 設計原則（変更後も維持）

1. tracker / task report がキャンペーン SoT — handoff / resume-point はポインタ + 揮発情報
2. Red 後の同一セッション新規実装は禁止 — fresh context への移行が目的
3. 退避は Hook で決定論的に — 劣化 AI への依存を最小化
4. 再開は「次にやる 1 件事前」 — transcript 復元ではない
5. fail_open デフォルト — guard Hook 障害でエージェント全停止しない（セキュリティ系を除く）

---

10. 未決事項（ADR 検討候補）

• campaign_slug の解決方法（task report パス vs tracker ポインタ vs 環境変数）
• resume-point と session_id tracker の責務境界
• guard Hook の fail 戦略（fail_open vs fail_closed）
• 8192 bytes 注入上限と resume-point の分割注入
• Phase 2 Cursor API（preCompact followup_message）との統合タイミング