@uniqbit/mate-core 0.16.0 → 0.17.0-canary.10

package/src/lib/prebuilt-workspace-prepare.ts

@@ -0,0 +1,152 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { PREBUILT_BUNDLE_MARKER as BUNDLE_MARKER } from "./preinstalled-plugins";
+import {
+  currentTarget,
+  getLocalWorkspaceDir,
+  validatePrebuiltWorkspace,
+  type PrebuiltWorkspaceTarget,
+} from "./prebuilt-workspace";
+
+export type PreparePrebuiltWorkspaceResult =
+  | { ok: true; workspacePath: string; reused: boolean; packages: Record<string, string> }
+  | { ok: false; workspacePath: string; failures: string[] };
+
+export const prebuiltWorkspaceDeps = {
+  /** Filesystem-only: a plain recursive copy, never a package manager or an install script. */
+  copy: (source: string, destination: string) =>
+    fs.cp(source, destination, { recursive: true, force: true, errorOnExist: false }),
+};
+
+/**
+ * Content identity of an installed tree: a version match is not enough, since
+ * two bundles can pin the same versions and still differ.
+ */
+export async function fingerprintWorkspace(root: string): Promise<string> {
+  const hash = crypto.createHash("sha256");
+  const walk = async (dir: string, prefix: string): Promise<void> => {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (prefix === "" && entry.name === BUNDLE_MARKER) continue;
+      const full = path.join(dir, entry.name);
+      const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        hash.update(`d:${relative}\n`);
+        await walk(full, relative);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        hash.update(`l:${relative}:${await fs.readlink(full).catch(() => "")}\n`);
+        continue;
+      }
+      hash.update(`f:${relative}:`);
+      hash.update(await fs.readFile(full));
+      hash.update("\n");
+    }
+  };
+  await walk(path.resolve(root), "");
+  return hash.digest("hex");
+}
+
+async function readBundleMarker(workspacePath: string): Promise<string | null> {
+  try {
+    const marker = JSON.parse(
+      await fs.readFile(path.join(workspacePath, BUNDLE_MARKER), "utf8"),
+    ) as { fingerprint?: string };
+    return marker.fingerprint ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function samePackages(a: Record<string, string>, b: Record<string, string>): boolean {
+  const names = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const name of names) if (a[name] !== b[name]) return false;
+  return true;
+}
+
+async function exists(target: string): Promise<boolean> {
+  return fs.access(target).then(
+    () => true,
+    () => false,
+  );
+}
+
+/**
+ * Copies a validated prebuilt workspace into the companion's machine-local
+ * workspace. Presents nothing, waits for nothing, reads no selection and
+ * writes none. A changed bundle is staged and validated before it replaces the
+ * framework-owned generated workspace; any failure leaves the existing
+ * workspace exactly as it was.
+ */
+export async function preparePrebuiltWorkspace(
+  companionPath: string,
+  bundlePath: string,
+  target: PrebuiltWorkspaceTarget = currentTarget(),
+): Promise<PreparePrebuiltWorkspaceResult> {
+  const workspacePath = getLocalWorkspaceDir(companionPath);
+  const source = path.resolve(bundlePath);
+
+  const bundle = await validatePrebuiltWorkspace(source, target);
+  if (!bundle.ok) return { ok: false, workspacePath, failures: bundle.failures };
+
+  const fingerprint = await fingerprintWorkspace(source);
+  if (await exists(workspacePath)) {
+    const existing = await validatePrebuiltWorkspace(workspacePath, target);
+    if (
+      existing.ok &&
+      samePackages(existing.packages, bundle.packages) &&
+      (await readBundleMarker(workspacePath)) === fingerprint
+    ) {
+      return { ok: true, workspacePath, reused: true, packages: existing.packages };
+    }
+  }
+
+  const staging = `${workspacePath}.staging`;
+  const previous = `${workspacePath}.previous`;
+  await fs.rm(staging, { recursive: true, force: true });
+  await fs.rm(previous, { recursive: true, force: true });
+
+  try {
+    await fs.mkdir(path.dirname(workspacePath), { recursive: true });
+    await prebuiltWorkspaceDeps.copy(source, staging);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    return {
+      ok: false,
+      workspacePath,
+      failures: [`${source}: copying the bundle failed: ${(error as Error).message}`],
+    };
+  }
+
+  const staged = await validatePrebuiltWorkspace(staging, target);
+  if (!staged.ok) {
+    await fs.rm(staging, { recursive: true, force: true });
+    return { ok: false, workspacePath, failures: staged.failures };
+  }
+
+  await fs.writeFile(
+    path.join(staging, BUNDLE_MARKER),
+    `${JSON.stringify({ fingerprint, packages: staged.packages }, null, 2)}\n`,
+    "utf8",
+  );
+
+  const hadExisting = await exists(workspacePath);
+  try {
+    if (hadExisting) await fs.rename(workspacePath, previous);
+    await fs.rename(staging, workspacePath);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    if (hadExisting && !(await exists(workspacePath))) await fs.rename(previous, workspacePath);
+    return {
+      ok: false,
+      workspacePath,
+      failures: [`${workspacePath}: replacing the workspace failed: ${(error as Error).message}`],
+    };
+  }
+  await fs.rm(previous, { recursive: true, force: true });
+
+  return { ok: true, workspacePath, reused: false, packages: staged.packages };
+}

package/src/lib/prebuilt-workspace.ts

@@ -0,0 +1,246 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import semver from "semver";
+
+import { OPENCODE_PLUGIN_PACKAGE_NAME } from "./opencode-plugin-package";
+import { getCurrentVersion } from "./update-checker";
+import {
+  CONTEXT_MODE_NODE_REQUIREMENT,
+  CONTEXT_MODE_PACKAGE_NAME,
+  CONTEXT_MODE_VERSION,
+} from "./context-mode-package";
+import { enforceableNodeVersion } from "./node-engine-version";
+import { getLocalWorkspaceDir } from "./preinstalled-plugins";
+
+/**
+ * Packages the distribution selects and pins for the machine-local workspace.
+ * A bundle may carry any subset; it may carry nothing else.
+ */
+export function getDistributionLocalDependencies(): Record<string, string> {
+  return {
+    [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION,
+    [OPENCODE_PLUGIN_PACKAGE_NAME]: getCurrentVersion(),
+  };
+}
+
+/** Assets a package must carry to count as fully installed rather than merely present. */
+const REQUIRED_PACKAGE_ASSETS: Record<string, string[]> = {
+  [CONTEXT_MODE_PACKAGE_NAME]: [
+    ".claude-plugin/plugin.json",
+    "hooks/hooks.json",
+    "skills/context-mode/SKILL.md",
+    "build/adapters/opencode/plugin.js",
+  ],
+};
+
+/** Runtime requirement the distribution knows independently of the installed manifest. */
+const DECLARED_NODE_REQUIREMENTS: Record<string, string> = {
+  [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_NODE_REQUIREMENT,
+};
+
+export interface PrebuiltWorkspaceTarget {
+  platform: string;
+  arch: string;
+  /** Null where no installed Node release backs the runtime, which leaves `engines.node` unenforced. */
+  nodeVersion: string | null;
+}
+
+export interface PrebuiltWorkspaceValidation {
+  ok: boolean;
+  /** One entry per failure, each naming the package or file it is about. */
+  failures: string[];
+  /** Installed versions keyed by package name, for comparing one bundle with another. */
+  packages: Record<string, string>;
+}
+
+export function currentTarget(): PrebuiltWorkspaceTarget {
+  return { platform: process.platform, arch: process.arch, nodeVersion: enforceableNodeVersion() };
+}
+
+interface InstalledManifest {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  engines?: { node?: string };
+  os?: string[];
+  cpu?: string[];
+}
+
+async function readJson<T>(file: string): Promise<T | null> {
+  try {
+    return JSON.parse(await fs.readFile(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Node's own resolution: nearest `node_modules` first, then each ancestor up to the bundle root. */
+async function resolveFromBundle(
+  nodeModules: string,
+  fromDir: string,
+  dependency: string,
+): Promise<InstalledManifest | null> {
+  let dir = fromDir;
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", ...dependency.split("/"), "package.json");
+    const manifest = await readJson<InstalledManifest>(candidate);
+    if (manifest) return manifest;
+    if (path.resolve(dir, "node_modules") === path.resolve(nodeModules)) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function listInstalledPackages(nodeModules: string): Promise<string[]> {
+  const entries = await fs.readdir(nodeModules, { withFileTypes: true }).catch(() => []);
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name.startsWith("@")) {
+      const scoped = await fs
+        .readdir(path.join(nodeModules, entry.name), { withFileTypes: true })
+        .catch(() => []);
+      for (const child of scoped) {
+        if (child.isDirectory() || child.isSymbolicLink())
+          names.push(`${entry.name}/${child.name}`);
+      }
+      continue;
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+/**
+ * Validates an explicitly supplied, fully installed dependency bundle before
+ * anything is copied: distribution-owned versions, a complete dependency
+ * graph, integrity, target architecture, and runtime compatibility. Nothing is
+ * installed, resolved, or downloaded — every answer comes off the filesystem.
+ */
+export async function validatePrebuiltWorkspace(
+  bundlePath: string,
+  target: PrebuiltWorkspaceTarget = currentTarget(),
+): Promise<PrebuiltWorkspaceValidation> {
+  const root = path.resolve(bundlePath);
+  const failures: string[] = [];
+  const packages: Record<string, string> = {};
+
+  const manifest = await readJson<InstalledManifest>(path.join(root, "package.json"));
+  if (!manifest || typeof manifest.dependencies !== "object" || manifest.dependencies === null) {
+    return {
+      ok: false,
+      failures: [`${root}: no framework-generated package.json with a dependencies map.`],
+      packages,
+    };
+  }
+
+  const owned = getDistributionLocalDependencies();
+  const nodeModules = path.join(root, "node_modules");
+
+  for (const [name, version] of Object.entries(manifest.dependencies)) {
+    const pinned = owned[name];
+    if (pinned === undefined) {
+      failures.push(`${name}: not a distribution-owned dependency; the bundle may not carry it.`);
+      continue;
+    }
+    if (version !== pinned) {
+      failures.push(`${name}: the distribution pins ${pinned}; the bundle declares ${version}.`);
+      continue;
+    }
+
+    const installed = await readJson<InstalledManifest>(
+      path.join(nodeModules, ...name.split("/"), "package.json"),
+    );
+    if (!installed) {
+      failures.push(`${name}: declared by the bundle but not installed in its node_modules.`);
+      continue;
+    }
+    if (installed.version !== pinned) {
+      failures.push(
+        `${name}: expected ${pinned} installed; found ${installed.version ?? "an unknown version"}.`,
+      );
+      continue;
+    }
+    packages[name] = pinned;
+
+    const missingAssets: string[] = [];
+    for (const asset of REQUIRED_PACKAGE_ASSETS[name] ?? []) {
+      const assetPath = path.join(nodeModules, ...name.split("/"), ...asset.split("/"));
+      if (
+        !(await fs.access(assetPath).then(
+          () => true,
+          () => false,
+        ))
+      )
+        missingAssets.push(asset);
+    }
+    if (missingAssets.length > 0) {
+      failures.push(`${name}: installed copy is incomplete; missing ${missingAssets.join(", ")}.`);
+    }
+
+    const declaredRequirement = DECLARED_NODE_REQUIREMENTS[name];
+    if (
+      declaredRequirement &&
+      target.nodeVersion !== null &&
+      !semver.satisfies(target.nodeVersion, declaredRequirement)
+    ) {
+      failures.push(
+        `${name}: requires Node.js ${declaredRequirement}; the target runs ${target.nodeVersion}.`,
+      );
+    }
+  }
+
+  for (const name of await listInstalledPackages(nodeModules)) {
+    const packageDir = path.join(nodeModules, ...name.split("/"));
+    const installed = await readJson<InstalledManifest>(path.join(packageDir, "package.json"));
+    if (!installed) {
+      failures.push(`${name}: installed directory has no readable package.json.`);
+      continue;
+    }
+
+    if (
+      Array.isArray(installed.os) &&
+      installed.os.length > 0 &&
+      !installed.os.includes(target.platform)
+    ) {
+      failures.push(
+        `${name}: built for ${installed.os.join(", ")}; the target platform is ${target.platform}.`,
+      );
+    }
+    if (
+      Array.isArray(installed.cpu) &&
+      installed.cpu.length > 0 &&
+      !installed.cpu.includes(target.arch)
+    ) {
+      failures.push(
+        `${name}: built for ${installed.cpu.join(", ")}; the target architecture is ${target.arch}.`,
+      );
+    }
+    if (
+      installed.engines?.node &&
+      target.nodeVersion !== null &&
+      !semver.satisfies(target.nodeVersion, installed.engines.node)
+    ) {
+      failures.push(
+        `${name}: requires Node.js ${installed.engines.node}; the target runs ${target.nodeVersion}.`,
+      );
+    }
+
+    for (const dependency of Object.keys(installed.dependencies ?? {})) {
+      if (installed.optionalDependencies?.[dependency] !== undefined) continue;
+      const resolved = await resolveFromBundle(nodeModules, packageDir, dependency);
+      if (!resolved) {
+        failures.push(`${dependency}: required by ${name} but not installed in the bundle.`);
+      }
+    }
+  }
+
+  return { ok: failures.length === 0, failures, packages };
+}
+
+export { getLocalWorkspaceDir };

package/src/lib/preinstalled-plugins.ts

@@ -0,0 +1,106 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import semver from "semver";
+
+import { FRAMEWORK_NAME } from "../framework";
+import { enforceableNodeVersion } from "./node-engine-version";
+
+/**
+ * A plugin reference bound to installed files is an absolute path to the
+ * installed package root, so the Agent Runtime loads it instead of resolving,
+ * fetching, or installing the published package.
+ */
+/** The framework-owned machine-local workspace; a leaf definition, since the
+ * managed-reference predicates depend on it. */
+export function getLocalWorkspaceDir(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "plugins", ".local");
+}
+
+/**
+ * Written by prebuilt preparation, and the only mark that the distribution
+ * *supplied* an installed workspace. Ordinary setup installs into the same
+ * location, and that must keep writing the published reference.
+ */
+export const PREBUILT_BUNDLE_MARKER = ".mate-prebuilt.json";
+
+export function getPreinstalledPluginDir(companionPath: string, packageName: string): string {
+  return path.join(getLocalWorkspaceDir(companionPath), "node_modules", ...packageName.split("/"));
+}
+
+/** True for a reference that is a path whose last segment is the package itself. */
+export function isPreinstalledPluginPath(entry: unknown, packageName: string): boolean {
+  if (typeof entry !== "string") return false;
+  if (!entry.includes("/") && !entry.includes("\\")) return false;
+  const normalized = entry.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.endsWith(`/${packageName}`);
+}
+
+/**
+ * The version behind a reference bound to an installed copy.
+ *
+ * A published reference carries its version in the string; a bound one carries
+ * it in the package it points at, so staleness has to be read off disk. Shared
+ * by every site that validates a bound reference, so they cannot disagree about
+ * what "stale" means.
+ */
+export async function installedVersionAt(packageRoot: string): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: string };
+    return manifest.version;
+  } catch {
+    return undefined;
+  }
+}
+
+export class PreinstalledPluginMismatchError extends Error {}
+
+/**
+ * Resolves an installed copy of a declared plugin package from a workspace the
+ * distribution supplied. Returns null where none was supplied — the ordinary
+ * workstation, whose setup-installed workspace carries no bundle marker, so the
+ * published reference is written exactly as before. A supplied copy that does
+ * not match what the Capability declares is reported by name rather than bound,
+ * and nothing is installed to repair it.
+ */
+export async function resolvePreinstalledPluginReference(
+  companionPath: string,
+  packageName: string,
+  expectedVersion: string,
+  nodeVersion: string | null = enforceableNodeVersion(),
+): Promise<string | null> {
+  const workspace = getLocalWorkspaceDir(companionPath);
+  const supplied = await fs.access(path.join(workspace, PREBUILT_BUNDLE_MARKER)).then(
+    () => true,
+    () => false,
+  );
+  if (!supplied) return null;
+
+  const dir = getPreinstalledPluginDir(companionPath, packageName);
+  let manifest: { version?: string; engines?: { node?: string } };
+  try {
+    manifest = JSON.parse(
+      await fs.readFile(path.join(dir, "package.json"), "utf8"),
+    ) as typeof manifest;
+  } catch {
+    return null;
+  }
+
+  if (manifest.version !== expectedVersion) {
+    throw new PreinstalledPluginMismatchError(
+      `${packageName}: the installed copy at ${dir} is ${manifest.version ?? "an unknown version"}; the capability declares ${expectedVersion}.`,
+    );
+  }
+  if (
+    manifest.engines?.node &&
+    nodeVersion !== null &&
+    !semver.satisfies(nodeVersion, manifest.engines.node)
+  ) {
+    throw new PreinstalledPluginMismatchError(
+      `${packageName}: the installed copy at ${dir} requires Node.js ${manifest.engines.node}; this runtime is ${nodeVersion}.`,
+    );
+  }
+  return dir;
+}

package/src/lib/update-checker.ts

@@ -20,6 +20,42 @@ export const updateCheckerDeps = {
   toIsoString: () => new Date().toISOString(),
 };
 
+/** Declares that the installation's version is fixed by the artifact it was built into. */
+export const UPDATE_POLICY_ENV = "MATE_UPDATE_POLICY";
+
+export type UpdatePolicy = "default" | "pinned";
+
+/**
+ * Reported at most once per process: the three automatic-update entry points
+ * each consult the policy, and an unrecognized value must not be repeated.
+ */
+let unrecognizedPolicyReported = false;
+
+/** Test seam — the policy is process-wide, so its report latch must be resettable. */
+export function resetUpdatePolicyReport(): void {
+  unrecognizedPolicyReported = false;
+}
+
+export function getUpdatePolicy(env: NodeJS.ProcessEnv = process.env): UpdatePolicy {
+  const raw = env[UPDATE_POLICY_ENV];
+  if (raw === undefined || raw.trim() === "") return "default";
+
+  const value = raw.trim();
+  if (value === "pinned") return "pinned";
+
+  if (!unrecognizedPolicyReported) {
+    unrecognizedPolicyReported = true;
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: unrecognized ${UPDATE_POLICY_ENV} value \`${value}\`; automatic update handling is unchanged.\n`,
+    );
+  }
+  return "default";
+}
+
+export function isPinnedDeployment(env: NodeJS.ProcessEnv = process.env): boolean {
+  return getUpdatePolicy(env) === "pinned";
+}
+
 const updateStateFileSlug = (packageName: string): string =>
   packageName.replace(/^@/, "").replace(/[^a-zA-Z0-9._-]+/g, "-");
 
@@ -75,6 +111,7 @@ export function isNewer(latest: string, current: string): boolean {
 }
 
 export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Promise<void> {
+  if (isPinnedDeployment()) return;
   try {
     const state = await store.load();
     if (!state.latestVersion) return;
@@ -95,6 +132,7 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
  * must stop; state-load failures never block.
  */
 export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<boolean> {
+  if (isPinnedDeployment()) return false;
   if (!getUpdateConfig().enforce) return false;
   try {
     const state = await store.load();
@@ -119,6 +157,7 @@ export async function fetchLatestVersion(): Promise<string> {
 }
 
 export function scheduleBackgroundCheck(store: UpdateStateStore): Promise<void> {
+  if (isPinnedDeployment()) return Promise.resolve();
   return (async () => {
     try {
       const state = await store.load();

package/src/opencode/companion-hooks.ts

@@ -9,6 +9,7 @@ import {
   unattendedSyncStalenessLines,
 } from "../runtime/companion-sync";
 import { hasLaunchEnvironment } from "../runtime/env";
+import { MATE_ENV } from "../runtime/env-names";
 import {
   buildArtifactError,
   extractPatchPaths,
@@ -122,7 +123,12 @@ export async function repairCompanionGitOnce(
   client: PluginInput["client"] | undefined,
   env: Record<string, string | undefined> = process.env,
 ): Promise<string[]> {
-  if (!context.companionPath || hasLaunchEnvironment(env)) return [];
+  if (
+    !context.companionPath ||
+    (hasLaunchEnvironment(env) &&
+      (env[MATE_ENV.repositoryPath] !== undefined || env[MATE_ENV.gitAutoMode] !== "1"))
+  )
+    return [];
   if (repairedCompanions.has(context.companionPath)) return [];
   repairedCompanions.add(context.companionPath);
 
@@ -182,7 +188,7 @@ type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext();
-  if (!context.companionPath || !context.repositoryPath) return {};
+  if (!context.companionPath) return {};
 
   /**
    * The repair sits above the returned hooks, so anything escaping it would
@@ -195,29 +201,33 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
-    event: async ({ event }: PluginEventInput) => {
-      if (event.type !== "session.idle") return;
-      const sessionID = event.properties.sessionID;
-      if (
-        !context.reactDoctorEnabled ||
-        reactDoctorScansInFlight.has(sessionID) ||
-        !dirtyReactDoctorSessions.delete(sessionID)
-      ) {
-        return;
-      }
-      await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
-    },
+    ...(context.repositoryPath
+      ? {
+          event: async ({ event }: PluginEventInput) => {
+            if (event.type !== "session.idle") return;
+            const sessionID = event.properties.sessionID;
+            if (
+              !context.reactDoctorEnabled ||
+              reactDoctorScansInFlight.has(sessionID) ||
+              !dirtyReactDoctorSessions.delete(sessionID)
+            ) {
+              return;
+            }
+            await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
+          },
+        }
+      : {}),
     "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
-      if (["write", "edit"].includes(toolName)) {
+      if (context.repositoryPath && ["write", "edit"].includes(toolName)) {
         const filePath = String(args.filePath ?? "");
         if (filePath && shouldBlockArtifactWrite(context, filePath)) {
           throw new Error(buildArtifactError(context, filePath));
         }
         refuseForkedCompanionWrite(context, filePath);
       }
-      if (toolName === "apply_patch") {
+      if (context.repositoryPath && toolName === "apply_patch") {
         for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
           if (shouldBlockArtifactWrite(context, filePath)) {
             throw new Error(buildArtifactError(context, filePath));
@@ -225,12 +235,27 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           refuseForkedCompanionWrite(context, filePath);
         }
       }
-    },
-    "tool.execute.after": async (input: ToolAfterInput) => {
-      if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
-        dirtyReactDoctorSessions.add(input.sessionID);
+      if (!context.repositoryPath && toolName === "write") {
+        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
+      }
+      if (!context.repositoryPath && toolName === "edit") {
+        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
+      }
+      if (!context.repositoryPath && toolName === "apply_patch") {
+        for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
+          refuseForkedCompanionWrite(context, filePath);
+        }
       }
     },
+    ...(context.repositoryPath
+      ? {
+          "tool.execute.after": async (input: ToolAfterInput) => {
+            if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
+              dirtyReactDoctorSessions.add(input.sessionID);
+            }
+          },
+        }
+      : {}),
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -18,6 +18,7 @@ import { getWrapperBinPath } from "../lib/package-paths";
 
 export {
   GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
+  GRAPHIFY_COMPANION_PATH_CONTRACT,
   buildCodebaseExplorationGuidanceSection,
   hasGraphifyCapability,
   hasOpenspecCapability,