@jjlabsio/claude-crew 0.1.45 → 0.1.47

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "claude-crew",
       "source": "./",
       "description": "오케스트레이터 + PM, 플래너, 개발, QA, 마케팅 에이전트 팀으로 단일 제품의 개발과 마케팅을 통합 관리",
-      "version": "0.1.45",
+      "version": "0.1.47",
       "author": {
         "name": "Jaejin Song",
         "email": "wowlxx28@gmail.com"
@@ -28,5 +28,5 @@
       "category": "workflow"
     }
   ],
-  "version": "0.1.45"
+  "version": "0.1.47"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crew",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": {
     "name": "Jaejin Song",

package/hooks/hooks.json

@@ -5,6 +5,11 @@
       {
         "matcher": "*",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/crew-session-restore.mjs\"",
+            "timeout": 5
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/setup-hud.mjs\"",
@@ -13,6 +18,30 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/crew-pre-compact.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/crew-context-guard-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Agent|Task",

package/lib/crew-state.mjs

@@ -0,0 +1,72 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+
+const STATE_VERSION = 1;
+const CURRENT_RUN_FILE = "current-run.json";
+
+export function currentRunPath(crewDir) {
+  return join(crewDir, "state", CURRENT_RUN_FILE);
+}
+
+export function checkpointsDir(crewDir) {
+  return join(crewDir, "state", "checkpoints");
+}
+
+export async function readRunState(crewDir) {
+  const path = currentRunPath(crewDir);
+  if (!existsSync(path)) return null;
+
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    throw new Error(`Failed to read crew run state at ${path}: ${error.message}`);
+  }
+}
+
+export async function writeRunState(crewDir, state) {
+  const stateDir = join(crewDir, "state");
+  await mkdir(stateDir, { recursive: true });
+
+  const nextState = {
+    ...state,
+    version: state.version ?? STATE_VERSION,
+    lastUpdatedAt: new Date().toISOString()
+  };
+
+  const destination = currentRunPath(crewDir);
+  const tempPath = join(
+    stateDir,
+    `.${CURRENT_RUN_FILE}.${process.pid}.${Date.now()}.tmp`
+  );
+
+  await writeFile(tempPath, `${JSON.stringify(nextState, null, 2)}\n`, "utf8");
+  await rename(tempPath, destination);
+  return nextState;
+}
+
+export async function createCheckpoint(crewDir) {
+  const state = await readRunState(crewDir);
+  if (!state) return null;
+
+  const dir = checkpointsDir(crewDir);
+  await mkdir(dir, { recursive: true });
+
+  const timestamp = new Date().toISOString().replace(/:/g, "-");
+  const checkpointPath = join(dir, `checkpoint-${timestamp}.json`);
+  await writeFile(checkpointPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  return checkpointPath;
+}
+
+export async function getLatestCheckpoint(crewDir) {
+  const dir = checkpointsDir(crewDir);
+  if (!existsSync(dir)) return null;
+
+  const { readdir } = await import("node:fs/promises");
+  const files = (await readdir(dir))
+    .filter((file) => /^checkpoint-.+\.json$/.test(file))
+    .sort((a, b) => a.localeCompare(b));
+
+  if (files.length === 0) return null;
+  return join(dir, basename(files.at(-1)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jjlabsio/claude-crew",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": "Jaejin Song <wowlxx28@gmail.com>",
   "license": "MIT",
@@ -19,6 +19,7 @@
     ".claude-plugin/",
     "agents/",
     "data/",
+    "lib/",
     "skills/",
     "hooks/",
     "hud/",

package/scripts/crew-context-guard-stop.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const BYPASS_REASONS = [
+  "context_limit",
+  "context_window",
+  "context_full",
+  "max_tokens",
+  "conversation_too_long",
+  "abort",
+  "cancel",
+  "interrupt",
+  "auth"
+];
+
+async function readStdin(timeoutMs = 3000) {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data || null), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data || null);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+  });
+}
+
+function pass() {
+  return { continue: true };
+}
+
+function sessionId(event) {
+  return String(event.session_id || event.sessionId || event.session?.id || "unknown")
+    .replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+function reasonText(event) {
+  return [
+    event.stop_reason,
+    event.stopReason,
+    event.reason,
+    event.error,
+    event.message
+  ].filter(Boolean).join(" ").toLowerCase();
+}
+
+function shouldBypass(event) {
+  const text = reasonText(event);
+  return BYPASS_REASONS.some((reason) => text.includes(reason));
+}
+
+function collectUsage(value, found = { inputTokens: null, contextWindow: null }) {
+  if (!value || typeof value !== "object") return found;
+
+  for (const [key, nested] of Object.entries(value)) {
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (
+      ["inputtokens", "inputtoken", "tokensinput", "totalinputtokens"].includes(normalized)
+      && Number.isFinite(Number(nested))
+    ) {
+      found.inputTokens = Math.max(found.inputTokens ?? 0, Number(nested));
+    }
+    if (
+      ["contextwindow", "contextwindowsize", "contextlimit", "maxcontexttokens"].includes(normalized)
+      && Number.isFinite(Number(nested))
+    ) {
+      found.contextWindow = Math.max(found.contextWindow ?? 0, Number(nested));
+    }
+    collectUsage(nested, found);
+  }
+
+  return found;
+}
+
+function parseUsageFromText(text) {
+  const inputMatches = [...text.matchAll(/"?(?:input_tokens|inputTokens|inputToken|total_input_tokens)"?\s*[:=]\s*(\d+)/gi)];
+  const windowMatches = [...text.matchAll(/"?(?:context_window|contextWindow|context_limit|max_context_tokens)"?\s*[:=]\s*(\d+)/gi)];
+
+  return {
+    inputTokens: inputMatches.length > 0 ? Math.max(...inputMatches.map((match) => Number(match[1]))) : null,
+    contextWindow: windowMatches.length > 0 ? Math.max(...windowMatches.map((match) => Number(match[1]))) : null
+  };
+}
+
+async function usageFromTranscript(event) {
+  const transcriptPath = event.transcript_path || event.transcriptPath;
+  if (!transcriptPath || !existsSync(transcriptPath)) {
+    return { inputTokens: null, contextWindow: null };
+  }
+
+  try {
+    const text = await readFile(transcriptPath, "utf8");
+    return parseUsageFromText(text.slice(-128 * 1024));
+  } catch {
+    return { inputTokens: null, contextWindow: null };
+  }
+}
+
+async function usageFor(event) {
+  const fromEvent = collectUsage(event);
+  const fromTranscript = await usageFromTranscript(event);
+  return {
+    inputTokens: fromEvent.inputTokens ?? fromTranscript.inputTokens,
+    contextWindow: fromEvent.contextWindow ?? fromTranscript.contextWindow
+  };
+}
+
+function counterPath(id) {
+  return join(tmpdir(), `crew-stop-guard-${id}.json`);
+}
+
+async function readCount(id) {
+  const path = counterPath(id);
+  if (!existsSync(path)) return 0;
+  try {
+    const payload = JSON.parse(await readFile(path, "utf8"));
+    return Number(payload.count) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function writeCount(id, count) {
+  await writeFile(
+    counterPath(id),
+    `${JSON.stringify({ count, updatedAt: new Date().toISOString() }, null, 2)}\n`,
+    "utf8"
+  );
+}
+
+function blockMessage(percent) {
+  return [
+    "Crew context guard: this session appears to be near the context window.",
+    `Estimated usage: ${Math.round(percent)}%.`,
+    "Run /compact before continuing so the crew workflow can checkpoint and preserve pending role, artifacts, and resume handles."
+  ].join("\n");
+}
+
+async function main() {
+  const raw = await readStdin();
+  if (!raw) {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  let event;
+  try { event = JSON.parse(raw); } catch {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  if (shouldBypass(event)) {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  const { inputTokens, contextWindow } = await usageFor(event);
+  if (!inputTokens || !contextWindow) {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  const percent = (inputTokens / contextWindow) * 100;
+  if (percent < 75 || percent >= 95) {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  const id = sessionId(event);
+  const count = await readCount(id);
+  if (count >= 2) {
+    console.log(JSON.stringify(pass()));
+    return;
+  }
+
+  await writeCount(id, count + 1);
+  const message = blockMessage(percent);
+  console.log(JSON.stringify({
+    continue: true,
+    decision: "block",
+    reason: message,
+    systemMessage: message,
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: message
+    }
+  }));
+}
+
+main();

package/scripts/crew-pre-compact.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { relative, resolve } from "node:path";
+
+import { createCheckpoint, readRunState } from "../lib/crew-state.mjs";
+
+async function readStdin(timeoutMs = 3000) {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolveInput) => {
+    let data = "";
+    const timer = setTimeout(() => resolveInput(data || null), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolveInput(data || null);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolveInput(null);
+    });
+  });
+}
+
+function emptyResponse() {
+  return { continue: true };
+}
+
+function hookResponse(message) {
+  return {
+    continue: true,
+    systemMessage: message,
+    hookSpecificOutput: {
+      hookEventName: "PreCompact",
+      additionalContext: message
+    }
+  };
+}
+
+function formatPath(cwd, path) {
+  if (!path) return null;
+  if (!path.startsWith("/")) return path;
+  return relative(cwd, path) || ".";
+}
+
+function pendingText(state) {
+  return state.pendingStatus || state.pending || "none";
+}
+
+function buildMessage({ state, checkpointPath, cwd }) {
+  const artifacts = Array.isArray(state.artifactPaths) ? state.artifactPaths : [];
+  const handles = state.agentHandles && typeof state.agentHandles === "object"
+    ? Object.entries(state.agentHandles)
+    : [];
+
+  return [
+    "# Crew PreCompact Checkpoint",
+    "",
+    `Workflow: ${state.workflow || "unknown"}`,
+    `Phase: ${state.phase || "unknown"}`,
+    `Task: ${state.taskFile || state.taskId || "unknown"}`,
+    `Active role: ${state.activeRole || "unknown"}`,
+    `Pending: ${pendingText(state)}`,
+    `Checkpoint: ${formatPath(cwd, checkpointPath)}`,
+    "Artifacts:",
+    ...(artifacts.length > 0 ? artifacts.map((path) => `- ${path}`) : ["- none"]),
+    "Resume handles:",
+    ...(handles.length > 0 ? handles.map(([role, handle]) => `- ${role}: ${handle}`) : ["- none"]),
+    "",
+    "After compaction, inspect the checkpoint and continue from the pending phase unless the user's newest request overrides it."
+  ].join("\n");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let event = {};
+  if (raw) {
+    try { event = JSON.parse(raw); } catch { /* ignore */ }
+  }
+
+  const cwd = resolve(event.cwd || process.cwd());
+  const crewDir = resolve(cwd, ".crew");
+
+  try {
+    const state = await readRunState(crewDir);
+    if (!state) {
+      console.log(JSON.stringify(emptyResponse()));
+      return;
+    }
+
+    const checkpointPath = await createCheckpoint(crewDir);
+    console.log(JSON.stringify(hookResponse(buildMessage({ state, checkpointPath, cwd }))));
+  } catch (error) {
+    console.log(JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PreCompact",
+        additionalContext: `CREW checkpoint failed: ${error.message}`
+      }
+    }));
+  }
+}
+
+main();

package/scripts/crew-session-restore.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+
+import { getLatestCheckpoint, readRunState } from "../lib/crew-state.mjs";
+
+async function readStdin(timeoutMs = 3000) {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolveInput) => {
+    let data = "";
+    const timer = setTimeout(() => resolveInput(data || null), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolveInput(data || null);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolveInput(null);
+    });
+  });
+}
+
+function emptyResponse() {
+  return { continue: true };
+}
+
+function hookResponse(message) {
+  return {
+    continue: true,
+    systemMessage: message,
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: message
+    }
+  };
+}
+
+function formatPath(cwd, path) {
+  if (!path) return null;
+  if (!path.startsWith("/")) return path;
+  return relative(cwd, path) || ".";
+}
+
+function pendingText(state) {
+  return state.pendingStatus || state.pending || "none";
+}
+
+function lastArtifact(state) {
+  if (state.pendingAgentResultPath) return state.pendingAgentResultPath;
+  if (Array.isArray(state.artifactPaths) && state.artifactPaths.length > 0) {
+    return state.artifactPaths.at(-1);
+  }
+  return "none";
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function findActiveState(crewDir) {
+  const current = await readRunState(crewDir);
+  if (current?.active) {
+    return { state: current, checkpointPath: await getLatestCheckpoint(crewDir) };
+  }
+
+  const checkpointPath = await getLatestCheckpoint(crewDir);
+  if (!checkpointPath || !existsSync(checkpointPath)) return null;
+
+  const checkpoint = await readJson(checkpointPath);
+  if (!checkpoint?.active) return null;
+  return { state: checkpoint, checkpointPath };
+}
+
+function buildMessage({ state, checkpointPath, cwd }) {
+  const checkpointLine = checkpointPath
+    ? formatPath(cwd, checkpointPath)
+    : "none";
+
+  return [
+    "<crew-session-restore>",
+    "Active crew workflow detected.",
+    "",
+    `Workflow: ${state.workflow || "unknown"}`,
+    `Phase: ${state.phase || "unknown"}`,
+    `Task: ${state.taskFile || state.taskId || "unknown"}`,
+    `Pending: ${pendingText(state)}`,
+    `Last artifact: ${lastArtifact(state)}`,
+    `Checkpoint: ${checkpointLine}`,
+    "",
+    "Treat this as prior-session context. Prioritize the user's newest request. Resume the crew workflow only if the user asks to continue.",
+    "</crew-session-restore>"
+  ].join("\n");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let event = {};
+  if (raw) {
+    try { event = JSON.parse(raw); } catch { /* ignore */ }
+  }
+
+  const cwd = resolve(event.cwd || process.cwd());
+  const crewDir = resolve(cwd, ".crew");
+
+  try {
+    const active = await findActiveState(crewDir);
+    if (!active) {
+      console.log(JSON.stringify(emptyResponse()));
+      return;
+    }
+
+    console.log(JSON.stringify(hookResponse(buildMessage({ ...active, cwd }))));
+  } catch (error) {
+    console.log(JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: `CREW restore failed: ${error.message}`
+      }
+    }));
+  }
+}
+
+main();

