@uniqbit/mate-core 0.15.4-canary.9 → 0.15.5-canary.0

package/claude-plugin/hooks/artifact-finish-nudge.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-// Thin shim: hook logic lives in src/hooks/artifact-finish-nudge.ts
-// (loaded via node's native TypeScript type stripping, engines node >= 24).
-import { run } from "../../src/hooks/artifact-finish-nudge.ts";
+// Thin shim: hook logic lives in src/hooks/artifact-finish-nudge.ts, loaded
+// through ts-loader.mjs because the installed plugin sits inside node_modules
+// where node's native type stripping is disabled.
+import "./ts-loader.mjs";
 
+const { run } = await import("../../src/hooks/artifact-finish-nudge.ts");
 process.exitCode = await run();

package/claude-plugin/hooks/session-banner.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-// Thin shim: hook logic lives in src/hooks/session-banner.ts
-// (loaded via node's native TypeScript type stripping, engines node >= 24).
-import { run } from "../../src/hooks/session-banner.ts";
+// Thin shim: hook logic lives in src/hooks/session-banner.ts, loaded through
+// ts-loader.mjs because the installed plugin sits inside node_modules where
+// node's native type stripping is disabled.
+import "./ts-loader.mjs";
 
+const { run } = await import("../../src/hooks/session-banner.ts");
 process.exitCode = run();

package/claude-plugin/hooks/ts-loader.mjs

@@ -0,0 +1,28 @@
+// Synchronous module loader that strips TypeScript types itself. Node's
+// built-in .ts loading refuses files under node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), which is exactly where the
+// published plugin lives — so the hook shims register this loader before
+// importing their src/hooks/*.ts implementation.
+import fs from "node:fs";
+import { registerHooks, stripTypeScriptTypes } from "node:module";
+import { fileURLToPath } from "node:url";
+
+// stripTypeScriptTypes emits an ExperimentalWarning; hooks must keep stderr
+// clean because Claude Code surfaces it to the user on non-zero exits.
+const emitWarning = process.emitWarning;
+process.emitWarning = (warning, ...args) => {
+  if (String(warning).includes("stripTypeScriptTypes")) return;
+  emitWarning.call(process, warning, ...args);
+};
+
+registerHooks({
+  load(url, context, next) {
+    if (!url.endsWith(".ts")) return next(url, context);
+    const source = fs.readFileSync(fileURLToPath(url), "utf8");
+    return {
+      format: "module",
+      source: stripTypeScriptTypes(source),
+      shortCircuit: true,
+    };
+  },
+});

package/claude-plugin/hooks/validate-artifact-path.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-// Thin shim: hook logic lives in src/hooks/validate-artifact-path.ts
-// (loaded via node's native TypeScript type stripping, engines node >= 24).
-import { run } from "../../src/hooks/validate-artifact-path.ts";
+// Thin shim: hook logic lives in src/hooks/validate-artifact-path.ts, loaded
+// through ts-loader.mjs because the installed plugin sits inside node_modules
+// where node's native type stripping is disabled.
+import "./ts-loader.mjs";
 
+const { run } = await import("../../src/hooks/validate-artifact-path.ts");
 process.exitCode = await run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.4-canary.9",
+  "version": "0.15.5-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/cap/openspec.ts

@@ -79,7 +79,26 @@ export async function runOpenspecCapCommand(
     readOpenSpecProjectSchema(companionPath),
   );
 
