@uniqbit/mate-core 0.15.4-canary.6 → 0.15.4-canary.8

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "mate",
+  "description": "Mate-managed Claude Code hooks: artifact-path guardrail, session banner, and the OpenSpec archive-finish nudge. Ships inside @uniqbit/mate-core and is loaded per managed launch via --plugin-dir; it is never published separately."
+}

package/claude-plugin/hooks/artifact-finish-nudge.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/artifact-finish-nudge.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/artifact-finish-nudge.ts";
+
+process.exitCode = await run();

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner, PostToolUse OpenSpec archive-finish nudge (self-gated at runtime)",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/validate-artifact-path.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-banner.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/artifact-finish-nudge.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin/hooks/session-banner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/session-banner.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/session-banner.ts";
+
+process.exitCode = run();

package/claude-plugin/hooks/validate-artifact-path.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/validate-artifact-path.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/validate-artifact-path.ts";
+
+process.exitCode = await run();

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.4-canary.6",
+  "version": "0.15.4-canary.8",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
     "src/",
     "wrappers/",
+    "claude-plugin/",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx"
   ],

package/src/cli/commands/install.ts

@@ -56,10 +56,14 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     process.exitCode = 1;
     return false;
   }
-  // Companion-declared plugins install first and hydrate into the registry
-  // before the plan is built, so one run goes install → load → plan and their
-  // own install requirements are part of the plan.
-  if (context.kind === "companion" && context.companionPath && context.config.plugins?.length) {
+  // Root-declared plugins (companion or hub) install first and hydrate into
+  // the registry before the plan is built, so one run goes install → load →
+  // plan and their own install requirements are part of the plan.
+  if (
+    (context.kind === "companion" || context.kind === "hub") &&
+    context.companionPath &&
+    context.config.plugins?.length
+  ) {
     reportPluginInstallResults(
       await installDeclaredPlugins(context.companionPath, context.config.plugins),
     );

package/src/cli/commands/plugin/install.ts

@@ -37,7 +37,7 @@ export interface PluginInstallCommandDeps {
 
 /**
  * @command mate plugin install <package>[@version]
- * @description Declares `<package>` in the companion's `framework.yaml`
+ * @description Declares `<package>` in the companion's (or hub's) `framework.yaml`
  * `plugins:` list (adding it, or updating its version if already declared)
  * and installs it immediately into the shared workspace, the same way
  * `mate install` would on its next run.
@@ -62,9 +62,9 @@ export async function runPluginInstallCommand(
     process.exitCode = 1;
     return false;
   }
-  if (context.kind !== "companion" || !context.companionPath) {
+  if ((context.kind !== "companion" && context.kind !== "hub") || !context.companionPath) {
     process.stderr.write(
-      `${FRAMEWORK_NAME}: \`plugin install\` requires a companion context; run it from inside a linked working repository.\n`,
+      `${FRAMEWORK_NAME}: \`plugin install\` requires a companion or hub context; run it from inside a linked working repository or a hub root.\n`,
     );
     process.exitCode = 1;
     return false;

package/src/cli/main.ts

@@ -30,6 +30,8 @@ export interface GateNeeds {
   updateGuard?: boolean;
   /** Block the command when the current directory resolves to a hub root. */
   notHubRoot?: boolean;
+  /** Block the command when the current directory resolves to a companion root. */
+  notCompanionRoot?: boolean;
   /** Require an unambiguous companion (selection wizard on ambiguity) before dispatch. */
   companion?: boolean;
   /** Require a complete installation (install preflight) before dispatch. */
@@ -91,12 +93,22 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       await showUpdateBannerIfAvailable(updateStore);
     }
 
-    if (needs.notHubRoot && (await deps.resolveRootContext()).kind === "hub") {
-      console.error(
-        `${FRAMEWORK_NAME}: this directory resolves to a companion hub root; companion commands are not available here. Use \`${FRAMEWORK_NAME} hub ...\` to manage the hub.`,
-      );
-      process.exitCode = 1;
-      return false;
+    if (needs.notHubRoot || needs.notCompanionRoot) {
+      const kind = (await deps.resolveRootContext()).kind;
+      if (needs.notHubRoot && kind === "hub") {
+        console.error(
+          `${FRAMEWORK_NAME}: this directory resolves to a companion hub root; companion commands are not available here. Use \`${FRAMEWORK_NAME} hub ...\` to manage the hub.`,
+        );
+        process.exitCode = 1;
+        return false;
+      }
+      if (needs.notCompanionRoot && kind === "companion") {
+        console.error(
+          `${FRAMEWORK_NAME}: this directory resolves to a companion root; hub commands are not available here. Run them from a hub root.`,
+        );
+        process.exitCode = 1;
+        return false;
+      }
     }
 
     if (needs.companion && !(await deps.ensureUnambiguousCompanion())) {
@@ -126,8 +138,9 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       return;
     case "plugin":
       // Declares into framework.yaml and installs on the spot, so it needs
-      // the same gating as `install` — an unambiguous companion, but must
-      // stay runnable when installation is otherwise incomplete.
+      // the same gating as `install` — an unambiguous companion (hubs pass
+      // trivially), but must stay runnable when installation is otherwise
+      // incomplete.
       if (!(await gate({ companion: true }))) return;
       await runPluginCommand(subcommand, rest);
       return;
@@ -144,9 +157,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
           if (!(await gate({ notHubRoot: true }))) return;
           break;
         // Hub commands establish and operate on a local hub root directly;
-        // they must not require a linked working repository or installation.
+        // they must not require a linked working repository or installation —
+        // but companions are never hubs.
         case "hub":
-          if (!(await gate({ updateGuard: true }))) return;
+          if (!(await gate({ updateGuard: true, notCompanionRoot: true }))) return;
           break;
         // open/tui consume a companion context.
         case "open":
@@ -160,7 +174,8 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       await runCompanionCommand(subcommand, rest);
       return;
     case "hub":
-      if (!(await gate({ updateGuard: true }))) return;
+      // Hubs are never companions: hub commands are blocked in companion roots.
+      if (!(await gate({ updateGuard: true, notCompanionRoot: true }))) return;
       await runHubCommand(subcommand ? [subcommand, ...rest] : []);
       return;
     case "claude":

package/src/hooks/artifact-finish-nudge.ts

@@ -0,0 +1,212 @@
+// Nudge the agent into the mate-artifact-finish workflow after a Bash command
+// visibly archived an OpenSpec change. Stateless PostToolUse hook: never denies
+// or blocks; emits additionalContext only on apparent success.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface NudgeOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+const ARCHIVE_PATH_PATTERN =
+  /(?:^|[\s/"'`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^/\s"'`,)]+)/;
+
+// The nudge only applies when the openspec capability is enabled and OpenSpec
+// git auto mode is on; the plugin registers the hook unconditionally, so the
+// gate is evaluated here from launch-injected environment before any parsing.
+export function isGateEnabled(env: HookEnv): boolean {
+  return env.MATE_OPENSPEC_ENABLED === "1" && env.MATE_GIT_AUTO_MODE === "1";
+}
+
+export function shellSplit(command: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: string | null = null;
+  let escaping = false;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      const next = command[index + 1] || "";
+      if (next === "\\" || /\s/.test(next) || next === "'" || next === '"') {
+        escaping = true;
+        continue;
+      }
+    }
+    if ((char === "'" || char === '"') && !quote) {
+      quote = char;
+      continue;
+    }
+    if (quote === char) {
+      quote = null;
+      continue;
+    }
+    const next = command[index + 1] || "";
+    const previous = command[index - 1] || "";
+    const isControlOperator =
+      !quote &&
+      (char === ";" ||
+        char === "|" ||
+        (char === "&" && next !== ">" && previous !== ">" && previous !== "<"));
+    if (isControlOperator) {
+      if (current) parts.push(current);
+      current = "";
+      if ((char === "|" || char === "&") && next === char) {
+        parts.push(char + next);
+        index += 1;
+      } else {
+        parts.push(char);
+      }
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function extractChangeFromPath(value: string): string | null {
+  const match = value.replaceAll("\\", "/").match(ARCHIVE_PATH_PATTERN);
+  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
+}
+
+// Shell syntax tokens are never change-name positionals: separators end the
+// archive invocation, redirections are skipped (a bare operator also consumes
+// its target token).
+const SEPARATOR_PATTERN = /^(\|\|?|&&?|;)$/;
+const REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)/;
+const BARE_REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)$/;
+
+export function extractArchiveCommand(command: string): string | null {
+  const parts = shellSplit(command);
+  const index = parts.findIndex(
+    (part, position) =>
+      part === "archive" &&
+      position > 0 &&
+      (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")),
+  );
+  if (index < 0) return null;
+  for (let position = index + 1; position < parts.length; position += 1) {
+    const part = parts[position];
+    if (!part || part === "--") continue;
+    if (SEPARATOR_PATTERN.test(part)) return null;
+    if (REDIRECTION_PATTERN.test(part)) {
+      if (BARE_REDIRECTION_PATTERN.test(part)) position += 1;
+      continue;
+    }
+    if (part.startsWith("-")) {
+      if (part === "--store") position += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+const MOVE_COMMANDS = new Set([
+  "mv",
+  "move",
+  "move-item",
+  "cmd",
+  "cmd.exe",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "pwsh.exe",
+]);
+
+function isPython(part: string): boolean {
+  return /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
+}
+
+export function extractMoveCommand(command: string): string | null {
+  const parts = shellSplit(command);
+  for (let index = 0; index < parts.length; index += 1) {
+    if (MOVE_COMMANDS.has(parts[index].toLowerCase())) {
+      for (const part of parts.slice(index + 1)) {
+        const change = extractChangeFromPath(part);
+        if (change) return change;
+      }
+    }
+    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
+      return extractChangeFromPath(command);
+    }
+  }
+  return null;
+}
+
+// Nudge only on apparent success: stay silent on a clear failure indication,
+// nudge when success is indicated or indeterminate.
+export function isClearFailure(response: unknown): boolean {
+  if (!response || typeof response !== "object") return false;
+  const value = response as Record<string, unknown>;
+  if (value.success === false || value.is_error === true) return true;
+  if (typeof value.error === "string" && value.error) return true;
+  if (value.interrupted === true) return true;
+  const exitCode = value.exit_code ?? value.exitCode;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): NudgeOutcome {
+  const silent: NudgeOutcome = { exitCode: 0, stdout: "" };
+  if (!isGateEnabled(env)) return silent;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  if (input.hook_event_name !== "PostToolUse" || input.tool_name !== "Bash") return silent;
+
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const change = extractArchiveCommand(command) || extractMoveCommand(command);
+  if (!change) return silent;
+  if (isClearFailure(input.tool_response)) return silent;
+
+  const context =
+    `OpenSpec change ${change} was just archived. Invoke the mate-artifact-finish ` +
+    `skill, then run \`mate artifact finish "${change}" --json\` to complete the ` +
+    "finish workflow (commit, tag, and push).";
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: context,
+      },
+    }),
+  };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry. The gate check precedes stdin parsing so a disabled gate
+// costs one env read.
+export async function run(): Promise<number> {
+  if (!isGateEnabled(process.env)) return 0;
+
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/session-banner.ts

@@ -0,0 +1,25 @@
+// Show the active Mate companion paths in Claude Code.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface BannerOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+// Fail-soft outside managed sessions: no MATE_* env, no banner.
+export function buildBanner(env: HookEnv): BannerOutcome {
+  const repoPath = env.MATE_REPO_PATH;
+  const artifactPath = env.MATE_ARTIFACT_PATH;
+  if (!repoPath || !artifactPath) return { exitCode: 0, stdout: "" };
+
+  const mateVersion = env.MATE_VERSION || "unknown";
+  const message = `mate v${mateVersion}\n  repo:     ${repoPath}\n  mate: ${artifactPath}`;
+  return { exitCode: 0, stdout: JSON.stringify({ systemMessage: message }) + "\n" };
+}
+
+// Plugin-shim entry.
+export function run(): number {
+  const outcome = buildBanner(process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/validate-artifact-path.ts

@@ -0,0 +1,236 @@
+// Block artifact writes outside the companion framework path.
+//
+// Artifact-like files may be written in the working repository only when the
+// target path is already ignored by git. That keeps local-only scratch files
+// possible without weakening the default repo split.
+//
+// Editing a file that already exists is always allowed: the guard exists to
+// stop new agent artifacts from landing in the working repo, not to freeze
+// files that are already part of it.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type HookEnv = Record<string, string | undefined>;
+
+export interface HookOutcome {
+  exitCode: number;
+  stderr: string;
+}
+
+const KNOWN_ARTIFACT_BASENAMES = new Set([
+  "CLAUDE.md",
+  "CONTEXT.md",
+  "design.md",
+  "explore-brief.md",
+  "proposal.md",
+  "spec.md",
+  "tasks.md",
+]);
+
+const ARTIFACT_PATH_MARKERS = [
+  "/changes/",
+  "/openspec/",
+  "/specs/",
+  "/docs/adr/",
+  "/docs/adrs/",
+  "/docs/decisions/",
+  "/docs/prd/",
+];
+
+const MD_REDIRECT_PATTERN = />{1,2}\s*([^\s;|&<>]+\.md)\b/g;
+const MD_TEE_PATTERN = /\btee\s+(?:-a\s+)?([^\s;|&<>]+\.md)\b/g;
+
+export function artifactLikePath(filePath: string): boolean {
+  if (!filePath) return false;
+
+  const basename = path.basename(filePath);
+  const normalized = "/" + filePath.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (KNOWN_ARTIFACT_BASENAMES.has(basename)) return true;
+
+  if (ARTIFACT_PATH_MARKERS.some((marker) => normalized.includes(marker))) return true;
+
+  if (basename.endsWith(".md") && basename !== "README.md") return true;
+
+  return false;
+}
+
+function repoRoot(env: HookEnv): string {
+  return env.MATE_REPO_PATH || process.cwd();
+}
+
+function companionRoot(env: HookEnv): string | null {
+  const companion = env.MATE_ARTIFACT_PATH;
+  return companion ? path.normalize(companion) : null;
+}
+
+// Claude Code's own config/state directory (plan files, settings, todos).
+// Writes there are agent-runtime state, never Mate artifacts.
+function claudeConfigRoot(env: HookEnv): string {
+  const configured = env.CLAUDE_CONFIG_DIR;
+  if (configured) return path.normalize(configured);
+  return path.normalize(path.join(env.HOME || os.homedir(), ".claude"));
+}
+
+function normalizePath(filePath: string, env: HookEnv): string {
+  if (path.isAbsolute(filePath)) return path.normalize(filePath);
+  return path.normalize(path.join(repoRoot(env), filePath));
+}
+
+function isUnder(target: string, root: string): boolean {
+  const relative = path.relative(path.normalize(root), path.normalize(target));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isGitignored(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "check-ignore", "--no-index", "-q", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+// A file already tracked in the working repo is product code being edited,
+// not a new agent artifact (e.g. packaged SKILL.md/spec.md template sources).
+function isGitTracked(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "ls-files", "--error-unmatch", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+function isProductDocumentationPath(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const parts = relPath.split(path.sep).filter(Boolean);
+  for (const [index, part] of parts.entries()) {
+    if (part === ".storybook" || part === "storybook") return true;
+
+    if (part !== "docs") continue;
+
+    const docsRoot = path.join(root, ...parts.slice(0, index + 1));
+    if (fs.existsSync(path.join(docsRoot, "package.json"))) return true;
+  }
+
+  return false;
+}
+
+function blockWrite(target: string, companion: string): HookOutcome {
+  const lines = [
+    "Mate guardrail: artifact writes must go to the companion framework path.",
+    ` target: ${target}`,
+    ` companion: ${companion}`,
+    "Use an absolute path under MATE_ARTIFACT_PATH instead.",
+  ];
+  if (path.basename(target) === "CLAUDE.md") {
+    lines.push(`Note: CLAUDE.md already lives in the companion repo at ${companion}/CLAUDE.md.`);
+  }
+  return { exitCode: 2, stderr: lines.join("\n") + "\n" };
+}
+
+function checkFilePath(
+  filePath: string,
+  companion: string | null,
+  env: HookEnv,
+  allowExisting = false,
+): HookOutcome | null {
+  if (!filePath || !companion) return null;
+
+  const normalized = normalizePath(filePath, env);
+  if (normalized.startsWith(companion)) return null;
+
+  if (isUnder(normalized, claudeConfigRoot(env))) return null;
+
+  if (allowExisting && fs.existsSync(normalized) && fs.statSync(normalized).isFile()) return null;
+
+  if (isProductDocumentationPath(normalized, env)) return null;
+
+  if (!artifactLikePath(filePath)) return null;
+
+  if (
+    isUnder(normalized, repoRoot(env)) &&
+    (isGitignored(normalized, env) || isGitTracked(normalized, env))
+  ) {
+    return null;
+  }
+
+  return blockWrite(filePath, companion);
+}
+
+export function commandMatches(command: string): string[] {
+  const targets: string[] = [];
+  for (const pattern of [MD_REDIRECT_PATTERN, MD_TEE_PATTERN]) {
+    const matcher = new RegExp(pattern.source, pattern.flags);
+    for (const match of command.matchAll(matcher)) {
+      const target = match[1].trim().replace(/^["']+|["']+$/g, "");
+      if (target) targets.push(target);
+    }
+  }
+  return targets;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): HookOutcome {
+  const allow: HookOutcome = { exitCode: 0, stderr: "" };
+
+  const companion = companionRoot(env);
+  if (!companion) return allow;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+
+  if (toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    const outcome = checkFilePath(
+      String(toolInput.file_path ?? ""),
+      companion,
+      env,
+      toolName === "Edit" || toolName === "MultiEdit",
+    );
+    return outcome ?? allow;
+  }
+
+  if (toolName === "Bash") {
+    const command = String(toolInput.command ?? "");
+    for (const target of commandMatches(command)) {
+      const outcome = checkFilePath(target, companion, env);
+      if (outcome) return outcome;
+    }
+    return allow;
+  }
+
+  return allow;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry: read the hook payload from stdin, evaluate, report.
+export async function run(): Promise<number> {
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stderr) process.stderr.write(outcome.stderr);
+  return outcome.exitCode;
+}

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

@@ -83,6 +83,7 @@ export abstract class LaunchAdapter {
       MATE_WRAPPER_BIN_PATH: wrapperBinPath,
       PATH: prependPathEntry(process.env.PATH, wrapperBinPath),
       MATE_GRAPHIFY_ENABLED: context.capabilities.some((c) => c.name === "graphify") ? "1" : "0",
+      MATE_OPENSPEC_ENABLED: context.capabilities.some((c) => c.name === "openspec") ? "1" : "0",
       MATE_REACT_DOCTOR_ENABLED: reactDoctorEnabled ? "1" : "0",
       MATE_GIT_AUTO_MODE: context.git === "auto" ? "1" : "0",
       MATE_REPO_ID: context.repository.id,