Claude Agent SDK セッション管理実践ガイド — fork・resume・rewindで「巻き戻せるAIエージェント」を作る

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

// Phase 1: read-onlyで分析
for await (const message of query({
  prompt: "認証モジュールのセキュリティ問題を分析して。修正はまだしないで",
  options: {
    cwd: "/path/to/project",
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  if (message.type === "system" && message.subtype === "init") {
    sessionId = message.session_id;
  }
  if ("result" in message) {
    console.log("分析結果:", message.result);
  }
}

// ユーザーに確認を求める
const approved = await askUserConfirmation("この修正方針で進めますか？");

if (approved && sessionId) {
  // Phase 2: resumeでwrite権限付きで再開
  for await (const message of query({
    prompt: "先ほど特定した問題を修正して",
    options: {
      resume: sessionId,
      allowedTools: ["Read", "Edit", "Write", "Bash"],
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message) {
      console.log("修正完了:", message.result);
    }
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
import { execSync } from "child_process";

const projectDir = "/path/to/project";
let mainSessionId: string | undefined;

// メインセッションでコードを分析
for await (const message of query({
  prompt: "このプロジェクトの認証ロジックを分析して、リファクタリング方針を提案して",
  options: {
    cwd: projectDir,
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  if (message.type === "system" && message.subtype === "init") {
    mainSessionId = message.session_id;
  }
}

// forkしてリファクタリングを試行
let forkSucceeded = false;
if (mainSessionId) {
  for await (const message of query({
    prompt: "提案した方針に基づいてリファクタリングを実行して",
    options: {
      resume: mainSessionId,
      forkSession: true,  // 元セッションを保護
      cwd: projectDir,
      allowedTools: ["Read", "Edit", "Write", "Bash"],
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message) {
      // ビルドで検証
      try {
        execSync("npm run build", { cwd: projectDir, stdio: "pipe" });
        execSync("npm test", { cwd: projectDir, stdio: "pipe" });
        forkSucceeded = true;
        console.log("リファクタリング成功 — 変更を採用");
      } catch {
        console.log("ビルド/テスト失敗 — 変更を破棄");
        execSync("git checkout .", { cwd: projectDir });
      }
    }
  }
}

if (!forkSucceeded) {
  // 元のセッションは無傷なので、別のアプローチを試せる
  console.log("元のセッションから別の方針で再試行可能");
}

import { query } from "@anthropic-ai/claude-agent-sdk";

const queryInstance = query({
  prompt: "テストカバレッジを向上させるためにテストファイルを追加して",
  options: {
    cwd: "/path/to/project",
    allowedTools: ["Read", "Edit", "Write"],
    permissionMode: "acceptEdits",
    enableFileCheckpointing: true,  // チェックポイントを有効化
  },
});

for await (const message of queryInstance) {
  if ("result" in message) {
    // ビルドで検証
    try {
      execSync("npm test", { cwd: "/path/to/project", stdio: "pipe" });
      console.log("テスト追加成功");
    } catch {
      // 失敗時はrewindで復元（userMessageIdを指定して任意の時点に戻せる）
      await queryInstance.rewindFiles(userMessageId);
      console.log("ファイルを変更前の状態に復元しました");
    }
  }
}

for await (const message of query({
  prompt: `ファイルの変更はすべてEditツールを使って行うこと。
echoリダイレクトやsedコマンドでのファイル書き換えは禁止。
タスク: CSSモジュールをTailwindに移行して`,
  options: {
    enableFileCheckpointing: true,
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"],
    // Bashを除外してEditツール使用を強制する方法もある
  },
})) {
  // ...
}

import { query } from "@anthropic-ai/claude-agent-sdk";
import { execSync } from "child_process";

const projectDir = "/path/to/project";
let baseSessionId: string | undefined;

// ベースセッションで分析
for await (const message of query({
  prompt: "パフォーマンスのボトルネックを特定して、2つの改善方針を提案して",
  options: {
    cwd: projectDir,
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  if (message.type === "system" && message.subtype === "init") {
    baseSessionId = message.session_id;
  }
}

if (!baseSessionId) throw new Error("セッションID取得失敗");

// アプローチA: キャッシュ戦略で改善
const tryApproach = async (approach: string, label: string) => {
  // git stashで作業ディレクトリをクリーンに保つ
  execSync("git stash", { cwd: projectDir });
  
  for await (const message of query({
    prompt: `方針「${approach}」で実装して`,
    options: {
      resume: baseSessionId,
      forkSession: true,
      cwd: projectDir,
      allowedTools: ["Read", "Edit", "Write", "Bash"],
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message) {
      try {
        execSync("npm run build", { cwd: projectDir, stdio: "pipe" });
        const testOutput = execSync("npm test -- --reporter=json", {
          cwd: projectDir,
          encoding: "utf-8",
        });
        return { label, success: true, result: testOutput };
      } catch (e) {
        return { label, success: false, result: String(e) };
      } finally {
        execSync("git checkout .", { cwd: projectDir });
        execSync("git stash pop", { cwd: projectDir });
      }
    }
  }
  return { label, success: false, result: "no result" };
};

const resultA = await tryApproach("キャッシュ層の追加", "A");
const resultB = await tryApproach("クエリの最適化", "B");

// 結果を比較して採用
const winner = resultA.success && !resultB.success ? resultA
  : !resultA.success && resultB.success ? resultB
  : resultA; // 両方成功なら任意の基準で選択

console.log(`採用: アプローチ ${winner.label}`);

import { query } from "@anthropic-ai/claude-agent-sdk";
import Database from "better-sqlite3";

const db = new Database("./sessions.db");
db.exec(`CREATE TABLE IF NOT EXISTS agent_sessions (
  task_id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  status TEXT DEFAULT 'running'
)`);

async function startOrResume(taskId: string, prompt: string) {
  const row = db.prepare(
    "SELECT session_id FROM agent_sessions WHERE task_id = ? AND status = 'running'"
  ).get(taskId) as { session_id: string } | undefined;

  const options = row
    ? { resume: row.session_id, allowedTools: ["Read", "Edit", "Write", "Bash"] as const }
    : { allowedTools: ["Read", "Edit", "Write", "Bash"] as const };

  for await (const message of query({ prompt, options })) {
    if (message.type === "system" && message.subtype === "init") {
      db.prepare(
        "INSERT OR REPLACE INTO agent_sessions (task_id, session_id, status) VALUES (?, ?, 'running')"
      ).run(taskId, message.session_id);
    }
    if ("result" in message) {
      db.prepare(
        "UPDATE agent_sessions SET status = 'completed' WHERE task_id = ?"
      ).run(taskId);
      return message.result;
    }
  }
}