rulesync 40.1.0 → 40.2.0

package/dist/{import-CZq4buOw.cjs → import-D-Be9rwv.cjs}

@@ -23496,6 +23496,62 @@ function findOpencodeV2McpContainers(mcp) {
 	return [...envelope !== null && Object.keys(envelope).length > 0 ? ["mcp.servers"] : [], ...isOpencodeV2GlobalTimeout(mcp.timeout) && Object.keys(mcp.timeout).length > 0 ? ["mcp.timeout"] : []];
 }
 /**
+* Returns the non-empty V2 global `mcp.timeout` object of an OpenCode `mcp`
+* value, or `undefined` when there is none.
+*/
+function getOpencodeV2GlobalMcpTimeout(mcp) {
+	return isRecord$1(mcp) && findOpencodeV2McpContainers(mcp).includes("mcp.timeout") ? mcp.timeout : void 0;
+}
+/**
+* Returns the raw entry an OpenCode `mcp` value holds for a server: the one
+* under the V2 `mcp.servers` envelope, or else the flat V1 entry.
+*/
+function getOpencodeMcpServerEntry(mcp, name) {
+	if (!isRecord$1(mcp)) return;
+	const envelope = getOpencodeV2McpEnvelope(mcp);
+	if (envelope !== null && Object.hasOwn(envelope, name)) return envelope[name];
+	return Object.hasOwn(mcp, name) ? mcp[name] : void 0;
+}
+const OPENCODE_V1_TO_V2_OAUTH_KEYS = new Map([...OPENCODE_V2_OAUTH_KEYS].map(([v2, v1]) => [v1, v2]));
+/**
+* Raises one V1-shaped OpenCode MCP server (`local` or `remote`) to the V2
+* spelling — the inverse of {@link lowerOpencodeV2Server}:
+*
+* - `enabled` is dropped and `disabled: true` written only for a disabled server;
+* - a number `timeout` becomes `{ catalog, execution }`, and camelCase `oauth`
+*   keys become snake_case.
+*
+* Values Rulesync's canonical form cannot hold are taken from the entry the
+* file already has for the server (`existing`): its `timeout` object and its
+* `oauth` object are kept verbatim whenever lowering them gives back exactly
+* what the canonical server carries, so a V2 file survives import and
+* generate unchanged. When the canonical `timeout` differs, the existing
+* `startup` value is still kept.
+*/
+function raiseOpencodeServerToV2(server, existing) {
+	const { enabled, timeout, oauth, ...rest } = server;
+	const raised = { ...rest };
+	if (enabled === false) raised.disabled = true;
+	const existingTimeout = isRecord$1(existing) && isRecord$1(existing.timeout) ? existing.timeout : null;
+	if (existingTimeout !== null && lowerOpencodeV2Timeout(existingTimeout) === timeout) raised.timeout = existingTimeout;
+	else if (typeof timeout === "number") {
+		const startup = existingTimeout?.startup;
+		raised.timeout = {
+			...startup !== void 0 && { startup },
+			catalog: timeout,
+			execution: timeout
+		};
+	} else if (timeout !== void 0) raised.timeout = timeout;
+	const existingOauth = isRecord$1(existing) && isRecord$1(existing.oauth) ? existing.oauth : null;
+	if (existingOauth !== null && isRecord$1(oauth) && (0, node_util.isDeepStrictEqual)(lowerOpencodeV2OAuth(existingOauth, ""), oauth)) raised.oauth = existingOauth;
+	else if (isRecord$1(oauth)) {
+		const snakeOauth = {};
+		for (const [key, value] of Object.entries(oauth)) setOwnEntry(snakeOauth, OPENCODE_V1_TO_V2_OAUTH_KEYS.get(key) ?? key, value);
+		raised.oauth = snakeOauth;
+	} else if (oauth !== void 0) raised.oauth = oauth;
+	return raised;
+}
+/**
 * Lowers OpenCode V2 `mcp` spellings found in a V1 config to the flat V1 map,
 * the way OpenCode V1 itself does since v1.18.24 (`normalizeMcp`):
 *
@@ -33957,6 +34013,69 @@ var JunieHooks = class JunieHooks extends ToolHooks {
 	}
 };
 //#endregion
+//#region src/features/hooks/hook-block-reason.ts
+/**
+* Source lines of a `sanitizeBlockReason(raw)` helper, emitted into generated
+* hook plugins that hand a hook command's output to the agent as the reason a
+* call was blocked (the Pi / oh-my-pi extension and the OpenCode-style plugin).
+* It returns the sanitized, length-capped text, or `""` when nothing survives
+* so the caller can substitute its own fallback.
+*
+* The text is sanitized because a hook command's output can relay third-party
+* content (linter output, matched file lines) into a terminal or, in RPC mode,
+* into an external client. Escape sequences, C1 and other control characters,
+* and format characters such as bidirectional overrides and zero-width joiners
+* are stripped so the reason cannot repaint or reorder what the user is shown,
+* and carriage returns are folded into newlines so it cannot overwrite an
+* already printed line. The format-character pass is a superset of the bidi
+* controls listed in `CONTROL_CHARACTERS_PATTERN`
+* (`src/utils/control-characters.ts`): a blocked-hook reason is short
+* diagnostic text, so dropping every `Cf` character is safer than enumerating
+* the harmful ones and missing `U+061C`, `U+FEFF`, or a future addition.
+*
+* Sanitization runs before truncation so a reason that begins with a progress
+* banner is still reported by its content. The raw text is only sliced to a
+* generous backstop first: a hook command may emit a large amount of output,
+* and the slice bounds the work even if a later edit reintroduces a pattern
+* that is not linear. A slice that actually fired is reported as truncated, so
+* the text is never silently cut.
+*
+* Both slices cut on UTF-16 code units, so each drops a trailing lone high
+* surrogate: the reason may travel as JSON, and half a surrogate pair is not
+* text a strict consumer has to accept.
+*
+* `typed` emits TypeScript parameter and return annotations (for the Pi
+* extension, a `.ts` module); without it the lines are plain JavaScript.
+*/
+function buildBlockReasonSanitizerLines({ typed }) {
+	const str = typed ? ": string" : "";
+	return [
+		"const MAX_BLOCK_REASON_LENGTH = 2000;",
+		"const MAX_SCANNED_REASON_LENGTH = 128_000;",
+		"",
+		`function dropTrailingLoneSurrogate(text${str})${str} {`,
+		"  return text.replace(/[\\ud800-\\udbff]$/, \"\");",
+		"}",
+		"",
+		`function sanitizeBlockReason(raw${str})${str} {`,
+		"  const scannedTruncated = raw.length > MAX_SCANNED_REASON_LENGTH;",
+		"  const scanned = scannedTruncated",
+		"    ? dropTrailingLoneSurrogate(raw.slice(0, MAX_SCANNED_REASON_LENGTH))",
+		"    : raw;",
+		"  const sanitized = scanned",
+		"    .replace(/\\r\\n?/g, \"\\n\")",
+		"    .replace(/\\u001b\\[[0-9;?]*[\\u0020-\\u002f]*[\\u0040-\\u007e]/g, \"\")",
+		"    .replace(/\\u001b\\][^\\u0007\\u001b]{0,256}(?:\\u0007|\\u001b\\\\)/g, \"\")",
+		"    .replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f-\\u009f]/g, \"\")",
+		"    .replace(/[\\p{Cf}\\p{Zl}\\p{Zp}]/gu, \"\")",
+		"    .trim();",
+		"  if (!sanitized) return \"\";",
+		"  if (sanitized.length <= MAX_BLOCK_REASON_LENGTH && !scannedTruncated) return sanitized;",
+		"  return `${dropTrailingLoneSurrogate(sanitized.slice(0, MAX_BLOCK_REASON_LENGTH))}...`;",
+		"}"
+	];
+}
+//#endregion
 //#region src/features/hooks/opencode-style-generator.ts
 /**
 * Tool events emitted as named `(input, ...)` hooks rather than through the
@@ -34027,6 +34146,87 @@ const SHELL_EVENT_TOOL_GATES = {
 		tool: "bash"
 	}
 };
+/**
+* Canonical events whose command receives a Claude Code-style JSON payload on
+* stdin and whose result can deny the call, mapped to the `hook_event_name`
+* the payload carries. Only `preToolUse` (`tool.execute.before`) takes part:
+* it is the one named hook where throwing aborts the call — OpenCode rejects
+* the tool call and returns the error message to the model (the `.env`
+* protection example in the plugins doc).
+*
+* The payload mirrors Claude Code's `PreToolUse` input: `hook_event_name`,
+* `session_id` (`input.sessionID`), `tool_use_id` (`input.callID`),
+* `tool_name` (the raw OpenCode tool name — `bash`, `edit`, `<server>_<tool>`
+* for MCP — the same subject a `matcher` is tested against), `tool_input`
+* (`output.args`) and `cwd` (the plugin context's `directory`, falling back to
+* `process.cwd()`). It is serialized lazily, on the first handler whose
+* matcher matches, so a tool call no hook applies to pays nothing for it.
+*
+* Bun Shell has no stdin option on a command and rejects redirections on a
+* subshell, so the payload is piped in by the shell's builtin `echo`
+* (`echo ${payload} | <command>`); Bun escapes the interpolated value, so the
+* payload never reaches the shell as syntax. The pipe feeds the first
+* pipeline of the command — a compound `a && b` or `a; b` gives the payload
+* to `a` only, so multi-step guards belong in a script.
+*
+* @see https://opencode.ai/docs/plugins/
+* @see https://bun.sh/docs/runtime/shell
+* @see https://code.claude.com/docs/en/hooks
+*/
+const STDIN_PAYLOAD_EVENTS = { preToolUse: "PreToolUse" };
+/**
+* Name of the helper the generated plugin defines when a `preToolUse` handler
+* is present. It interprets the command's result like Claude Code does for a
+* `PreToolUse` hook, throwing (which aborts the OpenCode tool call) when the
+* hook denies it:
+* - exit code 2 → deny, with the command's stderr as the reason;
+* - exit code 0 with JSON stdout whose `hookSpecificOutput.permissionDecision`
+*   is `"deny"` → deny, with `permissionDecisionReason` as the reason;
+* - exit code 0 otherwise → allow;
+* - any other non-zero exit → deny too, with stderr or the exit code.
+*
+* Every reason goes through the `sanitizeBlockReason` helper shared with the
+* Pi extension (`hook-block-reason.ts`): control and format characters are
+* stripped and the text is capped at 2000 characters before the model sees it.
+*
+* The other non-zero exit case is deliberate. Claude Code treats that as a
+*   non-blocking error, but before this payload contract existed the plugin
+*   ran the command through Bun Shell's default throwing mode, so every
+*   non-zero exit aborted the call. Keeping that preserves guards that block
+*   with `exit 1`, rather than silently failing them open.
+*/
+const PRE_TOOL_USE_RESULT_HELPER = "__rulesyncEnforcePreToolUseResult";
+const PRE_TOOL_USE_RESULT_HELPER_LINES = [
+	...buildBlockReasonSanitizerLines({ typed: false }),
+	"",
+	`const ${PRE_TOOL_USE_RESULT_HELPER} = (result) => {`,
+	"  const stderr = result.stderr.toString();",
+	"  if (result.exitCode === 0) {",
+	"    let parsed;",
+	"    try {",
+	"      parsed = JSON.parse(result.stdout.toString());",
+	"    } catch {",
+	"      return;",
+	"    }",
+	"    const specific = parsed && typeof parsed === \"object\" ? parsed.hookSpecificOutput : undefined;",
+	"    if (specific && typeof specific === \"object\" && specific.permissionDecision === \"deny\") {",
+	"      throw new Error(",
+	"        (typeof specific.permissionDecisionReason === \"string\" &&",
+	"          sanitizeBlockReason(specific.permissionDecisionReason)) ||",
+	"          \"Blocked by a preToolUse hook.\",",
+	"      );",
+	"    }",
+	"    return;",
+	"  }",
+	"  if (result.exitCode === 2) {",
+	"    throw new Error(sanitizeBlockReason(stderr) || \"Blocked by a preToolUse hook.\");",
+	"  }",
+	"  throw new Error(",
+	"    sanitizeBlockReason(stderr) ||",
+	"      \"preToolUse hook command failed with exit code \" + result.exitCode + \".\",",
+	"  );",
+	"};"
+];
 function escapeForTemplateLiteral(command) {
 	return command.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
 }
