@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/tools/setup/providers/claude-plugin-hooks.ts

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { PROJECTED_BANNER_FLAG } from "../../../hooks/session-banner";
+import { getClaudePluginRoot } from "../../../lib/package-paths";
+import type { ClaudeHookGroup } from "./claude-format";
+
+/**
+ * The bundled Claude plugin's hook wiring, read as a value. A managed launch
+ * loads it with `--plugin-dir`; an Unmanaged Session loads no plugin dir at
+ * all, so the working-target settings document has to carry it instead.
+ *
+ * A managed session loads the Working Repository's settings as its `local`
+ * source *alongside* the plugin, so every group carried over runs twice there.
+ * All three survive that: the guard, whose verdict is a function of the tool
+ * input alone; the guidance hook, which yields nothing when a launch
+ * environment is present and so cannot double the prompt the launch already
+ * appended; and the banner, whose carried copy is marked so it defers to the
+ * launch's.
+ */
+
+const GUARD_HOOK_SHIM = "validate-artifact-path.mjs";
+const GUIDANCE_HOOK_SHIM = "session-guidance.mjs";
+const BANNER_HOOK_SHIM = "session-banner.mjs";
+const PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}";
+
+interface PluginHookWiring {
+  hooks?: Record<string, ClaudeHookGroup[]>;
+}
+
+function readPluginHookWiring(pluginRoot: string): PluginHookWiring {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(pluginRoot, "hooks", "hooks.json"), "utf8"),
+    ) as unknown;
+    if (parsed && typeof parsed === "object") return parsed as PluginHookWiring;
+  } catch {
+    /* an installation missing its plugin assets contributes no hooks */
+  }
+  return {};
+}
+
+function resolveCommands(group: ClaudeHookGroup, pluginRoot: string): ClaudeHookGroup {
+  return {
+    ...group,
+    hooks: (group.hooks ?? []).map((hook) => ({
+      ...hook,
+      ...(hook.command ? { command: hook.command.split(PLUGIN_ROOT_TOKEN).join(pluginRoot) } : {}),
+    })),
+  };
+}
+
+function runsShim(shim: string): (group: ClaudeHookGroup) => boolean {
+  return (group) => (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
+}
+
+function groupsFor(
+  event: string,
+  shim: string,
+  pluginRoot: string = getClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return (readPluginHookWiring(pluginRoot).hooks?.[event] ?? [])
+    .filter(runsShim(shim))
+    .map((group) => resolveCommands(group, pluginRoot));
+}
+
+/**
+ * The guard's `PreToolUse` groups with `${CLAUDE_PLUGIN_ROOT}` resolved against
+ * the running installation, so the command works with no launch environment.
+ */
+export function mateGuardHookGroups(pluginRoot: string = getClaudePluginRoot()): ClaudeHookGroup[] {
+  return groupsFor("PreToolUse", GUARD_HOOK_SHIM, pluginRoot);
+}
+
+/**
+ * The guidance hook's `SessionStart` groups, resolved the same way. This is the
+ * channel that replaces `--append-system-prompt` where no launch supplies one:
+ * a settings document can declare a hook, and there is no settings key for the
+ * flag.
+ */
+export function mateGuidanceHookGroups(
+  pluginRoot: string = getClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("SessionStart", GUIDANCE_HOOK_SHIM, pluginRoot);
+}
+
+/**
+ * The banner's `SessionStart` group, resolved the same way and carrying
+ * `PROJECTED_BANNER_FLAG`. Without the marker the carried command would be
+ * byte-identical to the plugin's, and a managed session — which loads both —
+ * would print the banner twice.
+ */
+export function mateBannerHookGroups(
+  pluginRoot: string = getClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("SessionStart", BANNER_HOOK_SHIM, pluginRoot).map((group) => ({
+    ...group,
+    hooks: (group.hooks ?? []).map((hook) => ({
+      ...hook,
+      ...(hook.command ? { command: `${hook.command} ${PROJECTED_BANNER_FLAG}` } : {}),
+    })),
+  }));
+}
+
+/**
+ * Whether a hook group is one the working target placed. It matches a managed
+ * marker, so the entry that strips managed groups from a Working Repository has
+ * to be told to leave these alone.
+ */
+export function isMateGuardHookGroup(group: ClaudeHookGroup): boolean {
+  const own = new Set(
+    [...mateGuardHookGroups(), ...mateGuidanceHookGroups(), ...mateBannerHookGroups()].map(
+      (candidate) => JSON.stringify(candidate),
+    ),
+  );
+  return own.has(JSON.stringify(group));
+}

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

@@ -3,33 +3,22 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
-import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import type { FrameworkConfig } from "../../../lib/orchestrator/types";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
-import {
-  TOKENSAVE_CLAUDE_MD_MARKER,
-  TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES,
-} from "../capabilities/tokensave-shared";
 import {
   instructionBlockKey,
   removeManagedBlocksForPlugin,
   upsertManagedBlock,
 } from "../context-services";
 import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
+import { surfaceRoot } from "../surface-target";
 import { mergeDir, pruneEmptyAncestors } from "../utils";
-import {
-  ensureWorkingRepoLocalExcludes,
-  reconcileWorkingRepoCapabilityExcludes,
-} from "../working-repo-local-state";
-import {
-  cutFromMarker,
-  stripSectionFromFile,
-  type RemoveHeadingSectionOptions,
-} from "./agent-file-sections";
+import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
 import { patchSkillTreeMarkdownFiles } from "./skill-tree";
 import {
   filterClaudeHookGroups,
   mergeClaudeHookGroups,
+  removeManagedHookGroups,
   readClaudeMcpConfig,
   readClaudeSettings,
   toClaudeMcpEntry,
@@ -68,19 +57,6 @@ const COMPANION_GITIGNORE_ENTRIES = [
   ".claude/state/",
 ];
 
-// Command substrings that mark a working-repo hook group as Mate-managed.
-// The mate plugin hooks (validate-artifact-path, mate-session-banner,
-// mate-artifact-finish.sh) now ship in the bundled Claude plugin; their
-// markers are retained migration-only so stale managed groups written by
-// earlier releases keep being stripped, and are never re-added.
-const MANAGED_HOOK_MARKERS = [
-  "validate-artifact-path",
-  "mate-session-banner",
-  "react-doctor.sh",
-  "mate-artifact-finish.sh",
-  "tokensave",
-];
-
 // Hook files earlier releases copied into the companion; the bundled Claude
 // plugin replaced them. Setup and launch sync delete stale copies.
 const LEGACY_MATE_HOOK_FILES = [
@@ -126,51 +102,6 @@ function getAllManagedPermissionEntries(companionPath: string): Set<string> {
   ]);
 }
 
-function isManagedHookGroup(group: ClaudeHookGroup, extraMarkers: string[] = []): boolean {
-  return (group.hooks ?? []).some((hook) =>
-    [...MANAGED_HOOK_MARKERS, ...extraMarkers].some((marker) =>
-      (hook.command ?? "").includes(marker),
-    ),
-  );
-}
-
-function removeManagedHookGroups(
-  settings: ClaudeSettings,
-  extraMarkers: string[] = [],
-): ClaudeSettings {
-  const hooks = filterClaudeHookGroups(
-    settings.hooks ?? {},
-    (group) => !isManagedHookGroup(group, extraMarkers),
-  );
-
-  const next = { ...settings };
-  if (Object.keys(hooks).length > 0) {
-    next.hooks = hooks;
-  } else {
-    delete next.hooks;
-  }
-  return next;
-}
-
-async function stripTokensaveClaudeMdAppend(workingRepoPath: string): Promise<boolean> {
-  const claudeMdPath = path.join(workingRepoPath, "CLAUDE.md");
-  let content: string;
-  try {
-    content = await fs.readFile(claudeMdPath, "utf8");
-  } catch {
-    return false;
-  }
-
-  const stripped = cutFromMarker(content, TOKENSAVE_CLAUDE_MD_MARKER);
-  if (stripped === content) return false;
-  if (stripped.length > 0) {
-    await fs.writeFile(claudeMdPath, stripped, "utf8");
-  } else {
-    await fs.unlink(claudeMdPath);
-  }
-  return true;
-}
-
 // Resolved path of the companion-owned Claude settings document. This is the
 // single source of truth for Mate-managed Claude hooks, permissions, and MCP
 // servers; it is loaded at launch via `claude --settings`.
@@ -185,11 +116,42 @@ export function getCompanionClaudeMcpConfigPath(companionPath: string): string {
   return path.join(companionPath, ".mcp.json");
 }
 
+/**
+ * The Mate-managed `permissions.allow` entries of one pass, in emitted order.
+ * Rendered separately from the settings document so a working-target pass can
+ * obtain them without a write.
+ */
+export function renderManagedClaudePermissionEntries(
+  companionPath: string,
+  contributions: CapabilityContributionInput[] = [],
+): string[] {
+  return [
+    ...getBaseManagedPermissionEntries(companionPath),
+    ...contributions
+      .filter((input) => input.enabled)
+      .flatMap((input) => input.contributions.permissionEntries ?? []),
+  ];
+}
+
+/** The Mate-managed `.mcp.json` server map of one pass, as a value. */
+export function renderManagedClaudeMcpServers(
+  contributions: CapabilityContributionInput[] = [],
+): Record<string, unknown> {
+  const servers: Record<string, unknown> = {};
+  for (const input of contributions) {
+    if (!input.enabled) continue;
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      servers[descriptor.name] = toClaudeMcpEntry(descriptor);
+    }
+  }
+  return servers;
+}
+
 // Reconcile the Mate-managed Claude settings shape (hooks, permissions, MCP
 // servers) on top of whatever already exists in the settings document. Managed
 // groups/entries always lead their arrays so the emitted shape stays stable
 // across syncs; unmanaged content is preserved untouched.
