@uniqbit/mate-core 0.15.1-canary.0 → 0.15.1-canary.1

package/package.json

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

package/src/index.ts

@@ -24,6 +24,7 @@ export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli
 export type {
   CapabilityPlugin,
   InstructionsService,
+  LaunchPreflightContext,
   McpServerDescriptor,
   McpService,
   Plugin,

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

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { PUBLIC_NPM_REGISTRY } from "./public-npm";
+
+export const CONTEXT_MODE_PACKAGE_NAME = "context-mode";
+export const CONTEXT_MODE_VERSION = "1.0.169";
+export const CONTEXT_MODE_NODE_REQUIREMENT = ">=22.5.0";
+
+export function getContextModePackageReference(): string {
+  return `${CONTEXT_MODE_PACKAGE_NAME}@${CONTEXT_MODE_VERSION}`;
+}
+
+export function isContextModePackageReference(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value === CONTEXT_MODE_PACKAGE_NAME || value.startsWith(`${CONTEXT_MODE_PACKAGE_NAME}@`))
+  );
+}
+
+export function getContextModeInstallDir(companionPath: string): string {
+  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+}
+
+export function getContextModePackageRoot(companionPath: string): string {
+  return path.join(
+    getContextModeInstallDir(companionPath),
+    "node_modules",
+    CONTEXT_MODE_PACKAGE_NAME,
+  );
+}
+
+export function isContextModeNodeVersionSupported(version: string): boolean {
+  const [major = 0, minor = 0] = version.replace(/^v/, "").split(".").map(Number);
+  return major > 22 || (major === 22 && minor >= 5);
+}
+
+export function validateContextModeNodeRuntime(): void {
+  const result = spawnSync("node", ["--version"], { encoding: "utf8" });
+  const version = result.stdout?.trim() ?? "";
+  if (result.status !== 0 || !isContextModeNodeVersionSupported(version)) {
+    throw new Error(
+      `context-mode ${CONTEXT_MODE_VERSION} requires Node.js ${CONTEXT_MODE_NODE_REQUIREMENT}; found ${version || "no usable node executable"}.`,
+    );
+  }
+}
+
+export async function validateContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const root = getContextModePackageRoot(companionPath);
+  const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8")) as {
+    version?: string;
+  };
+  if (manifest.version !== CONTEXT_MODE_VERSION) {
+    throw new Error(
+      `Expected ${getContextModePackageReference()} at ${root}; found ${manifest.version ?? "an unknown version"}. Re-run \`mate companion setup\`.`,
+    );
+  }
+  await Promise.all(
+    [
+      ".claude-plugin/plugin.json",
+      "hooks/hooks.json",
+      "skills/context-mode/SKILL.md",
+      "build/adapters/opencode/plugin.js",
+    ].map((asset) => fs.access(path.join(root, asset))),
+  );
+}
+
+export async function installContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const installDir = getContextModeInstallDir(companionPath);
+  await fs.mkdir(installDir, { recursive: true });
+  await fs.writeFile(
+    path.join(installDir, "package.json"),
+    JSON.stringify(
+      { private: true, dependencies: { [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION } },
+      null,
+      2,
+    ) + "\n",
+    "utf8",
+  );
+  const result = spawnSync(
+    "npm",
+    ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
+    { cwd: installDir, encoding: "utf8" },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `Could not install ${getContextModePackageReference()}: ${result.error?.message ?? result.stderr?.trim() ?? `npm exited with ${result.status}`}`,
+    );
+  }
+  await validateContextModePackage(companionPath);
+}

package/src/lib/opencode-plugin-package.ts

@@ -44,53 +44,50 @@ export const opencodePluginCacheDeps = {
     }),
 };
 