package/scripts/setup-hud.mjs

@@ -11,6 +11,7 @@ import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { PLUGIN_ROOT } from './lib/pluginRoot.mjs';
 
 // ---------------------------------------------------------------------------
 // Read stdin (with timeout)
@@ -33,6 +34,39 @@ function gitExec(cmd, cwd) {
   } catch { return null; }
 }
 
+function readPluginVersion() {
+  const packageJson = JSON.parse(readFileSync(join(PLUGIN_ROOT, 'package.json'), 'utf-8'));
+  return packageJson.version;
+}
+
+function updatePluginRootCache(pluginRoot) {
+  try {
+    const crewDir = join(homedir(), '.claude', 'crew');
+    const cachePath = join(crewDir, 'plugin-root.json');
+
+    let shouldWrite = !existsSync(cachePath);
+    if (!shouldWrite) {
+      try {
+        const current = JSON.parse(readFileSync(cachePath, 'utf-8'));
+        shouldWrite = current.pluginRoot !== pluginRoot;
+      } catch {
+        shouldWrite = true;
+      }
+    }
+
+    if (!shouldWrite) return;
+
+    mkdirSync(crewDir, { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({
+      pluginRoot,
+      version: readPluginVersion(),
+      updatedAt: new Date().toISOString(),
+    }, null, 2));
+  } catch {
+    // Best-effort cache for runner fallback. HUD setup must continue on failure.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -74,6 +108,8 @@ async function main() {
       writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
     }
 
+    updatePluginRootCache(pluginRoot);
+
     console.log(JSON.stringify({ continue: true }));
   } catch (e) {
     console.log(JSON.stringify({

package/skills/crew-agent-runner/SKILL.md

@@ -7,20 +7,33 @@ description: 모든 crew 에이전트 dispatch의 중앙 규약 — provider별
 
 crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구현하지 않고 이 중앙 규약을 따른다. 본 스킬은 prepare, resolve, dispatch, resume, followup 주입, retry/fallback/escalate 판단의 공통 표면을 정의한다.
 
-설치 후 drift 차단용 pre-commit hook은 `node scripts/crew-agent-runner.mjs install-hooks`로 설치한다.
+설치 후 drift 차단용 pre-commit hook은 `node "$CREW_ROOT/scripts/crew-agent-runner.mjs" install-hooks`로 설치한다.
 (plugin 개발자 전용 — 사용자는 호출하지 않습니다. build/validate는 plugin source repo의 drift 차단 도구입니다.)
 
 ## Dispatch 절차
 
 업무 스킬(crew-plan/crew-interview/crew-dev)이 role을 실행해야 할 때 본 절차를 따른다.
 
+### Step 0. Runner 경로 결정
+
+오케스트레이터는 runner 호출 전에 plugin root를 결정하고, 결정된 경로를 `CREW_ROOT`로 사용한다.
+
+Fallback 체인 (순서 중요):
+
+1. `$CLAUDE_PLUGIN_ROOT`가 있으면 사용한다. 정상 Claude Code plugin 환경이므로 추가 검증하지 않는다.
+2. `~/.claude/crew/plugin-root.json`의 `pluginRoot`를 읽는다. 해당 경로에 `scripts/crew-agent-runner.mjs`가 존재하면 사용하고, 없으면 다음 fallback으로 진행한다.
+3. `git rev-parse --show-toplevel` 결과를 dev 환경 전용 후보로 사용한다. 해당 경로의 `package.json`에서 `name`이 `@jjlabsio/claude-crew`인지 검증하고, 맞으면 사용한다. 아니면 다음 fallback으로 진행한다.
+4. 모든 fallback이 실패하면 `'/crew-setup을 먼저 실행하세요'` 에러 메시지로 중단한다.
+
+이후 모든 runner 호출은 `node "$CREW_ROOT/scripts/crew-agent-runner.mjs"` 형식을 사용한다.
+
 ### 1. request 객체 작성
 
 `{ role, inputs (path+content), instruction, successGate, failureHandling, taskId }` 형태의 임시 JSON 파일을 작성한다.
 
 ### 2. prepare
 
-오케스트레이터는 `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+오케스트레이터는 `node "$CREW_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
 prepare는 provider/model/contract를 해석하고 다음 action 중 하나를 반환한다.
 
 ### 3a. dispatch action
@@ -67,8 +80,8 @@ capability를 넘어선 도구 요청이다. 오케스트레이터가 `contract.
 
 ### Codex 경로
 
-1. `node scripts/crew-agent-runner.mjs render-followup --previous-result <file> --new-input <file>` 실행 → followup prompt 문자열 → 임시 파일에 저장.
-2. `node scripts/crew-agent-runner.mjs dispatch --role <role> --request-file <new-request-with-followup-prompt> --resume-handle <agent_handle> --json` 실행.
+1. `node "$CREW_ROOT/scripts/crew-agent-runner.mjs" render-followup --previous-result <file> --new-input <file>` 실행 → followup prompt 문자열 → 임시 파일에 저장.
+2. `node "$CREW_ROOT/scripts/crew-agent-runner.mjs" dispatch --role <role> --request-file <new-request-with-followup-prompt> --resume-handle <agent_handle> --json` 실행.
    - 내부적으로 runner가 `crew-codex-companion.mjs task-resume-candidate`로 thread 일치 검증 후 `task --resume-last`를 호출하고 AgentResult를 정규화한다.
 3. AgentResult JSON을 받아 다음 상태 처리.
 

package/skills/crew-setup/SKILL.md

@@ -102,6 +102,27 @@ push는 하지 않는다.
 
 ---
 
+## Step 2b — Plugin Root 영속화
+
+`$CLAUDE_PLUGIN_ROOT`가 살아있는 setup 시점에 runner fallback용 plugin root를 사용자 데이터 영역에 저장한다.
+
+1. `~/.claude/crew/` 디렉토리가 없으면 생성한다.
+2. `~/.claude/crew/plugin-root.json`을 다음 형식으로 쓴다. 기존 파일이 있으면 덮어쓴다.
+   ```json
+   {
+     "pluginRoot": "<$CLAUDE_PLUGIN_ROOT 값>",
+     "version": "<현재 플러그인 버전>",
+     "updatedAt": "<ISO timestamp>"
+   }
+   ```
+3. plugin 자체 데이터인 version은 plugin root 기준 `package.json`에서 읽는다.
+
+**주의**:
+- plugin root는 `$CLAUDE_PLUGIN_ROOT` 값을 사용한다.
+- `~/.claude/crew/plugin-root.json`은 사용자 데이터이므로 home 기준 경로에 저장한다.
+
+---
+
 ## Step 3 — Provider 설정
 
 에이전트별로 어떤 provider(claude/codex)와 model을 사용할지 설정한다.