codex-plugin-doctor 1.57.0 → 1.58.0

package/dist/core/plugin-hooks.js

@@ -0,0 +1,190 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { pluginHookEvents } from "../domain/types.js";
+import { auditHookCommand } from "../security/security-audit.js";
+import { resolveSafePackagePath } from "./plugin-components.js";
+const ignoredMatcherEvents = new Set(["Stop", "UserPromptSubmit"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function packagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).replace(/\\/g, "/") || ".";
+}
+function finding(severity, id, message, impact, suggestedFix, evidence) {
+    return { severity, id, message, impact, suggestedFix, evidence };
+}
+function invalidShape(sourcePath, field) {
+    return finding("fail", "plugin.hook.invalid_shape", "The plugin lifecycle hook configuration has an invalid shape.", "Codex cannot safely interpret malformed lifecycle hook metadata.", "Use the official hook configuration schema for this field.", { sourcePath, field });
+}
+function unsupportedEvent(sourcePath, event) {
+    return finding("fail", "plugin.hook.unsupported_event", `The plugin lifecycle hook event \`${event}\` is not supported.`, "Codex will not invoke hook events outside the official lifecycle event set.", "Use one of the official plugin lifecycle hook events.", { sourcePath, event });
+}
+function invalidHookPath(manifestPath) {
+    return finding("fail", "plugin.hook.invalid_path", "The plugin lifecycle hook source must be a safe package-relative path.", "Paths outside the plugin package can expose unreviewed files to hook configuration loading.", "Use a `./` hook configuration path that stays within the plugin package.", { sourcePath: manifestPath, field: "hooks" });
+}
+function warning(id, sourcePath, event, field) {
+    const messages = {
+        "plugin.hook.unsupported_handler": [
+            "A plugin lifecycle hook uses a handler type the host skips.",
+            "Prompt and agent lifecycle handlers are not executed by this host.",
+            "Use a command handler for behavior that must run in this host."
+        ],
+        "plugin.hook.async_unsupported": [
+            "A plugin lifecycle hook requests unsupported asynchronous execution.",
+            "The host does not support asynchronous lifecycle hook execution.",
+            "Remove `async: true` or run the command synchronously."
+        ],
+        "plugin.hook.matcher_ignored": [
+            "A plugin lifecycle hook matcher is ignored for this event.",
+            "This lifecycle event does not use matcher filtering.",
+            "Remove the matcher from this event group."
+        ]
+    };
+    const [message, impact, suggestedFix] = messages[id];
+    return finding("warn", id, message, impact, suggestedFix, { sourcePath, event, field });
+}
+function validateHandler(rootPath, value, sourcePath, event, groupIndex, handlerIndex) {
+    const field = `hooks.${event}[${groupIndex}].hooks[${handlerIndex}]`;
+    if (!isPlainObject(value) || typeof value.type !== "string") {
+        return [invalidShape(sourcePath, field)];
+    }
+    const findings = [];
+    if (value.type !== "command" && value.type !== "prompt" && value.type !== "agent") {
+        return [invalidShape(sourcePath, `${field}.type`)];
+    }
+    if (value.async !== undefined && typeof value.async !== "boolean") {
+        findings.push(invalidShape(sourcePath, `${field}.async`));
+    }
+    else if (value.async === true) {
+        findings.push(warning("plugin.hook.async_unsupported", sourcePath, event, `${field}.async`));
+    }
+    if (value.type === "prompt" || value.type === "agent") {
+        findings.push(warning("plugin.hook.unsupported_handler", sourcePath, event, `${field}.type`));
+        return findings;
+    }
+    if (typeof value.command !== "string") {
+        findings.push(invalidShape(sourcePath, `${field}.command`));
+    }
+    else {
+        findings.push(...auditHookCommand(rootPath, sourcePath, event, `${field}.command`, value.command));
+    }
+    if (value.commandWindows !== undefined) {
+        if (typeof value.commandWindows !== "string") {
+            findings.push(invalidShape(sourcePath, `${field}.commandWindows`));
+        }
+        else {
+            findings.push(...auditHookCommand(rootPath, sourcePath, event, `${field}.commandWindows`, value.commandWindows));
+        }
+    }
+    if (value.timeout !== undefined && (typeof value.timeout !== "number" || !Number.isFinite(value.timeout) || value.timeout <= 0)) {
+        findings.push(invalidShape(sourcePath, `${field}.timeout`));
+    }
+    if (event === "SessionEnd" && typeof value.timeout === "number" && value.timeout > 3) {
+        findings.push(invalidShape(sourcePath, `${field}.timeout`));
+    }
+    if (value.statusMessage !== undefined && typeof value.statusMessage !== "string") {
+        findings.push(invalidShape(sourcePath, `${field}.statusMessage`));
+    }
+    if (value.additionalContextLimit !== undefined && (typeof value.additionalContextLimit !== "number" ||
+        !Number.isFinite(value.additionalContextLimit) ||
+        value.additionalContextLimit < 0)) {
+        findings.push(invalidShape(sourcePath, `${field}.additionalContextLimit`));
+    }
+    return findings;
+}
+function validateConfig(rootPath, config, sourcePath) {
+    if (!isPlainObject(config))
+        return [invalidShape(sourcePath, "root")];
+    const findings = [];
+    if (config.description !== undefined && typeof config.description !== "string") {
+        findings.push(invalidShape(sourcePath, "description"));
+    }
+    if (!isPlainObject(config.hooks)) {
+        findings.push(invalidShape(sourcePath, "hooks"));
+        return findings;
+    }
+    for (const [event, groups] of Object.entries(config.hooks)) {
+        if (!pluginHookEvents.includes(event)) {
+            findings.push(unsupportedEvent(sourcePath, event));
+            continue;
+        }
+        if (!Array.isArray(groups)) {
+            findings.push(invalidShape(sourcePath, `hooks.${event}`));
+            continue;
+        }
+        groups.forEach((group, groupIndex) => {
+            const groupField = `hooks.${event}[${groupIndex}]`;
+            if (!isPlainObject(group)) {
+                findings.push(invalidShape(sourcePath, groupField));
+                return;
+            }
+            if (group.matcher !== undefined && typeof group.matcher !== "string") {
+                findings.push(invalidShape(sourcePath, `${groupField}.matcher`));
+            }
+            else if (typeof group.matcher === "string" && ignoredMatcherEvents.has(event)) {
+                findings.push(warning("plugin.hook.matcher_ignored", sourcePath, event, `${groupField}.matcher`));
+            }
+            if (!Array.isArray(group.hooks)) {
+                findings.push(invalidShape(sourcePath, `${groupField}.hooks`));
+                return;
+            }
+            group.hooks.forEach((handler, handlerIndex) => {
+                findings.push(...validateHandler(rootPath, handler, sourcePath, event, groupIndex, handlerIndex));
+            });
+        });
+    }
+    return findings;
+}
+async function validateHookFile(rootPath, manifestPath, source) {
+    const resolved = await resolveSafePackagePath(rootPath, source);
+    if (!resolved) {
+        return [invalidHookPath(manifestPath)];
+    }
+    try {
+        if (!(await stat(resolved.path)).isFile())
+            throw new Error("not a regular file");
+    }
+    catch {
+        return [finding("fail", "plugin.hook.missing_file", "The plugin lifecycle hook source file is missing.", "Codex cannot load a hook configuration file that is absent or not a regular file.", "Create the referenced hook configuration JSON file inside the plugin package.", { sourcePath: resolved.packagePath })];
+    }
+    try {
+        return validateConfig(rootPath, JSON.parse(await readFile(resolved.path, "utf8")), resolved.packagePath);
+    }
+    catch {
+        return [finding("fail", "plugin.hook.invalid_json", "The plugin lifecycle hook source is not valid JSON.", "Codex cannot parse the hook configuration.", "Fix the JSON syntax in the hook configuration file.", { sourcePath: resolved.packagePath })];
+    }
+}
+export async function validatePluginHooks(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = packagePath(rootPath, discoveredPackage.manifestPath);
+    const configuredHooks = manifest.hooks;
+    if (configuredHooks === undefined) {
+        const defaultPath = "./hooks/hooks.json";
+        const resolved = await resolveSafePackagePath(rootPath, defaultPath);
+        if (!resolved)
+            return [invalidHookPath(manifestPath)];
+        try {
+            if (!(await stat(resolved.path)).isFile())
+                return [];
+        }
+        catch {
+            return [];
+        }
+        return validateHookFile(rootPath, manifestPath, defaultPath);
+    }
+    if (typeof configuredHooks === "string") {
+        return validateHookFile(rootPath, manifestPath, configuredHooks);
+    }
+    if (Array.isArray(configuredHooks)) {
+        if (configuredHooks.length === 0)
+            return [];
+        if (configuredHooks.every((value) => typeof value === "string")) {
+            return (await Promise.all(configuredHooks.map((source) => validateHookFile(rootPath, manifestPath, source)))).flat();
+        }
+        if (configuredHooks.every(isPlainObject)) {
+            return configuredHooks.flatMap((config) => validateConfig(rootPath, config, manifestPath));
+        }
+        return [invalidShape(manifestPath, "hooks")];
+    }
+    return validateConfig(rootPath, configuredHooks, manifestPath);
+}

