@orchid-labs/pluxx 0.1.13 → 0.1.15

package/dist/index.js

@@ -7415,10 +7415,20 @@ var McpServerSchema = external_exports.preprocess(
   external_exports.discriminatedUnion("transport", [McpServerHttpSchema, McpServerSseSchema, McpServerStdioSchema])
 );
 var HookEntrySchema = external_exports.object({
-  type: external_exports.enum(["command", "prompt"]).default("command"),
+  type: external_exports.enum(["command", "http", "mcp_tool", "prompt", "agent"]).default("command"),
   command: external_exports.string().optional(),
   prompt: external_exports.string().optional(),
   model: external_exports.string().optional(),
+  url: external_exports.string().url().optional(),
+  headers: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+  allowedEnvVars: external_exports.array(external_exports.string()).optional(),
+  server: external_exports.string().optional(),
+  tool: external_exports.string().optional(),
+  input: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
+  if: external_exports.string().optional(),
+  async: external_exports.boolean().optional(),
+  asyncRewake: external_exports.boolean().optional(),
+  shell: external_exports.enum(["bash"]).optional(),
   timeout: external_exports.number().optional(),
   matcher: external_exports.union([external_exports.string(), external_exports.record(external_exports.string(), external_exports.unknown())]).optional(),
   failClosed: external_exports.boolean().optional(),
@@ -7431,11 +7441,34 @@ var HookEntrySchema = external_exports.object({
       message: "Command hooks require a command."
     });
   }
-  if (entry.type === "prompt" && !entry.prompt) {
+  if (entry.type === "http" && !entry.url) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["url"],
+      message: "HTTP hooks require a url."
+    });
+  }
+  if (entry.type === "mcp_tool") {
+    if (!entry.server) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["server"],
+        message: "MCP tool hooks require a server."
+      });
+    }
+    if (!entry.tool) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["tool"],
+        message: "MCP tool hooks require a tool."
+      });
+    }
+  }
+  if ((entry.type === "prompt" || entry.type === "agent") && !entry.prompt) {
     ctx.addIssue({
       code: external_exports.ZodIssueCode.custom,
       path: ["prompt"],
-      message: "Prompt hooks require a prompt."
+      message: `${entry.type === "agent" ? "Agent" : "Prompt"} hooks require a prompt.`
     });
   }
 });
@@ -7822,7 +7855,7 @@ function getEnabledRuntimeReadinessBindings(capability, plan) {
   });
 }
 var NAMED_PROMPT_TARGET_NOTE = "Named `skills` / `commands` readiness targets currently translate through prompt-entry gating with best-effort matching because the core four do not share one exact per-skill or per-command runtime interception surface.";
-var CODEX_EXTERNAL_NOTE = "Codex readiness currently translates into generated hook/config guidance rather than an enforced plugin-bundled runtime surface.";
+var CODEX_EXTERNAL_NOTE = "Codex readiness now bundles translated hooks in the plugin, but Pluxx still emits `.codex/readiness.generated.json` and `.codex/hooks.generated.json` companion guidance because some Codex runtimes still gate hook activation behind `codex_hooks`.";
 function getRuntimeReadinessNamedPromptTargetNote() {
   return NAMED_PROMPT_TARGET_NOTE;
 }
@@ -7891,7 +7924,7 @@ function getRuntimeReadinessCapability(platform, pluginRootVar = "PLUGIN_ROOT")
         bundleEnforced: false,
         namedPromptTargetScope: "best-effort",
         scriptPath: ".codex/pluxx-readiness.mjs",
