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

package/src/lib/orchestrator/wrap-pass.ts

@@ -1,43 +1,32 @@
 import path from "node:path";
 
-import { renderWorkingRuntimeDocuments } from "../../tools/setup";
-import { renderAudienceLayer } from "../../tools/setup/audience-layer";
-import { loadAudienceRegistrations } from "../../tools/setup/audience-registrations";
-import { declaredAudiences } from "../../tools/setup/dynamic-plugins/audiences";
-import { buildSetupInstallationPlan } from "../../tools/setup/engine";
-import { getActiveDistribution } from "../../distribution";
-import { audienceLayerDir } from "../../runtime/audience-layer";
 import {
-  readManifest,
-  recordedAudience,
-  updateManifest,
-  withAudience,
-} from "../../runtime/runtime-document-manifest";
+  publishWorkingClaudePluginMarketplaces,
+  renderWorkingRuntimeDocuments,
+} from "../../tools/setup";
+import type { ClaudePluginFolders } from "../../tools/setup/providers/claude-plugin-folders";
 import { readCompanionConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import { entryFailureMessage, firstFailure, type ProjectionChangedPaths } from "./projection-types";
 import type { WrapRuntime } from "../../runtime/runtime-document-manifest";
 import { readWrapState, type WrapState } from "../../runtime/wrap-state";
-import type { NormalizedRegistration } from "../../tools/setup/registry";
 import type { FrameworkConfig, LinkedRepository } from "./types";
 import { project } from "./working-repo-projection";
 
 export interface WrapPassDependencies {
+  publishWorkingClaudePluginMarketplaces: typeof publishWorkingClaudePluginMarketplaces;
   renderWorkingRuntimeDocuments: typeof renderWorkingRuntimeDocuments;
   readCompanionConfig: typeof readCompanionConfig;
   project: typeof project;
-  loadAudienceRegistrations: typeof loadAudienceRegistrations;
-  renderAudienceLayer: typeof renderAudienceLayer;
   /** The registered companions, whose stale skill links a re-pin withdraws; the user's registry when absent. */
   globalConfigStore?: GlobalConfigStore;
 }
 
 export const wrapPassDeps: WrapPassDependencies = {
+  publishWorkingClaudePluginMarketplaces,
   renderWorkingRuntimeDocuments,
   readCompanionConfig,
   project,
-  loadAudienceRegistrations,
-  renderAudienceLayer,
 };
 
 export interface WrapPassOptions {
@@ -45,12 +34,6 @@ export interface WrapPassOptions {
   runtimes?: readonly WrapRuntime[];
   /** The companion config the caller already read; read from files otherwise. */
   config?: FrameworkConfig;
-  /**
-   * The audience to wrap the checkout for: a name records it, `null` withdraws
-   * it, absent keeps the one the manifest records. Never read from the
-   * environment: it is the only source of a bare session's audience.
-   */
-  audience?: string | null;
 }
 
 export type WrapPassResult =
@@ -70,21 +53,14 @@ export type WrapPassResult =
       runtimes: ReadonlySet<WrapRuntime>;
       /** The wrap state as this pass left it. */
       wrapState: WrapState;
-      /** The audience the checkout is wrapped for after this pass. */
-      audience: string | null;
+      /**
+       * The Claude plugin folders this pass published, when it covered Claude;
+       * what publication left undone is the caller's to present, never in `warnings`.
+       */
+      claudePluginFolders?: ClaudePluginFolders;
     }
   | { kind: "failed"; message: string };
 
-/** An audience a checkout may be wrapped for: declared by the companion, never the reserved base. */
-function wrappableAudience(config: FrameworkConfig, audience: string): boolean {
-  return audience !== "base" && declaredAudiences(config).includes(audience);
-}
-
-function describeUnwrappable(config: FrameworkConfig, audience: string): string {
-  const declared = declaredAudiences(config).filter((name) => name !== "base");
-  return `audience "${audience}" cannot be wrapped: the companion declares ${declared.length > 0 ? declared.join(", ") : "no audiences"}.`;
-}
-
 /**
  * One pass of the `wrap` scope, restricted to the requested runtimes by each
  * entry's runtime tag. Best-effort per entry like every projection: a failed
@@ -98,50 +74,19 @@ export async function runWrapPass(
 ): Promise<WrapPassResult> {
   const resolvedCompanionPath = path.resolve(companionPath);
   const config = options.config ?? (await deps.readCompanionConfig(resolvedCompanionPath));
-
-  const audienceWarnings: string[] = [];
-  let audience: string | null;
-  if (options.audience === undefined) {
-    const recorded = recordedAudience(await readManifest(repository.path));
-    /** A recorded audience the companion no longer declares falls back to base, never fails a prepare. */
-    if (recorded && !wrappableAudience(config, recorded)) {
-      audienceWarnings.push(
-        `${describeUnwrappable(config, recorded)} ${repository.id} is wrapped for base only.`,
-      );
-      audience = null;
-    } else {
-      audience = recorded;
-    }
-  } else {
-    audience = options.audience;
-    if (audience && !wrappableAudience(config, audience)) {
-      return { kind: "failed", message: describeUnwrappable(config, audience) };
-    }
-  }
-
-  let wrapped: { audience: string; registrations: NormalizedRegistration[] } | undefined;
-  if (audience) {
-    const loaded = await deps.loadAudienceRegistrations(resolvedCompanionPath, config, audience);
-    audienceWarnings.push(...loaded.warnings);
-    await deps.renderAudienceLayer({
-      companionPath: resolvedCompanionPath,
-      config,
-      audience,
-      activeProviders: buildSetupInstallationPlan(
-        config,
-        getActiveDistribution().registry.baseRegistrations(),
-      ).activeProviders,
-      registrations: loaded.registrations,
-    });
-    wrapped = { audience, registrations: loaded.registrations };
-  }
-
+  /** The render reads the marketplace files, so they are written first. */
+  const published =
+    !options.runtimes || options.runtimes.includes("claude")
+      ? await deps.publishWorkingClaudePluginMarketplaces(
+          resolvedCompanionPath,
+          config,
+          repository.path,
+        )
+      : undefined;
   const rendered = await deps.renderWorkingRuntimeDocuments(
     resolvedCompanionPath,
     config,
     repository.path,
-    undefined,
-    wrapped,
   );
   const result = await deps.project("wrap", {
     repoPath: repository.path,
@@ -149,7 +94,6 @@ export async function runWrapPass(
     repository,
     config,
     runtimeDocuments: rendered.documents,
-    audienceLayerDir: audience ? audienceLayerDir(resolvedCompanionPath, audience) : null,
     globalConfigStore: deps.globalConfigStore ?? new GlobalConfigStore(),
     ...(options.runtimes ? { runtimes: options.runtimes } : {}),
   });
@@ -157,12 +101,6 @@ export async function runWrapPass(
   const failure = firstFailure(result.outcomes);
   if (failure) return { kind: "failed", message: entryFailureMessage(failure, repository.id) };
 
-  const before = recordedAudience(await readManifest(repository.path));
-  const audienceChanged = before !== audience;
-  if (audienceChanged) {
-    await updateManifest(repository.path, (manifest) => withAudience(manifest, audience));
-  }
-
   /** Read once under the caller's lock, so it is exactly what the pass recorded. */
   let wrapState: WrapState;
   try {
@@ -194,10 +132,7 @@ export async function runWrapPass(
     .map((outcome) => outcome.path);
 
   return {
-    kind:
-      audienceChanged || result.outcomes.some((outcome) => outcome.state === "written")
-        ? "written"
-        : "current",
+    kind: result.outcomes.some((outcome) => outcome.state === "written") ? "written" : "current",
     projectionRoot: result.root,
     companionPath: resolvedCompanionPath,
     documents: [...new Set(documents)],
@@ -207,7 +142,6 @@ export async function runWrapPass(
       removed: result.outcomes.flatMap((outcome) => outcome.changed?.removed ?? []),
     },
     warnings: [
-      ...audienceWarnings,
       ...rendered.warnings,
       ...result.outcomes.flatMap((outcome) => outcome.warnings ?? []),
       /** A degradable failure does not fail the pass, but it is never silent. */
@@ -217,6 +151,6 @@ export async function runWrapPass(
     ],
     runtimes,
     wrapState,
-    audience,
+    ...(published ? { claudePluginFolders: published } : {}),
   };
 }

package/src/lib/package-paths.ts

@@ -32,10 +32,18 @@ export function getClaudePluginRoot(): string {
   return path.resolve(import.meta.dirname, "../../claude-plugin");
 }
 
+/**
+ * The `name` in the bundled Claude plugin's manifest. Claude Code identifies a
+ * plugin by its name, so a contributed folder using this one could take the
+ * place of Mate's plugin and its guardrail hooks.
+ */
+export const MATE_CLAUDE_PLUGIN_NAME = "mate-claude-plugin";
+
 const CLAUDE_PLUGIN_HOOK_SHIMS = [
   "validate-artifact-path.mjs",
   "session-banner.mjs",
   "session-guidance.mjs",
+  "companion-instructions.mjs",
 ] as const;
 
 /**

package/src/opencode/companion-hooks.ts

@@ -2,6 +2,8 @@ import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
 
+import { resolveArtifactTarget } from "../runtime/artifact-refusal";
+import { checkCommitAttribution } from "../runtime/commit-attribution-guard";
 import {
   companionForkRefusal,
   syncCompanionUnattended,
@@ -10,12 +12,14 @@ import {
 import { hasLaunchEnvironment } from "../runtime/env";
 import { MATE_ENV } from "../runtime/env-names";
 import { resolveProjection } from "../runtime/projection";
+import { checkSecretAccess, type SecretToolCall } from "../runtime/secret-guard";
 import { readWrapStateSync } from "../runtime/wrap-state";
 import {
   buildArtifactError,
+  extractPatchAdditions,
   extractPatchPaths,
   isArtifactPath,
-  normalizeTargetPath,
+  isCompanionTarget,
   shouldBlockArtifactWrite,
   type CompanionContext,
 } from "./companion-policy";
@@ -87,14 +91,55 @@ export async function refuseForkedCompanionWrite(
   env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   if (!filePath || !isArtifactPath(filePath)) return;
-  if (!normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
-    return;
-  }
+  if (!isCompanionTarget(context, filePath)) return;
   const refusal = await companionForkRefusal(env, context.companionPath);
   if (refusal) throw new Error(refusal);
 }
 
-/** Rejects when the tool call would write an artifact outside the companion. */
+/** OpenCode tool inputs in the shape the shared secret guard reads. */
+function secretToolCall(
+  context: CompanionContext,
+  tool: string,
+  args: Record<string, unknown>,
+): SecretToolCall | null {
+  const text = (value: unknown) => (typeof value === "string" ? value : "");
+  const target = (value: unknown) =>
+    text(value) ? resolveArtifactTarget(text(value), context.repositoryPath) : "";
+  switch (tool) {
+    case "read":
+      return { kind: "read", paths: [target(args.filePath)] };
+    case "write":
+      return {
+        kind: "write",
+        writes: [{ path: target(args.filePath), content: text(args.content) }],
+      };
+    case "edit":
+      return {
+        kind: "write",
+        writes: [{ path: target(args.filePath), content: text(args.newString) }],
+      };
+    case "apply_patch":
+      return {
+        kind: "write",
+        writes: extractPatchAdditions(text(args.patchText)).map((addition) => ({
+          path: target(addition.path),
+          content: addition.content,
+        })),
+      };
+    case "bash":
+      return { kind: "shell", command: text(args.command) };
+    case "grep":
+      return { kind: "search", paths: [target(args.path)], globs: [text(args.include)] };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Rejects when the tool call touches a secret, commits with a model co-author
+ * trailer, or would write an artifact outside the companion. Checked in that
+ * order, as in the Claude hook.
+ */
 export async function guardToolInput(
   context: CompanionContext,
   tool: string,
@@ -102,6 +147,20 @@ export async function guardToolInput(
   env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const args = (input ?? {}) as Record<string, unknown>;
+
+  const secretCall = context.companionPath ? secretToolCall(context, tool, args) : null;
+  if (secretCall) {
+    const companionRoot = path.normalize(context.companionPath);
+    const refusal = await checkSecretAccess(secretCall, {
+      companionPath: context.companionPath,
+      isCompanionPath: (filePath) => filePath.startsWith(companionRoot),
+    });
+    if (refusal) throw new Error(refusal);
+  }
+  if (tool === "bash") {
+    const refusal = checkCommitAttribution(String(args.command ?? ""));
+    if (refusal) throw new Error(refusal);
+  }
   const filePaths =
     tool === "write" || tool === "edit"
       ? [String(args.filePath ?? "")]

package/src/opencode/companion-policy.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
+import { artifactRefusal, resolveArtifactTarget } from "../runtime/artifact-refusal";
 import { persistedCompanionGitStalenessLines } from "../runtime/companion-sync";
 import { resolveCompanionRuntime, type CompanionRuntimeContext } from "../runtime/env";
 import { projectionFreshness, projectionStalenessLines } from "../runtime/freshness";
@@ -60,7 +61,7 @@ export function isArtifactPath(filePath: string): boolean {
 }
 
 export function isProductDocumentationPath(context: CompanionContext, filePath: string): boolean {
-  const normalized = normalizeTargetPath(context, filePath);
+  const normalized = resolveArtifactTarget(filePath, context.repositoryPath);
   const relativePath = path.relative(context.repositoryPath, normalized);
   if (!relativePath || relativePath.startsWith("..")) {
     return false;
@@ -86,12 +87,10 @@ export function isProductDocumentationPath(context: CompanionContext, filePath:
   return false;
 }
 
-export function normalizeTargetPath(context: CompanionContext, filePath: string): string {
-  if (path.isAbsolute(filePath)) {
-    return path.normalize(filePath);
-  }
-
-  return path.normalize(path.join(context.repositoryPath, filePath));
+export function isCompanionTarget(context: CompanionContext, filePath: string): boolean {
+  return resolveArtifactTarget(filePath, context.repositoryPath).startsWith(
+    path.normalize(context.companionPath),
+  );
 }
 
 export function isGitignored(context: CompanionContext, filePath: string): boolean {
@@ -99,7 +98,7 @@ export function isGitignored(context: CompanionContext, filePath: string): boole
     return false;
   }
 
-  const normalized = normalizeTargetPath(context, filePath);
+  const normalized = resolveArtifactTarget(filePath, context.repositoryPath);
   if (!normalized.startsWith(path.normalize(context.repositoryPath))) {
     return false;
   }
@@ -126,7 +125,7 @@ export function shouldBlockArtifactWrite(context: CompanionContext, filePath: st
     return false;
   }
 
-  if (normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
+  if (isCompanionTarget(context, filePath)) {
     return false;
   }
 
@@ -155,16 +154,36 @@ export function extractPatchPaths(patchText: string): string[] {
   return paths;
 }
 
-export function buildArtifactError(context: CompanionContext, filePath: string): string {
-  const rel = path.relative(context.repositoryPath, filePath);
-  const suggested = path.join(context.companionPath, rel);
+/**
+ * What a patch would add to each file it touches: the `+` lines of every
+ * section, keyed by the section's target (a move's destination when present).
+ */
+export function extractPatchAdditions(patchText: string): { path: string; content: string }[] {
+  const additions: { path: string; content: string[] }[] = [];
+  let current: { path: string; content: string[] } | undefined;
+  for (const line of patchText.split("\n")) {
+    const marker = /^\*\*\* (Add|Update|Delete|Move to) File:\s*(.+)$/.exec(line);
+    if (marker) {
+      if (marker[1] === "Move to" && current) {
+        current.path = marker[2].trim();
+      } else {
+        current = { path: marker[2].trim(), content: [] };
+        additions.push(current);
+      }
+      continue;
+    }
+    if (current && line.startsWith("+")) current.content.push(line.slice(1));
+  }
+  return additions.map((entry) => ({ path: entry.path, content: entry.content.join("\n") }));
+}
 
-  return [
-    `${context.frameworkName} guardrail: artifact writes must go to the companion framework path.`,
-    `  target:   ${filePath}`,
-    `  suggested: ${suggested}`,
-    `Rewrite to ${suggested} and retry.`,
-  ].join("\n");
+export function buildArtifactError(context: CompanionContext, filePath: string): string {
+  return artifactRefusal({
+    target: filePath,
+    resolved: resolveArtifactTarget(filePath, context.repositoryPath),
+    companion: context.companionPath,
+    repoRoot: context.repositoryPath,
+  });
 }
 
 /**

package/src/opencode/projected-guidance.ts

@@ -44,6 +44,9 @@ export function resolveOpenCodeGuidance(
   if (!projection) return { guidance: null, errors: [] };
 
   const policy = readCompanionPolicy(projection.companionPath);
-  const guidance = buildOpenCodeGuidance(policy.enabledCapabilities.map((name) => ({ name })));
+  const guidance = buildOpenCodeGuidance(
+    policy.enabledCapabilities.map((name) => ({ name })),
+    { secretGuardrails: policy.secrets.guardrails },
+  );
   return { guidance: guidance.errors.length > 0 ? null : guidance, errors: guidance.errors };
 }

package/src/opencode/session-prepare.ts

@@ -1,5 +1,6 @@
 import type { Cleanup, Context } from "@opencode/plugin/promise/plugin";
 
+import { errorMessage } from "../runtime/error-message";
 import {
   PREPARE_TIMEOUT_MS,
   type PrepareRun,
@@ -52,7 +53,7 @@ async function report(
 }
 
 function failedRun(error: unknown): PrepareRun {
-  return { ok: false, notes: [error instanceof Error ? error.message : String(error)] };
+  return { ok: false, notes: [errorMessage(error)] };
 }
 
 /** No remote: OpenCode holds MCP servers and skills until `setup` returns. */

package/src/opencode/tui.tsx

@@ -6,6 +6,7 @@
  * does not accept it, so the jsx-key rules cannot be satisfied — only suppressed.
  * Arrays render through `.map`: Solid re-runs it whole on a store change, fine for a few lines.
  */
+import { BRAND_ACCENT } from "../brand/palette";
 import { mateVersion } from "../runtime/install";
 import { readContext, readStalenessLines } from "./companion-policy";
 
@@ -47,7 +48,8 @@ export const STALENESS_POLL_MS = 5_000;
 
 type SessionNotes = { lines: string[] };
 
-const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
+/** The `mate v<version>` line uses the brand accent, which reads on light and dark themes alike. */
+export const MATE_VERSION_COLOR = BRAND_ACCENT;
 const MATE_VERSION = process.env.MATE_VERSION ?? mateVersion();
 
 function SessionContext({
@@ -72,7 +74,7 @@ function SessionContext({
       paddingBottom={sidebar ? 1 : 0}
       flexShrink={0}
     >
-      <text fg={MIDNIGHT_PURPLE_BRIGHT}>mate v{MATE_VERSION}</text>
+      <text fg={MATE_VERSION_COLOR}>mate v{MATE_VERSION}</text>
       <text fg={text.muted}>repo: {context.repositoryPath}</text>
       <text fg={text.muted}>mate: {context.companionPath}</text>
       {notes.lines.map((note) => (

package/src/runtime/artifact-refusal.ts

@@ -0,0 +1,63 @@
+/** The artifact-write refusal both runtimes print; pure, so either guard can import it. */
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+/** Matched by consumers and tests; keep byte-identical. */
+export const ARTIFACT_REFUSAL_HEADLINE = "artifact writes must go to the companion framework path.";
+
+export interface ArtifactRefusalInput {
+  /** As the tool supplied it, relative or absolute. */
+  target: string;
+  /** The absolute path the guard judged. */
+  resolved: string;
+  companion: string;
+  /** The Working Repository root relative targets resolve against. */
+  repoRoot: string;
+}
+
+/** The absolute path both guards judge: a relative target resolves against the repo root, never a `cd`. */
+export function resolveArtifactTarget(target: string, repoRoot: string): string {
+  if (path.isAbsolute(target)) return path.normalize(target);
+  return path.normalize(path.join(repoRoot, target));
+}
+
+function relativeInside(target: string, root: string): string | null {
+  const relative = path.relative(path.normalize(root), path.normalize(target));
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return null;
+  return relative;
+}
+
+/** The refusal text, without a trailing newline. */
+export function artifactRefusal({
+  target,
+  resolved,
+  companion,
+  repoRoot,
+}: ArtifactRefusalInput): string {
+  const isRelative = !path.isAbsolute(target);
+  const inside = relativeInside(resolved, repoRoot);
+  const suggested = inside ? path.join(companion, inside) : null;
+
+  const lines = [
+    `${FRAMEWORK_NAME} guardrail: ${ARTIFACT_REFUSAL_HEADLINE}`,
+    ` target:    ${target}`,
+  ];
+  if (isRelative) lines.push(` resolved:  ${resolved}`);
+  lines.push(` companion: ${companion}`);
+  if (suggested) lines.push(` suggested: ${suggested}`);
+  if (isRelative) {
+    lines.push(
+      "Relative paths resolve against the working repository; a preceding `cd` is not followed.",
+    );
+  }
+  lines.push(
+    suggested
+      ? "Rewrite to the suggested absolute path and retry."
+      : `Use an absolute path under ${companion}.`,
+  );
+  if (path.basename(target) === "CLAUDE.md") {
+    lines.push(`Note: CLAUDE.md already lives in the companion repo at ${companion}/CLAUDE.md.`);
+  }
+  return lines.join("\n");
+}

package/src/runtime/claude-delivery-plan.ts

@@ -1,4 +1,7 @@
+import path from "node:path";
+
 import type { ClaudeHookGroup } from "./claude-hook-group";
+import type { SessionKind } from "./session-kind";
 import { NOT_WRAPPED, readWrapStateSync, type WrapState } from "./wrap-state";
 
 /**
@@ -7,13 +10,6 @@ import { NOT_WRAPPED, readWrapStateSync, type WrapState } from "./wrap-state";
  * may import it.
  */
 
-/**
- * `managed-repo`: `mate claude` with a Working Repository; its prepare just
- * reconciled the Claude wrap, which the launcher asserts. `managed-companion`:
- * a companion-scoped launch. `unmanaged`: a session with no launch environment.
- */
-export type SessionKind = "managed-repo" | "managed-companion" | "unmanaged";
-
 export interface ClaudeDeliveryPlan {
   /** Capability hook groups; `launchSettingsExclude` is what `--settings` must not repeat. */
   readonly hooks: {
@@ -28,9 +24,95 @@ export interface ClaudeDeliveryPlan {
   readonly reconcile: "attended-prepare" | "prepare-hook" | "none";
   /** Companion Git synchronization. */
   readonly gitSync: "launch-preflight" | "prepare-hook" | "banner";
+  /**
+   * Plugin folders loaded as Claude plugins. A managed launch passes Mate's
+   * bundled plugin and every gathered Capability folder but `launchExclude`,
+   * the folders the wrap carries; a Claude-wrapped plain session gets those
+   * from the wrap alone.
+   */
+  readonly plugins: {
+    readonly owner: "launch-flag" | "wrap" | "none";
+    readonly launchExclude: readonly string[];
+  };
+  /** Companion Instructions, per thread kind; `dirAccess` through settings loads no memory file. */
+  readonly instructions: ClaudeInstructionOwners;
+}
+
+export interface ClaudeInstructionOwners {
+  /** `wrap-session-hook`: the wrap's session-prepare hook, once it has prepared, for a launch and a plain session alike. */
+  readonly main: "native-memory" | "wrap-session-hook" | "none";
+  /** `plugin-subagent-hook`: the bundled plugin's SubagentStart copy; `wrap-subagent-hook`: the wrap's. */
+  readonly subagents: "plugin-subagent-hook" | "native-memory" | "wrap-subagent-hook" | "none";
+}
+
+/**
+ * Whether the session's launch passes `--plugin-dir`: every managed launch does, a plain
+ * session cannot. Not whether the session loads plugin folders: a Claude-wrapped plain
+ * session gets them from the wrap.
+ */
+export function launchPassesClaudePluginFolders(kind: SessionKind): boolean {
+  return kind !== "unmanaged";
 }
 
 export function planClaudeDelivery(kind: SessionKind, wrap: WrapState): ClaudeDeliveryPlan {
+  return {
+    ...planChannels(kind, wrap),
+    plugins: planPlugins(kind, wrap),
+    instructions: planClaudeInstructions(kind, wrap.runtimes.has("claude")),
+  };
+}
+
+/**
+ * The instruction owners alone, for a hook that knows its wrap without reading
+ * one: a wrap-carried hook runs only because a Claude wrap installed it, maybe
+ * the main checkout's, so it must not gate on this Checkout's manifest.
+ */
+export function planClaudeInstructions(
+  kind: SessionKind,
+  wrappedForClaude: boolean,
+): ClaudeInstructionOwners {
+  switch (kind) {
+    case "managed-repo":
+      return { main: "wrap-session-hook", subagents: "plugin-subagent-hook" };
+    case "managed-companion":
+      return { main: "native-memory", subagents: "native-memory" };
+    case "unmanaged":
+      return wrappedForClaude
+        ? { main: "wrap-session-hook", subagents: "wrap-subagent-hook" }
+        : { main: "none", subagents: "none" };
+  }
+}
+
+/**
+ * The folders a managed launch passes with `--plugin-dir`, in order: the
+ * bundled plugin, then each gathered folder the wrap does not carry, matched
+ * by resolved path. None when the launch flag does not own plugin folders.
+ */
+export function launchPluginFolders(
+  plan: ClaudeDeliveryPlan,
+  gathered: readonly string[],
+  bundledPluginRoot: string,
+): string[] {
+  if (plan.plugins.owner !== "launch-flag") return [];
+  const carried = new Set(plan.plugins.launchExclude.map((dir) => path.resolve(dir)));
+  return [bundledPluginRoot, ...gathered.filter((dir) => !carried.has(path.resolve(dir)))];
+}
+
+function planPlugins(kind: SessionKind, wrap: WrapState): ClaudeDeliveryPlan["plugins"] {
+  switch (kind) {
+    case "managed-repo":
+      return { owner: "launch-flag", launchExclude: wrap.carriedClaudePluginDirectories };
+    case "managed-companion":
+      return { owner: "launch-flag", launchExclude: [] };
+    case "unmanaged":
+      return { owner: wrap.runtimes.has("claude") ? "wrap" : "none", launchExclude: [] };
+  }
+}
+
+function planChannels(
+  kind: SessionKind,
+  wrap: WrapState,
+): Omit<ClaudeDeliveryPlan, "plugins" | "instructions"> {
   switch (kind) {
     case "managed-repo":
       return {