@remixhq/claude-plugin 0.1.11 → 0.1.14

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "remix",
   "description": "Remix collaboration workflows for Claude Code",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "author": {
     "name": "Remix"
   },

package/agents/remix-collab.md

@@ -22,10 +22,10 @@ Operating rules:
    - use `remix_collab_memory_change_step_diff` only after you have identified a specific `changeStepId`.
 8. Use raw git for historical reads only after Remix memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or raw patch details.
 9. Clearly explain local mutation risk before using tools that can modify the local repo.
-10. Assume the installed hook is the normal automatic recording path for completed assistant turns in a bound repo: changed turn => `remix_collab_add`, no-diff turn => `remix_collab_record_turn`.
-11. Do not proactively call `remix_collab_add` or `remix_collab_record_turn` during normal work. The hook should do the automatic per-turn recording unless recovery is required.
-12. Only use manual `remix_collab_add` or `remix_collab_record_turn` when the user explicitly asks for it, or when doing operational recovery, backfills, or debugging after automatic recording could not complete safely.
-13. When you must choose manually, treat `remix_collab_add` or the clearer alias `remix_collab_add_change_step` as the code-diff tool, and treat `remix_collab_record_turn` or `remix_collab_record_no_diff_turn` as no-diff prompt/response history only.
+10. In a bound repo, Remix MCP tools are the required workflow layer for ordinary collaboration work.
+11. In a bound repo, exactly one final `remix_collab_finalize_turn` is required before the final user-facing response.
+12. The final recording call must use the exact user prompt and your final assistant response.
+13. Do not finish the turn before recording. Do not make additional repo mutations after the final turn-recording call unless you intend to record again.
 14. Do not duplicate core business logic in reasoning. Use the MCP tools to inspect and execute the workflow.
 
 When appropriate:
@@ -35,7 +35,6 @@ When appropriate:
 - use `remix_collab_checkout` to continue work on an existing app id without creating a fork
 - use memory summary/search/timeline tools before repo inspection when historical context or reasoning is needed
 - use the explicit change-step diff tool only after you already know which `changeStepId` matters
-- use `remix_collab_add` only when a manual changed-turn recording step is explicitly needed
-- use `remix_collab_record_turn` only when a manual no-diff turn recording step is explicitly needed
+- use `remix_collab_finalize_turn` as the final turn recorder
 - use `remix_collab_review_queue` for reviewable merge requests, `remix_collab_my_merge_requests` for authored requests, and `remix_collab_list_app_merge_requests` for app-scoped MR flows with required `queue` set to `app_reviewable`, `app_outgoing`, or `app_related_visible`
 - use merge request tools for review and approval flows

package/dist/hook-post-collab.cjs

@@ -6,6 +6,10 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -22,6 +26,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hook-post-collab.ts
+var hook_post_collab_exports = {};
+__export(hook_post_collab_exports, {
+  runHookPostCollab: () => runHookPostCollab
+});
+module.exports = __toCommonJS(hook_post_collab_exports);
+
+// src/hook-diagnostics.ts
+var import_node_crypto2 = require("crypto");
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
 
 // src/hook-state.ts
 var import_promises = __toESM(require("fs/promises"), 1);