-function buildManagedClaudeSettings(
+export function renderManagedClaudeSettings(
   existing: ClaudeSettings,
   companionPath: string,
   config: FrameworkConfig,
@@ -203,12 +165,8 @@ function buildManagedClaudeSettings(
   const declaredPermissionEntries = contributions.flatMap(
     (input) => input.contributions.permissionEntries ?? [],
   );
-  const enabledDeclaredPermissionEntries = contributions
-    .filter((input) => input.enabled)
-    .flatMap((input) => input.contributions.permissionEntries ?? []);
-
-  // Mate's own hooks (artifact-path guard, session banner, archive-finish
-  // nudge) ship in the bundled Claude plugin loaded at launch; settings-sync
+  // Mate's own hooks (artifact-path guard, session banner, companion
+  // guidance) ship in the bundled Claude plugin loaded at launch; settings-sync
   // only strips their legacy managed groups (via removeManagedHookGroups) and
   // reconciles the capability hooks that remain settings-delivered.
   const hooks = removeManagedHookGroups(existing, declaredMarkers).hooks ?? {};
@@ -233,10 +191,7 @@ function buildManagedClaudeSettings(
     ...getAllManagedPermissionEntries(companionPath),
     ...declaredPermissionEntries,
   ]);
-  const managedAllow = [
-    ...getBaseManagedPermissionEntries(companionPath),
-    ...enabledDeclaredPermissionEntries,
-  ];
+  const managedAllow = renderManagedClaudePermissionEntries(companionPath, contributions);
   const existingPermissions = existing.permissions ?? {};
   const existingAllow = Array.isArray(existingPermissions.allow) ? existingPermissions.allow : [];
   const nextAllow = [
@@ -284,7 +239,7 @@ export async function syncCompanionClaudeSettings(
 ): Promise<void> {
   const settingsPath = getCompanionClaudeSettingsPath(companionPath);
   const existing = await readClaudeSettings(settingsPath);
-  const settings = buildManagedClaudeSettings(existing, companionPath, config, contributions);
+  const settings = renderManagedClaudeSettings(existing, companionPath, config, contributions);
 
   await writeClaudeSettings(settingsPath, settings);
 
@@ -302,11 +257,13 @@ export async function reconcileClaudeContributions(
   ctx: SetupContext,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
-  const { companionPath, config } = ctx;
+  /** Resolved once per pass; every write site below is relative to it. */
+  const root = surfaceRoot(ctx);
+  const { config } = ctx;
 
   if (ctx.scope === "hub") {
-    await reconcileClaudeMcpContributions(ctx, inputs);
-    await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
+    await reconcileClaudeMcpContributions(root, inputs);
+    await reconcileClaudeAgentDefinitionContributions(root, inputs);
     return;
   }
 
@@ -314,17 +271,17 @@ export async function reconcileClaudeContributions(
   // runs while the Claude runtime is active; a deactivated runtime's pass is
   // teardown-only and must not resurrect files the provider teardown removed.
   if (ctx.activeProviders.includes("claude")) {
-    await syncCompanionClaudeSettings(companionPath, config, inputs);
+    await syncCompanionClaudeSettings(root, config, inputs);
   }
 
-  await reconcileClaudeMcpContributions(ctx, inputs);
-  await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
+  await reconcileClaudeMcpContributions(root, inputs);
+  await reconcileClaudeAgentDefinitionContributions(root, inputs);
 
   for (const input of inputs) {
     // Guidance sections are managed blocks in CLAUDE.md. Current sections are
     // upserted, then stale keys (content changes, disabled capability) are
     // swept. CLAUDE.md is Claude-exclusive, so no shared-file guard applies.
-    const guidancePath = path.join(companionPath, "CLAUDE.md");
+    const guidancePath = path.join(root, "CLAUDE.md");
     const sections = input.enabled ? (input.contributions.guidanceSections ?? []) : [];
     const keepKeys = new Set<string>();
     for (const section of sections) {
@@ -337,12 +294,12 @@ export async function reconcileClaudeContributions(
     }
 
     for (const skillTree of input.contributions.skillTrees ?? []) {
-      const skillDir = path.join(companionPath, ".claude", "skills", skillTree.name);
+      const skillDir = path.join(root, ".claude", "skills", skillTree.name);
       if (input.enabled) {
         await mergeDir(skillTree.sourceDir, skillDir);
       } else {
         await fs.rm(skillDir, { recursive: true, force: true });
-        await pruneEmptyAncestors(path.join(companionPath, ".claude", "skills"), companionPath);
+        await pruneEmptyAncestors(path.join(root, ".claude", "skills"), root);
       }
     }
   }
@@ -350,13 +307,13 @@ export async function reconcileClaudeContributions(
 
 /** Reconcile only MCP entries without touching Claude settings or guidance. */
 async function reconcileClaudeMcpContributions(
-  ctx: SetupContext,
+  root: string,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
   for (const input of inputs) {
     for (const descriptor of input.contributions.mcpServers ?? []) {
       await updateClaudeMcpServer(
-        getCompanionClaudeMcpConfigPath(ctx.companionPath),
+        getCompanionClaudeMcpConfigPath(root),
         descriptor.name,
         input.enabled ? toClaudeMcpEntry(descriptor) : null,
       );
@@ -370,10 +327,10 @@ async function reconcileClaudeMcpContributions(
  * (no shared-file merge), so it needs no companion-only surface.
  */
 async function reconcileClaudeAgentDefinitionContributions(
-  ctx: SetupContext,
+  root: string,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
-  const agentsDir = path.join(ctx.companionPath, ".claude", "agents");
+  const agentsDir = path.join(root, ".claude", "agents");
   for (const input of inputs) {
     for (const agent of input.contributions.agentDefinitions ?? []) {
       const agentPath = path.join(agentsDir, `${agent.name}.md`);
@@ -382,7 +339,7 @@ async function reconcileClaudeAgentDefinitionContributions(
         await fs.writeFile(agentPath, agent.content, "utf8");
       } else {
         await fs.rm(agentPath, { force: true });
-        await pruneEmptyAncestors(agentsDir, ctx.companionPath);
+        await pruneEmptyAncestors(agentsDir, root);
       }
     }
   }
@@ -401,128 +358,6 @@ async function syncCompanionClaudeMcpConfig(companionPath: string): Promise<void
   });
 }
 
-// Reconcile the working repo for a Claude launch. Mate-managed Claude settings
-// now live in companion settings (see `syncCompanionClaudeSettings`) and are
-// loaded at launch via `--settings`, so Mate no longer writes them into the
-// working repo. Existing Mate-managed hooks are removed during migration;
-// user-authored settings remain in place. This also keeps the git exclude for
-// that file current and strips the TokenSave CLAUDE.md append the installer may
-// have added.
-export async function syncWorkingRepoClaudeSettings(
-  workingRepoPath: string,
-  companionPath: string,
-  config: FrameworkConfig,
-  globalConfigStore = new GlobalConfigStore(),
-): Promise<void> {
-  await ensureWorkingRepoLocalExcludes(workingRepoPath);
-  const tokensaveEnabled = (config.capabilities ?? []).some(
-    (capability) => capability.name === "tokensave",
-  );
-  await reconcileWorkingRepoCapabilityExcludes(
-    workingRepoPath,
-    tokensaveEnabled ? TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES : [],
-    TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES,
-  );
-  await syncWorkingRepoClaudeAdditionalDirectories(
-    workingRepoPath,
-    companionPath,
-    globalConfigStore,
-  );
-  await stripTokensaveClaudeMdAppend(workingRepoPath);
-}
-
-async function syncWorkingRepoClaudeAdditionalDirectories(
-  workingRepoPath: string,
-  companionPath: string,
-  globalConfigStore: GlobalConfigStore,
-): Promise<void> {
-  const settingsPath = path.join(workingRepoPath, ".claude", "settings.local.json");
-  // Migrate hooks only. Existing permissions and MCP entries stay in the
-  // working repo; additionalDirectories is reconciled below.
-  const existing = removeManagedHookGroups(await readClaudeSettings(settingsPath));
-  const permissions = { ...existing.permissions };
-  const existingAdditionalDirectories = Array.isArray(permissions.additionalDirectories)
-    ? permissions.additionalDirectories
-    : [];
-  const registeredCompanionPaths = new Set(
-    (await globalConfigStore.list()).map((registeredCompanionPath) =>
-      path.resolve(registeredCompanionPath),
-    ),
-  );
-  const resolvedCompanionPath = path.resolve(companionPath);
-  const additionalDirectories = Array.from(
-    new Set(
-      existingAdditionalDirectories
-        .map((directory) => path.resolve(directory))
-        .filter(
-          (directory) =>
-            !registeredCompanionPaths.has(directory) || directory === resolvedCompanionPath,
-        )
-        .concat(resolvedCompanionPath),
-    ),
-  );
-
-  const settings: ClaudeSettings = {
-    ...existing,
-    permissions: {
-      ...permissions,
-      additionalDirectories,
-    },
-  };
-
-  await writeClaudeSettings(settingsPath, settings);
-}
-
-export async function cleanupWorkingRepoClaudeSettings(
-  workingRepoPath: string,
-  registeredCompanionPaths: string[],
-): Promise<boolean> {
-  const settingsPath = path.join(workingRepoPath, ".claude", "settings.local.json");
-  let existing: ClaudeSettings;
-  try {
-    const parsed = JSON.parse(await fs.readFile(settingsPath, "utf8")) as unknown;
-    if (!parsed || typeof parsed !== "object") return stripTokensaveClaudeMdAppend(workingRepoPath);
-    existing = parsed as ClaudeSettings;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return stripTokensaveClaudeMdAppend(workingRepoPath);
-    }
-    return false;
-  }
-
-  const settings = removeManagedHookGroups(existing);
-  const permissions = { ...settings.permissions };
-  const managedPaths = new Set(
-    registeredCompanionPaths.map((candidate) => path.resolve(candidate)),
-  );
-  const currentDirectories = Array.isArray(permissions.additionalDirectories)
-    ? permissions.additionalDirectories
-    : [];
-  const additionalDirectories = currentDirectories.filter(
-    (candidate) => !managedPaths.has(path.resolve(candidate)),
-  );
-  if (additionalDirectories.length > 0) {
-    permissions.additionalDirectories = additionalDirectories;
-  } else {
-    delete permissions.additionalDirectories;
-  }
-  if (Object.keys(permissions).length > 0) {
-    settings.permissions = permissions;
-  } else {
-    delete settings.permissions;
-  }
-
-  const settingsChanged = JSON.stringify(settings) !== JSON.stringify(existing);
-  if (settingsChanged && Object.keys(settings).length === 0) {
-    await fs.unlink(settingsPath);
-    await pruneEmptyAncestors(path.join(workingRepoPath, ".claude"), workingRepoPath);
-  } else if (settingsChanged) {
-    await writeClaudeSettings(settingsPath, settings);
-  }
-  const guidanceChanged = await stripTokensaveClaudeMdAppend(workingRepoPath);
-  return settingsChanged || guidanceChanged;
-}
-
 async function configureClaude(companionPath: string): Promise<void> {
   // Mate hooks are delivered by the bundled Claude plugin at launch; nothing
   // is copied into `companion/.claude/hooks/` anymore. Stale copies from

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

@@ -18,6 +18,7 @@ import {
   upsertManagedBlock,
 } from "../context-services";
 import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
+import { surfaceRoot } from "../surface-target";
 import { mergeDir, pruneEmptyAncestors } from "../utils";
 import {
   getOpenCodePluginReferences,
@@ -424,22 +425,23 @@ export async function reconcileOpenCodeContributions(
   ctx: SetupContext,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
-  const { companionPath } = ctx;
+  /** Resolved once per pass; every write site below is relative to it. */
+  const root = surfaceRoot(ctx);
 
   if (ctx.scope === "hub") {
-    await reconcileOpenCodeMcpContributions(ctx, inputs);
-    await reconcileOpenCodeAgentDefinitionContributions(ctx, inputs);
+    await reconcileOpenCodeMcpContributions(root, inputs);
+    await reconcileOpenCodeAgentDefinitionContributions(root, inputs);
     return;
   }
 
-  await reconcileOpenCodeMcpContributions(ctx, inputs);
-  await reconcileOpenCodeAgentDefinitionContributions(ctx, inputs);
+  await reconcileOpenCodeMcpContributions(root, inputs);
+  await reconcileOpenCodeAgentDefinitionContributions(root, inputs);
 
   for (const input of inputs) {
     for (const pluginReference of input.contributions.pluginReferences ?? []) {
       const configFiles = pluginReference.configFiles ?? OPENCODE_CONTRIBUTION_CONFIG_FILES;
       for (const name of configFiles) {
-        const configPath = path.join(companionPath, ".opencode", name);
+        const configPath = path.join(root, ".opencode", name);
         const { present, config } = await readOpenCodeConfig(configPath);
         if (!input.enabled && !present) continue;
         const preserved = getOpenCodePluginReferences(config).filter(
@@ -456,7 +458,7 @@ export async function reconcileOpenCodeContributions(
     // Guidance sections are managed blocks in AGENTS.md. Capability disable
     // strips them here; runtime teardown of the shared AGENTS.md is guarded in
     // the provider teardown paths (kept while another active runtime uses it).
-    const guidancePath = path.join(companionPath, "AGENTS.md");
+    const guidancePath = path.join(root, "AGENTS.md");
     const sections = input.enabled ? (input.contributions.guidanceSections ?? []) : [];
     const keepKeys = new Set<string>();
     for (const section of sections) {
@@ -469,12 +471,12 @@ export async function reconcileOpenCodeContributions(
     }
 
     for (const skillTree of input.contributions.skillTrees ?? []) {
-      const skillDir = path.join(companionPath, ".opencode", "skills", skillTree.name);
+      const skillDir = path.join(root, ".opencode", "skills", skillTree.name);
       if (input.enabled) {
         await mergeDir(skillTree.sourceDir, skillDir);
       } else {
         await fs.rm(skillDir, { recursive: true, force: true });
-        await pruneEmptyAncestors(path.join(companionPath, ".opencode", "skills"), companionPath);
+        await pruneEmptyAncestors(path.join(root, ".opencode", "skills"), root);
       }
     }
   }
@@ -482,13 +484,13 @@ export async function reconcileOpenCodeContributions(
 
 /** Reconcile only MCP entries without touching OpenCode plugins or guidance. */
 async function reconcileOpenCodeMcpContributions(
-  ctx: SetupContext,
+  root: string,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
   for (const input of inputs) {
     for (const descriptor of input.contributions.mcpServers ?? []) {
       await updateOpenCodeMcpServer(
-        getCompanionOpenCodeConfigPath(ctx.companionPath),
+        getCompanionOpenCodeConfigPath(root),
         descriptor.name,
         input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
       );
@@ -496,6 +498,31 @@ async function reconcileOpenCodeMcpContributions(
   }
 }
 
+/** The Mate-managed `mcp` map of one pass, as a value. */
+export function renderManagedOpenCodeMcpServers(
+  contributions: CapabilityContributionInput[] = [],
+): Record<string, unknown> {
+  const servers: Record<string, unknown> = {};
+  for (const input of contributions) {
+    if (!input.enabled) continue;
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      servers[descriptor.name] = toOpenCodeMcpEntry(descriptor);
+    }
+  }
+  return servers;
+}
+
+/**
+ * The Mate-managed `permission.external_directory` map, as a value. Rendered
+ * once for both destinations a session can reach it through — the projected
+ * document and the launch environment — so the two cannot drift.
+ */
+export function renderCompanionExternalDirectoryPermissions(
+  companionPath: string,
+): Record<string, string> {
+  return { [companionPath]: "allow", [`${companionPath}/**`]: "allow" };
+}
+
 /**
  * Reconcile declared agent definition files under `.opencode/agents/`. Runs
  * in both companion and hub scope — an agent definition is fully
@@ -503,10 +530,10 @@ async function reconcileOpenCodeMcpContributions(
  * surface.
  */
 async function reconcileOpenCodeAgentDefinitionContributions(
-  ctx: SetupContext,
+  root: string,
   inputs: CapabilityContributionInput[],
 ): Promise<void> {
-  const agentsDir = path.join(ctx.companionPath, ".opencode", "agents");
+  const agentsDir = path.join(root, ".opencode", "agents");
   for (const input of inputs) {
     for (const agent of input.contributions.agentDefinitions ?? []) {
       const agentPath = path.join(agentsDir, `${agent.name}.md`);
@@ -515,7 +542,7 @@ async function reconcileOpenCodeAgentDefinitionContributions(
         await fs.writeFile(agentPath, agent.content, "utf8");
       } else {
         await fs.rm(agentPath, { force: true });
-        await pruneEmptyAncestors(agentsDir, ctx.companionPath);
+        await pruneEmptyAncestors(agentsDir, root);
       }
     }
   }