-/**
- * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
- * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
- * layout, so the first managed launch after a setup or update does not depend
- * on registry access. Best effort: failures are reported, never thrown.
- */
-export async function warmOpenCodePluginCache(
-  version: string = getCurrentVersion(),
+export async function warmOpenCodePackageCache(
+  packageName: string,
+  packageReference: string,
   env: NodeJS.ProcessEnv = process.env,
   registry = PUBLIC_NPM_REGISTRY,
 ): Promise<WarmPluginCacheResult> {
-  // Escape hatch for tests and intentionally offline environments: skip the
-  // pre-fetch entirely instead of attempting a registry install.
   if (env.MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH === "1") {
     return { ok: true, detail: "pre-fetch disabled via MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH" };
   }
-
-  const reference = getOpenCodePluginPackageReference(version);
-  const specDir = path.join(getOpenCodeCacheDir(env), "packages", reference);
-
+  const version = packageReference.slice(packageName.length + 1);
+  const specDir = path.join(getOpenCodeCacheDir(env), "packages", packageReference);
   try {
     await fs.mkdir(specDir, { recursive: true });
     await fs.writeFile(
       path.join(specDir, "package.json"),
-      JSON.stringify({ dependencies: { [OPENCODE_PLUGIN_PACKAGE_NAME]: version } }, null, 2) + "\n",
+      JSON.stringify({ dependencies: { [packageName]: version } }, null, 2) + "\n",
       "utf8",
     );
-
     const result = opencodePluginCacheDeps.runInstall(specDir, registry);
-    if (result.error) {
-      return { ok: false, detail: result.error.message };
-    }
+    if (result.error) return { ok: false, detail: result.error.message };
     if (result.status !== 0) {
-      const output = `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`;
-      return { ok: false, detail: output };
+      return {
+        ok: false,
+        detail: `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`,
+      };
     }
-
-    await fs.access(
-      path.join(
-        specDir,
-        "node_modules",
-        ...OPENCODE_PLUGIN_PACKAGE_NAME.split("/"),
-        "package.json",
-      ),
-    );
+    await fs.access(path.join(specDir, "node_modules", ...packageName.split("/"), "package.json"));
     return { ok: true };
   } catch (error) {
     return { ok: false, detail: (error as Error).message };
   }
 }
+
+/**
+ * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
+ * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
+ * layout, so the first managed launch after a setup or update does not depend
+ * on registry access. Best effort: failures are reported, never thrown.
+ */
+export async function warmOpenCodePluginCache(
+  version: string = getCurrentVersion(),
+  env: NodeJS.ProcessEnv = process.env,
+  registry = PUBLIC_NPM_REGISTRY,
+): Promise<WarmPluginCacheResult> {
+  const reference = getOpenCodePluginPackageReference(version);
+  return warmOpenCodePackageCache(OPENCODE_PLUGIN_PACKAGE_NAME, reference, env, registry);
+}

package/src/lib/orchestrator/adapters/claude.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 
 import { buildCompanionGuidance } from "../../../playbooks/companion-guidance";
+import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
 import {
   getCompanionClaudeMcpConfigPath,
   getCompanionClaudeSettingsPath,
@@ -11,6 +12,19 @@ export class ClaudeAdapter extends LaunchAdapter {
   readonly toolName = "claude";
   readonly interactive = true;
 
+  async validateLaunch(context: AdapterContext): Promise<void> {
+    if (context.capabilities.some((capability) => capability.name === "context-mode")) {
+      try {
+        await validateContextModePackage(context.companionPath);
+      } catch (error) {
+        throw new Error(
+          `Claude context-mode plugin is unavailable: ${(error as Error).message} Repair it with \`mate companion setup\`.`,
+          { cause: error },
+        );
+      }
+    }
+  }
+
   buildArgs(context: AdapterContext, args: string[]): string[] {
     // Load Mate-managed Claude config from companion settings when present,
     // layered on top of the user's user/project/local sources so global
@@ -29,6 +43,11 @@ export class ClaudeAdapter extends LaunchAdapter {
     const mcpConfigArgs = existsSync(companionMcpConfigPath)
       ? ["--mcp-config", companionMcpConfigPath]
       : [];
+    const contextModeArgs = context.capabilities.some(
+      (capability) => capability.name === "context-mode",
+    )
+      ? ["--plugin-dir", getContextModePackageRoot(context.companionPath)]
+      : [];
 
     return [
       "--add-dir",
@@ -37,6 +56,7 @@ export class ClaudeAdapter extends LaunchAdapter {
       buildCompanionGuidance(context),
       ...settingsArgs,
       ...mcpConfigArgs,
+      ...contextModeArgs,
       ...args,
     ];
   }

package/src/lib/orchestrator/adapters/opencode.ts

@@ -171,7 +171,6 @@ export class OpenCodeAdapter extends LaunchAdapter {
       )),
       ...this.validateGuidance(context),
     ];
-
     if (errors.length > 0) {
       throw new LaunchPreflightError(
         [
@@ -197,9 +196,11 @@ export class OpenCodeAdapter extends LaunchAdapter {
     } catch {
       return [`Unreadable OpenCode configuration: ${configPath}`];
     }
+    if (!isRecord(config)) {
+      return [`Unreadable OpenCode configuration: ${configPath}`];
+    }
 
-    const plugins =
-      isRecord(config) && Array.isArray(config.plugin) ? (config.plugin as unknown[]) : [];
+    const plugins = Array.isArray(config.plugin) ? (config.plugin as unknown[]) : [];
     const mateReferences = plugins.filter(isMateOpenCodePluginReference) as string[];
 
     if (mateReferences.includes(expectedPluginReference)) {

package/src/lib/orchestrator/launcher.ts

@@ -1,5 +1,7 @@
 // oxlint-disable no-underscore-dangle
 import { syncCompanionFiles, syncWorkingRepoClaudeSettings } from "../../tools/setup";
+import { getActiveDistribution } from "../../distribution";
+import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
 import type { LaunchAdapter, AdapterContext } from "./adapters/base";
 import { ClaudeAdapter } from "./adapters/claude";
 import { OpenCodeAdapter } from "./adapters/opencode";
@@ -8,6 +10,7 @@ import { syncCompanionGit } from "./companion-git-sync";
 import { resolveForLaunch, type LaunchContext } from "./framework-context";
 import {
   RepositoryNotSelectedError,
+  LaunchPreflightError,
   ToolNotAllowedError,
   type FrameworkConfig,
   type LaunchRequest,
@@ -70,6 +73,7 @@ export class FrameworkLauncher {
       state.companionPath,
       state.config,
     );
+    await this.runCapabilityPreflight(state, request.tool);
     await state.adapter.validateLaunch(adapterContext);
 
     return {
@@ -127,6 +131,54 @@ export class FrameworkLauncher {
     };
   }
 
+  private async runCapabilityPreflight(
+    state: ResolvedLaunchState,
+    providerId: string,
+  ): Promise<void> {
+    const context: LaunchPreflightContext = {
+      companionPath: state.companionPath,
+      config: state.config,
+      repository: state.repository,
+      providerId,
+    };
+    const preflights = getActiveDistribution()
+      .registry.getAll()
+      .reduce<
+        Array<{
+          capability: CapabilityPlugin;
+          preflight: NonNullable<NonNullable<CapabilityPlugin["forProvider"]>[string]["preflight"]>;
+        }>
+      >((entries, plugin) => {
+        if (plugin.kind !== "capability" || !plugin.isEnabled(state.config)) return entries;
+        const capability = plugin as CapabilityPlugin;
+        const preflight = capability.forProvider?.[providerId]?.preflight;
+        if (preflight) entries.push({ capability, preflight });
+        return entries;
+      }, []);
+    const results = await Promise.all(
+      preflights.map(async ({ capability, preflight }) => {
+        try {
+          return await preflight(context);
+        } catch (error) {
+          const detail = error instanceof Error ? error.message : String(error);
+          throw new LaunchPreflightError(
+            `Capability preflight failed for ${capability.id} on ${providerId}: ${detail}`,
+            { cause: error },
+          );
+        }
+      }),
+    );
+    const diagnostics = results.flat();
+
+    if (diagnostics.length > 0) {
+      throw new LaunchPreflightError(
+        ["Capability launch preflight failed.", ...diagnostics.map((item) => `- ${item}`)].join(
+          "\n",
+        ),
+      );
+    }
+  }
+
   private async resolveConfig(): Promise<LaunchContext> {
     return resolveForLaunch(process.cwd());
   }

package/src/plugins.ts

@@ -14,4 +14,5 @@ export { createTokensavePlugin } from "./tools/setup/capabilities/tokensave";
 export { createHeadroomPlugin } from "./tools/setup/capabilities/headroom";
 export { createRtkPlugin } from "./tools/setup/capabilities/rtk";
 export { createGraphifyPlugin } from "./tools/setup/capabilities/graphify";
+export { createContextModePlugin } from "./tools/setup/capabilities/context-mode";
 export { createGitignorePlugin } from "./tools/setup/plugins/gitignore";

package/src/templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh

@@ -39,6 +39,23 @@ function shellSplit(command) {
       quote = null;
       continue;
     }
+    const next = command[index + 1] || "";
+    const previous = command[index - 1] || "";
+    const isControlOperator = !quote && (
+      char === ";" || char === "|" ||
+      (char === "&" && next !== ">" && previous !== ">" && previous !== "<")
+    );
+    if (isControlOperator) {
+      if (current) parts.push(current);
+      current = "";
+      if ((char === "|" || char === "&") && next === char) {
+        parts.push(char + next);
+        index += 1;
+      } else {
+        parts.push(char);
+      }
+      continue;
+    }
     if (!quote && /\s/.test(char)) {
       if (current) parts.push(current);
       current = "";
@@ -55,6 +72,13 @@ function extractChangeFromPath(value) {
   return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
 }
 
+// Shell syntax tokens are never change-name positionals: separators end the
+// archive invocation, redirections are skipped (a bare operator also consumes
+// its target token).
+const separatorPattern = /^(\|\|?|&&?|;)$/;
+const redirectionPattern = /^(\d*(>>?|<)|&>>?)/;
+const bareRedirectionPattern = /^(\d*(>>?|<)|&>>?)$/;
+
 function extractArchiveCommand(command) {
   const parts = shellSplit(command);
   const index = parts.findIndex((part, position) =>
@@ -64,6 +88,11 @@ function extractArchiveCommand(command) {
   for (let position = index + 1; position < parts.length; position += 1) {
     const part = parts[position];
     if (!part || part === "--") continue;
+    if (separatorPattern.test(part)) return null;
+    if (redirectionPattern.test(part)) {
+      if (bareRedirectionPattern.test(part)) position += 1;
+      continue;
+    }
     if (part.startsWith("-")) {
       if (part === "--store") position += 1;
       continue;
@@ -93,27 +122,38 @@ function extractMoveCommand(command) {
   return null;
 }
 
+// Nudge only on apparent success: stay silent on a clear failure indication,
+// nudge when success is indicated or indeterminate.
+function isClearFailure(response) {
+  if (!response || typeof response !== "object") return false;
+  if (response.success === false || response.is_error === true) return true;
+  if (typeof response.error === "string" && response.error) return true;
+  if (response.interrupted === true) return true;
+  const exitCode = response.exit_code ?? response.exitCode;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
 let input = {};
 try {
   input = JSON.parse(fs.readFileSync(inputFile, "utf8") || "{}");
 } catch {}
 
-if (input.hook_event_name !== "PreToolUse" || input.tool_name !== "Bash") process.exit(0);
+if (input.hook_event_name !== "PostToolUse" || input.tool_name !== "Bash") process.exit(0);
 const command = input.tool_input && typeof input.tool_input.command === "string"
   ? input.tool_input.command
   : "";
 const change = extractArchiveCommand(command) || extractMoveCommand(command);
 if (!change) process.exit(0);
+if (isClearFailure(input.tool_response)) process.exit(0);
 
-const reason =
-  "Standalone archival for OpenSpec change " + change + " is blocked. Invoke the " +
-  "mate-artifact-finish skill, then run `mate artifact finish \"" + change + "\" --json`. " +
-  "The finish command performs the normal OpenSpec archive and completes commit, tag, and push.";
+const context =
+  "OpenSpec change " + change + " was just archived. Invoke the mate-artifact-finish " +
+  "skill, then run `mate artifact finish \"" + change + "\" --json` to complete the " +
+  "finish workflow (commit, tag, and push).";
 process.stdout.write(JSON.stringify({
   hookSpecificOutput: {
-    hookEventName: "PreToolUse",
-    permissionDecision: "deny",
-    permissionDecisionReason: reason,
+    hookEventName: "PostToolUse",
+    additionalContext: context,
   },
 }));
 ' "$input_file"

package/src/tools/setup/capabilities/context-mode.ts

@@ -0,0 +1,197 @@
+// oxlint-disable no-await-in-loop -- config files are reconciled sequentially with shared ownership state
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  CONTEXT_MODE_PACKAGE_NAME,
+  getContextModeInstallDir,
+  getContextModePackageReference,
+  installContextModePackage,
+  isContextModePackageReference,
+  validateContextModePackage,
+} from "../../../lib/context-mode-package";
+import { warmOpenCodePackageCache } from "../../../lib/opencode-plugin-package";
+import type { CapabilityPlugin, LaunchPreflightContext, SetupContext } from "../plugin";
+import { pruneEmptyAncestors } from "../utils";
+
+type Config = Record<string, unknown>;
+interface ContextModePluginDeps {
+  installPackage?: typeof installContextModePackage;
+  validatePackage?: typeof validateContextModePackage;
+  warmOpenCodePackage?: typeof warmOpenCodePackageCache;
+}
+interface OwnershipState {
+  opencodeConfigs: string[];
+}
+
+export const CONTEXT_MODE_OPENCODE_GUIDANCE = `## Context Mode
+
+Use Context Mode tools for commands or tool calls whose output may be large, for sandboxed analysis of large files or structured data, and when indexing large fetched content.
+
+Canonical Mate policy and any more specific tool-routing instructions remain authoritative. In particular, follow explicit requirements to use TokenSave for codebase exploration, Context7 for library documentation, and specialized tools for their assigned operations; Context Mode complements rather than replaces them.`;
+
+function getOwnershipPath(companionPath: string): string {
+  return path.join(companionPath, ".mate", "state", "context-mode.json");
+}
+
+async function readOwnership(companionPath: string): Promise<OwnershipState> {
+  try {
+    return JSON.parse(await fs.readFile(getOwnershipPath(companionPath), "utf8")) as OwnershipState;
+  } catch {
+    return { opencodeConfigs: [] };
+  }
+}
+
+async function writeOwnership(companionPath: string, state: OwnershipState): Promise<void> {
+  const statePath = getOwnershipPath(companionPath);
+  if (state.opencodeConfigs.length === 0) {
+    await fs.rm(statePath, { force: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(statePath, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+function isRecord(value: unknown): value is Config {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readConfig(filePath: string): Promise<Config> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function hasContextModeMcp(config: Config): boolean {
+  const servers = isRecord(config.mcpServers)
+    ? config.mcpServers
+    : isRecord(config.mcp)
+      ? config.mcp
+      : {};
+  return Object.entries(servers).some(
+    ([name, value]) =>
+      name.toLowerCase().includes("context-mode") || JSON.stringify(value).includes("context-mode"),
+  );
+}
+
+async function assertNoMcpConflict(ctx: SetupContext, provider: "claude" | "opencode") {
+  const configPath =
+    provider === "claude"
+      ? path.join(ctx.companionPath, ".mcp.json")
+      : path.join(ctx.companionPath, ".opencode", "opencode.json");
+  if (hasContextModeMcp(await readConfig(configPath))) {
+    throw new Error(
+      `Cannot enable context-mode for ${provider}: ${configPath} already contains a context-mode MCP registration. Remove the duplicate registration or deselect the context-mode capability; Mate did not modify it.`,
+    );
+  }
+}
+
+async function updateOpenCodeConfig(ctx: SetupContext, enabled: boolean): Promise<void> {
+  const reference = getContextModePackageReference();
+  const ownership = await readOwnership(ctx.companionPath);
+  for (const name of ["opencode.json", "tui.json"]) {
+    const configPath = path.join(ctx.companionPath, ".opencode", name);
+    const owned = ownership.opencodeConfigs.includes(name);
+    if (!enabled && !owned) continue;
+    const config = await readConfig(configPath);
+    const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+    const contextModeReferences = plugins.filter(isContextModePackageReference);
+    if (enabled && contextModeReferences.some((entry) => entry !== reference)) {
+      throw new Error(
+        `Cannot enable ${reference}: ${configPath} contains user-owned context-mode reference ${contextModeReferences.join(", ")}. Mate did not modify it.`,
+      );
+    }
+    const preserved = plugins.filter((entry) => !(entry === reference && owned));
+    if (enabled) {
+      if (!contextModeReferences.includes(reference)) {
+        config.plugin = [...plugins, reference];
+        ownership.opencodeConfigs.push(name);
+      }
+    } else if (preserved.length > 0) {
+      config.plugin = preserved;
+    } else {
+      delete config.plugin;
+    }
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  }
+  if (!enabled) ownership.opencodeConfigs = [];
+  await writeOwnership(ctx.companionPath, ownership);
+}
+
+async function validateOpenCodeReferences(ctx: LaunchPreflightContext): Promise<string[]> {
+  const expected = getContextModePackageReference();
+  const diagnostics: string[] = [];
+  for (const name of ["opencode.json", "tui.json"]) {
+    const configPath = path.join(ctx.companionPath, ".opencode", name);
+    const config = await readConfig(configPath);
+    const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+    if (!plugins.includes(expected)) {
+      diagnostics.push(
+        `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+      );
+    }
+  }
+  return diagnostics;
+}
+
+export function createContextModePlugin(deps: ContextModePluginDeps = {}): CapabilityPlugin {
+  const installPackage = deps.installPackage ?? installContextModePackage;
+  const validatePackage = deps.validatePackage ?? validateContextModePackage;
+  const warmOpenCodePackage = deps.warmOpenCodePackage ?? warmOpenCodePackageCache;
+  return {
+    id: "context-mode",
+    kind: "capability",
+    label: "Context Mode",
+    description: "Protect context windows with pinned native Claude and OpenCode plugins.",
+    defaultSelected: false,
+    isEnabled: (config) =>
+      (config.capabilities ?? []).some((capability) => capability.name === "context-mode"),
+    async apply(ctx) {
+      if (ctx.mode === "setup") {
+        await installPackage(ctx.companionPath);
+      } else {
+        await validatePackage(ctx.companionPath);
+      }
+      await ctx.instructions?.append(CONTEXT_MODE_OPENCODE_GUIDANCE, {
+        providers: ["opencode"],
+      });
+    },
+    async teardown(ctx) {
+      await fs.rm(getContextModeInstallDir(ctx.companionPath), { recursive: true, force: true });
+      await pruneEmptyAncestors(getContextModeInstallDir(ctx.companionPath), ctx.companionPath);
+    },
+    forProvider: {
+      claude: {
+        async apply(ctx) {
+          await assertNoMcpConflict(ctx, "claude");
+        },
+        async teardown() {},
+      },
+      opencode: {
+        preflight: validateOpenCodeReferences,
+        async apply(ctx) {
+          await assertNoMcpConflict(ctx, "opencode");
+          await updateOpenCodeConfig(ctx, true);
+          if (ctx.mode === "setup") {
+            const result = await warmOpenCodePackage(
+              CONTEXT_MODE_PACKAGE_NAME,
+              getContextModePackageReference(),
+            );
+            if (!result.ok) {
+              process.stderr.write(
+                `mate: could not pre-fetch ${getContextModePackageReference()} for OpenCode: ${result.detail ?? "unknown error"}\n`,
+              );
+            }
+          }
+        },
+        async teardown(ctx) {
+          await updateOpenCodeConfig(ctx, false);
+        },
+      },
+    },
+  };
+}

package/src/tools/setup/context-services.ts

@@ -234,8 +234,12 @@ export class ContextServiceMediator {
     };
 
     const instructions: InstructionsService = {
-      append: async (content: string) => {
-        const hosts = hostingProviders.filter((provider) => provider.hosting.instructions);
+      append: async (content: string, options) => {
+        const hosts = hostingProviders.filter(
+          (provider) =>
+            provider.hosting.instructions &&
+            (options?.providers === undefined || options.providers.includes(provider.id)),
+        );
         if (hosts.length === 0) {
           warn(`${pluginId}: no active provider hosts instruction injection; skipping append`);
           return;

package/src/tools/setup/plugin.ts

@@ -1,4 +1,4 @@
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 
 export interface SetupContext {
@@ -18,6 +18,13 @@ export interface SetupContext {
   templates?: TemplatesService;
 }
 
+export interface LaunchPreflightContext {
+  companionPath: string;
+  config: FrameworkConfig;
+  repository: LinkedRepository;
+  providerId: string;
+}
+
 /** Provider-agnostic description of an MCP server to register. */
 export interface McpServerDescriptor {
   name: string;
@@ -32,7 +39,7 @@ export interface McpService {
 }
 
 export interface InstructionsService {
-  append(content: string): Promise<void>;
+  append(content: string, options?: { providers?: string[] }): Promise<void>;
 }
 
 export interface TemplatesService {
@@ -113,6 +120,7 @@ export interface CapabilityPlugin extends Plugin {
     {
       apply(ctx: SetupContext): Promise<void>;
       teardown(ctx: SetupContext): Promise<void>;
+      preflight?(ctx: LaunchPreflightContext): Promise<string[]>;
     }
   >;
 }

package/src/tools/setup/providers/claude.ts

@@ -267,7 +267,7 @@ function buildManagedClaudeSettings(
     ...(hooks.SessionStart ?? []),
   ];
   if (openspecEnabled) {
-    hooks.PreToolUse = [
+    hooks.PostToolUse = [
       {
         matcher: "Bash",
         hooks: [
@@ -277,7 +277,7 @@ function buildManagedClaudeSettings(
           },
         ],
       },
-      ...(hooks.PreToolUse ?? []),
+      ...(hooks.PostToolUse ?? []),
     ];
   }
   if (reactDoctorEnabled) {