@@ -34041,6 +34241,17 @@ function validateAndSanitizeMatcher(matcher) {
 	}
 	return sanitized.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
+/** The per-canonical-event gates and payload flag every handler of it carries. */
+function handlerExtrasFor(canonicalEvent) {
+	const shellGate = SHELL_EVENT_TOOL_GATES[canonicalEvent];
+	const propertyGate = GENERIC_EVENT_PROPERTY_GATES[canonicalEvent];
+	const stdinEvent = shellGate ? void 0 : STDIN_PAYLOAD_EVENTS[canonicalEvent];
+	return {
+		...shellGate ? { toolGate: shellGate.tool } : {},
+		...propertyGate ? { propertyGate } : {},
+		...stdinEvent ? { stdinEvent } : {}
+	};
+}
 /**
 * Group the effective hooks into named (tool.execute.*) and generic event
 * handler groups, keyed by tool event name. Mutates the supplied groups.
@@ -34048,7 +34259,7 @@ function validateAndSanitizeMatcher(matcher) {
 function collectOpencodeStyleHandlers({ effectiveHooks, eventMap, namedEventHandlers, genericEventHandlers }) {
 	for (const [canonicalEvent, definitions] of Object.entries(effectiveHooks)) {
 		const shellGate = SHELL_EVENT_TOOL_GATES[canonicalEvent];
-		const propertyGate = GENERIC_EVENT_PROPERTY_GATES[canonicalEvent];
+		const extras = handlerExtrasFor(canonicalEvent);
 		const toolEvent = shellGate?.toolEvent ?? eventMap[canonicalEvent];
 		if (!toolEvent) continue;
 		const matcherSupported = !shellGate && Object.hasOwn(NAMED_HOOK_MATCHER_SUBJECTS, toolEvent) && NAMED_HOOK_MATCHER_SUBJECTS[toolEvent] !== null;
@@ -34060,8 +34271,7 @@ function collectOpencodeStyleHandlers({ effectiveHooks, eventMap, namedEventHand
 			handlers.push({
 				command: def.command,
 				matcher: def.matcher ? def.matcher : void 0,
-				...shellGate ? { toolGate: shellGate.tool } : {},
-				...propertyGate ? { propertyGate } : {}
+				...extras
 			});
 		}
 		if (handlers.length > 0) {
@@ -34094,46 +34304,79 @@ function buildGenericEventBodyLines(genericEventHandlers) {
 	bodyLines.push("    },");
 	return bodyLines;
 }
+function stdinPayloadVariable(stdinEvent) {
+	return `__rulesync${stdinEvent}Input`;
+}
+/**
+* The statement that runs a handler's command. A handler with a stdin payload
+* pipes the payload in and hands the result to the deny-aware helper; every
+* other handler keeps Bun Shell's default mode, where a non-zero exit throws.
+*/
+function buildRunStatement(handler) {
+	const escapedCommand = escapeForTemplateLiteral(handler.command);
+	if (handler.stdinEvent) {
+		const payload = stdinPayloadVariable(handler.stdinEvent);
+		return `${PRE_TOOL_USE_RESULT_HELPER}(await $\`echo \${${payload}()} | ${escapedCommand}\`.nothrow().quiet());`;
+	}
+	return `await $\`${escapedCommand}\`;`;
+}
 /** Emit the named (`tool.execute.*`) handler blocks. */
 function buildNamedEventBodyLines(namedEventHandlers) {
 	const bodyLines = [];
 	for (const [eventName, handlers] of Object.entries(namedEventHandlers)) {
 		const matcherSubject = NAMED_HOOK_MATCHER_SUBJECTS[eventName] ?? null;
-		bodyLines.push(`    "${eventName}": async (input) => {`);
+		const stdinEvents = [...new Set(handlers.flatMap((handler) => handler.stdinEvent ? [handler.stdinEvent] : []))];
+		bodyLines.push(`    "${eventName}": async (${stdinEvents.length > 0 ? "input, output" : "input"}) => {`);
+		for (const stdinEvent of stdinEvents) {
+			const payload = stdinPayloadVariable(stdinEvent);
+			bodyLines.push(`      let ${payload}Cache;`);
+			bodyLines.push(`      const ${payload} = () =>`);
+			bodyLines.push(`        (${payload}Cache ??= JSON.stringify({`);
+			bodyLines.push(`          hook_event_name: "${stdinEvent}",`);
+			bodyLines.push("          session_id: input.sessionID,");
+			bodyLines.push("          tool_use_id: input.callID,");
+			bodyLines.push("          tool_name: input.tool,");
+			bodyLines.push("          tool_input: output?.args,");
+			bodyLines.push("          cwd: directory ?? process.cwd(),");
+			bodyLines.push("        }));");
+		}
 		for (const handler of handlers) {
-			const escapedCommand = escapeForTemplateLiteral(handler.command);
+			const runStatement = buildRunStatement(handler);
 			if (handler.toolGate) {
 				bodyLines.push(`      if (input.tool === "${handler.toolGate}") {`);
-				bodyLines.push(`        await $\`${escapedCommand}\`;`);
+				bodyLines.push(`        ${runStatement}`);
 				bodyLines.push("      }");
 			} else if (handler.matcher && matcherSubject !== null) {
 				const safeMatcher = validateAndSanitizeMatcher(handler.matcher);
 				bodyLines.push("      {");
 				bodyLines.push(`        const __re = new RegExp("${safeMatcher}");`);
 				bodyLines.push(`        if (__re.test(${matcherSubject})) {`);
-				bodyLines.push(`          await $\`${escapedCommand}\`;`);
+				bodyLines.push(`          ${runStatement}`);
 				bodyLines.push("        }");
 				bodyLines.push("      }");
-			} else bodyLines.push(`      await $\`${escapedCommand}\`;`);
+			} else bodyLines.push(`      ${runStatement}`);
 		}
 		bodyLines.push("    },");
 	}
 	return bodyLines;
 }
 /** Wrap the handler body lines in the requested export shape. */
