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

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

@@ -1,8 +1,8 @@
 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 { PROJECTED_FLAG } from "../../../runtime/projected-flag";
 import { runtimeClaudePluginRoot } from "../../../runtime/runtime-directory";
 import { hookGroupKey, type ClaudeHookGroup } from "./claude-format";
 
@@ -12,12 +12,11 @@ import { hookGroupKey, type ClaudeHookGroup } from "./claude-format";
  * 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.
+ * source *alongside* the plugin, so every group carried over runs twice there;
+ * a plain session may load both too, through `--plugin-dir`. The guard is
+ * input-pure, the guidance hook yields under a launch environment, and the
+ * banner, prepare and SubagentStart instruction copies carried here hold
+ * `PROJECTED_FLAG`, so one copy of each acts.
  *
  * The wiring is read from the installed plugin, but every command names
  * `<mate home>/runtime/claude-plugin`, so a reinstall or Node switch does not
@@ -28,6 +27,7 @@ const GUARD_HOOK_SHIM = "validate-artifact-path.mjs";
 const GUIDANCE_HOOK_SHIM = "session-guidance.mjs";
 const BANNER_HOOK_SHIM = "session-banner.mjs";
 const PREPARE_HOOK_SHIM = "session-prepare.mjs";
+const INSTRUCTIONS_HOOK_SHIM = "companion-instructions.mjs";
 const PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}";
 
 interface PluginHookWiring {
@@ -46,16 +46,23 @@ function readPluginHookWiring(pluginRoot: string): PluginHookWiring {
   return {};
 }
 
-function resolveCommands(group: ClaudeHookGroup, pluginRoot: string): ClaudeHookGroup {
+function mapCommands(
+  group: ClaudeHookGroup,
+  rewrite: (command: string) => string,
+): ClaudeHookGroup {
   return {
     ...group,
     hooks: (group.hooks ?? []).map((hook) => ({
       ...hook,
-      ...(hook.command ? { command: hook.command.split(PLUGIN_ROOT_TOKEN).join(pluginRoot) } : {}),
+      ...(hook.command ? { command: rewrite(hook.command) } : {}),
     })),
   };
 }
 
+function resolveCommands(group: ClaudeHookGroup, pluginRoot: string): ClaudeHookGroup {
+  return mapCommands(group, (command) => command.split(PLUGIN_ROOT_TOKEN).join(pluginRoot));
+}
+
 function runsShim(group: ClaudeHookGroup, shim: string): boolean {
   return (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
 }
@@ -90,31 +97,43 @@ export function mateGuidanceHookGroups(
 
 /**
  * The banner's `SessionStart` group, resolved the same way and carrying
- * `PROJECTED_BANNER_FLAG`. Without the marker the carried command would be
+ * `PROJECTED_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(
   commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", BANNER_HOOK_SHIM, commandRoot).map((group) => ({
-    ...group,
-    hooks: (group.hooks ?? []).map((hook) => ({
-      ...hook,
-      ...(hook.command ? { command: `${hook.command} ${PROJECTED_BANNER_FLAG}` } : {}),
-    })),
-  }));
+  return withProjectedFlag(groupsFor("SessionStart", BANNER_HOOK_SHIM, commandRoot));
+}
+
+function withProjectedFlag(groups: ClaudeHookGroup[]): ClaudeHookGroup[] {
+  return groups.map((group) => mapCommands(group, (command) => `${command} ${PROJECTED_FLAG}`));
+}
+
+/**
+ * The `SubagentStart` instruction group, resolved the same way and carrying
+ * `PROJECTED_FLAG`: a session that loads both this copy and the plugin's,
+ * through a launch or `--plugin-dir`, would otherwise deliver the instructions
+ * twice.
+ */
+export function mateInstructionHookGroups(
+  commandRoot: string = runtimeClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return withProjectedFlag(groupsFor("SubagentStart", INSTRUCTIONS_HOOK_SHIM, commandRoot));
 }
 
 /**
  * The session-prepare `SessionStart` group, resolved the same way. Its declared
  * `timeout` sits above the shim's own bound, so Claude Code never kills a
- * prepare the shim has not given up on. Inert under a launch environment.
+ * prepare the shim has not given up on. It carries `PROJECTED_FLAG`: this copy
+ * alone prepares, which it skips under a launch environment, and then delivers
+ * the main thread's instructions; the plugin's copy stays inert.
  */
 export function mateSessionPrepareHookGroups(
   commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", PREPARE_HOOK_SHIM, commandRoot);
+  return withProjectedFlag(groupsFor("SessionStart", PREPARE_HOOK_SHIM, commandRoot));
 }
 
 function mateOwnHookGroups(commandRoot: string): ClaudeHookGroup[] {
@@ -123,6 +142,7 @@ function mateOwnHookGroups(commandRoot: string): ClaudeHookGroup[] {
     ...mateGuidanceHookGroups(commandRoot),
     ...mateBannerHookGroups(commandRoot),
     ...mateSessionPrepareHookGroups(commandRoot),
+    ...mateInstructionHookGroups(commandRoot),
   ];
 }
 

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

@@ -4,6 +4,17 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import type { FrameworkConfig } from "../../../lib/orchestrator/types";
+import { getClaudePluginRoot } from "../../../lib/package-paths";
+import { writeAtomicThroughLink } from "../../../runtime/write-atomic";
+import { resolveSecretPolicy } from "../../../runtime/policy";
+import {
+  CLAUDE_LOCAL_CONFIG_DOCUMENT,
+  CLAUDE_SETTINGS_DOCUMENT,
+  renderedDocument,
+  type ManagedRegion,
+  type RenderedRuntimeDocuments,
+} from "../../../runtime/runtime-document-manifest";
+import { projectableSecretDenyPatterns } from "../../../runtime/secret-patterns";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
 import {
   instructionBlockKey,
@@ -11,9 +22,19 @@ import {
   upsertManagedBlock,
 } from "../context-services";
 import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
-import { surfaceRoot } from "../surface-target";
+import { projectionRepoRoot, surfaceRoot } from "../surface-target";
 import { mergeDir, pruneEmptyAncestors } from "../utils";
 import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
+import {
+  claudeUserConfigDir,
+  definesUserClaudeAttribution,
+  isManagedClaudeAttribution,
+  MANAGED_CLAUDE_ATTRIBUTION,
+} from "./claude-attribution";
+import {
+  inspectClaudePluginFolders,
+  type PublishedClaudePluginFolder,
+} from "./claude-plugin-folders";
 import { patchSkillTreeMarkdownFiles } from "./skill-tree";
 import {
   filterClaudeHookGroups,
@@ -28,6 +49,13 @@ import {
   type ClaudeHookGroup,
   type ClaudeSettings,
 } from "./claude-format";
+import {
+  mateBannerHookGroups,
+  mateGuardHookGroups,
+  mateGuidanceHookGroups,
+  mateInstructionHookGroups,
+  mateSessionPrepareHookGroups,
+} from "./claude-plugin-hooks";
 import { getSetupRootTemplates } from "./utils";
 
 async function configureClaudeGuidance(companionPath: string): Promise<void> {
@@ -106,6 +134,54 @@ function getAllManagedPermissionEntries(companionPath: string): Set<string> {
   ]);
 }
 
+/**
+ * Claude Code features Mate turns off because they compete with its own
+ * workflow: plan mode writes plans outside the Companion Repository, the
+ * Artifact tool competes with `mate report`, and DesignSync has no role in a
+ * Mate session. `ExitPlanMode` stays allowed so a user who enters plan mode
+ * by hand can still leave it. Fixed, not configurable.
+ */
+export const MANAGED_CLAUDE_DENY_ENTRIES: readonly string[] = ["EnterPlanMode", "DesignSync"];
+
+const SECRET_DENY_TOOLS = ["Read", "Edit"] as const;
+
+/**
+ * Claude deny rules for the default secret files, at any depth. Claude checks
+ * deny before allow, so only patterns that can't match an allow-listed file are
+ * rendered; the hook enforces the rest of the pattern set. Claude applies
+ * `Edit(...)` rules to every built-in file-editing tool, `Write` included, so
+ * no `Write(...)` rule is rendered: Claude never matches one and warns about it.
+ */
+export function renderSecretDenyEntries(): string[] {
+  return projectableSecretDenyPatterns().flatMap((pattern) =>
+    SECRET_DENY_TOOLS.map((tool) => `${tool}(**/${pattern})`),
+  );
+}
+
+/** The managed `permissions.deny` list: fixed tool denies, plus secret files while guardrails are on. */
+function renderManagedClaudeDenyEntries(companionPath: string): string[] {
+  return [
+    ...MANAGED_CLAUDE_DENY_ENTRIES,
+    ...(resolveSecretPolicy(companionPath).guardrails ? renderSecretDenyEntries() : []),
+  ];
+}
+
+/**
+ * Every deny entry Mate may have written, whatever the current config says, so
+ * an opt-out strips the secret entries instead of keeping them as user entries.
+ */
+function getAllManagedDenyEntries(): Set<string> {
+  return new Set([
+    ...MANAGED_CLAUDE_DENY_ENTRIES,
+    ...renderSecretDenyEntries(),
+    // Legacy secret entries: Claude Code never matched Write() rules for file
+    // permission checks and warns about them, so setup no longer emits them.
+    // Keep them managed so re-running setup strips them from existing installs.
+    ...projectableSecretDenyPatterns().map((pattern) => `Write(**/${pattern})`),
+  ]);
+}
+const MANAGED_CLAUDE_FORCED_SETTINGS = { enableArtifact: false } as const;
+
 /** Companion-owned Claude settings: sole source of Mate-managed hooks, permissions and MCP servers. */
 export function getCompanionClaudeSettingsPath(companionPath: string): string {
   return path.join(companionPath, ".claude", "settings.local.json");
@@ -121,7 +197,7 @@ export function getCompanionClaudeMcpConfigPath(companionPath: string): string {
  * Rendered separately from the settings document so a working-target pass can
  * obtain them without a write.
  */
-export function renderManagedClaudePermissionEntries(
+function renderManagedClaudePermissionEntries(
   companionPath: string,
   contributions: CapabilityContributionInput[] = [],
 ): string[] {
@@ -134,7 +210,7 @@ export function renderManagedClaudePermissionEntries(
 }
 
 /** The Mate-managed `.mcp.json` server map of one pass, as a value. */
-export function renderManagedClaudeMcpServers(
+function renderManagedClaudeMcpServers(
   contributions: CapabilityContributionInput[] = [],
 ): Record<string, unknown> {
   const servers: Record<string, unknown> = {};
@@ -151,7 +227,7 @@ export function renderManagedClaudeMcpServers(
  * Enabled Capabilities' Claude hook groups per event, in declared order, as a
  * value: what a Claude wrap carries into the Working Repository.
  */
-export function renderManagedClaudeHookGroups(
+function renderManagedClaudeHookGroups(
   contributions: CapabilityContributionInput[] = [],
 ): Record<string, ClaudeHookGroup[]> {
   const hooks: Record<string, ClaudeHookGroup[]> = {};
@@ -173,6 +249,7 @@ function renderManagedClaudeSettings(
   companionPath: string,
   config: FrameworkConfig,
   contributions: CapabilityContributionInput[] = [],
+  userDefinesAttribution: boolean,
 ): ClaudeSettings {
   // Declared markers and permission entries widen the managed strip set for
   // every registered Capability, enabled or not, so deselection tears down.
@@ -221,6 +298,13 @@ function renderManagedClaudeSettings(
   } else {
     delete permissions.allow;
   }
+  // permissions.deny: same reconciliation as allow, against the fixed set.
+  const managedDeny = getAllManagedDenyEntries();
+  const existingDeny = Array.isArray(existingPermissions.deny) ? existingPermissions.deny : [];
+  permissions.deny = [
+    ...existingDeny.filter((entry) => !managedDeny.has(entry)),
+    ...renderManagedClaudeDenyEntries(companionPath),
+  ];
 
   const mcpServers = { ...existing.mcpServers };
   // tokensave (and any future Mate-managed MCP server) now lives in the
@@ -228,7 +312,12 @@ function renderManagedClaudeSettings(
   // entry is removed so it cannot shadow the `.mcp.json` definition.
   delete mcpServers.tokensave;
 
-  const settings: ClaudeSettings = { ...existing, hooks, autoMemoryEnabled: false };
+  const settings: ClaudeSettings = {
+    ...existing,
+    hooks,
+    autoMemoryEnabled: false,
+    ...MANAGED_CLAUDE_FORCED_SETTINGS,
+  };
   if (Object.keys(hooks).length === 0) {
     delete settings.hooks;
   }
@@ -242,10 +331,190 @@ function renderManagedClaudeSettings(
   } else {
     delete settings.mcpServers;
   }
+  /** The document's own value is kept; Mate's yields to one the user scope sets. */
+  if (!("attribution" in existing) || isManagedClaudeAttribution(existing.attribution)) {
+    if (userDefinesAttribution) delete settings.attribution;
+    else settings.attribution = { ...MANAGED_CLAUDE_ATTRIBUTION };
+  }
 
   return settings;
 }
 
+/**
+ * Loaded by a managed session beside the launch's plugin, so each Mate hook
+ * here runs twice there: the guard is input-pure, guidance yields under a
+ * launch env, and the banner, prepare and instruction copies carry
+ * `--projected`, so one copy of each acts. Capability groups run once: the
+ * launch omits them from `--settings`.
+ *
+ * `permissions.additionalDirectories` grants companion file access only; it
+ * loads no `CLAUDE.md`.
+ *
+ * Unlike {@link renderManagedClaudeSettings}, this carries no
+ * `autoMemoryEnabled: false`. Whether a Wrap should leave the user's choice
+ * alone there is an open question, not settled policy.
+ */
+function claudeSettingsRegions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+  repoRoot: string,
+  pluginFolders: readonly PublishedClaudePluginFolder[],
+): ManagedRegion[] {
+  const capabilityHooks = renderManagedClaudeHookGroups(inputs);
+  const mateHooks: Record<string, unknown[]> = {
+    PreToolUse: mateGuardHookGroups(),
+    SessionStart: [
+      ...mateBannerHookGroups(),
+      ...mateGuidanceHookGroups(),
+      ...mateSessionPrepareHookGroups(),
+    ],
+    SubagentStart: mateInstructionHookGroups(),
+  };
+  const events = [...new Set([...Object.keys(mateHooks), ...Object.keys(capabilityHooks)])];
+  return [
+    ...events.map((event): ManagedRegion => ({
+      at: ["hooks", event],
+      kind: "list",
+      values: [...(mateHooks[event] ?? []), ...(capabilityHooks[event] ?? [])],
+    })),
+    /**
+     * `stripPrefix` heals a repository an older Mate wrapped. That version wrote
+     * the whole launch environment here, and Claude Code applies `env` to the
+     * session, so every hook in a bare session inherited `MATE_*` and read the
+     * repository as a Managed Session — silently, since looking managed is
+     * exactly what makes the guidance hook emit nothing. Guidance must be the
+     * projection's to give in an Unmanaged Session, so no `MATE_*` key may
+     * survive here. It sets no entry of its own: the
+     * `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` an earlier wrap set is
+     * reverted from the manifest, so a user's own value stays.
+     */
+    {
+      at: ["env"],
+      kind: "map",
+      entries: {},
+      stripPrefix: "MATE_",
+    },
+    {
+      at: ["permissions", "allow"],
+      kind: "list",
+      values: renderManagedClaudePermissionEntries(ctx.companionPath, inputs),
+    },
+    {
+      at: ["permissions", "deny"],
+      kind: "list",
+      values: renderManagedClaudeDenyEntries(ctx.companionPath),
+    },
+    ...claudePluginRegions(pluginFolders),
+    /**
+     * Yields: the document is the user's, so their own `enableArtifact` wins,
+     * and unwrapping restores it instead of deleting a key Mate overwrote.
+     */
+    ...Object.entries(MANAGED_CLAUDE_FORCED_SETTINGS).map(([key, value]): ManagedRegion => ({
+      at: [key],
+      kind: "value",
+      value,
+      yields: true,
+    })),
+    /**
+     * Placed only while no scope sets attribution: a project-scope value would
+     * lose to this local one, yielding or not. Mate's own earlier value does
+     * not count as the user's.
+     */
+    ...(definesUserClaudeAttribution({ repoRoot })
+      ? []
+      : [
+          {
+            at: ["attribution"],
+            kind: "value",
+            value: { ...MANAGED_CLAUDE_ATTRIBUTION },
+            yields: true,
+          } satisfies ManagedRegion,
+        ]),
+  ];
+}
+
+/**
+ * Each published plugin folder as a local `directory` marketplace and its one
+ * enabled plugin, so a plain session in a trusted folder loads it in place. The
+ * path is the folder as the launch passes it, so the wrap state can name what
+ * the launch must leave to the wrap.
+ */
+function claudePluginRegions(published: readonly PublishedClaudePluginFolder[]): ManagedRegion[] {
+  return [
+    {
+      at: ["extraKnownMarketplaces"],
+      kind: "map",
+      entries: Object.fromEntries(
+        published.map(({ path: folder, marketplace }) => [
+          marketplace,
+          { source: { source: "directory", path: folder } },
+        ]),
+      ),
+    },
+    {
+      at: ["enabledPlugins"],
+      kind: "map",
+      entries: Object.fromEntries(
+        published.map(({ plugin, marketplace }) => [`${plugin}@${marketplace}`, true]),
+      ),
+    },
+  ];
+}
+
+/**
+ * The working target's Claude documents, rendered as values. Each is a document
+ * the runtime finds by walking up from the current directory, and every path
+ * inside one still names the Companion Repository — only where the document is
+ * placed differs from the companion target.
+ */
+export async function renderClaudeWorkingDocuments(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<RenderedRuntimeDocuments> {
+  const repoRoot = projectionRepoRoot(ctx);
+  /** Reads the folders only; the pass published them before this render. */
+  const pluginFolders = (
+    await inspectClaudePluginFolders(inputs, { bundledPluginRoot: getClaudePluginRoot() })
+  ).published;
+  return {
+    documents: [
+      ...renderedDocument(
+        CLAUDE_SETTINGS_DOCUMENT,
+        claudeSettingsRegions(ctx, inputs, repoRoot, pluginFolders),
+      ),
+      /**
+       * Local scope, not `.mcp.json`: a project-scoped server is inert until a
+       * human approves it in a session, which an Unmanaged Session is exactly the
+       * case that cannot rely on. The repo path is the key Claude Code files a
+       * project under, resolved so a symlinked working directory still matches.
+       *
+       * Confirmed against a real `~/.claude.json`: the keys there are the
+       * directories sessions started in, not repository roots — sibling
+       * directories of one checkout each hold their own entry, as do temporary
+       * directories. So this reaches exactly one session: the one started at the
+       * repository root. A session started in a subdirectory of a wrapped
+       * repository has its own key, finds no `mcpServers` under it, and sees none
+       * of these servers — the Unmanaged Session case this document exists for,
+       * missed. That limit is deliberate. The directories a session might start
+       * in are unbounded, and every one of them would be a fresh entry in the
+       * user's global configuration that nothing later reclaims; keying the
+       * repository root only keeps the projection's footprint there to a single
+       * key. A subdirectory session still gets the rest of the projection — the
+       * documents inside the repository are found by the runtime's own upward
+       * walk — it loses only the MCP servers.
+       */
+      ...renderedDocument(CLAUDE_LOCAL_CONFIG_DOCUMENT, [
+        {
+          at: ["projects", repoRoot, "mcpServers"],
+          kind: "map",
+          entries: renderManagedClaudeMcpServers(inputs),
+        },
+      ]),
+    ],
+    warnings: [],
+  };
+}
+
 // Write the Mate-managed Claude settings into the companion repo. This is the
 // config surface Mate owns and loads at launch via `--settings`, so hooks,
 // permissions, and MCP servers no longer need to live in the working repo.
@@ -253,10 +522,17 @@ export async function syncCompanionClaudeSettings(
   companionPath: string,
   config: FrameworkConfig,
   contributions: CapabilityContributionInput[] = [],
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const settingsPath = getCompanionClaudeSettingsPath(companionPath);
   const existing = await readClaudeSettings(settingsPath);
-  const settings = renderManagedClaudeSettings(existing, companionPath, config, contributions);
+  const settings = renderManagedClaudeSettings(
+    existing,
+    companionPath,
+    config,
+    contributions,
+    definesUserClaudeAttribution({ userConfigDir: claudeUserConfigDir(env) }),
+  );
 
   await writeClaudeSettings(settingsPath, settings);
 
@@ -395,7 +671,7 @@ async function configureClaude(companionPath: string): Promise<void> {
   try {
     await fs.access(agentsMdDest);
   } catch {
-    await fs.copyFile(agentsMdSrc, agentsMdDest);
+    await writeAtomicThroughLink(agentsMdDest, await fs.readFile(agentsMdSrc));
   }
 
   const claudeMdSrc = path.join(getSetupRootTemplates(), "TEMPLATE_CLAUDE.md");
@@ -403,7 +679,7 @@ async function configureClaude(companionPath: string): Promise<void> {
   try {
     await fs.access(claudeMdDest);
   } catch {
-    await fs.copyFile(claudeMdSrc, claudeMdDest);
+    await writeAtomicThroughLink(claudeMdDest, await fs.readFile(claudeMdSrc));
   }
 }