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

package/src/cli/parse-flags.ts

@@ -1,6 +1,5 @@
 import {
   type GitModeSelection,
-  type OpenSpecSchemaSelection,
   listSetupCapabilityCompatibilities,
 } from "../lib/orchestrator/setup-compatibilities";
 import type { CapabilityConfig } from "../lib/orchestrator/types";
@@ -63,6 +62,31 @@ export function parseFlags(
   return flags;
 }
 
+/** Tokens that are neither flags nor flag values, read with the rules of {@link parseFlags}. */
+export function positionalArgs(
+  argv: string[],
+  booleanFlags: BooleanFlagSet = NO_BOOLEAN_FLAGS,
+): string[] {
+  const names: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) names.push(token);
+    else if (token.includes("=") || booleanFlags.has(token.slice(2))) continue;
+    else if (argv[index + 1] && !argv[index + 1].startsWith("--")) index += 1;
+  }
+  return names;
+}
+
+/** A flag's value when it was given one, so a bare or repeated flag reads as absent. */
+export function stringFlag(value: CliFlags[string] | undefined): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** The first of `names` given bare or more than once, which {@link stringFlag} would read as absent. */
+export function malformedValueFlag(flags: CliFlags, names: readonly string[]): string | undefined {
+  return names.find((name) => flags[name] !== undefined && typeof flags[name] !== "string");
+}
+
 export function parseAllowedAgents(flags: CliFlags): string[] | undefined {
   const allowedAgents = flags["allowed-agent"];
   return Array.isArray(allowedAgents)
@@ -95,12 +119,6 @@ export function parseCapabilities(flags: CliFlags): CapabilityConfig[] | undefin
   return names.map((name) => index.get(name) ?? { name });
 }
 