-function wrapInExportShape({ bodyLines, exportStyle }) {
+function wrapInExportShape({ preambleLines, bodyLines, exportStyle }) {
+	const pluginContextPattern = preambleLines.length > 0 ? "{ $, directory }" : "{ $ }";
 	const lines = [];
 	if (exportStyle === "default") {
 		lines.push("export default {");
 		lines.push("  id: \"rulesync-hooks\",");
-		lines.push("  server: async ({ $ }) => {");
+		lines.push(`  server: async (${pluginContextPattern}) => {`);
+		for (const line of preambleLines) lines.push(line === "" ? "" : `    ${line}`);
 		lines.push("    return {");
 		for (const line of bodyLines) lines.push(line === "" ? "" : `  ${line}`);
 		lines.push("    };");
 		lines.push("  },");
 		lines.push("};");
 	} else {
-		lines.push("export const RulesyncHooksPlugin = async ({ $ }) => {");
+		lines.push(`export const RulesyncHooksPlugin = async (${pluginContextPattern}) => {`);
+		for (const line of preambleLines) lines.push(line === "" ? "" : `  ${line}`);
 		lines.push("  return {");
 		lines.push(...bodyLines);
 		lines.push("  };");
@@ -34158,8 +34401,10 @@ function generateOpencodeStylePluginCode(config, supportedEvents, toolConfigKey,
 		namedEventHandlers,
 		genericEventHandlers
 	});
+	const bodyLines = [...buildGenericEventBodyLines(genericEventHandlers), ...buildNamedEventBodyLines(namedEventHandlers)];
 	return wrapInExportShape({
-		bodyLines: [...buildGenericEventBodyLines(genericEventHandlers), ...buildNamedEventBodyLines(namedEventHandlers)],
+		preambleLines: Object.values(namedEventHandlers).some((handlers) => handlers.some((handler) => handler.stdinEvent !== void 0)) ? PRE_TOOL_USE_RESULT_HELPER_LINES : [],
+		bodyLines,
 		exportStyle
 	}).join("\n");
 }
@@ -35304,36 +35549,12 @@ function failureLinesByMode(dialect) {
 * `PI_SETTLE_BLOCKING_EVENT`): such a failure is rethrown for Pi to report
 * instead of continuing the agent.
 *
-* The chosen text is sanitized because a hook command's output can relay
-* third-party content (linter output, matched file lines) into a terminal or,
-* in RPC mode, into an external client. Escape sequences, C1 and other control
-* characters, and format characters such as bidirectional overrides and
-* zero-width joiners are stripped so the reason cannot repaint or reorder what
-* the user is shown, and carriage returns are folded into newlines so it cannot
-* overwrite an already printed line. The format-character pass is a superset of
-* the bidi controls listed in `CONTROL_CHARACTERS_PATTERN`
-* (`src/utils/control-characters.ts`): a blocked-hook reason is short
-* diagnostic text, so dropping every `Cf` character is safer than enumerating
-* the harmful ones and missing `U+061C`, `U+FEFF`, or a future addition.
-*
-* Sanitization runs before truncation so a reason that begins with a progress
-* banner is still reported by its content. The raw text is only sliced to a
-* generous backstop first: a hook command may emit up to `exec`'s full
-* `maxBuffer`, and the slice bounds the work even if a later edit reintroduces
-* a pattern that is not linear. A slice that actually fired is reported as
-* truncated, so the text is never silently cut.
-*
-* Both slices cut on UTF-16 code units, so each drops a trailing lone high
-* surrogate: the reason travels to an RPC client as JSON, and half a surrogate
-* pair is not text a strict consumer has to accept.
+* The chosen text goes through `sanitizeBlockReason`, shared with the
+* OpenCode-style plugin (see `hook-block-reason.ts`): control and format
+* characters are stripped and the result is capped at 2000 characters.
 */
 const BLOCK_REASON_HELPER_LINES = [
-	"const MAX_BLOCK_REASON_LENGTH = 2000;",
-	"const MAX_SCANNED_REASON_LENGTH = 128_000;",
-	"",
-	"function dropTrailingLoneSurrogate(text: string): string {",
-	"  return text.replace(/[\\ud800-\\udbff]$/, \"\");",
-	"}",
+	...buildBlockReasonSanitizerLines({ typed: true }),
 	"",
 	"function toBlockReason(error: unknown): string {",
 	"  const result = error as { stdout?: unknown; stderr?: unknown; code?: unknown } | null;",
@@ -35347,20 +35568,7 @@ const BLOCK_REASON_HELPER_LINES = [
 	"      : error instanceof Error",
 	"        ? error.message",
 	"        : String(error));",
-	"  const scannedTruncated = raw.length > MAX_SCANNED_REASON_LENGTH;",
-	"  const scanned = scannedTruncated",
-	"    ? dropTrailingLoneSurrogate(raw.slice(0, MAX_SCANNED_REASON_LENGTH))",
-	"    : raw;",
-	"  const sanitized = scanned",
-	"    .replace(/\\r\\n?/g, \"\\n\")",
-	"    .replace(/\\u001b\\[[0-9;?]*[\\u0020-\\u002f]*[\\u0040-\\u007e]/g, \"\")",
-	"    .replace(/\\u001b\\][^\\u0007\\u001b]{0,256}(?:\\u0007|\\u001b\\\\)/g, \"\")",
-	"    .replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f-\\u009f]/g, \"\")",
-	"    .replace(/[\\p{Cf}\\p{Zl}\\p{Zp}]/gu, \"\")",
-	"    .trim();",
-	"  if (!sanitized) return \"Hook command failed.\";",
-	"  if (sanitized.length <= MAX_BLOCK_REASON_LENGTH && !scannedTruncated) return sanitized;",
-	"  return `${dropTrailingLoneSurrogate(sanitized.slice(0, MAX_BLOCK_REASON_LENGTH))}...`;",
+	"  return sanitizeBlockReason(raw) || \"Hook command failed.\";",
 	"}"
 ];
 /**
@@ -48979,12 +49187,18 @@ function warnAboutToggleDroppedKeys(serverName, serverConfig, logger) {
 * - enabledTools/disabledTools -> top-level tools map (with server name prefix)
 * - OpenCode-supported extras (timeout, oauth, protocol, codemode) -> passed through verbatim
 */
-function convertServerToOpencodeFormat(serverName, serverConfig, existingEntry, logger) {
+function convertServerToOpencodeFormat(serverName, serverConfig, existingEntry, configShape, logger) {
 	const serverRecord = serverConfig;
 	const passthrough = {};
 	for (const key of OPENCODE_PASSTHROUGH_SERVER_FIELDS) if (serverRecord[key] !== void 0) passthrough[key] = serverRecord[key];
 	const enabled = serverConfig.disabled !== void 0 ? !serverConfig.disabled : true;
 	if (declaresNoTransport(serverConfig)) {
+		if (configShape === "v2") return warnAndSkipMcpServer({
+			toolName: "OpenCode",
+			serverName,
+			reason: "no transport, and the OpenCode V2 shape (\"configShape\": \"v2\") has no toggle-only entry",
+			logger
+		});
 		if (serverConfig.disabled === void 0) {
 			if (existingEntry !== void 0 && !isOpencodeTransportServer(existingEntry)) {
 				warnAboutToggleDroppedKeys(serverName, serverConfig, logger);
@@ -49032,11 +49246,11 @@ function convertServerToOpencodeFormat(serverName, serverConfig, existingEntry,
 		...serverConfig.cwd && { cwd: serverConfig.cwd }
 	};
 }
-function convertToOpencodeFormat(mcpServers, existingMcp, logger) {
+function convertToOpencodeFormat(mcpServers, existingMcp, configShape, logger) {
 	const tools = {};
 	return {
 		mcp: Object.fromEntries(Object.entries(mcpServers).map(([serverName, serverConfig]) => {
-			const converted = convertServerToOpencodeFormat(serverName, serverConfig, existingMcp[serverName], logger);
+			const converted = convertServerToOpencodeFormat(serverName, serverConfig, existingMcp[serverName], configShape, logger);
 			if (serverConfig.enabledTools) for (const tool of serverConfig.enabledTools) tools[`${serverName}_${tool}`] = true;
 			if (serverConfig.disabledTools) for (const tool of serverConfig.disabledTools) tools[`${serverName}_${tool}`] = false;
 			return converted === null ? null : [serverName, converted];
@@ -49044,6 +49258,7 @@ function convertToOpencodeFormat(mcpServers, existingMcp, logger) {
 		tools
 	};
 }
+const OpencodeMcpFeatureOptionsSchema = zod_mini.z.looseObject({ configShape: zod_mini.z.optional(zod_mini.z.enum(["v1", "v2"])) });
 var OpencodeMcp = class extends ToolMcp {
 	/** Directory layout; OpenCode forks (MiMo Code) override it. */
 	static layout = OPENCODE_LAYOUT;
@@ -49082,6 +49297,19 @@ var OpencodeMcp = class extends ToolMcp {
 		return this.json;
 	}
 	/**
+	* Reads the `configShape` option of the target's `mcp` feature options
+	* (`targets.opencode.mcp.configShape`). Only a layout that reads the V2
+	* spellings back can be given the V2 shape.
+	*/
+	static resolveConfigShape(options) {
+		if (!options) return "v1";
+		const parsed = OpencodeMcpFeatureOptionsSchema.safeParse(options);
+		if (!parsed.success) throw new Error(`Invalid options for the ${this.layout.toolTarget} mcp feature: \`configShape\` must be either "v1" or "v2".`);
+		const configShape = parsed.data.configShape ?? "v1";
+		if (configShape === "v2" && !this.layout.readsV2ConfigSpellings) throw new Error(`Invalid options for the ${this.layout.toolTarget} mcp feature: \`configShape: "v2"\` is supported only for OpenCode.`);
+		return configShape;
+	}
+	/**
 	* opencode.json may contain other settings, so it should not be deleted.
 	*/
 	isDeletable() {
@@ -49125,7 +49353,8 @@ var OpencodeMcp = class extends ToolMcp {
 			logger
 		});
 	}
-	static async fromRulesyncMcp({ outputRoot = process.cwd(), rulesyncMcp, validate = true, global = false, logger }) {
+	static async fromRulesyncMcp({ outputRoot = process.cwd(), rulesyncMcp, validate = true, global = false, logger, featureOptions }) {
+		const configShape = this.resolveConfigShape(featureOptions);
 		const basePaths = this.getSettablePaths({ global });
 		const jsonDir = (0, node_path.join)(outputRoot, basePaths.relativeDirPath);
 		let fileContent = null;
@@ -49143,16 +49372,21 @@ var OpencodeMcp = class extends ToolMcp {
 		});
 		const existingJson = (0, jsonc_parser.parse)(fileContent || "{}");
 		const existingMcp = OpencodeConfigSchema.safeParse(this.lowerConfig(existingJson));
-		if (this.layout.readsV2ConfigSpellings && isRecord$1(existingJson)) {
-			const containers = findOpencodeV2McpContainers(existingJson.mcp);
+		const existingRawMcp = isRecord$1(existingJson) ? existingJson.mcp : void 0;
+		if (configShape === "v1" && this.layout.readsV2ConfigSpellings) {
+			const containers = findOpencodeV2McpContainers(existingRawMcp);
 			if (containers.length > 0) logger?.warn(`OpenCode MCP: the whole "mcp" key is rewritten in the flat V1 shape, so ${containers.map(quoteValueForWarning).join(" and ")} ${containers.length === 1 ? "is" : "are"} not kept.`);
 		}
-		const { mcp: convertedMcp, tools: mcpTools } = convertToOpencodeFormat(transformedServers, (existingMcp.success ? existingMcp.data.mcp : void 0) ?? {}, logger);
-		const generatedMcp = undefinedWhenEmpty(convertedMcp);
+		const { mcp: convertedMcp, tools: mcpTools } = convertToOpencodeFormat(transformedServers, (existingMcp.success ? existingMcp.data.mcp : void 0) ?? {}, configShape, logger);
+		const generatedServers = undefinedWhenEmpty(convertedMcp);
+		const generatedMcp = configShape === "v2" ? this.toV2Mcp({
+			servers: convertedMcp,
+			existingRawMcp
+		}) : generatedServers;
 		const generatedTools = Object.keys(mcpTools).length > 0 ? mcpTools : void 0;
 		warnOpencodeDotDirOverrides({
 			generated: {
-				mcp: generatedMcp,
+				mcp: generatedServers,
 				tools: generatedTools
 			},
 			overlays: (await readOpencodeDotDirConfigLayers({
@@ -49188,6 +49422,28 @@ var OpencodeMcp = class extends ToolMcp {
 		});
 	}
 	/**
+	* Builds the V2 `mcp` value: each server raised to the V2 spelling under the
+	* `mcp.servers` envelope, keeping what the existing file has that Rulesync
+	* cannot express (see {@link raiseOpencodeServerToV2}), plus the existing
+	* global `mcp.timeout`, which has no canonical counterpart.
+	*/
+	static toV2Mcp({ servers, existingRawMcp }) {
+		const v2Servers = {};
+		for (const [name, server] of Object.entries(servers)) Object.defineProperty(v2Servers, name, {
+			value: raiseOpencodeServerToV2(server, getOpencodeMcpServerEntry(existingRawMcp, name)),
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+		const globalTimeout = getOpencodeV2GlobalMcpTimeout(existingRawMcp);
+		const hasServers = Object.keys(v2Servers).length > 0;
+		if (!hasServers && globalTimeout === void 0) return;
+		return {
+			...globalTimeout !== void 0 && { timeout: globalTimeout },
+			...hasServers && { servers: v2Servers }
+		};
+	}
+	/**
 	* Register additional instruction file paths into the shared opencode config
 	* (`opencode.json` / `opencode.jsonc`) under the `instructions` key.
 	*
@@ -54907,7 +55163,8 @@ var McpProcessor = class extends FeatureProcessor {
 	toolTarget;
 	global;
 	getFactory;
-	constructor({ outputRoot = process.cwd(), inputRoots, toolTarget, global = false, getFactory = defaultGetFactory$3, dryRun = false, logger }) {
+	featureOptions;
+	constructor({ outputRoot = process.cwd(), inputRoots, toolTarget, global = false, getFactory = defaultGetFactory$3, dryRun = false, logger, featureOptions }) {
 		super({
 			outputRoot,
 			inputRoots,
@@ -54919,6 +55176,7 @@ var McpProcessor = class extends FeatureProcessor {
 		this.toolTarget = result.data;
 		this.global = global;
 		this.getFactory = getFactory;
+		this.featureOptions = featureOptions;
 	}
 	/**
 	* Implementation of abstract method from FeatureProcessor
@@ -55000,7 +55258,8 @@ var McpProcessor = class extends FeatureProcessor {
 				outputRoot: this.outputRoot,
 				rulesyncMcp: filteredRulesyncMcp,
 				global: this.global,
-				logger: this.logger
+				logger: this.logger,
+				featureOptions: this.featureOptions
 			});
 		}));
 		const auxiliaryFiles = await factory.class.getAuxiliaryFiles?.({
@@ -57781,12 +58040,14 @@ var CodewhaleSkill = class CodewhaleSkill extends ToolSkill {
 const CodexCliSkillFrontmatterSchema = zod_mini.z.looseObject({
 	name: zod_mini.z.string(),
 	description: zod_mini.z.string(),
-	metadata: zod_mini.z.optional(zod_mini.z.looseObject({ "short-description": zod_mini.z.optional(zod_mini.z.string()) }))
+	metadata: zod_mini.z.optional(zod_mini.z.looseObject({ "short-description": zod_mini.z.optional(zod_mini.z.string()) })),
+	"disable-model-invocation": zod_mini.z.optional(zod_mini.z.boolean())
 });
 /**
 * Relative path (within a skill directory) of the Codex `agents/openai.yaml` sidecar.
 * Codex CLI reads UI metadata, invocation policy, and tool dependencies from this file;
-* `SKILL.md` frontmatter only carries `name` and `description`.
+* from `SKILL.md` frontmatter it reads only `name`, `description` and
+* `metadata.short-description`, ignoring any other key.
 * @see https://developers.openai.com/codex/skills.md
 */
 const CODEX_OPENAI_YAML_RELATIVE_PATH = CODEXCLI_OPENAI_YAML_RELATIVE_PATH;
@@ -57876,6 +58137,40 @@ function openaiYamlToCodexcliSection(parsed) {
 	return Object.keys(section).length > 0 ? section : void 0;
 }
 /**
+* Build the `SKILL.md` `metadata` map: the root-level rulesync `metadata` with
+* the legacy `codexcli.short-description` merged in. The tool-specific value wins
+* over a root `metadata.short-description`, as a target section overrides the
+* root default everywhere else. Values are stringified because the Agent Skills
+* spec types `metadata` as a string-to-string map, and `.agents/skills/` is read
+* by other spec clients too; Codex itself deserializes `short-description` as a
+* string.
+* @see https://agentskills.io/specification
+*/
+function buildSkillMetadata({ rootMetadata, shortDescription }) {
+	const merged = {
+		...rootMetadata,
+		...shortDescription !== void 0 && { "short-description": shortDescription }
+	};
+	return Object.keys(merged).length > 0 ? toStringMetadata(merged) : void 0;
+}
+/**
+* Drop `policy.allow_implicit_invocation: false` from an imported sidecar section
+* when the `SKILL.md` frontmatter already carries `disable-model-invocation: true`,
+* since the root flag regenerates exactly that value. Keeping both would store the
+* same setting twice in `.rulesync/skills/`.
+*/
+function dropPolicyImpliedByRootFlag(section, disableModelInvocation) {
+	const policy = section?.policy;
+	if (!section || disableModelInvocation !== true || policy === null || typeof policy !== "object" || Array.isArray(policy) || policy.allow_implicit_invocation !== false) return section;
+	const { allow_implicit_invocation: _implied, ...restPolicy } = policy;
+	const { policy: _policy, ...restSection } = section;
+	const result = {
+		...restSection,
+		...Object.keys(restPolicy).length > 0 && { policy: restPolicy }
+	};
+	return Object.keys(result).length > 0 ? result : void 0;
+}
+/**
 * Represents a Codex CLI skill directory.
 * Codex CLI supports skills in both project mode (under $CWD/.agents/skills)
 * and global mode (under ~/.agents/skills — Rulesync resolves the home
@@ -57926,16 +58221,20 @@ var CodexCliSkill = class CodexCliSkill extends ToolSkill {
 	}
 	toRulesyncSkill() {
 		const frontmatter = this.getFrontmatter();
+		const disableModelInvocation = frontmatter["disable-model-invocation"];
 		const { parsed, rest } = extractOpenaiYamlFile(this.getOtherFiles());
-		const openaiSection = openaiYamlToCodexcliSection(parsed);
+		const openaiSection = dropPolicyImpliedByRootFlag(openaiYamlToCodexcliSection(parsed), disableModelInvocation);
+		const { "short-description": shortDescription, ...rootMetadata } = frontmatter.metadata ?? {};
 		const codexcliSection = {
-			...frontmatter.metadata?.["short-description"] && { "short-description": frontmatter.metadata["short-description"] },
+			...shortDescription !== void 0 && { "short-description": shortDescription },
 			...openaiSection
 		};
 		const rulesyncFrontmatter = {
 			name: frontmatter.name,
 			description: frontmatter.description,
 			targets: ["*"],
+			...disableModelInvocation !== void 0 && { "disable-model-invocation": disableModelInvocation },
+			...Object.keys(rootMetadata).length > 0 && { metadata: rootMetadata },
 			...Object.keys(codexcliSection).length > 0 && { codexcli: codexcliSection }
 		};
 		return new RulesyncSkill({
@@ -57952,10 +58251,16 @@ var CodexCliSkill = class CodexCliSkill extends ToolSkill {
 	static fromRulesyncSkill({ outputRoot = process.cwd(), rulesyncSkill, validate = true, global = false }) {
 		const settablePaths = CodexCliSkill.getSettablePaths({ global });
 		const rulesyncFrontmatter = rulesyncSkill.getFrontmatter();
+		const metadata = buildSkillMetadata({
+			rootMetadata: rulesyncFrontmatter.metadata,
+			shortDescription: rulesyncFrontmatter.codexcli?.["short-description"]
+		});
+		const disableModelInvocation = rulesyncFrontmatter["disable-model-invocation"];
 		const codexFrontmatter = {
 			name: rulesyncFrontmatter.name,
 			description: rulesyncFrontmatter.description,
-			...rulesyncFrontmatter.codexcli?.["short-description"] && { metadata: { "short-description": rulesyncFrontmatter.codexcli["short-description"] } }
+			...disableModelInvocation !== void 0 && { "disable-model-invocation": disableModelInvocation },
+			...metadata !== void 0 && { metadata }
 		};
 		const target = toPosixPath(CODEX_OPENAI_YAML_RELATIVE_PATH);
 		const baseOtherFiles = rulesyncSkill.getOtherFiles().filter((file) => toPosixPath(file.relativeFilePathToDirPath) !== target);
@@ -67443,6 +67748,16 @@ var CopilotSubagent = class CopilotSubagent extends ToolSubagent {
 *    (`preferred` lets a `subagents` settings override or the `/subagents`
 *    picker replace the model; `required` locks dispatch to the authored
 *    list). CLI v1.0.81+; the shared reference page still lists `model` only.
+*  - `model` may also be a list of models in preference order. The Copilot
+*    CLI changelog for v1.0.83 (2026-09-04) says "Custom agents can list
+*    several models in `model`, tried in order until one is available to
+*    you"; the CLI command reference and the shared configuration reference
+*    still document `model` as a string, so older CLI versions may not read
+*    the list form (a string is the safe form there). The VS Code Copilot
+*    harness documents the same array spelling. Preserve a list as authored
+*    instead of rewriting it to the separate `models` field.
+*    https://github.com/github/copilot-cli/blob/main/changelog.md#1083---2026-09-04
+*    https://github.com/microsoft/vscode-docs/blob/main/docs/agents/reference/custom-agent-file-reference.md
 *
 * `looseObject` is used so that future additional fields are passed through
 * unchanged (consistent with the rest of rulesync's frontmatter schemas).
@@ -67452,7 +67767,7 @@ const CopilotCliSubagentFrontmatterSchema = zod_mini.z.looseObject({
 	name: zod_mini.z.optional(zod_mini.z.string()),
 	target: zod_mini.z.optional(zod_mini.z.string()),
 	tools: zod_mini.z.optional(zod_mini.z.union([zod_mini.z.string(), zod_mini.z.array(zod_mini.z.string())])),
-	model: zod_mini.z.optional(zod_mini.z.string()),
+	model: zod_mini.z.optional(zod_mini.z.union([zod_mini.z.string(), zod_mini.z.array(zod_mini.z.string())])),
 	models: zod_mini.z.optional(zod_mini.z.array(zod_mini.z.string())),
 	modelPolicy: zod_mini.z.optional(zod_mini.z.enum(["preferred", "required"])),
 	"disable-model-invocation": zod_mini.z.optional(zod_mini.z.boolean()),
@@ -107241,7 +107556,8 @@ function buildMcpStrategy(ctx) {
 			toolTarget,
 			global,
 			dryRun,
-			logger
+			logger,
+			featureOptions: config.getFeatureOptions(toolTarget, "mcp")
 		}),
 		loadSource: (p) => p.loadToolFiles(),
 		toRulesync: (p, files) => p.convertToolFilesToRulesyncFiles(files),
@@ -108971,7 +109287,8 @@ async function generateMcpCore(params) {
 			toolTarget,
 			global: config.getGlobal(),
 			dryRun: config.isPreviewMode(),
-			logger
+			logger,
+			featureOptions: config.getFeatureOptions(toolTarget, "mcp")
 		});
 		const result = await processFeatureWithRulesyncFiles({
 			config,