@@ -29,7 +47,8 @@ var import_node_os = __toESM(require("os"), 1);
 var import_node_path = __toESM(require("path"), 1);
 var import_node_crypto = require("crypto");
 function stateRoot() {
-  return import_node_path.default.join(import_node_os.default.tmpdir(), "remix-claude-plugin-hooks");
+  const configured = process.env.REMIX_CLAUDE_PLUGIN_HOOK_STATE_ROOT?.trim();
+  return configured || import_node_path.default.join(import_node_os.default.tmpdir(), "remix-claude-plugin-hooks");
 }
 function statePath(sessionId) {
   return import_node_path.default.join(stateRoot(), `${sessionId}.json`);
@@ -94,6 +113,7 @@ async function tryRemoveStaleStateLock(sessionId) {
 async function acquireStateLock(sessionId) {
   const lockPath = stateLockPath(sessionId);
   const deadline = Date.now() + STATE_LOCK_WAIT_MS;
+  await import_promises.default.mkdir(stateRoot(), { recursive: true });
   while (true) {
     try {
       await import_promises.default.mkdir(lockPath);
@@ -328,19 +348,139 @@ async function markPendingTurnConsultedMemory(sessionId) {
   });
 }
 
+// package.json
+var package_default = {
+  name: "@remixhq/claude-plugin",
+  version: "0.1.14",
+  description: "Claude Code plugin for Remix collaboration workflows",
+  homepage: "https://github.com/RemixDotOne/remix-claude-plugin",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/RemixDotOne/remix-claude-plugin.git"
+  },
+  type: "module",
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  files: [
+    "dist",
+    ".claude-plugin/plugin.json",
+    ".mcp.json",
+    "skills",
+    "hooks",
+    "agents"
+  ],
+  scripts: {
+    build: "tsup",
+    postbuild: `node -e "const fs=require('node:fs'); for (const p of ['dist/mcp-server.cjs','dist/hook-pre-git.cjs','dist/hook-user-prompt.cjs','dist/hook-post-collab.cjs','dist/hook-stop-collab.cjs']) fs.chmodSync(p, 0o755);"`,
+    dev: "tsx src/mcp-server.ts",
+    typecheck: "tsc -p tsconfig.json --noEmit",
+    prepack: "npm run build"
+  },
+  dependencies: {
+    "@remixhq/core": "^0.1.9",
+    "@remixhq/mcp": "^0.1.9"
+  },
+  devDependencies: {
+    "@types/node": "^25.4.0",
+    tsup: "^8.5.1",
+    tsx: "^4.21.0",
+    typescript: "^5.9.3"
+  }
+};
+
+// src/metadata.ts
+var pluginMetadata = {
+  name: package_default.name,
+  version: package_default.version,
+  description: package_default.description,
+  pluginId: "remix",
+  agentName: "remix-collab"
+};
+
+// src/hook-diagnostics.ts
+var MAX_LOG_BYTES = 512 * 1024;
+function resolveClaudeRoot() {
+  const configured = process.env.CLAUDE_CONFIG_DIR?.trim();
+  return configured || import_node_path2.default.join(import_node_os2.default.homedir(), ".claude");
+}
+function resolvePluginDataDirName() {
+  return `${pluginMetadata.pluginId}-${pluginMetadata.pluginId}`;
+}
+function getHookDiagnosticsDirPath() {
+  const configured = process.env.REMIX_CLAUDE_PLUGIN_HOOK_DIAGNOSTICS_DIR?.trim();
+  return configured || import_node_path2.default.join(resolveClaudeRoot(), "plugins", "data", resolvePluginDataDirName());
+}
+function getHookDiagnosticsLogPath() {
+  return import_node_path2.default.join(getHookDiagnosticsDirPath(), "hooks.ndjson");
+}
+function toFieldValue(value) {
+  if (value === null) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "boolean") return value;
+  return void 0;
+}
+function normalizeFields(fields) {
+  if (!fields) return {};
+  const normalizedEntries = Object.entries(fields).map(([key, value]) => {
+    const normalized = toFieldValue(value);
+    return normalized === void 0 ? null : [key, normalized];
+  }).filter((entry) => entry !== null);
+  return Object.fromEntries(normalizedEntries);
+}
+async function rotateLogIfNeeded(logPath) {
+  const stat = await import_promises2.default.stat(logPath).catch(() => null);
+  if (!stat || stat.size < MAX_LOG_BYTES) {
+    return;
+  }
+  const rotatedPath = `${logPath}.1`;
+  await import_promises2.default.rm(rotatedPath, { force: true }).catch(() => void 0);
+  await import_promises2.default.rename(logPath, rotatedPath).catch(() => void 0);
+}
+async function appendHookDiagnosticsEvent(params) {
+  try {
+    const logPath = getHookDiagnosticsLogPath();
+    await import_promises2.default.mkdir(import_node_path2.default.dirname(logPath), { recursive: true });
+    await rotateLogIfNeeded(logPath);
+    const event = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      hook: params.hook,
+      pluginVersion: pluginMetadata.version,
+      pid: process.pid,
+      sessionId: params.sessionId?.trim() || null,
+      turnId: params.turnId?.trim() || null,
+      stage: params.stage.trim(),
+      result: params.result,
+      reason: params.reason?.trim() || null,
+      toolName: params.toolName?.trim() || null,
+      repoRoot: params.repoRoot?.trim() || null,
+      message: params.message?.trim() || null,
+      fields: normalizeFields(params.fields)
+    };
+    await import_promises2.default.appendFile(logPath, `${JSON.stringify(event)}
+`, "utf8");
+  } catch {
+  }
+}
+
 // src/hook-utils.ts