-        companionArtifacts: [".codex/readiness.generated.json", ".codex/hooks.generated.json"],
+        companionArtifacts: [".codex/readiness.generated.json", "hooks/hooks.json", ".codex/hooks.generated.json"],
         bindings: [
           {
             gate: "session-start",
@@ -8115,7 +8148,7 @@ var PLATFORM_LIMIT_POLICIES = {
 var PLATFORM_VALIDATION_RULES = {
   "claude-code": {
     platform: "claude-code",
-    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, marketplaces, and output styles.",
+    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, marketplaces, output styles, and adjacent plugin assets like LSP, monitors, and themes.",
     limits: PLATFORM_LIMITS["claude-code"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["claude-code"],
     skillDiscoveryDirs: [
@@ -8154,13 +8187,13 @@ var PLATFORM_VALIDATION_RULES = {
     hooks: {
       supported: true,
       files: ["hooks/hooks.json", ".claude-plugin/plugin.json", "~/.claude/settings.json", ".claude/settings.json", ".claude/settings.local.json"],
-      eventNames: ["SessionStart", "PreToolUse", "PostToolUse", "PermissionRequest", "TaskCreated", "TaskCompleted", "Stop", "Notification", "ConfigChange"],
-      notes: "Hook configs can be stored in hooks/hooks.json, inlined in plugin.json, added in settings files, or scoped through skill and agent frontmatter."
+      eventNames: ["SessionStart", "Setup", "UserPromptSubmit", "UserPromptExpansion", "PreToolUse", "PermissionRequest", "PermissionDenied", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "SubagentStart", "SubagentStop", "TaskCreated", "TaskCompleted", "Stop", "StopFailure", "TeammateIdle", "InstructionsLoaded", "ConfigChange", "CwdChanged", "FileChanged", "WorktreeCreate", "WorktreeRemove", "PreCompact", "PostCompact", "Elicitation", "ElicitationResult", "SessionEnd"],
+      notes: "Hook configs can be stored in hooks/hooks.json, inlined in plugin.json, added in settings files, or scoped through skill and agent frontmatter. Claude also documents a broader lifecycle event set than the older simplified Pluxx model."
     },
     instructions: {
       files: ["CLAUDE.md"],
       format: "markdown",
-      notes: "Claude keeps persistent instructions in CLAUDE.md and pushes longer procedures into skills."
+      notes: "Claude keeps persistent instructions in CLAUDE.md and pushes longer procedures into skills. Related enforcement and distribution config also depends on managed, user, project, and local settings scopes."
     },
     sources: [
       { label: "Claude Code MCP docs", url: "https://code.claude.com/docs/en/mcp" },
@@ -8174,6 +8207,9 @@ var PLATFORM_VALIDATION_RULES = {
       { label: "Claude Code plugins reference", url: "https://code.claude.com/docs/en/plugins-reference" },
       { label: "Claude Code hooks guide", url: "https://code.claude.com/docs/en/hooks-guide" },
       { label: "Claude Code hooks docs", url: "https://code.claude.com/docs/en/hooks" },
+      { label: "Claude Code settings docs", url: "https://code.claude.com/docs/en/settings" },
+      { label: "Claude Code permissions docs", url: "https://code.claude.com/docs/en/permissions" },
+      { label: "Claude Code memory docs", url: "https://code.claude.com/docs/en/memory" },
       { label: "Claude Code skills docs", url: "https://code.claude.com/docs/en/skills" },
       { label: "Claude Code sub-agents docs", url: "https://code.claude.com/docs/en/sub-agents" },
       { label: "Claude Code env vars docs", url: "https://code.claude.com/docs/en/env-vars" }
@@ -8212,13 +8248,13 @@ var PLATFORM_VALIDATION_RULES = {
     hooks: {
       supported: true,
       files: ["hooks/hooks.json", ".cursor/hooks.json", "~/.cursor/hooks.json"],
-      eventNames: ["sessionStart", "preToolUse", "postToolUse", "subagentStart", "subagentStop", "beforeShellExecution", "afterShellExecution"],
-      notes: "Cursor plugin hooks live under hooks/hooks.json; project and user hooks also exist separately and reload on save."
+      eventNames: ["sessionStart", "sessionEnd", "preToolUse", "postToolUse", "postToolUseFailure", "subagentStart", "subagentStop", "beforeShellExecution", "afterShellExecution", "beforeMCPExecution", "afterMCPExecution", "beforeReadFile", "afterFileEdit", "beforeSubmitPrompt", "preCompact", "stop", "afterAgentResponse", "afterAgentThought", "beforeTabFileRead", "afterTabFileEdit"],
+      notes: "Cursor plugin hooks live under hooks/hooks.json; project and user hooks also exist separately and reload on save. The official event surface spans both Agent and Tab flows."
     },
     instructions: {
       files: ["rules/", "AGENTS.md"],
       format: "mdc + markdown",
-      notes: "rules/ is the plugin-native instruction surface. AGENTS.md remains useful as shared repo guidance. Cursor subagents use markdown files under .cursor/agents or ~/.cursor/agents (with .claude/.codex compatibility paths)."
+      notes: "rules/ is the plugin-native instruction surface. AGENTS.md remains useful as shared repo guidance. Cursor subagents use markdown files under .cursor/agents or ~/.cursor/agents (with .claude/.codex compatibility paths). Cursor rules do not apply to Tab."
     },
     sources: [
       { label: "Cursor plugins overview", url: "https://cursor.com/docs/plugins" },
@@ -8238,7 +8274,7 @@ var PLATFORM_VALIDATION_RULES = {
   },
   "codex": {
     platform: "codex",
-    summary: "Codex plugins use .codex-plugin/plugin.json with skills, optional .mcp.json and .app.json, marketplace catalogs, cache installs, AGENTS.md instructions, and separate hook configuration.",
+    summary: "Codex plugins use .codex-plugin/plugin.json with skills, optional .mcp.json and .app.json, marketplace catalogs, cache installs, AGENTS.md instructions, and native bundled hook support plus broader project or user hook config.",
     limits: PLATFORM_LIMITS["codex"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["codex"],
     skillDiscoveryDirs: [
@@ -8266,9 +8302,9 @@ var PLATFORM_VALIDATION_RULES = {
     },
     hooks: {
       supported: true,
-      files: [".codex/hooks.json", "~/.codex/hooks.json"],
+      files: ["hooks/hooks.json", ".codex/hooks.json", "~/.codex/hooks.json"],
       eventNames: ["SessionStart", "PreToolUse", "PermissionRequest", "PostToolUse", "UserPromptSubmit", "Stop"],
-      notes: "Codex documents hooks in project/user config, guarded by the codex_hooks feature flag; the current plugin build guide does not document plugin-packaged hooks."
+      notes: "Codex documents hooks in project and user config, and the hooks docs still mention the codex_hooks feature flag/runtime caveat. The official hooks docs also cover plugin-bundled hooks, which Pluxx now emits at hooks/hooks.json."
     },
     instructions: {
       files: ["AGENTS.md", "AGENTS.override.md"],
@@ -8286,6 +8322,9 @@ var PLATFORM_VALIDATION_RULES = {
       { label: "Codex hooks docs", url: "https://developers.openai.com/codex/hooks" },
       { label: "Codex skills docs", url: "https://developers.openai.com/codex/skills" },
       { label: "Codex MCP docs", url: "https://developers.openai.com/codex/mcp" },
+      { label: "Codex basic config docs", url: "https://developers.openai.com/codex/config-basic" },
+      { label: "Codex agent approvals and security docs", url: "https://developers.openai.com/codex/agent-approvals-security" },
+      { label: "Codex app commands docs", url: "https://developers.openai.com/codex/app/commands" },
       { label: "Codex AGENTS.md guide", url: "https://developers.openai.com/codex/guides/agents-md" },
       { label: "Codex subagents docs", url: "https://developers.openai.com/codex/subagents" },
       { label: "Codex subagents concept docs", url: "https://developers.openai.com/codex/concepts/subagents" },
@@ -8296,7 +8335,7 @@ var PLATFORM_VALIDATION_RULES = {
   },
   "opencode": {
     platform: "opencode",
-    summary: "OpenCode plugins are code-first JS or TS modules loaded from local plugin dirs or npm references in config, with native skills, commands, agents, MCP, and permission surfaces.",
+    summary: "OpenCode plugins are code-first JS or TS modules loaded from local plugin dirs or npm references in config, with native skills, commands, agents, MCP, permission, custom-tool, and plugin-event surfaces.",
     limits: PLATFORM_LIMITS["opencode"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["opencode"],
     skillDiscoveryDirs: [
@@ -8326,13 +8365,13 @@ var PLATFORM_VALIDATION_RULES = {
     hooks: {
       supported: true,
       files: ["plugin module (index.ts/index.js)"],
-      eventNames: [],
-      notes: "OpenCode hooks are plugin event handlers implemented in code, not a separate hooks.json file."
+      eventNames: ["command.executed", "file.edited", "file.watcher.updated", "installation.updated", "lsp.client.diagnostics", "lsp.updated", "message.part.removed", "message.part.updated", "message.removed", "message.updated", "permission.asked", "permission.replied", "server.connected", "session.created", "session.compacted", "session.deleted", "session.diff", "session.error", "session.idle", "session.status", "session.updated", "todo.updated", "shell.env", "tool.execute.before", "tool.execute.after", "tui.prompt.append", "tui.command.execute", "tui.toast.show", "experimental.session.compacting"],
+      notes: "OpenCode hooks are plugin event handlers implemented in code, not a separate hooks.json file. The official surface is an event bus rather than a small lifecycle-hook JSON schema."
     },
     instructions: {
       files: ["AGENTS.md", "CLAUDE.md", "opencode.json"],
       format: "markdown + json + code",
-      notes: "OpenCode supports AGENTS.md, CLAUDE.md fallback, config instructions, and plugin runtime instruction injection."
+      notes: "OpenCode supports AGENTS.md, CLAUDE.md fallback, config instructions, and plugin runtime instruction injection. Config layering also includes remote config, managed config files, and macOS managed preferences."
     },
     sources: [
       { label: "OpenCode SDK docs", url: "https://opencode.ai/docs/sdk/" },
@@ -8693,8 +8732,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       commands: {
         mode: "degrade",
-        nativeSurfaces: ["skills/", "AGENTS.md"],
-        notes: "Current Codex docs do not document plugin-packaged slash-command parity."
+        nativeSurfaces: ["skills/", "AGENTS.md", ".codex/commands.generated.json"],
+        notes: "Current Codex docs do not document plugin-packaged slash-command parity, so Pluxx keeps canonical command intent through routing guidance plus a generated companion mirror."
       },
       agents: {
         mode: "translate",
@@ -8703,8 +8742,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       hooks: {
         mode: "translate",
-        nativeSurfaces: [".codex/hooks.json", "~/.codex/hooks.json"],
-        notes: "Hooks are native, but they currently live next to config layers rather than inside the documented plugin bundle structure."
+        nativeSurfaces: ["hooks/hooks.json", ".codex/hooks.json", "~/.codex/hooks.json"],
+        notes: "Hooks are native. Pluxx bundles translated Codex hooks in the plugin and still tracks the project/user config paths plus the codex_hooks feature-gate caveat."
       },
       permissions: {
         mode: "translate",
@@ -8947,6 +8986,7 @@ var CompilerIntentSkillPolicySchema = external_exports.object({
   skillDir: external_exports.string(),
   title: external_exports.string(),
   description: external_exports.string().optional(),
+  sourceFrontmatter: external_exports.record(external_exports.unknown()).optional(),
   source: external_exports.object({
     kind: external_exports.literal("claude-allowed-tools"),
     platform: external_exports.literal("claude-code").default("claude-code")
@@ -9082,6 +9122,23 @@ function collectUserConfigEntries(config, platforms = config.targets) {
   ]);
 }
 
+// src/distribution-lifecycle.ts
+var VERIFY_STALE_ACTIONS = {
+  codex: "in Codex, use Plugins > Refresh if available, or restart Codex so the plugin cache reloads"
+};
+var PUBLISH_RELOAD_INSTRUCTIONS = {
+  "claude-code": "If Claude is already open, run /reload-plugins in the active session.",
+  cursor: "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up.",
+  codex: "If Codex is already open, use Plugins > Refresh if that action is available in your current UI, or restart Codex so the plugin is picked up.",
+  opencode: "If OpenCode is already open, restart or reload it so the plugin is picked up."
+};
+function getVerifyInstallStaleAction(target) {
+  return VERIFY_STALE_ACTIONS[target];
+}
+function getPublishReloadInstruction(target) {
+  return PUBLISH_RELOAD_INSTRUCTIONS[target];
+}
+
 // src/cli/publish.ts
 var INSTALLER_TARGETS = ["claude-code", "cursor", "codex", "opencode"];
 function runCommandDefault(command, args, options) {
@@ -9724,7 +9781,7 @@ claude plugin install "\${PLUGIN_NAME}@\${MARKETPLACE_NAME}" --scope user
 
 echo
 echo "Installed \${PLUGIN_NAME}@\${MARKETPLACE_NAME} into Claude Code user scope."
-echo "If Claude is already open, run /reload-plugins in the active session."
+echo "${getPublishReloadInstruction("claude-code")}"
 `;
 }
 function renderInstallCursorScript(config) {
@@ -9781,7 +9838,7 @@ ${renderInstallerMcpPathMaterializationSnippet("cursor", "$INSTALL_DIR")}
 ${renderInstallerRuntimeBootstrapSnippet("$INSTALL_DIR")}
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
-echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
+echo "${getPublishReloadInstruction("cursor")}"
 `;
 }
 function renderInstallCodexScript(config) {
@@ -9898,7 +9955,7 @@ NODE
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "Updated Codex marketplace catalog at $MARKETPLACE_PATH"
-echo "If Codex is already open, use Plugins > Refresh if that action is available in your current UI, or restart Codex so the plugin is picked up."
+echo "${getPublishReloadInstruction("codex")}"
 `;
 }
 function renderInstallOpenCodeScript(config) {
@@ -10045,7 +10102,7 @@ fi
 echo "Installed $PLUGIN_NAME plugin code to $INSTALL_DIR"
 echo "Installed OpenCode wrapper at $ENTRY_PATH"
 echo "Synced namespaced skills into $SKILLS_ROOT"
-echo "If OpenCode is already open, restart or reload it so the plugin is picked up."
+echo "${getPublishReloadInstruction("opencode")}"
 `;
 }
 function replaceInstallerPlaceholders(script, config, context) {
@@ -10241,7 +10298,7 @@ import { existsSync as existsSync5, lstatSync as lstatSync2, readdirSync as read
 import { resolve as resolve5 } from "path";
 
 // src/cli/doctor.ts
-import { spawn } from "child_process";
+import { spawn, spawnSync as spawnSync2 } from "child_process";
 import { accessSync, constants, existsSync as existsSync4, lstatSync, readFileSync as readFileSync4, readdirSync as readdirSync2 } from "fs";
 import { basename, dirname as dirname2, resolve as resolve4 } from "path";
 
@@ -11131,6 +11188,166 @@ function checkInstalledBundleIntegrity(checks, rootDir, layout) {
     path: layout.manifestPath
   });
 }
+function parseInstalledPermissionRules(scriptSource) {
+  const match = scriptSource.match(/const RULES = (\[[\s\S]*?\]);\nconst ACTION_PRIORITY/);
+  if (!match?.[1]) {
+    throw new Error("Could not locate embedded RULES payload in hooks/pluxx-permissions.mjs.");
+  }
+  const parsed = JSON.parse(match[1]);
+  if (!Array.isArray(parsed)) {
+    throw new Error("Embedded RULES payload is not an array.");
+  }
+  return parsed;
+}
+function materializePermissionPattern(pattern) {
+  return pattern.replace(/\*\*/g, "probe/path").replace(/\*/g, "probe");
+}
+function buildInstalledPermissionProbe(platform, rule) {
+  const value = materializePermissionPattern(rule.pattern);
+  if (rule.kind === "Bash") {
+    return {
+      action: rule.action,
+      raw: rule.raw,
+      mode: platform === "cursor" ? "cursor-shell" : "claude-pretool",
+      event: platform === "cursor" ? { command: value } : { tool_name: "Bash", tool_input: { command: value } }
+    };
+  }
+  if (rule.kind === "Read") {
+    return {
+      action: rule.action,
+      raw: rule.raw,
+      mode: platform === "cursor" ? "cursor-read" : "claude-pretool",
+      event: platform === "cursor" ? { file_path: value } : { tool_name: "Read", tool_input: { file_path: value } }
+    };
+  }
+  if (rule.kind === "Edit") {
+    return {
+      action: rule.action,
+      raw: rule.raw,
+      mode: platform === "cursor" ? "cursor" : "claude-pretool",
+      event: { tool_name: "Edit", tool_input: { file_path: value } }
+    };
+  }
+  if (rule.kind === "Skill") {
+    return {
+      action: rule.action,
+      raw: rule.raw,
+      mode: platform === "cursor" ? "cursor" : "claude-pretool",
+      event: { tool_name: "Skill", tool_input: { name: value } }
+    };
+  }
+  if (rule.kind === "MCP") {
+    const canonical = value.includes(".") ? value : `${value}.probe`;
+    const dotIndex = canonical.indexOf(".");
+    const server = canonical.slice(0, dotIndex).trim();
+    const tool = canonical.slice(dotIndex + 1).trim();
+    if (!server || !tool) return null;
+    return {
+      action: rule.action,
+      raw: rule.raw,
+      mode: platform === "cursor" ? "cursor-mcp" : "claude-pretool",
+      event: platform === "cursor" ? { tool_name: `mcp__${server}__${tool.replace(/\./g, "__")}` } : { tool_name: `mcp__${server}__${tool.replace(/\./g, "__")}` }
+    };
+  }
+  return null;
+}
+function extractPermissionDecision(platform, payload) {
+  if (platform === "claude-code") {
+    const hookSpecificOutput = payload.hookSpecificOutput;
+    if (!hookSpecificOutput || typeof hookSpecificOutput !== "object") return void 0;
+    const decision2 = hookSpecificOutput.permissionDecision;
+    return typeof decision2 === "string" ? decision2 : void 0;
+  }
+  const decision = payload.permission;
+  return typeof decision === "string" ? decision : void 0;
+}
+function smokeCheckInstalledPermissionHook(rootDir, layout) {
+  if (layout.platform !== "claude-code" && layout.platform !== "cursor") {
+    return null;
+  }
+  const scriptPath = resolve4(rootDir, "hooks/pluxx-permissions.mjs");
+  if (!existsSync4(scriptPath)) {
+    return null;
+  }
+  const rules = parseInstalledPermissionRules(readFileSync4(scriptPath, "utf-8"));
+  const selected = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    if (selected.has(rule.action)) continue;
+    const probe = buildInstalledPermissionProbe(layout.platform, rule);
+    if (!probe) continue;
+    selected.set(rule.action, probe);
+  }
+  if (selected.size === 0) {
+    return {
+      ok: false,
+      detail: "Permission hook script is present, but no supported canonical probe cases could be derived from its embedded rules."
+    };
+  }
+  const failures = [];
+  const successes = [];
+  for (const probe of selected.values()) {
+    const result = spawnSync2("node", [scriptPath, probe.mode], {
+      cwd: rootDir,
+      input: JSON.stringify(probe.event),
+      encoding: "utf-8",
+      env: process.env
+    });
+    if (result.status !== 0) {
+      failures.push(`${probe.raw} exited ${result.status ?? "null"}${result.stderr ? `: ${result.stderr.trim()}` : ""}`);
+      continue;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(result.stdout || "{}");
+    } catch (error) {
+      failures.push(`${probe.raw} returned non-JSON output: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const decision = extractPermissionDecision(layout.platform, payload);
+    if (decision !== probe.action) {
+      failures.push(`${probe.raw} returned ${decision ?? "no decision"} instead of ${probe.action}`);
+      continue;
+    }
+    successes.push(`${probe.raw} -> ${decision}`);
+  }
+  return failures.length > 0 ? { ok: false, detail: failures.join("; ") } : { ok: true, detail: `Validated ${successes.join(", ")}` };
+}
+function checkInstalledPermissionHook(checks, rootDir, layout) {
+  const permissionScriptPath = "hooks/pluxx-permissions.mjs";
+  let scriptResult;
+  try {
+    scriptResult = smokeCheckInstalledPermissionHook(rootDir, layout);
+  } catch (error) {
+    addCheck(checks, {
+      level: "error",
+      code: "consumer-permission-hook-invalid",
+      title: "Installed bundled permission hook behavior is broken",
+      detail: error instanceof Error ? error.message : String(error),
+      fix: "Rebuild or reinstall the plugin so the bundled permission hook script and hook wiring stay aligned with the declared permission rules.",
+      path: permissionScriptPath
+    });
+    return;
+  }
+  if (!scriptResult) {
+    addCheck(checks, {
+      level: "info",
+      code: "consumer-permission-hook-not-applicable",
+      title: "No bundled permission hook smoke check for this install",
+      detail: layout.platform === "claude-code" || layout.platform === "cursor" ? "This installed bundle does not include hooks/pluxx-permissions.mjs." : "This platform does not currently use a bundled pluxx-permissions.mjs hook script for permission enforcement.",
+      fix: "No action needed unless you expected bundled permission-hook enforcement in this installed bundle.",
+      path: permissionScriptPath
+    });
+    return;
+  }
+  addCheck(checks, {
+    level: scriptResult.ok ? "success" : "error",
+    code: scriptResult.ok ? "consumer-permission-hook-valid" : "consumer-permission-hook-invalid",
+    title: scriptResult.ok ? "Installed bundled permission hook returns expected decisions" : "Installed bundled permission hook behavior is broken",
+    detail: scriptResult.detail,
+    fix: scriptResult.ok ? "No action needed." : "Rebuild or reinstall the plugin so the bundled permission hook script and hook wiring stay aligned with the declared permission rules.",
+    path: permissionScriptPath
+  });
+}
 function findMissingInstalledStdioRuntimePaths(rootDir, stdioEntries) {
   const missing = /* @__PURE__ */ new Set();
   for (const server of stdioEntries) {
@@ -11398,6 +11615,7 @@ async function doctorConsumer(rootDir = process.cwd()) {
   });
   checkConsumerManifest(checks, rootDir, layout);
   checkInstalledBundleIntegrity(checks, rootDir, layout);
+  checkInstalledPermissionHook(checks, rootDir, layout);
   checkInstalledUserConfig(checks, rootDir);
   checkInstalledEnvValidation(checks, rootDir);
   checkInstalledRuntimeScriptRoles(checks, rootDir);
@@ -11557,9 +11775,8 @@ function getVerifyInstallRecoveryActions(check) {
   }
   if (check.stale) {
     actions.push(`rerun pluxx install --target ${check.platform} to replace the stale local install`);
-    if (check.platform === "codex") {
-      actions.push("in Codex, use Plugins > Refresh if available, or restart Codex so the plugin cache reloads");
-    }
+    const staleAction = getVerifyInstallStaleAction(check.platform);
+    if (staleAction) actions.push(staleAction);
   }
   if (check.errors > 0 && actions.length === 0) {
     actions.push(`run pluxx doctor --consumer "${check.consumerPath}" for the detailed host-specific failure`);

package/dist/instructions.d.ts

@@ -0,0 +1,6 @@
+import type { PluginConfig } from './schema';
+export declare function resolveInstructionsPath(rootDir: string, config: Pick<PluginConfig, 'instructions'>): string | null;
+export declare function readInstructionsContent(rootDir: string, config: Pick<PluginConfig, 'instructions'>): Promise<string | null>;
+export declare function readInstructionsContentSync(rootDir: string, config: Pick<PluginConfig, 'instructions'>): string | null;
+export declare function renderTitledInstructionsDocument(config: Pick<PluginConfig, 'name' | 'description' | 'brand'>, content: string, titleSuffix?: string): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAG5C,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,GACzC,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,GACzC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,GACzC,MAAM,GAAG,IAAI,CAIf;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,SAAW,GAAG,MAAM,CAQ9J"}

package/dist/mcp-native-overrides.d.ts

@@ -0,0 +1,14 @@
+import type { PluginConfig, TargetPlatform, UserConfigEntry } from './schema';
+type JsonRecord = Record<string, unknown>;
+type NativeMcpServerOverrides = Record<string, Record<string, unknown>>;
+type NativeMcpPlatformOverrides = Partial<Record<TargetPlatform, {
+    mcpServers: NativeMcpServerOverrides;
+}>>;
+export declare function extractNativeMcpAuthConfig(cfg: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function buildNativeMcpPlatformOverrides(platform: TargetPlatform, servers: Record<string, unknown>): NativeMcpPlatformOverrides | undefined;
+export declare function getNativeMcpServerOverride(config: PluginConfig, platform: TargetPlatform, serverName: string): JsonRecord | undefined;
+export declare function getNativeJsonHeadersOverride(config: PluginConfig, platform: TargetPlatform, serverName: string): Record<string, string> | undefined;
+export declare function getNativeCodexMcpEntryOverride(config: PluginConfig, serverName: string): JsonRecord | undefined;
+export declare function collectNativeMcpAuthUserConfigEntries(config: PluginConfig, platforms: TargetPlatform[], existingFields: UserConfigEntry[]): UserConfigEntry[];
+export {};
+//# sourceMappingURL=mcp-native-overrides.d.ts.map

package/dist/mcp-native-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-native-overrides.d.ts","sourceRoot":"","sources":["../src/mcp-native-overrides.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG7E,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AACzC,KAAK,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AACvE,KAAK,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE;IAAE,UAAU,EAAE,wBAAwB,CAAA;CAAE,CAAC,CAAC,CAAA;AA6B3G,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAqB5G;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,0BAA0B,GAAG,SAAS,CAkBxC;AAWD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,MAAM,GACjB,UAAU,GAAG,SAAS,CAKxB;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAGpC;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,UAAU,GAAG,SAAS,CAkBxB;AAED,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,cAAc,EAAE,EAC3B,cAAc,EAAE,eAAe,EAAE,GAChC,eAAe,EAAE,CAoDnB"}