package/dist/core/runtime-plan.js

@@ -2,10 +2,12 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { packageVersion } from "../version.js";
 import { discoverPackage } from "./discover-package.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
 import { readJsonFile } from "./read-json-file.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
 import { DOCKER_RUNTIME_IMAGE } from "./runtime-sandbox.js";
 import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
+import { resolveContainedPackagePath } from "./package-path.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -68,7 +70,7 @@ function remoteNetworkClass(rawUrl) {
     }
     return "public_https";
 }
-function planDigestPayload(plan) {
+function planDigestPayload(plan, rawServerArgs = {}) {
     return {
         schemaVersion: plan.schemaVersion,
         kind: "doctor.runtime.plan.digest.v1",
@@ -76,7 +78,10 @@ function planDigestPayload(plan) {
         execution: plan.execution,
         status: plan.status,
         summary: plan.summary,
-        servers: plan.servers,
+        servers: plan.servers.map((server) => ({
+            ...server,
+            args: rawServerArgs[server.name] ?? server.args
+        })),
         findings: plan.findings.map((finding) => ({
             id: finding.id,
             severity: finding.severity,
@@ -84,13 +89,59 @@ function planDigestPayload(plan) {
         }))
     };
 }
-function buildRuntimePlanDigest(plan) {
-    return sha256(stableStringify(planDigestPayload(plan)));
+function buildRuntimePlanDigest(plan, rawServerArgs = {}) {
+    return sha256(stableStringify(planDigestPayload(plan, rawServerArgs)));
+}
+const secretRuntimeArgumentFlag = /^--?(?:token|api[-_]?key|apikey|password|secret|credential|authorization|bearer)$/i;
+const secretRuntimeArgumentInline = /^(--?(?:token|api[-_]?key|apikey|password|secret|credential|authorization|bearer))[=:].*$/i;
+const authorizationBearerHeader = /^authorization\s*:\s*bearer\s+\S+/i;
+const inlineAuthorizationBearerHeader = /^(?:--header|-H)=authorization\s*:\s*bearer\s+\S+/i;
+function redactRuntimeArguments(args) {
+    return args.map((arg, index) => {
+        const inlineMatch = arg.match(secretRuntimeArgumentInline);
+        if (inlineMatch) {
+            return `${inlineMatch[1]}=[REDACTED]`;
+        }
+        if (authorizationBearerHeader.test(arg)) {
+            return "[REDACTED]";
+        }
+        if (inlineAuthorizationBearerHeader.test(arg)) {
+            return "[REDACTED]";
+        }
+        if (index > 0 && secretRuntimeArgumentFlag.test(args[index - 1])) {
+            return "[REDACTED]";
+        }
+        return arg;
+    });
+}
+function buildFailedRuntimePlan(targetPath, generatedAt, execution, finding) {
+    const partialPlan = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.runtime.plan",
+        version: packageVersion,
+        targetPath,
+        status: "fail",
+        exitCode: 1,
+        runtimeExecution: "not_started",
+        execution,
+        summary: {
+            serverCount: 0,
+            executableServerCount: 0,
+            highRiskServerCount: 0,
+            findings: { fail: 1, warn: 0, total: 1 }
+        },
+        servers: [],
+        findings: [finding]
+    };
+    return {
+        ...partialPlan,
+        generatedAt,
+        digest: buildRuntimePlanDigest(partialPlan)
+    };
 }
 export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString(), options = {}) {
     const rootPath = path.resolve(targetPath);
     const discoveredPackage = await discoverPackage(rootPath);
-    const security = await buildSecurityAudit(rootPath);
     const execution = options.sandbox === "docker"
         ? {
             backend: "docker",
@@ -99,7 +150,8 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             packageMount: "read_only"
         }
         : { backend: "native", image: null, network: "host", packageMount: "host" };
-    if (!discoveredPackage?.manifest.mcpServers) {
+    if (!discoveredPackage || !Object.hasOwn(discoveredPackage.manifest, "mcpServers")) {
+        const security = await buildSecurityAudit(rootPath);
         const partialPlan = {
             schemaVersion: "1.0.0",
             kind: "doctor.runtime.plan",
@@ -124,16 +176,43 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             digest: buildRuntimePlanDigest(partialPlan)
         };
     }
+    const manifestMcpServers = discoveredPackage.manifest.mcpServers;
+    if (typeof manifestMcpServers !== "string" ||
+        !manifestMcpServers ||
+        !manifestMcpServers.startsWith("./")) {
+        return buildFailedRuntimePlan(discoveredPackage.rootPath, generatedAt, execution, {
+            id: typeof manifestMcpServers === "string"
+                ? "plugin.manifest.invalid_path"
+                : "plugin.manifest.invalid_field",
+            severity: "fail",
+            message: "The plugin manifest mcpServers field must be a non-empty package-relative path.",
+            impact: "Runtime planning cannot safely resolve malformed MCP server configuration metadata.",
+            suggestedFix: "Use a non-empty ./ path for mcpServers that remains inside the package.",
+            evidence: { manifestPath: ".codex-plugin/plugin.json", field: "mcpServers" }
+        });
+    }
+    const mcpConfigPath = await resolveContainedPackagePath(discoveredPackage.rootPath, manifestMcpServers);
+    if (!mcpConfigPath) {
+        return buildFailedRuntimePlan(discoveredPackage.rootPath, generatedAt, execution, {
+            id: "plugin.security.mcp_config_path",
+            severity: "fail",
+            message: "The MCP server config path resolves outside the package root.",
+            impact: "Runtime planning cannot safely inspect MCP server metadata outside the package.",
+            suggestedFix: "Use an MCP server config path that remains inside the package root.",
+            evidence: { manifestPath: ".codex-plugin/plugin.json", field: "mcpServers" }
+        });
+    }
+    const security = await buildSecurityAudit(rootPath);
     let parsedConfig;
     try {
-        parsedConfig = await readJsonFile(path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers));
+        parsedConfig = await readJsonFile(mcpConfigPath);
     }
     catch {
         parsedConfig = {};
     }
-    const serverEntries = isPlainObject(parsedConfig) && isPlainObject(parsedConfig.mcpServers)
-        ? Object.entries(parsedConfig.mcpServers)
-        : [];
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    const serverEntries = normalizedConfig.ok ? Object.entries(normalizedConfig.servers) : [];
+    const rawServerArgs = {};
     const servers = serverEntries
         .filter((entry) => isPlainObject(entry[1]))
         .map(([serverName, serverConfig]) => {
@@ -142,13 +221,15 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
         const { riskLevel, riskReasons } = buildRisk(serverName, serverConfig, security.findings);
         const networkClass = url ? remoteNetworkClass(url) : undefined;
         const sanitizedUrl = url ? inspectRemoteMcpUrl(url).sanitizedUrl : null;
+        const args = Array.isArray(serverConfig.args)
+            ? serverConfig.args.filter((arg) => typeof arg === "string")
+            : [];
+        rawServerArgs[serverName] = args;
         return {
             name: serverName,
             transport: command ? "stdio" : "http",
             command,
-            args: Array.isArray(serverConfig.args)
-                ? serverConfig.args.filter((arg) => typeof arg === "string")
-                : [],
+            args: redactRuntimeArguments(args),
             cwd: command ? normalizeCwd(discoveredPackage.rootPath, serverConfig.cwd) : null,
             url: sanitizedUrl,
             ...(networkClass ? { networkClass } : {}),
@@ -182,12 +263,12 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
         kind: "doctor.runtime.plan",
         version: packageVersion,
         targetPath: discoveredPackage.rootPath,
-        status: highRiskServerCount > 0
+        status: !normalizedConfig.ok || highRiskServerCount > 0 || security.status === "fail"
             ? "fail"
             : security.status === "warn"
                 ? "warn"
                 : "pass",
-        exitCode: (highRiskServerCount > 0 ? 1 : 0),
+        exitCode: (!normalizedConfig.ok || highRiskServerCount > 0 || security.status === "fail" ? 1 : 0),
         runtimeExecution: "not_started",
         execution,
         summary: {
@@ -202,7 +283,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
     return {
         ...partialPlan,
         generatedAt,
-        digest: buildRuntimePlanDigest(partialPlan)
+        digest: buildRuntimePlanDigest(partialPlan, rawServerArgs)
     };
 }
 export function evaluateRuntimeApproval(plan, options) {

package/dist/core/runtime-probe.js

@@ -6,6 +6,7 @@ import readline from "node:readline";
 import { evaluateMcpConformance } from "./mcp-conformance.js";
 import { probeRemoteMcpServer } from "./remote-mcp-probe.js";
 import { buildRuntimeLaunch, DOCKER_RUNTIME_STARTUP_TIMEOUT_MS, RuntimeSandboxError } from "./runtime-sandbox.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
 import { formatRequestTranscript as formatRequestTranscriptForLog, formatResponseTranscript as formatResponseTranscriptForLog } from "./runtime-transcript.js";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const PROMPT_PROBE_PLACEHOLDER = "codex-plugin-doctor-probe";
@@ -262,14 +263,8 @@ async function loadMcpServers(mcpConfigPath) {
     catch {
         return null;
     }
-    if (!isPlainObject(parsedConfig)) {
-        return null;
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers)) {
-        return null;
-    }
-    return servers;
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    return normalizedConfig.ok ? normalizedConfig.servers : null;
 }
 function getCapabilities(message) {
     if (!isPlainObject(message.result)) {

package/dist/core/validate-plugin.js

@@ -2,6 +2,9 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { discoverPackage } from "./discover-package.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
+import { validatePluginComponents } from "./plugin-components.js";
+import { validatePluginHooks } from "./plugin-hooks.js";
 import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
 import { probeRuntime, remoteReliabilityGatePassed } from "./runtime-probe.js";
 function buildFailure(id, message, impact, suggestedFix, evidence) {
@@ -24,6 +27,9 @@ function buildWarning(id, message, impact, suggestedFix, evidence) {
         ...(evidence ? { evidence } : {})
     };
 }
+function hasInvalidComponentPath(findings, field) {
+    return findings.some((finding) => finding.id === "plugin.manifest.invalid_path" && finding.evidence?.field === field);
+}
 function remoteUrlIssueFindingId(issue) {
     return issue === "insecure_non_loopback"
         ? "plugin.security.insecure_http_url"
@@ -223,9 +229,11 @@ function validateRequiredManifestFields(discoveredPackage) {
 }
 async function validateSkillsDirectory(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (manifest.skills === undefined) {
         return [];
     }
+    if (typeof manifest.skills !== "string")
+        return [];
     const skillsPath = path.resolve(rootPath, manifest.skills);
     if (!isPathWithinRoot(rootPath, skillsPath)) {
         return [
@@ -233,7 +241,7 @@ async function validateSkillsDirectory(discoveredPackage) {
                 manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
                 field: "skills",
                 configuredPath: manifest.skills,
-                resolvedPath: skillsPath
+                resolvedPath: relativePackagePath(rootPath, skillsPath)
             })
         ];
     }
@@ -246,13 +254,13 @@ async function validateSkillsDirectory(discoveredPackage) {
             manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
             field: "skills",
             configuredPath: manifest.skills,
-            resolvedPath: skillsPath
+            resolvedPath: relativePackagePath(rootPath, skillsPath)
         })
     ];
 }
 async function validateSkillDefinitions(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (typeof manifest.skills !== "string") {
         return [];
     }
     const skillsPath = path.resolve(rootPath, manifest.skills);
@@ -319,7 +327,7 @@ async function validateSkillDefinitions(discoveredPackage) {
 }
 async function validateMcpConfig(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.mcpServers) {
+    if (typeof manifest.mcpServers !== "string") {
         return [];
     }
     const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
@@ -353,20 +361,28 @@ async function validateMcpConfig(discoveredPackage) {
             buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "json" })
         ];
     }
-    if (!isPlainObject(parsedConfig)) {
-        return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
-        ];
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
+        if (normalizedConfig.reason === "ambiguous_shape") {
+            return [
+                buildFailure("plugin.mcp.ambiguous_shape", "The referenced `.mcp.json` file uses an ambiguous MCP config layout.", "Codex cannot safely choose between multiple wrapper layouts when they appear in one configuration file.", "Use exactly one supported layout: a direct server map, `mcp_servers`, or `mcpServers`.", { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
+            ];
+        }
+        if (normalizedConfig.field === "server" && normalizedConfig.invalidServerNames) {
+            return normalizedConfig.invalidServerNames.map((serverName) => buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "server"
+            }));
+        }
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`, {
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a valid MCP server map.", "Without valid server entries, Codex cannot discover the bundled MCP server definitions.", `Use a direct server map, \`mcp_servers\`, or \`mcpServers\` in \`${mcpConfigPath}\`.`, {
                 configPath: relativePackagePath(rootPath, mcpConfigPath),
-                field: "mcpServers"
+                field: normalizedConfig.field
             })
         ];
     }
+    const servers = normalizedConfig.servers;
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
@@ -433,11 +449,17 @@ export async function validatePlugin(targetPath, options = {}) {
             findings: withFindingFingerprints([await buildMissingManifestFailure(rootPath)], rootPath)
         };
     }
+    const componentFindings = await validatePluginComponents(discoveredPackage);
+    const hookFindings = await validatePluginHooks(discoveredPackage);
+    const hasInvalidSkillsPath = hasInvalidComponentPath(componentFindings, "skills");
+    const hasInvalidMcpPath = hasInvalidComponentPath(componentFindings, "mcpServers");
     const staticFindings = [
         ...validateRequiredManifestFields(discoveredPackage),
-        ...(await validateSkillsDirectory(discoveredPackage)),
-        ...(await validateSkillDefinitions(discoveredPackage)),
-        ...(await validateMcpConfig(discoveredPackage))
+        ...componentFindings,
+        ...hookFindings,
+        ...(hasInvalidSkillsPath ? [] : await validateSkillsDirectory(discoveredPackage)),
+        ...(hasInvalidSkillsPath ? [] : await validateSkillDefinitions(discoveredPackage)),
+        ...(hasInvalidMcpPath ? [] : await validateMcpConfig(discoveredPackage))
     ];
     const staticFailed = staticFindings.some((finding) => finding.severity === "fail");
     const runtimeResult = options.runtime && !staticFailed

package/dist/domain/types.d.ts

@@ -55,7 +55,41 @@ export interface PluginManifest {
     description?: string;
     skills?: string;
     mcpServers?: string;
+    author?: unknown;
+    homepage?: unknown;
+    repository?: unknown;
+    license?: unknown;
+    keywords?: unknown;
+    apps?: unknown;
+    hooks?: PluginHooks;
+    interface?: unknown;
+}
+export declare const pluginHookEvents: readonly ["PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "UserPromptSubmit", "SubagentStop", "Stop", "SessionStart", "SubagentStart", "SessionEnd"];
+export type PluginHookEvent = (typeof pluginHookEvents)[number];
+export interface PluginHookCommandHandler {
+    type: "command";
+    command: string;
+    commandWindows?: string;
+    timeout?: number;
+    statusMessage?: string;
+    additionalContextLimit?: number;
+    async?: boolean;
+}
+export interface PluginHookUnsupportedHandler {
+    type: "prompt" | "agent";
+    async?: boolean;
+    [key: string]: unknown;
+}
+export type PluginHookHandler = PluginHookCommandHandler | PluginHookUnsupportedHandler;
+export interface PluginHookMatcherGroup {
+    matcher?: string;
+    hooks: PluginHookHandler[];
+}
+export interface PluginHookConfig {
+    description?: string;
+    hooks: Partial<Record<PluginHookEvent, PluginHookMatcherGroup[]>>;
 }
+export type PluginHooks = string | string[] | PluginHookConfig | PluginHookConfig[];
 export interface DiscoveredPackage {
     rootPath: string;
     manifestPath: string;

package/dist/domain/types.js

@@ -1 +1,13 @@
-export {};
+export const pluginHookEvents = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "UserPromptSubmit",
+    "SubagentStop",
+    "Stop",
+    "SessionStart",
+    "SubagentStart",
+    "SessionEnd"
+];