-var import_promises3 = __toESM(require("fs/promises"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
+var import_promises4 = __toESM(require("fs/promises"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 
-// node_modules/@remixhq/core/dist/chunk-FAZUMWBS.js
-var import_promises2 = __toESM(require("fs/promises"), 1);
+// node_modules/@remixhq/core/dist/chunk-GEHSFPCD.js
+var import_promises3 = __toESM(require("fs/promises"), 1);
 var import_path = __toESM(require("path"), 1);
 function getCollabBindingPath(repoRoot) {
   return import_path.default.join(repoRoot, ".remix", "config.json");
 }
 async function readCollabBinding(repoRoot) {
   try {
-    const raw = await import_promises2.default.readFile(getCollabBindingPath(repoRoot), "utf8");
+    const raw = await import_promises3.default.readFile(getCollabBindingPath(repoRoot), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed?.schemaVersion !== 1) return null;
     if (!parsed.projectId || !parsed.currentAppId || !parsed.upstreamAppId) return null;
@@ -384,6 +524,11 @@ function extractToolInput(payload) {
 function extractToolResponse(payload) {
   return getNestedRecord(payload.tool_response) ?? getNestedRecord(payload.toolResponse);
 }
+function extractToolStructuredData(payload) {
+  const toolResponse = extractToolResponse(payload);
+  const structuredContent = getNestedRecord(toolResponse?.structuredContent) ?? getNestedRecord(payload.structuredContent);
+  return getNestedRecord(toolResponse?.data) ?? getNestedRecord(structuredContent?.data) ?? structuredContent;
+}
 function extractToolName(payload) {
   return extractString(payload, ["tool_name", "toolName"]);
 }
@@ -397,6 +542,26 @@ function normalizeHookToolName(toolName) {
   }
   return trimmed;
 }
+function extractAssistantResponse(payload) {
+  const candidateKeys = [
+    "last_assistant_message",
+    "lastAssistantMessage",
+    "assistant_response",
+    "assistantResponse",
+    "assistant_message",
+    "assistantMessage",
+    "response",
+    "message"
+  ];
+  return extractString(payload, candidateKeys) ?? extractString(extractToolResponse(payload) ?? {}, candidateKeys) ?? extractString(extractToolStructuredData(payload) ?? {}, candidateKeys) ?? extractString(extractToolInput(payload), candidateKeys);
+}
+function extractFinalizeTurnMode(payload) {
+  const mode = extractString(extractToolStructuredData(payload) ?? {}, ["mode"]) ?? extractString(extractToolResponse(payload) ?? {}, ["mode"]) ?? extractString(payload, ["mode"]);
+  if (mode === "changed_turn" || mode === "no_diff_turn") {
+    return mode;
+  }
+  return null;
+}
 function extractString(input, keys) {
   for (const key of keys) {
     const value = input[key];
@@ -462,7 +627,7 @@ function collectPathTargetsFromObject(input, keys) {
   return keys.flatMap((key) => collectStringPathValue(input[key]));
 }
 function resolveCandidatePath(targetPath, baseDir) {
-  return import_node_path2.default.isAbsolute(targetPath) ? import_node_path2.default.normalize(targetPath) : import_node_path2.default.resolve(baseDir, targetPath);
+  return import_node_path3.default.isAbsolute(targetPath) ? import_node_path3.default.normalize(targetPath) : import_node_path3.default.resolve(baseDir, targetPath);
 }
 function extractToolPathTargets(payload, toolName) {
   const name = (toolName ?? extractToolName(payload) ?? "").trim().toLowerCase();
@@ -474,16 +639,16 @@ function extractToolPathTargets(payload, toolName) {
 }
 async function findBoundRepo(startPath) {
   if (!startPath) return null;
-  let current = import_node_path2.default.resolve(startPath);
-  let stats = await import_promises3.default.stat(current).catch(() => null);
+  let current = import_node_path3.default.resolve(startPath);
+  let stats = await import_promises4.default.stat(current).catch(() => null);
   if (stats?.isFile()) {
-    current = import_node_path2.default.dirname(current);
+    current = import_node_path3.default.dirname(current);
   }
   while (true) {
-    const bindingPath = import_node_path2.default.join(current, ".remix", "config.json");
-    const bindingStats = await import_promises3.default.stat(bindingPath).catch(() => null);
+    const bindingPath = import_node_path3.default.join(current, ".remix", "config.json");
+    const bindingStats = await import_promises4.default.stat(bindingPath).catch(() => null);
     if (bindingStats?.isFile()) return current;
-    const parent = import_node_path2.default.dirname(current);
+    const parent = import_node_path3.default.dirname(current);
     if (parent === current) return null;
     current = parent;
   }
@@ -532,15 +697,28 @@ function isShellToolName(toolName) {
 function isRemoteChangeRecordingToolName(toolName) {
   return /remix_collab_(add|add_change_step)$/i.test(toolName);
 }
-function getManualRecordingScope(toolName) {
-  if (/remix_collab_add_change_step$/i.test(toolName)) {
-    return "change_step";
+function hasManualFullTurnPayload(payload) {
+  const toolInput = extractToolInput(payload);
+  return Boolean(extractString(toolInput, ["prompt"]) && extractAssistantResponse(payload));
+}
+function getManualRecordingScope(payload, toolName) {
+  if (/remix_collab_finalize_turn$/i.test(toolName)) {
+    return "full_turn";
+  }
+  if (/remix_collab_(add|add_change_step)$/i.test(toolName)) {
+    return hasManualFullTurnPayload(payload) ? "full_turn" : "change_step";
   }
-  if (/remix_collab_(add|record_turn|record_no_diff_turn)$/i.test(toolName)) {
+  if (/remix_collab_(record_turn|record_no_diff_turn)$/i.test(toolName)) {
     return "full_turn";
   }
   return null;
 }
+function didFinalizeTurnRecordRemoteChange(payload, toolName) {
+  if (!/remix_collab_finalize_turn$/i.test(toolName)) {
+    return false;
+  }
+  return extractFinalizeTurnMode(payload) === "changed_turn";
+}
 function isLikelyMutatingShellCommand(command) {
   const normalized = command.trim().toLowerCase();
   if (!normalized) return false;
@@ -580,22 +758,71 @@ function isLikelyMutatingShellCommand(command) {
   }
   return false;
 }
-async function main() {
-  const payload = await readJsonStdin();
+async function runHookPostCollab(payload) {
   const sessionId = typeof payload.session_id === "string" && payload.session_id.trim() ? payload.session_id.trim() : null;
   const toolName = normalizeHookToolName(extractToolName(payload));
+  await appendHookDiagnosticsEvent({
+    hook: "PostToolUse",
+    sessionId,
+    stage: "payload_received",
+    result: "start",
+    toolName,
+    fields: {
+      hasSessionId: Boolean(sessionId),
+      hasToolName: Boolean(toolName)
+    }
+  });
   if (!sessionId || !toolName) {
+    await appendHookDiagnosticsEvent({
+      hook: "PostToolUse",
+      sessionId,
+      stage: "payload_validation",
+      result: "skip",
+      reason: !sessionId ? "missing_session_id" : "missing_tool_name",
+      toolName
+    });
     return;
   }
   const toolSucceeded = didToolSucceed(payload);
-  const remoteChangeRecordedButSyncFailed = isRemoteChangeRecordingToolName(toolName) && isRemoteChangeRecordedButLocalSyncFailed(payload);
+  const remoteChangeRecordedButSyncFailed = (isRemoteChangeRecordingToolName(toolName) || /remix_collab_finalize_turn$/i.test(toolName)) && isRemoteChangeRecordedButLocalSyncFailed(payload);
+  await appendHookDiagnosticsEvent({
+    hook: "PostToolUse",
+    sessionId,
+    stage: "tool_classified",
+    result: "info",
+    toolName,
+    fields: {
+      toolSucceeded,
+      remoteChangeRecordedButSyncFailed,
+      isMemoryTool: isMemoryToolName(toolName),
+      isRepoMutationTool: isRepoMutationToolName(toolName),
+      isShellTool: isShellToolName(toolName),
+      isStructuredLocalWriteTool: isStructuredLocalWriteToolName(toolName),
+      isStructuredLocalReadTool: isStructuredLocalReadToolName(toolName)
+    }
+  });
   if (!toolSucceeded && !remoteChangeRecordedButSyncFailed) {
+    await appendHookDiagnosticsEvent({
+      hook: "PostToolUse",
+      sessionId,
+      stage: "tool_result_gate",
+      result: "skip",
+      reason: "tool_failed_or_skipped",
+      toolName
+    });
     return;
   }
   if (toolSucceeded && isMemoryToolName(toolName)) {
     await markPendingTurnConsultedMemory(sessionId);
+    await appendHookDiagnosticsEvent({
+      hook: "PostToolUse",
+      sessionId,
+      stage: "memory_marked_consulted",
+      result: "success",
+      toolName
+    });
   }
-  const manualRecordingScope = getManualRecordingScope(toolName);
+  const manualRecordingScope = getManualRecordingScope(payload, toolName);
   if (isRepoMutationToolName(toolName) || manualRecordingScope) {
     const targetRepo = await resolveBoundRepoFromToolCwd(payload);
     if (targetRepo) {
@@ -614,9 +841,31 @@ async function main() {
         await markTouchedRepoManuallyRecorded(sessionId, targetRepo.repoRoot, {
           toolName,
           scope: manualRecordingScope,
-          remoteChangeRecorded: toolSucceeded ? isRemoteChangeRecordingToolName(toolName) : remoteChangeRecordedButSyncFailed
+          remoteChangeRecorded: toolSucceeded ? isRemoteChangeRecordingToolName(toolName) || didFinalizeTurnRecordRemoteChange(payload, toolName) : remoteChangeRecordedButSyncFailed
         });
       }
+      await appendHookDiagnosticsEvent({
+        hook: "PostToolUse",
+        sessionId,
+        stage: "repo_marked_from_tool_cwd",
+        result: "success",
+        toolName,
+        repoRoot: targetRepo.repoRoot,
+        fields: {
+          hasObservedWrite: isRepoMutationToolName(toolName),
+          manualRecordingScope,
+          remoteChangeRecordedButSyncFailed
+        }
+      });
+    } else {
+      await appendHookDiagnosticsEvent({
+        hook: "PostToolUse",
+        sessionId,
+        stage: "repo_marked_from_tool_cwd",
+        result: "skip",
+        reason: "repo_not_bound_from_tool_cwd",
+        toolName
+      });
     }
   }
   if (toolSucceeded && isShellToolName(toolName)) {
@@ -635,10 +884,44 @@ async function main() {
       if (hasObservedWrite) {
         await markTouchedRepoObservedWrite(sessionId, targetRepo.repoRoot, { toolName });
       }
+      await appendHookDiagnosticsEvent({
+        hook: "PostToolUse",
+        sessionId,
+        stage: "shell_repo_marked",
+        result: "success",
+        toolName,
+        repoRoot: targetRepo.repoRoot,
+        fields: {
+          hasObservedWrite,
+          bashCommandLength: bashCommand?.length ?? 0
+        }
+      });
+    } else {
+      await appendHookDiagnosticsEvent({
+        hook: "PostToolUse",
+        sessionId,
+        stage: "shell_repo_marked",
+        result: "skip",
+        reason: "repo_not_bound_from_shell_cwd",
+        toolName
+      });
     }
   }
   if (toolSucceeded && (isStructuredLocalWriteToolName(toolName) || isStructuredLocalReadToolName(toolName))) {
-    const touchedRepos = await resolveTouchedBoundReposFromPaths(extractToolPathTargets(payload, toolName));
+    const touchedPaths = extractToolPathTargets(payload, toolName);
+    const touchedRepos = await resolveTouchedBoundReposFromPaths(touchedPaths);
+    await appendHookDiagnosticsEvent({
+      hook: "PostToolUse",
+      sessionId,
+      stage: "path_targets_resolved",
+      result: touchedRepos.length > 0 ? "info" : "skip",
+      reason: touchedRepos.length > 0 ? null : "no_bound_repos_from_paths",
+      toolName,
+      fields: {
+        touchedPathCount: touchedPaths.length,
+        boundRepoCount: touchedRepos.length
+      }
+    });
     for (const repo of touchedRepos) {
       await upsertTouchedRepo(sessionId, {
         repoRoot: repo.repoRoot,
@@ -651,13 +934,46 @@ async function main() {
       if (isStructuredLocalWriteToolName(toolName)) {
         await markTouchedRepoObservedWrite(sessionId, repo.repoRoot, { toolName });
       }
+      await appendHookDiagnosticsEvent({
+        hook: "PostToolUse",
+        sessionId,
+        stage: "path_repo_marked",
+        result: "success",
+        toolName,
+        repoRoot: repo.repoRoot,
+        fields: {
+          hasObservedWrite: isStructuredLocalWriteToolName(toolName)
+        }
+      });
     }
   }
+  await appendHookDiagnosticsEvent({
+    hook: "PostToolUse",
+    sessionId,
+    stage: "completed",
+    result: "success",
+    toolName
+  });
+}
+async function main() {
+  const payload = await readJsonStdin();
+  await runHookPostCollab(payload);
 }
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
+  void appendHookDiagnosticsEvent({
+    hook: "PostToolUse",
+    stage: "unhandled_error",
+    result: "error",
+    reason: "exception",
+    message
+  });
   process.stderr.write(`${message}
 `);
   process.exitCode = 0;
 });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runHookPostCollab
+});
 //# sourceMappingURL=hook-post-collab.cjs.map