-  const result = spawnSync("openspec", forwardedArgs, { cwd, stdio: "inherit" });
+  if (forwardedArgs[0] === "init" || forwardedArgs[0] === "update") {
+    const reset = spawnSync("openspec", ["config", "reset", "--all", "-y"], {
+      cwd,
+      stdio: "inherit",
+    });
+    if (reset.error) {
+      process.stderr.write(`Failed to reset openspec config: ${reset.error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    if (reset.status !== 0) {
+      process.exitCode = reset.status ?? 1;
+      return;
+    }
+  }
+
+  const result = spawnSync("openspec", forwardedArgs, {
+    cwd,
+    stdio: "inherit",
+  });
   if (result.error) {
     process.stderr.write(`Failed to run openspec: ${result.error.message}\n`);
     process.exitCode = 1;

package/src/cli/commands/companion/hub.ts

@@ -50,6 +50,7 @@ async function selectRegisteredCompanion(): Promise<string> {
 async function runHubInit(argv: string[]): Promise<void> {
   const folder = positionalArgs(argv)[0] ?? process.cwd();
   const hubPath = await initializeCompanionHub(folder);
+  await updateHubPlugins(hubPath);
   console.log(`Initialized companion hub: ${hubPath}`);
 }
 

package/src/cli/commands/plugin/install.ts

@@ -2,8 +2,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
+import { backfillHubAllowedAgents } from "../../../lib/orchestrator/companion-hub";
 import { ConfigStore } from "../../../lib/orchestrator/config-store";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { FrameworkConfig, PluginDeclaration } from "../../../lib/orchestrator/types";
+import { applySetupCompatibilities } from "../../../tools/setup";
 import { hydrateDynamicPlugins } from "../../../tools/setup/dynamic-plugins/hydrate";
 import {
   installDeclaredPlugins,
@@ -33,6 +35,7 @@ function withDeclaration(
 export interface PluginInstallCommandDeps {
   cwd?: string;
   installDeps?: PluginInstallDeps;
+  setupHub?: (companionPath: string, config: FrameworkConfig) => Promise<void>;
 }
 
 /**
@@ -78,8 +81,10 @@ export async function runPluginInstallCommand(
   );
   const store = new ConfigStore(configPath);
   const nextPlugins = withDeclaration(context.config.plugins ?? [], packageName, version);
-  if (nextPlugins !== context.config.plugins) {
-    await store.save({ ...context.config, plugins: nextPlugins });
+  const nextConfig = { ...context.config, plugins: nextPlugins };
+  const agentsBackfilled = context.kind === "hub" && backfillHubAllowedAgents(nextConfig);
+  if (nextPlugins !== context.config.plugins || agentsBackfilled) {
+    await store.save(nextConfig);
   }
 
   const results = await installDeclaredPlugins(
@@ -89,6 +94,13 @@ export async function runPluginInstallCommand(
   );
   reportPluginInstallResults(results);
   await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  if (context.kind === "hub") {
+    await (
+      deps.setupHub ??
+      ((companionPath, config) =>
+        applySetupCompatibilities(companionPath, config, "sync", undefined, undefined, "hub"))
+    )(context.companionPath, nextConfig);
+  }
 
   return results.find((result) => result.package === packageName)?.status !== "failed";
 }

package/src/hooks/artifact-finish-nudge.ts

@@ -79,6 +79,36 @@ function extractChangeFromPath(value: string): string | null {
   return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
 }
 
+// Best-effort shell variable substitution, NOT a shell interpreter: a change
+// name is often built up through variables (DEST="...archive/$TARGET"; mv a
+// "$DEST") rather than appearing as a literal path next to mv/archive. This
+// resolves $NAME/${NAME} references against preceding literal NAME=value
+// assignment tokens in the same command string; unresolved references are
+// left as-is, which keeps prior (silent) behavior for anything it can't follow.
+const ASSIGNMENT_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/;
+const VARIABLE_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function substituteVariables(value: string, vars: Map<string, string>): string {
+  return value.replace(VARIABLE_REFERENCE_PATTERN, (match, braced: string, bare: string) => {
+    const name = braced ?? bare;
+    return vars.has(name) ? vars.get(name)! : match;
+  });
+}
+
+// Assignments are collected in left-to-right token order so a later
+// assignment (e.g. DEST) can reference an earlier one (e.g. TARGET) the same
+// way the shell would resolve it at that point in the script.
+function collectVariableAssignments(parts: string[]): Map<string, string> {
+  const vars = new Map<string, string>();
+  for (const part of parts) {
+    const match = part.match(ASSIGNMENT_PATTERN);
+    if (!match) continue;
+    const [, name, rawValue] = match;
+    vars.set(name, substituteVariables(rawValue, vars));
+  }
+  return vars;
+}
+
 // Shell syntax tokens are never change-name positionals: separators end the
 // archive invocation, redirections are skipped (a bare operator also consumes
 // its target token).
@@ -95,6 +125,7 @@ export function extractArchiveCommand(command: string): string | null {
       (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")),
   );
   if (index < 0) return null;
+  const vars = collectVariableAssignments(parts);
   for (let position = index + 1; position < parts.length; position += 1) {
     const part = parts[position];
     if (!part || part === "--") continue;
@@ -107,7 +138,7 @@ export function extractArchiveCommand(command: string): string | null {
       if (part === "--store") position += 1;
       continue;
     }
-    return part;
+    return substituteVariables(part, vars);
   }
   return null;
 }
@@ -130,15 +161,16 @@ function isPython(part: string): boolean {
 
 export function extractMoveCommand(command: string): string | null {
   const parts = shellSplit(command);
+  const vars = collectVariableAssignments(parts);
   for (let index = 0; index < parts.length; index += 1) {
     if (MOVE_COMMANDS.has(parts[index].toLowerCase())) {
       for (const part of parts.slice(index + 1)) {
-        const change = extractChangeFromPath(part);
+        const change = extractChangeFromPath(substituteVariables(part, vars));
         if (change) return change;
       }
     }
     if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
-      return extractChangeFromPath(command);
+      return extractChangeFromPath(substituteVariables(command, vars));
     }
   }
   return null;

package/src/lib/context-mode-package.ts

@@ -20,7 +20,7 @@ export function isContextModePackageReference(value: unknown): value is string {
 }
 
 export function getContextModeInstallDir(companionPath: string): string {
-  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+  return path.join(companionPath, ".mate", "plugins", ".local");
 }
 
 export function getContextModePackageRoot(companionPath: string): string {

package/src/lib/orchestrator/companion-git-sync.ts

@@ -9,6 +9,9 @@ import { LaunchPreflightError } from "./types";
 
 const execFile = promisify(execFileCallback);
 
+/** Bounded but far above any diagnostic output; default 1 MiB kills git mid-merge on large trees. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
 export interface GitCommandResult {
   status: number;
   stdout: string;
@@ -26,22 +29,30 @@ export interface CompanionGitSyncResult {
 export class CompanionGitSyncError extends LaunchPreflightError {
   readonly companionPath: string;
   readonly conflictingPaths: string[];
+  readonly reason: string;
+  readonly recovery: string;
+  readonly stashRef: string | undefined;
 
   constructor(
     companionPath: string,
     reason: string,
     conflictingPaths: string[] = [],
     recovery = "Resolve or abort the Git operation, then retry the launch.",
+    stashRef?: string,
   ) {
     const conflicts = conflictingPaths.length
       ? `\n  Conflicting paths:\n${conflictingPaths.map((entry) => `    - ${entry}`).join("\n")}`
       : "";
+    const stash = stashRef
+      ? `  Local changes were stashed as ${stashRef}. Recover with \`git stash apply ${stashRef}\` in the companion.`
+      : "";
     super(
       [
         "mate: companion Git synchronization failed.",
         `  Companion: ${companionPath}`,
         `  ${reason}`,
         conflicts,
+        stash,
         `  ${recovery}`,
         "  Bypass: `mate claude -- --no-git` or `mate opencode -- --no-git`.",
       ]
@@ -51,6 +62,9 @@ export class CompanionGitSyncError extends LaunchPreflightError {
     this.name = "CompanionGitSyncError";
     this.companionPath = companionPath;
     this.conflictingPaths = conflictingPaths;
+    this.reason = reason;
+    this.recovery = recovery;
+    this.stashRef = stashRef;
   }
 }
 
@@ -68,6 +82,7 @@ export const companionGitSyncDeps: { runGit: GitRunner } = {
         cwd,
         encoding: "utf8",
         env: gitEnv,
+        maxBuffer: GIT_MAX_BUFFER,
       });
       return { status: 0, stdout: String(result.stdout), stderr: String(result.stderr) };
     } catch (error) {
@@ -106,6 +121,21 @@ function outputLines(stdout: string): string[] {
     .filter(Boolean);
 }
 
+/** Matches Git progress-meter lines such as `Updating files:  76% (11340/14790)` or `..., done.` */
+const GIT_PROGRESS_LINE = /^\S.*?: +\d+% \(\d+\/\d+\)(?:, done\.)?$/;
+
+function stripGitProgress(text: string): string {
+  return text
+    .split(/\r\n|\r|\n/)
+    .filter((line) => !GIT_PROGRESS_LINE.test(line.trim()))
+    .join("\n")
+    .trim();
+}
+
+export function describeGitFailure(result: GitCommandResult): string {
+  return stripGitProgress(result.stderr) || stripGitProgress(result.stdout) || "unknown Git error";
+}
+
 export class CompanionGitSync {
   constructor(private readonly runGit: GitRunner = companionGitSyncDeps.runGit) {}
 
@@ -160,7 +190,42 @@ export class CompanionGitSync {
       stashRef = ref.stdout.trim();
     }
 
-    const merge = await this.command(companionPath, ["merge", target.ref, "--no-edit"]);
+    const headBefore = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    try {
+      await this.mergeAndRestore(companionPath, target, stashRef);
+    } catch (error) {
+      if (stashRef && error instanceof CompanionGitSyncError && !error.stashRef) {
+        throw new CompanionGitSyncError(
+          error.companionPath,
+          error.reason,
+          error.conflictingPaths,
+          error.recovery,
+          stashRef,
+        );
+      }
+      throw error;
+    }
+
+    const headAfter = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    return {
+      skipped: false,
+      changed: headBefore.stdout.trim() !== headAfter.stdout.trim(),
+      companionPath,
+    };
+  }
+
+  private async mergeAndRestore(
+    companionPath: string,
+    target: SyncTarget,
+    stashRef: string | undefined,
+  ): Promise<void> {
+    const merge = await this.command(companionPath, [
+      "merge",
+      target.ref,
+      "--no-stat",
+      "--no-progress",
+      "--no-edit",
+    ]);
     if (merge.status !== 0) {
       await this.resolveManagedConflicts(companionPath, target.ref);
       const conflicts = await this.unresolvedPaths(companionPath);
@@ -220,12 +285,6 @@ export class CompanionGitSync {
       // Keep the stash if dropping it fails; it remains a recoverable backup.
       await this.command(companionPath, ["stash", "drop", stashRef]);
     }
-
-    return {
-      skipped: false,
-      changed: merge.status === 0 && merge.stdout.trim() !== "",
-      companionPath,
-    };
   }
 
   private async assertSafeCompanionRoot(
@@ -410,7 +469,7 @@ export class CompanionGitSync {
   }
 
   private detail(result: GitCommandResult): string {
-    return (result.stderr || result.stdout || "unknown Git error").trim();
+    return describeGitFailure(result);
   }
 
   private failure(

package/src/lib/orchestrator/companion-hub.ts

@@ -8,12 +8,14 @@ import { FRAMEWORK_NAME } from "../../framework";
 import { ConfigStore, validateHubConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import type { FrameworkConfig, HubMember, HubMemberSource } from "./types";
+import { listSetupProviderCompatibilities } from "./setup-compatibilities";
 import {
   installDeclaredPlugins,
   type PluginInstallDeps,
   type PluginInstallResult,
 } from "../../tools/setup/dynamic-plugins/install";
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import { applySetupCompatibilities } from "../../tools/setup";
 import { findRepoLocalRegistryFile } from "./repo-local-registry";
 
 export interface GitCommandResult {
@@ -41,6 +43,7 @@ export interface HubSyncResult {
 export interface HubPluginSyncDeps {
   installDeps?: PluginInstallDeps;
   hydrate?: (options: { companionPath: string }) => Promise<void>;
+  setup?: (companionPath: string, config: FrameworkConfig, mode: "setup" | "sync") => Promise<void>;
 }
 
 export function defaultGitCommand(cwd: string, args: string[]): GitCommandResult {
@@ -123,7 +126,7 @@ export async function initializeCompanionHub(
   } else {
     const config: FrameworkConfig = {
       type: "hub",
-      allowedAgents: [],
+      allowedAgents: listSetupProviderCompatibilities().map((entry) => entry.agent),
       packageManagers: [],
       capabilities: [],
       hub: { companions: [] },
@@ -365,16 +368,35 @@ export async function syncHub(
   return results;
 }
 
+/**
+ * Hubs persisted before provider bootstrapping carry `allowedAgents: []`;
+ * an empty list on a hub means "all built-in agents", not "none".
+ */
+export function backfillHubAllowedAgents(config: FrameworkConfig): boolean {
+  if (config.type !== "hub" || config.allowedAgents.length > 0) return false;
+  config.allowedAgents = listSetupProviderCompatibilities().map((entry) => entry.agent);
+  return true;
+}
+
 export async function updateHubPlugins(
   hubPath: string,
   deps: HubPluginSyncDeps = {},
 ): Promise<PluginInstallResult[]> {
-  const { config } = await assertHubRoot(hubPath);
+  const { config, store } = await assertHubRoot(hubPath);
+  if (backfillHubAllowedAgents(config)) await store.save(config);
   const declarations = config.plugins ?? [];
-  if (declarations.length === 0) return [];
-
   const resolvedHubPath = path.resolve(hubPath);
-  const results = await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps);
-  await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  const results =
+    declarations.length > 0
+      ? await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps)
+      : [];
+  if (declarations.length > 0) {
+    await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  }
+  await (
+    deps.setup ??
+    ((companionPath, setupConfig, mode) =>
+      applySetupCompatibilities(companionPath, setupConfig, mode, undefined, undefined, "hub"))
+  )(resolvedHubPath, config, "sync");
   return results;
 }

package/src/lib/orchestrator/types.ts

@@ -96,8 +96,8 @@ export type PluginDeclarationPolicy = "default" | "optional";
 /**
  * A companion-declared npm plugin: installed by setup/install into the
  * companion's own shared plugin workspace (`.mate/plugins/`) and loaded
- * from there on every invocation. Declaration registers the plugin;
- * enablement stays in the `capabilities` list.
+ * from there on every invocation. Declaration both registers and activates
+ * the plugin; dynamic plugins do not need a separate `capabilities` entry.
  */
 export interface PluginDeclaration {
   /** npm package name (e.g. `@acme/custom-plugin`). */

package/src/lib/package-paths.ts

@@ -46,6 +46,7 @@ export function validateClaudePluginAssets(pluginRoot = getClaudePluginRoot()):
   const expected = [
     path.join(".claude-plugin", "plugin.json"),
     path.join("hooks", "hooks.json"),
+    path.join("hooks", "ts-loader.mjs"),
     ...CLAUDE_PLUGIN_HOOK_SHIMS.map((shim) => path.join("hooks", shim)),
   ];
   const missing = expected.filter((asset) => !fs.existsSync(path.join(pluginRoot, asset)));

package/src/opencode/companion-hooks.ts

@@ -179,15 +179,12 @@ function detectCommandArchive(input: unknown, output: unknown): string | null {
 
 function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
   const current = readArchiveEntries(archiveDir);
-  const newlyArchived = [...current].filter((entry) => !snapshot.has(entry)).toSorted();
-  snapshot.clear();
-  for (const entry of current) snapshot.add(entry);
-  return newlyArchived;
+  return [...current].filter((entry) => !snapshot.has(entry)).toSorted();
 }
 
 function appendOpenSpecFinishNudge(
   context: CompanionContext,
-  archiveSnapshot: Set<string>,
+  archiveSnapshot: Set<string> | undefined,
   nudgedCommandChanges: Set<string>,
   input: { tool?: unknown },
   output: { output?: string },
@@ -196,8 +193,10 @@ function appendOpenSpecFinishNudge(
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
   const changes: string[] = [];
-  for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
-    changes.push(entry.slice("YYYY-MM-DD-".length));
+  if (archiveSnapshot) {
+    for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
+      changes.push(entry.slice("YYYY-MM-DD-".length));
+    }
   }
   const commandChange =
     String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
@@ -313,22 +312,36 @@ async function runReactDoctorScan(
 }
 
 type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
+type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
+type ToolBeforeOutput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[1];
 type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
 
+interface ArchiveCallSnapshot {
+  sessionID: string;
+  entries: Set<string>;
+}
+
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
   if (!context.companionPath || !context.repositoryPath) return {};
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const archiveSnapshot = readArchiveEntries(archiveDir);
+  const archiveCallSnapshots = new Map<string, ArchiveCallSnapshot>();
   const nudgedCommandChanges = new Set<string>();
   const dirtyReactDoctorSessions = new Set<string>();
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
     event: async ({ event }: PluginEventInput) => {
+      if (event.type === "session.deleted") {
+        const sessionID = event.properties.info.id;
+        for (const [callID, snapshot] of archiveCallSnapshots) {
+          if (snapshot.sessionID === sessionID) archiveCallSnapshots.delete(callID);
+        }
+        return;
+      }
       if (event.type !== "session.idle") return;
       const sessionID = event.properties.sessionID;
       if (
@@ -340,10 +353,7 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
       }
       await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
     },
-    "tool.execute.before": async (
-      input: { tool: unknown },
-      output: { args: { filePath?: unknown; patchText?: unknown } | undefined },
-    ) => {
+    "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
       if (["write", "edit"].includes(toolName)) {
@@ -359,13 +369,24 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           }
         }
       }
+      if (context.gitAutoModeEnabled) {
+        archiveCallSnapshots.set(input.callID, {
+          sessionID: input.sessionID,
+          entries: readArchiveEntries(archiveDir),
+        });
+      }
     },
     "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
       if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
         dirtyReactDoctorSessions.add(input.sessionID);
       }
+      const archiveSnapshot = archiveCallSnapshots.get(input.callID)?.entries;
+      archiveCallSnapshots.delete(input.callID);
       appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
     },
+    dispose: async () => {
+      archiveCallSnapshots.clear();
+    },
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -103,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${FRAMEWORK_NAME} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run ${FRAMEWORK_NAME} artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
     );
   }