@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/lib/delivery/stages.ts

@@ -0,0 +1,111 @@
+/**
+ * The Delivery Path stage contract: the action-named sequence Studio and the docs check
+ * read. Review stages come from a schema's artifacts.
+ */
+
+/** A skill stage runs a Mate skill; a human stage is a person reviewing one artifact. */
+export type DeliveryStageKind = "skill" | "human";
+
+interface StageBase {
+  /** Stable identifier, e.g. `archive` or `review-specs`. */
+  id: string;
+  /** The action the stage performs, e.g. `Archive change`. */
+  label: string;
+  kind: DeliveryStageKind;
+  /** Optional stages can be skipped and never block a later stage. */
+  optional: boolean;
+}
+
+export type SkillStageId =
+  | "clarify-intent"
+  | "explore"
+  | "propose"
+  | "apply"
+  | "inspect-outcome"
+  | "refine-code"
+  | "archive"
+  | "publish";
+
+export interface SkillStage extends StageBase {
+  id: SkillStageId;
+  kind: "skill";
+  /** The Mate skill that drives the stage. */
+  skill: string;
+}
+
+export interface ReviewStage extends StageBase {
+  kind: "human";
+  skill: null;
+  /** The schema artifact the person reviews. */
+  artifact: string;
+}
+
+export type DeliveryStage = SkillStage | ReviewStage;
+
+export interface DeliveryPath {
+  stages: DeliveryStage[];
+  /** False when the schema's artifacts could not be read, so reviews are unknown. */
+  reviewsKnown: boolean;
+}
+
+/** Artifact sets of the schemas Mate ships, in dependency order. */
+export const SCHEMA_ARTIFACTS = {
+  "mate-v1": ["proposal", "specs", "design", "tasks"],
+  "mate-minimal": ["specs", "tasks"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** A schema Mate ships. */
+export type MateSchema = keyof typeof SCHEMA_ARTIFACTS;
+
+/** The schema every companion is set to. */
+export const DEFAULT_SCHEMA: MateSchema = "mate-v1";
+
+export function isMateSchema(schema: string): schema is MateSchema {
+  return Object.hasOwn(SCHEMA_ARTIFACTS, schema);
+}
+
+function skillStage(id: SkillStageId, label: string, skill: string, optional = false): SkillStage {
+  return { id, label, kind: "skill", skill, optional };
+}
+
+const BEFORE_REVIEWS: readonly SkillStage[] = [
+  skillStage("clarify-intent", "Clarify intent", "mate-clarify-intent", true),
+  skillStage("explore", "Explore change", "mate-explore-change"),
+  skillStage("propose", "Propose change", "mate-propose-change"),
+];
+
+const AFTER_REVIEWS: readonly SkillStage[] = [
+  skillStage("apply", "Apply change", "mate-apply-change"),
+  skillStage("inspect-outcome", "Inspect outcome", "mate-show-me", true),
+  skillStage("refine-code", "Refine code", "mate-simplify-code", true),
+  skillStage("archive", "Archive change", "mate-archive-change"),
+  skillStage("publish", "Publish companion artifacts", "mate-publish-artifact"),
+];
+
+/** Every skill a Delivery Path stage is driven by, in stage order. */
+export const DELIVERY_STAGE_SKILLS: readonly string[] = [...BEFORE_REVIEWS, ...AFTER_REVIEWS].map(
+  (stage) => stage.skill,
+);
+
+function reviewStage(artifact: string): ReviewStage {
+  return {
+    id: `review-${artifact}`,
+    label: `Review ${artifact}`,
+    kind: "human",
+    skill: null,
+    artifact,
+    optional: false,
+  };
+}
+
+/**
+ * The Delivery Path for one schema. `artifacts` are its artifact ids in dependency order;
+ * `undefined` means the schema could not be read, which yields the skill stages alone with
+ * `reviewsKnown: false` rather than a guessed review set.
+ */
+export function deliveryPath(artifacts: readonly string[] | undefined): DeliveryPath {
+  return {
+    stages: [...BEFORE_REVIEWS, ...(artifacts ?? []).map(reviewStage), ...AFTER_REVIEWS],
+    reviewsKnown: artifacts !== undefined,
+  };
+}

package/src/lib/delivery/token.ts

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** The only environment variable a forge token is read from. */
+export const FORGE_TOKEN_ENV = "MATE_GIT_TOKEN";
+
+export interface ForgeToken {
+  token: string;
+  source: typeof FORGE_TOKEN_ENV | "gh";
+}
+
+export interface ForgeTokenDeps {
+  env?: Record<string, string | undefined>;
+  /** `gh auth token`, or null when the GitHub CLI is missing or signed out. */
+  ghToken?: () => Promise<string | null>;
+}
+
+/** Variables `gh auth token` would report instead of the stored login. */
+const GH_TOKEN_VARIABLES = [
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_ENTERPRISE_TOKEN",
+  "GITHUB_ENTERPRISE_TOKEN",
+];
+
+/** `env` without the token variables, so `gh` reports only its stored login. */
+export function ghAuthEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const scrubbed = { ...env };
+  for (const name of GH_TOKEN_VARIABLES) delete scrubbed[name];
+  return scrubbed;
+}
+
+async function defaultGhToken(): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("gh", ["auth", "token"], {
+      timeout: 10_000,
+      env: ghAuthEnv(process.env),
+    });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The forge token from `MATE_GIT_TOKEN`, then `gh auth token`. Other variables such as
+ * `GITHUB_TOKEN` are deliberately ignored so a broadly scoped CI token is never picked up.
+ * The returned value is for the forge request only: callers never print, log, or store it.
+ */
+export async function resolveForgeToken(deps: ForgeTokenDeps = {}): Promise<ForgeToken | null> {
+  const env = deps.env ?? process.env;
+  const fromEnv = env[FORGE_TOKEN_ENV]?.trim();
+  if (fromEnv) return { token: fromEnv, source: FORGE_TOKEN_ENV };
+  const fromGh = (await (deps.ghToken ?? defaultGhToken)())?.trim();
+  return fromGh ? { token: fromGh, source: "gh" } : null;
+}

package/src/lib/frontmatter.ts

@@ -0,0 +1,18 @@
+import { parse } from "yaml";
+
+/** A leading `---` block; group 1 is its YAML, the match ends after the closing line. */
+export const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+/** A Markdown file's leading YAML frontmatter; null when absent, malformed, or not a mapping. */
+export function readFrontmatter(source: string): Record<string, unknown> | null {
+  const header = FRONTMATTER_PATTERN.exec(source)?.[1];
+  if (header === undefined) return null;
+  try {
+    const parsed: unknown = parse(header);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -40,11 +40,11 @@ export interface WarmPluginCacheResult {
 
 export const opencodePluginCacheDeps = {
   runInstall: (cwd: string, registry: string) =>
-    spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent", "--registry", registry], {
-      cwd,
-      encoding: "utf8" as const,
-      stdio: ["ignore", "pipe", "pipe"] as const,
-    }),
+    spawnSync(
+      "npm",
+      ["install", "--no-audit", "--no-fund", "--loglevel=error", "--registry", registry],
+      { cwd, encoding: "utf8" as const, stdio: ["ignore", "pipe", "pipe"] as const },
+    ),
 };
 
 export async function warmOpenCodePackageCache(

package/src/lib/openspec-cli.ts

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Set on every `openspec` process Mate starts. Mate decides the CLI version, so
+ * OpenSpec's own "update available" hint is wrong advice here.
+ */
+export const OPENSPEC_ENV = {
+  OPENSPEC_TELEMETRY: "0",
+  OPENSPEC_NO_UPDATE_CHECK: "1",
+} as const satisfies Record<string, string>;
+
+/** The bundled CLI, with its version when its manifest is readable, or the reinstall message. */
+export type OpenSpecLocation = { bin: string; version?: string } | { missing: string };
+
+export interface OpenSpecRunOptions {
+  cwd: string;
+  /** `capture` (default) collects output; `inherit` streams it to the terminal. */
+  stdio?: "capture" | "inherit";
+  /** Milliseconds before the child is killed. */
+  timeout?: number;
+  /** Base environment, `process.env` by default; {@link OPENSPEC_ENV} always wins. */
+  env?: NodeJS.ProcessEnv;
+  /** The CLI to run instead of the located one, e.g. when vendoring from a given CLI. */
+  bin?: string;
+}
+
+/**
+ * `code` is 1 when the CLI is missing or fails to start, with Mate's message as
+ * `stderr`; `null` when the child was killed. With `stdio: "inherit"` only that
+ * message is returned, the CLI's own output went to the terminal.
+ */
+export interface OpenSpecRun {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  /** Set when the bundled CLI is missing, so nothing ran. */
+  missing?: true;
+}
+
+export type RunOpenSpec = (args: string[], options: OpenSpecRunOptions) => Promise<OpenSpecRun>;
+
+function readVersion(bin: string): string | undefined {
+  try {
+    const manifest = path.resolve(path.dirname(bin), "../package.json");
+    return (JSON.parse(fs.readFileSync(manifest, "utf8")) as { version: string }).version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Finds the OpenSpec CLI shipped with mate-core the way Node resolves it, never
+ * an `openspec` on `PATH`. `resolve` exists for layout tests.
+ */
+export function resolveOpenSpec(
+  resolve: (id: string) => string = require.resolve,
+): OpenSpecLocation {
+  let entryPath: string;
+  try {
+    // The package exports only `.` (dist/index.js); the binary sits beside dist/.
+    entryPath = resolve("@fission-ai/openspec");
+  } catch {
+    return { missing: "bundled OpenSpec CLI is missing. Reinstall Mate to restore it." };
+  }
+  const bin = path.resolve(path.dirname(entryPath), "../bin/openspec.js");
+  if (!fs.existsSync(bin)) {
+    return { missing: `bundled OpenSpec CLI is missing at ${bin}. Reinstall Mate to restore it.` };
+  }
+  return { bin, version: readVersion(bin) };
+}
+
+/** The one in-process seam: suites point `locate` at a stub CLI. */
+export const openSpecCliDeps = {
+  locate: (): OpenSpecLocation => resolveOpenSpec(),
+};
+
+/** The CLI every OpenSpec process Mate starts runs. */
+export function locateOpenSpec(): OpenSpecLocation {
+  return openSpecCliDeps.locate();
+}
+
+/** Runs the bundled CLI with {@link OPENSPEC_ENV} over the base environment. Never rejects. */
+export function runOpenSpec(args: string[], options: OpenSpecRunOptions): Promise<OpenSpecRun> {
+  const location = options.bin ? { bin: options.bin } : locateOpenSpec();
+  if ("missing" in location) {
+    return Promise.resolve({ code: 1, stdout: "", stderr: location.missing, missing: true });
+  }
+  return new Promise((resolve) => {
+    // A JS entry runs on the current runtime, not its `#!/usr/bin/env node` shebang,
+    // which needs an executable bit and `node` on PATH and does not work on Windows.
+    const [command, commandArgs] = location.bin.endsWith(".js")
+      ? [process.execPath, [location.bin, ...args]]
+      : [location.bin, args];
+    const child = spawn(command, commandArgs, {
+      cwd: options.cwd,
+      env: { ...(options.env ?? process.env), ...OPENSPEC_ENV },
+      stdio: options.stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+      ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => (stdout += chunk));
+    child.stderr?.on("data", (chunk: string) => (stderr += chunk));
+    child.once("error", (error) =>
+      resolve({ code: 1, stdout, stderr: `failed to run openspec: ${error.message}` }),
+    );
+    child.once("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}

package/src/lib/openspec-scopes.ts

@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRONTMATTER_PATTERN } from "./frontmatter";
+
+export const BOM = "";
+
+export interface ScopePair {
+  repository: string;
+  area: string;
+}
+
+/**
+ * A leading `<!-- mate:delta … -->` comment; group 1 is its YAML, the match ends after
+ * the closing `-->` line. OpenSpec skips HTML comments, so a delta carrying its metadata
+ * here passes `validate --strict`.
+ */
+export const DELTA_COMMENT_PATTERN =
+  /^<!--[ \t]*mate:delta[ \t]*\r?\n([\s\S]*?)\r?\n-->[ \t]*(?:\r?\n|$)/;
+
+/** Reads `scopes` from a `mate:delta` comment, else from frontmatter (proposals, legacy deltas). */
+export function parseScopes(source: string): ScopePair[] {
+  const text = source.startsWith(BOM) ? source.slice(BOM.length) : source;
+  const match = DELTA_COMMENT_PATTERN.exec(text) ?? FRONTMATTER_PATTERN.exec(text);
+  if (!match) return [];
+
+  try {
+    const parsed = parse(match[1]) as unknown;
+    if (!parsed || typeof parsed !== "object") return [];
+    const scopes = (parsed as Record<string, unknown>).scopes;
+    if (!Array.isArray(scopes)) return [];
+    return scopes.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      const pair = entry as Record<string, unknown>;
+      return typeof pair.repository === "string" && typeof pair.area === "string"
+        ? [{ repository: pair.repository, area: pair.area }]
+        : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+async function specFiles(directory: string): Promise<string[]> {
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) return specFiles(full);
+      return entry.isFile() && entry.name.endsWith(".md") ? [full] : [];
+    }),
+  );
+  return nested.flat();
+}
+
+async function readOrEmpty(file: string): Promise<string> {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Repositories a change directory (active or archived) declares in its proposal
+ * frontmatter and delta `scopes`, deduplicated case-insensitively, first spelling kept.
+ */
+export async function scopedRepositories(changeDir: string): Promise<string[]> {
+  const sources = [
+    await readOrEmpty(path.join(changeDir, "proposal.md")),
+    ...(await Promise.all((await specFiles(path.join(changeDir, "specs"))).map(readOrEmpty))),
+  ];
+  const seen = new Map<string, string>();
+  for (const pair of sources.flatMap(parseScopes)) {
+    const key = pair.repository.toLowerCase();
+    if (!seen.has(key)) seen.set(key, pair.repository);
+  }
+  return [...seen.values()];
+}

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

@@ -0,0 +1,50 @@
+/** Reads the operator's `claude` arguments as tokens, for where Mate's appended prompt goes. */
+
+export const APPEND_PROMPT_FLAG = "--append-system-prompt";
+
+function flagArgs(args: readonly string[]): readonly string[] {
+  const terminator = args.indexOf("--");
+  return terminator === -1 ? args : args.slice(0, terminator);
+}
+
+/**
+ * The operator's own `--append-system-prompt` values, lifted out of `args`:
+ * Claude keeps only the last such flag, so each would replace Mate's Agent
+ * Guidance instead of following it. A trailing flag without a value
+ * stays, for Claude to reject. `boundary` is where a lifted flag stood before
+ * an argument that is no flag: a variadic option such as `--add-dir` before
+ * it would otherwise read that argument as its own value, so Mate's flag goes
+ * there. Only the first such place is kept: Claude reads one prompt.
+ */
+export function liftAppendedPrompts(args: readonly string[]): {
+  args: string[];
+  prompts: string[];
+  boundary?: number;
+} {
+  const flags = flagArgs(args);
+  const kept: string[] = [];
+  const prompts: string[] = [];
+  const liftedAt: number[] = [];
+  for (let index = 0; index < flags.length; index += 1) {
+    const arg = flags[index]!;
+    if (arg === APPEND_PROMPT_FLAG && index + 1 < flags.length) {
+      prompts.push(flags[index + 1]!);
+      liftedAt.push(kept.length);
+      index += 1;
+    } else if (arg.startsWith(`${APPEND_PROMPT_FLAG}=`)) {
+      prompts.push(arg.slice(APPEND_PROMPT_FLAG.length + 1));
+      liftedAt.push(kept.length);
+    } else {
+      kept.push(arg);
+    }
+  }
+  const passthrough = [...kept, ...args.slice(flags.length)];
+  const boundary = liftedAt.find(
+    (at) => at > 0 && at < passthrough.length && !passthrough[at]!.startsWith("-"),
+  );
+  return {
+    args: passthrough,
+    prompts,
+    ...(boundary === undefined ? {} : { boundary }),
+  };
+}

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

@@ -5,23 +5,26 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { buildCompanionGuidance } from "../../../playbooks/companion-guidance";
 import {
+  launchPluginFolders,
   planClaudeDelivery,
   type ClaudeDeliveryPlan,
-  type SessionKind,
 } from "../../../runtime/claude-delivery-plan";
 import { hookGroupKey, type ClaudeHookGroup } from "../../../runtime/claude-hook-group";
+import { resolveSecretPolicy } from "../../../runtime/policy";
+import { managedSessionKind } from "../../../runtime/session-kind";
 import { NOT_WRAPPED } from "../../../runtime/wrap-state";
 import { writeAtomic } from "../../../runtime/write-atomic";
 import {
   getCompanionClaudeMcpConfigPath,
   getCompanionClaudeSettingsPath,
 } from "../../../tools/setup/providers/claude";
+import { definesUserClaudeAttribution } from "../../../tools/setup/providers/claude-attribution";
 import type { ClaudeSettings } from "../../../tools/setup/providers/claude-format";
-import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
 import { getClaudePluginRoot, validateClaudePluginAssets } from "../../package-paths";
 import type { PrepareResult } from "../session-prepare";
 import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
+import { APPEND_PROMPT_FLAG, liftAppendedPrompts } from "./claude-args";
 
 /** The paths are present only where the plan names that channel and the file exists. */
 interface ClaudeDelivery {
@@ -33,6 +36,8 @@ interface ClaudeDelivery {
 /** A Claude launch's context: the delivery its plan chose, and the files it chose or wrote. */
 interface ClaudeLaunchContext extends AdapterContext {
   delivery: ClaudeDelivery;
+  /** The Capability plugin folders this launch's own prepare gathered, in order. */
+  pluginDirectories: readonly string[];
 }
 
 /** Where a launch with a Working Repository writes its derived `--settings`; git-ignored. */
@@ -44,12 +49,15 @@ export function launchSettingsPath(companionPath: string, repositoryId: string):
 /**
  * Companion settings minus `exclude`, so each wrap-carried group runs once. A
  * file, not inline JSON (platform arg limits); per repository, so concurrent
- * launches never race.
+ * launches never race. `--settings` outranks every file scope, so `attribution`
+ * is dropped when the user or the repository sets its own, even one added
+ * after the companion's last sync.
  */
 async function writeLaunchSettings(
   companionSettingsPath: string,
   target: string,
   exclude: readonly ClaudeHookGroup[],
+  repoRoot: string,
 ): Promise<void> {
   const settings = JSON.parse(await fs.readFile(companionSettingsPath, "utf8")) as ClaudeSettings;
   const excluded = new Set(exclude.map(hookGroupKey));
@@ -60,6 +68,9 @@ async function writeLaunchSettings(
   }
   const derived: ClaudeSettings = { ...settings, hooks };
   if (Object.keys(hooks).length === 0) delete derived.hooks;
+  if (definesUserClaudeAttribution({ repoRoot })) {
+    delete derived.attribution;
+  }
 
   await fs.mkdir(path.dirname(target), { recursive: true });
   await writeAtomic(target, `${JSON.stringify(derived, null, 2)}\n`);
@@ -76,7 +87,12 @@ async function settingsPathFor(
   if (plan.hooks.owner === "settings") return companionSettingsPath;
   /** Owner `wrap` is planned only for `managed-repo`, which has a repository. */
   const settingsPath = launchSettingsPath(companionPath, repository!.id);
-  await writeLaunchSettings(companionSettingsPath, settingsPath, plan.hooks.launchSettingsExclude);
+  await writeLaunchSettings(
+    companionSettingsPath,
+    settingsPath,
+    plan.hooks.launchSettingsExclude,
+    repository!.path,
+  );
   return settingsPath;
 }
 
@@ -91,7 +107,7 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
    */
   async planLaunch(context: AdapterContext, prepared: PrepareResult): Promise<ClaudeLaunchContext> {
     const { repository, companionPath } = context;
-    const kind: SessionKind = repository ? "managed-repo" : "managed-companion";
+    const kind = managedSessionKind(Boolean(repository));
     const wrap = prepared.wrapState ?? NOT_WRAPPED;
     if (repository && !wrap.runtimes.has("claude")) {
       throw new LaunchPreflightError(
@@ -106,7 +122,7 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
       ...(plan.mcp === "mcp-config" && existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
       ...(settingsPath ? { settingsPath } : {}),
     };
-    return { ...context, delivery };
+    return { ...context, delivery, pluginDirectories: prepared.claudePluginDirectories ?? [] };
   }
 
   /** A failed Claude wrap pass names the entry that failed. */
@@ -121,7 +137,7 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
     return super.launchFailure(prepared);
   }
 
-  async validateLaunch(context: ClaudeLaunchContext): Promise<void> {
+  async validateLaunch(_context: ClaudeLaunchContext): Promise<void> {
     /** The bundled plugin carries the artifact-path guard; never launch without it. */
     try {
       validateClaudePluginAssets();
@@ -131,22 +147,14 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
         { cause: error },
       );
     }
-
-    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 },
-        );
-      }
-    }
   }
 
   /**
-   * Plan in, flags out; decides nothing. `--append-system-prompt`, `--plugin-dir`
-   * and context-mode are unconditional: no settings document can carry them.
+   * Plan in, flags out; decides nothing. `--append-system-prompt` is
+   * unconditional: no settings document can carry it. It holds the Agent
+   * Guidance alone; the Companion Instructions come from the wrap's session hook.
+   * `--plugin-dir` passes the folders `launchPluginFolders` names, from the
+   * running install's bundled plugin.
    */
   buildArgs(context: ClaudeLaunchContext, args: string[]): string[] {
     const { plan, settingsPath, mcpConfigPath } = context.delivery;
@@ -156,31 +164,31 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
         ? ["--setting-sources", "user,project,local", "--settings", settingsPath]
         : [];
     const addDirArgs = plan.dirAccess === "add-dir" ? ["--add-dir", context.companionPath] : [];
+    const pluginDirArgs = launchPluginFolders(
+      plan,
+      context.pluginDirectories,
+      getClaudePluginRoot(),
+    ).flatMap((dir) => ["--plugin-dir", dir]);
     const mcpConfigArgs =
       plan.mcp === "mcp-config" && mcpConfigPath ? ["--mcp-config", mcpConfigPath] : [];
-    const contextModeArgs = context.capabilities.some(
-      (capability) => capability.name === "context-mode",
-    )
-      ? ["--plugin-dir", getContextModePackageRoot(context.companionPath)]
-      : [];
 
+    const guidance = buildCompanionGuidance({
+      ...context,
+      secretGuardrails: resolveSecretPolicy(context.companionPath).guardrails,
+    });
+    const { args: passthrough, prompts, boundary } = liftAppendedPrompts(args);
+    const promptArgs = [APPEND_PROMPT_FLAG, [guidance, ...prompts].filter(Boolean).join("\n\n")];
+    const launchArgs = [...settingsArgs, ...mcpConfigArgs, ...pluginDirArgs];
+
+    if (boundary === undefined) {
+      return [...addDirArgs, ...promptArgs, ...launchArgs, ...passthrough];
+    }
     return [
       ...addDirArgs,
-      "--append-system-prompt",
-      buildCompanionGuidance(context),
-      ...settingsArgs,
-      ...mcpConfigArgs,
-      /** The bundled plugin from the running install, beside context-mode's. */
-      "--plugin-dir",
-      getClaudePluginRoot(),
-      ...contextModeArgs,
-      ...args,
+      ...launchArgs,
+      ...passthrough.slice(0, boundary),
+      ...promptArgs,
+      ...passthrough.slice(boundary),
     ];
   }
-
-  extendEnvironment(_context: ClaudeLaunchContext): NodeJS.ProcessEnv {
-    return {
-      CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1",
-    };
-  }
 }

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

@@ -6,6 +6,7 @@ const path = await import("node:path");
 
 import { MATE_ENV } from "../../../runtime/env";
 import { validateGuidanceData, type MateGuidanceFile } from "../../../runtime/guidance";
+import { resolveSecretPolicy } from "../../../runtime/policy";
 
 import { validateOpenCodePluginAssets } from "../../package-paths";
 import { readOpenCodeConfig } from "../../../tools/setup/providers/opencode-format";
@@ -118,6 +119,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
   private buildGuidance(context: AdapterContext): MateGuidanceFile {
     return buildOpenCodeGuidance(context.capabilities, {
       companionScoped: !context.repository,
+      secretGuardrails: resolveSecretPolicy(context.companionPath).guardrails,
     });
   }