-export function parseOpenSpecSchema(flags: CliFlags): OpenSpecSchemaSelection | undefined {
-  const schema = flags["openspec-schema"];
-  if (schema === "mate-v1" || schema === "default") return schema;
-  return undefined;
-}
-
 export function parseGitMode(flags: CliFlags): GitModeSelection | undefined {
   const gitMode = flags["git-mode"];
   if (gitMode === "auto" || gitMode === "default") return gitMode;

package/src/cli/setup-selector.tsx

@@ -9,14 +9,10 @@ import { getRequiredPluginIds, withRequiredSelections } from "../tools/setup/pol
 
 import {
   type GitModeSelection,
-  type OpenSpecSchemaSelection,
   type SetupSelections,
-  applyOpenSpecSchemaSelection,
   DEFAULT_GIT_MODE_SELECTION,
-  getOpenSpecSchemaSelection,
   listSetupCapabilityCompatibilities,
   listSetupGitModeCompatibilities,
-  listSetupOpenSpecSchemaCompatibilities,
   listSetupPackageManagerCompatibilities,
   listSetupProviderCompatibilities,
 } from "../lib/orchestrator/setup-compatibilities";
@@ -28,16 +24,14 @@ interface SetupSelectorOptions {
   stderr?: NodeJS.WriteStream;
 }
 
-export type WizardStep = "providers" | "capabilities" | "openspecSchema" | "gitMode";
+export type WizardStep = "providers" | "capabilities" | "gitMode";
 
 interface SetupSelectorProps {
   activeIndex: number;
   currentStep: number;
-  steps: WizardStep[];
   selectedProviders: Set<string>;
   selectedPackageManagers: Set<string>;
   selectedCapabilities: Set<string>;
-  selectedOpenSpecSchema: OpenSpecSchemaSelection;
   selectedGitMode: GitModeSelection;
   onMounted?: () => void;
 }
@@ -47,7 +41,7 @@ export const setupSelectorDeps = {
 };
 
 export interface SetupSelectorItem {
-  kind: "provider" | "packageManager" | "capability" | "openspecSchema" | "gitMode";
+  kind: "provider" | "packageManager" | "capability" | "gitMode";
   id: string;
   label: string;
   description: string;
@@ -62,48 +56,17 @@ export interface SetupSelectorState {
   selectedProviders: Set<string>;
   selectedPackageManagers: Set<string>;
   selectedCapabilities: Set<string>;
-  selectedOpenSpecSchema: OpenSpecSchemaSelection;
   selectedGitMode: GitModeSelection;
 }
 
-const BASE_WIZARD_STEPS: readonly Exclude<WizardStep, "openspecSchema">[] = [
-  "providers",
-  "capabilities",
-  "gitMode",
-];
+export const WIZARD_STEPS: readonly WizardStep[] = ["providers", "capabilities", "gitMode"];
 
 const STEP_DISPLAY_NAMES: Record<WizardStep, string> = {
   providers: "Agents",
   capabilities: "Capabilities",
-  openspecSchema: "OpenSpec Schema Profile",
   gitMode: "Git Auto Mode",
 };
 
-export const OPENSPEC_SCHEMA_SKIP_MESSAGE = "OpenSpec not selected - skipping";
-
-function hasOpenSpecSelected(selectedCapabilities: Set<string>): boolean {
-  return selectedCapabilities.has("openspec");
-}
-
-export function getOpenSpecSchemaStepMessage(
-  step: WizardStep,
-  selectedCapabilities: Set<string>,
-): string | null {
-  return step === "openspecSchema" && !hasOpenSpecSelected(selectedCapabilities)
-    ? OPENSPEC_SCHEMA_SKIP_MESSAGE
-    : null;
-}
-
-export function buildWizardSteps(options: {
-  selectedCapabilities: Set<string>;
-  lockOpenSpecSchemaStep?: boolean;
-}): WizardStep[] {
-  if (!hasOpenSpecSelected(options.selectedCapabilities) && !options.lockOpenSpecSchemaStep) {
-    return [...BASE_WIZARD_STEPS];
-  }
-  return ["providers", "capabilities", "openspecSchema", "gitMode"];
-}
-
 export function parseSelectorInput(
   input: string,
 ): "up" | "down" | "toggle" | "submit" | "cancel" | "back" | null {
@@ -147,9 +110,7 @@ function markRequiredItems(items: SetupSelectorItem[]): SetupSelectorItem[] {
   );
 }
 
-export function getSelectableItems(
-  activeOpenSpecSchema?: OpenSpecSchemaSelection,
-): SetupSelectorItem[] {
+export function getSelectableItems(): SetupSelectorItem[] {
   const baseItems: SetupSelectorItem[] = [
     ...listSetupProviderCompatibilities().map((entry) => ({
       kind: "provider" as const,
@@ -177,12 +138,6 @@ export function getSelectableItems(
   return markRequiredItems([
     ...baseItems,
     ...getDistributionSelectorItems(knownIds),
-    ...listSetupOpenSpecSchemaCompatibilities(activeOpenSpecSchema).map((entry) => ({
-      kind: "openspecSchema" as const,
-      id: entry.id,
-      label: entry.label,
-      description: entry.description,
-    })),
     ...listSetupGitModeCompatibilities().map((entry) => ({
       kind: "gitMode" as const,
       id: entry.id,
@@ -192,17 +147,13 @@ export function getSelectableItems(
   ]);
 }
 
-export function getItemsForStep(
-  step: WizardStep,
-  activeOpenSpecSchema?: OpenSpecSchemaSelection,
-): SetupSelectorItem[] {
+export function getItemsForStep(step: WizardStep): SetupSelectorItem[] {
   const kindMap: Record<WizardStep, SetupSelectorItem["kind"]> = {
     providers: "provider",
     capabilities: "capability",
-    openspecSchema: "openspecSchema",
     gitMode: "gitMode",
   };
-  return getSelectableItems(activeOpenSpecSchema).filter((item) => item.kind === kindMap[step]);
+  return getSelectableItems().filter((item) => item.kind === kindMap[step]);
 }
 
 export function getDisabledCapabilityIds(selectedPackageManagers: Set<string>): Set<string> {
@@ -260,7 +211,6 @@ export function toggleSelectableItem(
     selectedProviders,
     selectedPackageManagers,
     selectedCapabilities,
-    selectedOpenSpecSchema: state.selectedOpenSpecSchema,
     selectedGitMode: state.selectedGitMode,
   };
 }
@@ -269,40 +219,30 @@ export function selectRadioItem(
   state: SetupSelectorState,
   current: SetupSelectorItem,
 ): SetupSelectorState {
-  if (current.kind !== "openspecSchema" && current.kind !== "gitMode") return state;
+  if (current.kind !== "gitMode") return state;
   return {
     selectedProviders: new Set(state.selectedProviders),
     selectedPackageManagers: new Set(state.selectedPackageManagers),
     selectedCapabilities: new Set(state.selectedCapabilities),
-    selectedOpenSpecSchema:
-      current.kind === "openspecSchema"
-        ? (current.id as OpenSpecSchemaSelection)
-        : state.selectedOpenSpecSchema,
-    selectedGitMode:
-      current.kind === "gitMode" ? (current.id as GitModeSelection) : state.selectedGitMode,
+    selectedGitMode: current.id as GitModeSelection,
   };
 }
 
 function getInitialActiveIndexForStep(
   step: WizardStep,
-  selectedOpenSpecSchema: OpenSpecSchemaSelection,
   selectedGitMode: GitModeSelection = DEFAULT_GIT_MODE_SELECTION,
 ): number {
-  if (step !== "openspecSchema" && step !== "gitMode") return 0;
-  const items = getItemsForStep(step, selectedOpenSpecSchema);
-  const selected = step === "gitMode" ? selectedGitMode : selectedOpenSpecSchema;
-  const index = items.findIndex((item) => item.id === selected);
+  if (step !== "gitMode") return 0;
+  const index = getItemsForStep(step).findIndex((item) => item.id === selectedGitMode);
   return index >= 0 ? index : 0;
 }
 
 function SetupSelectorApp({
   activeIndex,
   currentStep,
-  steps,
   selectedProviders,
   selectedPackageManagers,
   selectedCapabilities,
-  selectedOpenSpecSchema,
   selectedGitMode,
   onMounted,
 }: SetupSelectorProps) {
@@ -310,26 +250,18 @@ function SetupSelectorApp({
     onMounted?.();
   }, [onMounted]);
 
-  const totalSteps = steps.length;
-  const stepKey = steps[currentStep];
+  const totalSteps = WIZARD_STEPS.length;
+  const stepKey = WIZARD_STEPS[currentStep];
   const stepName = STEP_DISPLAY_NAMES[stepKey];
   const disabledCapabilityIds = getDisabledCapabilityIds(selectedPackageManagers);
-  const openSpecSkipMessage = getOpenSpecSchemaStepMessage(stepKey, selectedCapabilities);
-  const skipMessage = openSpecSkipMessage;
-  const showOpenSpecSkipMessage = skipMessage !== null;
-  const navigableItems = showOpenSpecSkipMessage
-    ? []
-    : getItemsForStep(stepKey, selectedOpenSpecSchema);
-  const isRadioStep =
-    (stepKey === "openspecSchema" || stepKey === "gitMode") && !showOpenSpecSkipMessage;
+  const navigableItems = getItemsForStep(stepKey);
+  const isRadioStep = stepKey === "gitMode";
   const isLastStep = currentStep === totalSteps - 1;
   const enterHint = isLastStep ? "enter confirm" : "enter next";
   const backHint = currentStep > 0 ? " · ← back" : "";
-  const footerHint = showOpenSpecSkipMessage
-    ? `${enterHint}${backHint} · q cancel`
-    : isRadioStep
-      ? `↑↓ navigate · enter select · ${enterHint}${backHint} · q cancel`
-      : `↑↓ navigate · space toggle · ${enterHint}${backHint} · q cancel`;
+  const footerHint = isRadioStep
+    ? `↑↓ navigate · enter select · ${enterHint}${backHint} · q cancel`
+    : `↑↓ navigate · space toggle · ${enterHint}${backHint} · q cancel`;
 
   const menuItems: SelectMenuItem[] = navigableItems.flatMap((item): SelectMenuItem[] => {
     if (item.kind === "provider") {
@@ -356,16 +288,6 @@ function SetupSelectorApp({
         },
       ];
     }
-    if (item.kind === "openspecSchema") {
-      return [
-        {
-          key: `openspecSchema:${item.id}`,
-          label: item.label,
-          description: item.description,
-          indicator: renderIndicator(selectedOpenSpecSchema === item.id, { mode: "radio" }),
-        },
-      ];
-    }
     if (item.kind === "gitMode") {
       return [
         {
@@ -384,15 +306,11 @@ function SetupSelectorApp({
       <WizardHeader title={stepName} step={currentStep} totalSteps={totalSteps} />
       {currentStep === 0 && <Text dimColor>Always installing: bun (node) · uv (python)</Text>}
       <Box marginTop={1} flexDirection="column">
-        {showOpenSpecSkipMessage ? (
-          <Text dimColor>{skipMessage}</Text>
-        ) : (
-          <SelectMenu
-            items={menuItems}
-            activeIndex={activeIndex}
-            mode={isRadioStep ? "radio" : "multi"}
-          />
-        )}
+        <SelectMenu
+          items={menuItems}
+          activeIndex={activeIndex}
+          mode={isRadioStep ? "radio" : "multi"}
+        />
       </Box>
       <WizardFooter hint={footerHint} />
     </Box>
@@ -426,11 +344,7 @@ export async function selectSetupCompatibilities(
     let selectedProviders = new Set(initialSelections.allowedAgents);
     let selectedPackageManagers = new Set(initialSelections.packageManagers);
     let selectedCapabilities = new Set(initialSelections.capabilities.map((entry) => entry.name));
-    let selectedOpenSpecSchema =
-      initialSelections.selectedOpenSpecSchema ??
-      getOpenSpecSchemaSelection(initialSelections.capabilities);
     let selectedGitMode = initialSelections.selectedGitMode;
-    let openSpecSchemaStepLocked = hasOpenSpecSelected(selectedCapabilities);
     let rendered: ReturnType<typeof inkRender> | undefined;
 
     const cleanup = () => {
@@ -449,31 +363,17 @@ export async function selectSetupCompatibilities(
       resolve(value);
     };
 
-    const getSteps = () =>
-      buildWizardSteps({
-        selectedCapabilities,
-        lockOpenSpecSchemaStep: openSpecSchemaStepLocked,
-      });
-
-    const getCurrentStep = () => getSteps()[currentStep];
-
-    const getCurrentItems = () => {
-      const step = getCurrentStep();
-      return step === "openspecSchema" && !hasOpenSpecSelected(selectedCapabilities)
-        ? []
-        : getItemsForStep(step, selectedOpenSpecSchema);
-    };
+    const getCurrentStep = () => WIZARD_STEPS[currentStep];
+    const getCurrentItems = () => getItemsForStep(getCurrentStep());
 
     const rerender = () => {
       rendered?.rerender(
         <SetupSelectorApp
           activeIndex={activeIndex}
           currentStep={currentStep}
-          steps={getSteps()}
           selectedProviders={selectedProviders}
           selectedPackageManagers={selectedPackageManagers}
           selectedCapabilities={selectedCapabilities}
-          selectedOpenSpecSchema={selectedOpenSpecSchema}
           selectedGitMode={selectedGitMode}
         />,
       );
@@ -510,14 +410,13 @@ export async function selectSetupCompatibilities(
       if (action === "toggle") {
         const stepItems = getCurrentItems();
         const current = stepItems[activeIndex];
-        if (!current || current.kind === "openspecSchema") return;
+        if (!current) return;
 
         const next = toggleSelectableItem(
           {
             selectedProviders,
             selectedPackageManagers,
             selectedCapabilities,
-            selectedOpenSpecSchema,
             selectedGitMode,
           },
           current,
@@ -525,7 +424,6 @@ export async function selectSetupCompatibilities(
         selectedProviders = next.selectedProviders;
         selectedPackageManagers = next.selectedPackageManagers;
         selectedCapabilities = next.selectedCapabilities;
-        selectedOpenSpecSchema = next.selectedOpenSpecSchema;
         selectedGitMode = next.selectedGitMode;
         activeIndex = Math.max(0, Math.min(activeIndex, getCurrentItems().length - 1));
         rerender();
@@ -534,20 +432,14 @@ export async function selectSetupCompatibilities(
 
       if (action === "submit") {
         const stepKey = getCurrentStep();
-        if (
-          (stepKey === "openspecSchema" && hasOpenSpecSelected(selectedCapabilities)) ||
-          stepKey === "gitMode"
-        ) {
+        if (stepKey === "gitMode") {
           const current = getCurrentItems()[activeIndex];
-          const selectedRadioValue =
-            stepKey === "gitMode" ? selectedGitMode : selectedOpenSpecSchema;
-          if (current && current.id !== selectedRadioValue) {
+          if (current && current.id !== selectedGitMode) {
             const next = selectRadioItem(
               {
                 selectedProviders,
                 selectedPackageManagers,
                 selectedCapabilities,
-                selectedOpenSpecSchema,
                 selectedGitMode,
               },
               current,
@@ -555,25 +447,15 @@ export async function selectSetupCompatibilities(
             selectedProviders = next.selectedProviders;
             selectedPackageManagers = next.selectedPackageManagers;
             selectedCapabilities = next.selectedCapabilities;
-            selectedOpenSpecSchema = next.selectedOpenSpecSchema;
             selectedGitMode = next.selectedGitMode;
             rerender();
             return;
           }
         }
 
-        if (stepKey === "capabilities" && hasOpenSpecSelected(selectedCapabilities)) {
-          openSpecSchemaStepLocked = true;
-        }
-
-        const steps = getSteps();
-        if (currentStep < steps.length - 1) {
+        if (currentStep < WIZARD_STEPS.length - 1) {
           currentStep++;
-          activeIndex = getInitialActiveIndexForStep(
-            steps[currentStep],
-            selectedOpenSpecSchema,
-            selectedGitMode,
-          );
+          activeIndex = getInitialActiveIndexForStep(WIZARD_STEPS[currentStep], selectedGitMode);
           rerender();
           return;
         }
@@ -583,19 +465,15 @@ export async function selectSetupCompatibilities(
         doResolve({
           allowedAgents: [...selectedProviders],
           packageManagers: [...selectedPackageManagers],
-          capabilities: applyOpenSpecSchemaSelection(
-            [
-              ...listSetupCapabilityCompatibilities()
-                .filter((entry) => selectedCapabilities.has(entry.capability.name))
-                .map((entry) => entry.capability),
-              // Distribution-registered capabilities without a builtin entry.
-              ...[...selectedCapabilities]
-                .filter((id) => !builtinCapabilityIds.has(id))
-                .map((id) => ({ name: id })),
-            ],
-            selectedOpenSpecSchema,
-          ),
-          selectedOpenSpecSchema,
+          capabilities: [
+            ...listSetupCapabilityCompatibilities()
+              .filter((entry) => selectedCapabilities.has(entry.capability.name))
+              .map((entry) => entry.capability),
+            // Distribution-registered capabilities without a builtin entry.
+            ...[...selectedCapabilities]
+              .filter((id) => !builtinCapabilityIds.has(id))
+              .map((id) => ({ name: id })),
+          ],
           selectedGitMode,
         });
         rendered?.unmount();
@@ -624,11 +502,9 @@ export async function selectSetupCompatibilities(
         <SetupSelectorApp
           activeIndex={activeIndex}
           currentStep={currentStep}
-          steps={getSteps()}
           selectedProviders={selectedProviders}
           selectedPackageManagers={selectedPackageManagers}
           selectedCapabilities={selectedCapabilities}
-          selectedOpenSpecSchema={selectedOpenSpecSchema}
           selectedGitMode={selectedGitMode}
           onMounted={onMounted}
         />,

package/src/cli/usage.ts

@@ -30,6 +30,10 @@ export function usage(): string {
     ` ${n} artifact publish <anchor|change-name> [--type openspec] [--no-push] [--json]`,
     "   target: a dated archive anchor, or a change name matching exactly one archive",
     ` ${n} artifact pending [--json]`,
+    ` ${n} artifact link <change>... [--repository <org/repo>] [--branch <b> [--direct]]`,
+    "   [--not-applicable <reason>] [--pr <url>] [--refresh]",
+    "   [--confirm-merged|--confirm-open|--confirm-dropped] [--json]",
+    ` ${n} artifact archive <change> [--repository <org/repo>] [--branch <b> [--direct]|--not-applicable <reason>|--skip-branch] [--json]`,
     ` ${n} doctor`,
     ` ${n} report [--days N] [--input FILE|-] [--json]`,
     ` ${n} studio [--writable] [--terminal] [--detach-timeout <minutes>]`,

package/src/hooks/companion-instructions.ts

@@ -0,0 +1,190 @@
+/** Delivers the Companion Instructions to a Claude main thread or subagent. */
+import { errorMessage } from "../runtime/error-message";
+import { planClaudeInstructions } from "../runtime/claude-delivery-plan";
+import {
+  COMPANION_INSTRUCTIONS_BUDGET,
+  buildCompanionInstructions,
+  companionInstructionsUnavailableLine,
+  type CompanionInstructionsInput,
+  type InstructionReader,
+} from "../runtime/companion-instructions";
+import { MATE_ENV, hasLaunchEnvironment } from "../runtime/env";
+import { FRAMEWORK_NAME } from "../runtime/framework";
+import { PROJECTED_FLAG } from "../runtime/projected-flag";
+import { resolveProjection } from "../runtime/projection";
+import { managedSessionKind, type SessionKind } from "../runtime/session-kind";
+import { hookOutcome, runHook, type HookCall, type HookEnv } from "./hook-io";
+
+export interface InstructionHookPayload {
+  hookSpecificOutput?: { hookEventName: InstructionEvent; additionalContext: string };
+  systemMessage?: string;
+}
+
+export interface InstructionHookInput {
+  hook_event_name?: string;
+  agent_type?: string;
+  cwd?: string;
+}
+
+/** A hook run, with the shim arguments already read. */
+export interface InstructionHookCall extends Omit<HookCall, "argv"> {
+  /** The copy a wrap carries, marked `--projected`. */
+  projected: boolean;
+  /** Where the projection resolves; the event's `cwd` when unset. */
+  directory?: string;
+}
+
+export interface InstructionHookDeps {
+  read?: InstructionReader;
+  resolveProjection?: typeof resolveProjection;
+}
+
+/**
+ * Agents never given a copy, since Claude Code's matchers cannot exclude them:
+ * Explore and Plan skip project memory by design, and a fork inherits its
+ * parent's context, which already holds the instructions.
+ */
+const SKIPPED_AGENTS = new Set(["Explore", "Plan", "fork"]);
+
+type InstructionEvent = "SessionStart" | "SubagentStart";
+
+const INPUT_FIELDS = ["hook_event_name", "agent_type", "cwd"] as const;
+
+function normalizeInput(raw: unknown): InstructionHookInput {
+  const input: InstructionHookInput = {};
+  if (!raw || typeof raw !== "object") return input;
+  for (const field of INPUT_FIELDS) {
+    const value = (raw as Record<string, unknown>)[field];
+    if (typeof value === "string") input[field] = value;
+  }
+  return input;
+}
+
+function sessionKind(env: HookEnv): SessionKind {
+  if (!hasLaunchEnvironment(env)) return "unmanaged";
+  return managedSessionKind(Boolean(env[MATE_ENV.repositoryPath]));
+}
+
+/**
+ * A copy runs only because the bundled plugin or a Claude wrap installed it, so
+ * a session with no launch environment is planned as Claude-wrapped without
+ * reading the Checkout's manifest: a linked worktree runs the main checkout's
+ * wrapped settings and has none of its own.
+ */
+function ownsEvent(event: InstructionEvent, kind: SessionKind, projected: boolean): boolean {
+  const owners = planClaudeInstructions(kind, true);
+  if (event === "SessionStart") return owners.main === "wrap-session-hook" && projected;
+  if (owners.subagents === "plugin-subagent-hook") return !projected;
+  if (owners.subagents === "wrap-subagent-hook") return projected;
+  return false;
+}
+
+/** A launch sets every path; a partial one is not completed from a projection, which may name another repository. */
+function launchReaderInput(env: HookEnv): CompanionInstructionsInput | null {
+  const companionPath = env[MATE_ENV.companionPath];
+  const id = env[MATE_ENV.repositoryId];
+  const repoPath = env[MATE_ENV.repositoryPath];
+  const wrapperBinPath = env[MATE_ENV.wrapperBinPath];
+  if (!companionPath || !id || !repoPath || !wrapperBinPath) return null;
+  return { companionPath, repository: { id, path: repoPath }, wrapperBinPath };
+}
+
+/** The environment always wins: a managed session never reads the projection. */
+function readerInput(
+  env: HookEnv,
+  kind: SessionKind,
+  cwd: string,
+  resolve: typeof resolveProjection,
+): CompanionInstructionsInput | null {
+  if (kind !== "unmanaged") return launchReaderInput(env);
+  const projection = resolve(cwd);
+  if (!projection) return null;
+  return {
+    companionPath: projection.companionPath,
+    /** A linked worktree on a projection copied from the main checkout names itself, not that checkout. */
+    repository: { id: projection.repositoryId, path: projection.repoRoot },
+    wrapperBinPath: projection.wrapperBinPath,
+  };
+}
+
+function oversizeMessage(source: string): string {
+  const marker = FRAMEWORK_NAME.toUpperCase();
+  const budget = COMPANION_INSTRUCTIONS_BUDGET.toLocaleString("en-US");
+  return `${FRAMEWORK_NAME}: the ${marker}:COMPANION block in ${source} leaves no room within the ${budget}-character budget, so the instructions exceed it; Claude Code may deliver them as a file preview. Shorten the block.`;
+}
+
+function evaluate(
+  { env, cwd, projected, directory }: InstructionHookCall,
+  input: InstructionHookInput,
+  deps: InstructionHookDeps,
+): InstructionHookPayload | null {
+  const resolve = deps.resolveProjection ?? resolveProjection;
+  const read = deps.read ?? buildCompanionInstructions;
+  const event = input.hook_event_name;
+  if (event !== "SessionStart" && event !== "SubagentStart") return null;
+  if (event === "SubagentStart" && SKIPPED_AGENTS.has(input.agent_type ?? "")) return null;
+
+  const kind = sessionKind(env);
+  if (!ownsEvent(event, kind, projected)) return null;
+
+  const reader = readerInput(env, kind, directory || input.cwd || cwd, resolve);
+  if (!reader) return null;
+
+  const result = read(reader);
+  if (result.kind === "unavailable") {
+    const line = companionInstructionsUnavailableLine(result);
+    return instructionOutput(event, line, line);
+  }
+  const warning = result.oversized ? oversizeMessage(result.source) : undefined;
+  return instructionOutput(event, result.text, warning);
+}
+
+function instructionOutput(
+  event: InstructionEvent,
+  additionalContext: string,
+  systemMessage?: string,
+): InstructionHookPayload {
+  return {
+    hookSpecificOutput: { hookEventName: event, additionalContext },
+    ...(systemMessage ? { systemMessage } : {}),
+  };
+}
+
+function failure(error: unknown): InstructionHookPayload {
+  return {
+    systemMessage: `${FRAMEWORK_NAME}: companion instructions hook failed: ${errorMessage(error)}`,
+  };
+}
+
+/**
+ * Its own hook output, apart from the Agent Guidance's: Claude Code caps each
+ * output at 10,000 characters. A missing `AGENTS.md` is stated as a fact, never
+ * as an instruction to stop: a SessionStart hook cannot block, and a pause
+ * would stall a `-p` or SDK session.
+ */
+export function instructionHookPayload(
+  call: InstructionHookCall,
+  deps: InstructionHookDeps = {},
+): InstructionHookPayload | null {
+  try {
+    return evaluate(call, normalizeInput(call.input), deps);
+  } catch (error) {
+    return failure(error);
+  }
+}
+
+/** Plugin-shim entry; exits zero even when reading its input fails. */
+export function run(argv: readonly string[] = process.argv.slice(2)): Promise<number> {
+  return runHook(
+    (input) =>
+      hookOutcome(
+        instructionHookPayload({
+          env: process.env,
+          cwd: process.cwd(),
+          projected: argv.includes(PROJECTED_FLAG),
+          input,
+        }),
+      ),
+    (error) => hookOutcome(failure(error)),
+  );
+}