@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -37,6 +37,7 @@ const { getDirName } = runtimeNamePolicy;
 const capabilityRegistry = require("./capability-registry.cjs");
 const hostIntegration = require("./host-integration.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const frontmatterModule = require("./frontmatter.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // #2870: install-scope.cts is a leaf-tier sibling (imports only
@@ -275,8 +276,22 @@ const kiloAgentPermissionOrder = [
     'codesearch',
     'lsp',
 ];
+const kiloMcpPermissionPattern = /^mcp__([A-Za-z0-9_-]+)__((?:[A-Za-z0-9_-]+)|\*)$/;
+/**
+ * Derive Kilo's native `{server}_{tool}` MCP permission key (kilo.ai/docs —
+ * external, fixed format we don't control). Not injective: both capture
+ * groups allow `_`, so e.g. `mcp__a_b__c` and `mcp__a__b_c` derive the same
+ * key. `buildKiloAgentPermissionBlock`'s `Set` resolves any such collision
+ * deterministically to first-seen-wins — see its regression test. Changing
+ * the derivation to avoid the collision isn't an option: Kilo's own runtime
+ * only recognizes this exact key shape.
+ */
 function convertClaudeToKiloPermissionTool(claudeTool) {
-    return claudeToKiloAgentPermissions[claudeTool] || null;
+    const builtinPermission = claudeToKiloAgentPermissions[claudeTool];
+    if (builtinPermission)
+        return builtinPermission;
+    const mcpPermission = kiloMcpPermissionPattern.exec(claudeTool);
+    return mcpPermission ? `${mcpPermission[1]}_${mcpPermission[2]}` : null;
 }
 function buildKiloAgentPermissionBlock(claudeTools) {
     const allowedPermissions = new Set();
@@ -290,6 +305,11 @@ function buildKiloAgentPermissionBlock(claudeTools) {
     for (const permission of kiloAgentPermissionOrder) {
         lines.push(`  ${permission}: ${allowedPermissions.has(permission) ? 'allow' : 'deny'}`);
     }
+    for (const permission of allowedPermissions) {
+        if (kiloAgentPermissionOrder.includes(permission))
+            continue;
+        lines.push(`  ${permission}: allow`);
+    }
     return lines;
 }
 function replaceRelativePathReference(content, fromPath, toPath) {
@@ -644,6 +664,137 @@ function convertClaudeCommandToKimiCodeSkill(content, skillName, _runtime = null
     return convertClaudeCommandToKimiSkill(content, skillName, _runtime, cmdNames);
 }
 const KIMI_CANONICAL_GSD_AGENT_RE = /^gsd-[a-z0-9-]+$/;
+/** Split a `tools:` comma list without tearing a quoted scalar that contains a literal comma. */
+function splitToolScalars(text) {
+    const parts = [];
+    let current = '';
+    let quote = null;
+    for (const ch of text) {
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ',') {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+/** Normalize one complete frontmatter tool scalar through the shared YAML parser. */
+function decodeToolScalar(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const value = raw.trim();
+    if (!value)
+        return null;
+    if (value.startsWith('"') || value.startsWith("'")) {
+        try {
+            const decoded = frontmatterModule.parseFrontmatter('---\ntool: ' + value + '\n---\n').tool;
+            return typeof decoded === 'string' && decoded.trim() ? decoded.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // A bare (unquoted) scalar may carry a trailing `  # comment` (YAML requires
+    // whitespace before `#` to start a comment) — every caller here passes a
+    // single already-comma-split token, never the whole `tools:` line, so this
+    // is safe to strip unconditionally rather than pushing the concern onto
+    // each call site. Strip BEFORE the malformed-quote check below: a comment
+    // may itself contain a `"`/`'` (e.g. `Bash # note: "internal"`), which is
+    // not a real YAML quote delimiter and must not cause a false rejection.
+    const commentIndex = value.search(/[ \t]#/);
+    const stripped = commentIndex === -1 ? value : value.slice(0, commentIndex).trimEnd();
+    if (!stripped)
+        return null;
+    if (stripped.endsWith('"') || stripped.endsWith("'"))
+        return null;
+    return stripped;
+}
+/** Append validated canonical grants without reserializing unrelated frontmatter. */
+function appendAgentTools(content, grants) {
+    if (grants.length === 0)
+        return content;
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(eol);
+    if (lines[0] !== '---')
+        return content;
+    const frontmatterEnd = lines.indexOf('---', 1);
+    if (frontmatterEnd === -1)
+        return content;
+    const toolsIndex = lines.findIndex((line, index) => index < frontmatterEnd && /^tools:[ \t]*(.*)$/.test(line));
+    if (toolsIndex === -1)
+        return content;
+    const toolsMatch = /^tools:[ \t]*(.*)$/.exec(lines[toolsIndex]);
+    if (!toolsMatch)
+        return content;
+    // Plain (non-leading-quote) YAML scalars have no internal quoting — a `#`
+    // after whitespace is a real comment start regardless of nearby quote
+    // characters (verified: real YAML truncates `Read, "x #1"` at the space
+    // before `#` too), so this scan does not need to be quote-aware. The one
+    // case that DOES need protection — a value that IS a leading quoted scalar
+    // — is refused outright below rather than parsed past.
+    const commentIndex = toolsMatch[1].search(/[ \t]#/);
+    let inlineValue = commentIndex === -1 ? toolsMatch[1] : toolsMatch[1].slice(0, commentIndex);
+    let inlineComment = commentIndex === -1 ? '' : toolsMatch[1].slice(commentIndex);
+    // A header that is ONLY a comment (`tools: # note`) has no leading space in
+    // the captured group — the outer regex's `[ \t]*` already consumed it — so
+    // the `[ \t]#` scan above never fires. Reclassify as no inline value so the
+    // block-list scan below runs instead of swallowing the comment as content.
+    if (inlineValue.trim().startsWith('#')) {
+        inlineComment = toolsMatch[1];
+        inlineValue = '';
+    }
+    // A value that STARTS with a quote is a YAML quoted scalar occupying the
+    // whole node — nothing may follow it on the same line except a comment
+    // (`tools: "Bash"` is valid; `tools: "Bash", Read` is not, even before this
+    // function touches it). Appending in place would corrupt otherwise-valid
+    // frontmatter, so refuse rather than emit invalid YAML. A value that STARTS
+    // with `[` is a YAML flow sequence (`tools: [Bash, Read]`) — its own commas
+    // are node-internal, not scalar separators, and content cannot follow its
+    // closing `]` on the same line either, so the same refusal applies.
+    if (/^["'[]/.test(inlineValue.trim()))
+        return content;
+    const existing = [];
+    let insertAt = toolsIndex + 1;
+    if (inlineValue.trim()) {
+        existing.push(...splitToolScalars(inlineValue).map(decodeToolScalar).filter((value) => value !== null));
+    }
+    else {
+        while (insertAt < frontmatterEnd) {
+            const item = /^([ \t]+)-[ \t]*(\S.*)$/.exec(lines[insertAt]);
+            if (!item)
+                break;
+            const decoded = decodeToolScalar(item[2]);
+            if (decoded !== null)
+                existing.push(decoded);
+            insertAt += 1;
+        }
+    }
+    const present = new Set(existing);
+    const additions = grants.filter((grant) => !present.has(grant) && (present.add(grant), true));
+    if (additions.length === 0)
+        return content;
+    if (inlineValue.trim()) {
+        lines[toolsIndex] = `tools: ${inlineValue.trimEnd()}, ${additions.join(', ')}${inlineComment}`;
+    }
+    else {
+        const firstItem = /^([ \t]+)-/.exec(lines[toolsIndex + 1]);
+        const indent = firstItem ? firstItem[1] : '  ';
+        lines.splice(insertAt, 0, ...additions.map((grant) => `${indent}- ${JSON.stringify(grant)}`));
+    }
+    return lines.join(eol);
+}
 function parseKimiAgentSource(source) {
     if (typeof source === 'string') {
         return {
@@ -671,7 +822,9 @@ function parseFrontmatterTools(frontmatter) {
             continue;
         if (collecting) {
             if (trimmed.startsWith('- ')) {
-                tools.push(trimmed.slice(2).trim());
+                const tool = decodeToolScalar(trimmed.slice(2));
+                if (tool !== null)
+                    tools.push(tool);
                 continue;
             }
             collecting = false;
@@ -682,10 +835,13 @@ function parseFrontmatterTools(frontmatter) {
         }
         if (trimmed.startsWith('tools:') || trimmed.startsWith('allowed-tools:')) {
             const value = trimmed.slice(trimmed.indexOf(':') + 1).trim();
-            if (value) {
-                for (const tool of value.split(',')) {
-                    const name = tool.trim();
-                    if (name)
+            // A comment-only value (`tools: # note`) has no real inline content —
+            // fall through to the block-list scan below instead of decoding the
+            // comment text as a bogus tool name and silently dropping the list.
+            if (value && !value.startsWith('#')) {
+                for (const tool of splitToolScalars(value)) {
+                    const name = decodeToolScalar(tool);
+                    if (name !== null)
                         tools.push(name);
                 }
             }
@@ -847,7 +1003,8 @@ function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSuba
 /**
  * Apply Antigravity-specific content conversion — path replacement + command name conversion.
  * Path mappings depend on install mode:
- *   Global: ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agents/
+ *   Global: ~/.claude/skills/ → ~/.gemini/config/skills/ (#3738),
+ *          ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agents/
  *   Local:  ~/.claude/ → .agents/, ./.claude/ → ./.agents/
  * Applied to ALL Antigravity content (skills, agents, engine files).
  * @param {string} content - Source content to convert
@@ -856,6 +1013,18 @@ function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSuba
 function convertClaudeToAntigravityContent(content, isGlobal = false) {
     let c = content;
     if (isGlobal) {
+        // #3738: global skills install under ~/.gemini/config/skills (the dir AGY
+        // scans for global discovery), so skills-path references must divert there
+        // — BEFORE the configHome rewrite below, which is correct for gsd-core
+        // runtime-file references (settings, workflows, VERSION) but wrong for the
+        // skills dir itself.
+        c = c.replace(/\$HOME\/\.claude\/skills\//g, '$HOME/.gemini/config/skills/');
+        c = c.replace(/~\/\.claude\/skills\//g, '~/.gemini/config/skills/');
+        // Bare skills form (no trailing slash) — must also precede the generic
+        // slash rule, which would otherwise divert it to the retired configHome
+        // path ($HOME/.gemini/antigravity/skills).
+        c = c.replace(/\$HOME\/\.claude\/skills\b/g, '$HOME/.gemini/config/skills');
+        c = c.replace(/~\/\.claude\/skills\b/g, '~/.gemini/config/skills');
         c = c.replace(/\$HOME\/\.claude\//g, '$HOME/.gemini/antigravity/');
         c = c.replace(/~\/\.claude\//g, '~/.gemini/antigravity/');
         // Bare form (no trailing slash) — must come after slash form to avoid double-replace
@@ -1609,26 +1778,37 @@ Execute mode fallback:
 ## C. Task() → spawn_agent Mapping
 GSD workflows use \`Task(...)\` (Claude Code syntax). Translate to Codex collaboration tools:
 
-**Schema detection (required first step):** Codex exposes two \`spawn_agent\` schemas:
-- **agent_type-capable schema** (e.g. \`multi_agent_v2\`): \`spawn_agent\` accepts \`agent_type\`, \`message\`, \`reasoning_effort\`, \`fork_context\`, etc. — typed GSD agent dispatch is available.
-- **Generic schema** (\`multi_agent_v1\`): \`spawn_agent\` accepts only \`message\`, \`items\`, \`fork_context\` — there is **no \`agent_type\` field**. Typed GSD agent dispatch is unavailable in this session.
+**Schema detection (required first step):** Before spawning, inspect the \`spawn_agent\`
+tool's visible parameter schema (via \`tool_search\` or the tool list). Use the presence
+of \`agent_type\` only to choose typed dispatch versus the generic-agent workaround.
+Detect optional fields independently: \`model\`, \`reasoning_effort\`, \`task_name\`,
+\`fork_turns\`, and \`fork_context\` may be added or removed without \`agent_type\` changing.
+Never infer one field from a schema/version label or from the presence of another field.
 
-Before spawning, inspect the \`spawn_agent\` tool's visible parameter schema (via \`tool_search\` or the tool list) to determine which form is active.
+- **agent_type-capable schema:** \`spawn_agent\` advertises \`agent_type\` — typed GSD agent dispatch is available.
+- **Generic schema:** \`spawn_agent\` does not advertise \`agent_type\` — typed GSD agent dispatch is unavailable in this session, even if other optional fields are present.
 
 Typed mapping (agent_type-capable schema only):
 - \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
 - \`Agent(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
-- \`Task(model="...")\` → omit. \`spawn_agent\` has no inline \`model\` parameter;
-  GSD embeds the resolved per-agent model directly into each agent's \`.toml\`
-  at install time so \`model_overrides\` from \`.planning/config.json\` and
-  \`~/.gsd/defaults.json\` are honored automatically by Codex's agent router.
-- Resolved \`reasoning_effort="low|medium|high|xhigh"\` (\`xhigh\` is a GSD/Codex tier, not a generic runtime enum) → pass \`reasoning_effort\`
-  to \`spawn_agent\` when the runtime/tool supports it. Omit missing, empty,
-  inherited, or unsupported values; do not invent one-off effort literals in
-  workflow prose.
+- \`Task(model="{resolved_model}")\` → pass \`model="{resolved_model}"\` when the
+  visible \`spawn_agent\` schema advertises \`model\` and the resolved value is explicit.
+  This is how \`model_profile\` tier routing, including \`adaptive\`, reaches the child agent.
+  Omit \`model\` only when the schema does not advertise \`model\`, or when the value is
+  missing, empty, or \`"inherit"\`; omission deliberately inherits the session/static agent
+  configuration. Explicit \`model_overrides\` may also be embedded in agent \`.toml\` files,
+  but ordinary profile-resolved models are not, so a TOML file is not a reason to discard
+  an available inline value.
+- Before each typed spawn, obtain the paired effort for its role with
+  \`gsd_run query resolve-model <subagent_type> --pick effort\` when the workflow has not
+  already exposed it. The resolver's unified \`effort\` field maps to the Codex spawn argument
+  \`reasoning_effort\`; do not look for a resolver field named \`reasoning_effort\`.
+  Pass it when the visible \`spawn_agent\` schema advertises \`reasoning_effort\`. Omit the
+  field when it is not advertised, or when the value is missing, empty, \`"inherit"\`, or
+  unsupported; do not invent one-off effort literals in workflow prose.
 - \`fork_context: false\` by default — GSD agents load their own context via \`<required_reading>\` blocks
-- \`task_name\` — required by the collaboration schema; provide a descriptive name for each spawned task
-- \`fork_turns\` — optional parameter controlling turn-forking depth; coexists with \`fork_context\` (not a replacement)
+- \`task_name\` — when advertised, provide a descriptive name for each spawned task
+- \`fork_turns\` — when advertised, controls turn-forking depth; coexists with \`fork_context\` (not a replacement)
 - \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct \`spawn_agent\` mapping,
   but Codex declares \`dispatch.isolation: orchestrator-worktree\` (#2584). Codex
   \`spawn_agent\` still does not create or bind a git worktree; instead GSD itself
@@ -1702,7 +1882,26 @@ function neutralizeAgentReferences(content, instructionFile) {
     c = c.replace(/Do NOT load full `AGENTS\.md` files[^\n]*/g, '');
     return c;
 }
-function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
+/**
+ * Render one frontmatter `key: value` line whose value came from user config.
+ *
+ * #3706: both `model:` and `variant:` interpolate a value read from
+ * `.planning/config.json` / `~/.gsd/defaults.json`. Raw interpolation lets a value
+ * containing a newline inject additional TOP-LEVEL frontmatter keys into the
+ * generated agent file — proven by execution during the #3705 security review
+ * (`"sonnet\ntools: [\"*\"]\npermission: bypass"` produced two extra keys).
+ *
+ * That sink predates #3706, but this change adds a SECOND write to it, so it is
+ * closed here rather than doubled. Both the decision and the escaping live in
+ * frontmatter.cts so there is exactly one set of YAML scalar rules; a value that
+ * round-trips bare is still emitted bare, so generated files do not churn.
+ */
+function frontmatterScalar(key, value) {
+    return frontmatterModule.agentScalarNeedsDoubleQuoting(value)
+        ? `${key} "${frontmatterModule.escapeDoubleQuotedScalar(value)}"`
+        : `${key} ${value}`;
+}
+function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null, variant = null } = {}) {
     // Replace tool name references in content (applies to all files)
     let convertedContent = content;
     convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
@@ -1827,7 +2026,23 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
         // respected on OpenCode (which uses static agent frontmatter, not inline
         // Task() model parameters). See #2256.
         if (modelOverride) {
-            newLines.push(['model:', modelOverride].join(' '));
+            newLines.push(frontmatterScalar('model:', modelOverride));
+        }
+        // #3706: deliver the RESOLVED reasoning effort to the spawned subagent.
+        // `query resolve-model` reported an effort that never reached OpenCode, so
+        // every subagent ran at whatever opencode.jsonc defaults the model to — for
+        // a custom provider commonly the most expensive setting.
+        //
+        // OpenCode ONLY: `EFFORT_ARGV` declares surfaces for claude/opencode/codex
+        // and NO kilo entry, so the Kilo converter below deliberately does not emit
+        // this. Unlike the model side — where #2794 J8 requires kilo and opencode to
+        // resolve identically — there is no kilo effort surface to render into, and
+        // inventing one would emit a key that runtime never documented.
+        //
+        // Omitted entirely when absent, per #1156's rule for `model: inherit`:
+        // never an empty or sentinel value, let the runtime use its own default.
+        if (variant) {
+            newLines.push(frontmatterScalar('variant:', variant));
         }
     }
     // For commands: add tools object if we had allowed-tools or tools
@@ -1899,7 +2114,9 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
         }
         if (isAgent && inAgentTools) {
             if (trimmed.startsWith('- ')) {
-                agentTools.push(trimmed.substring(2).trim());
+                const tool = decodeToolScalar(trimmed.substring(2));
+                if (tool !== null)
+                    agentTools.push(tool);
                 continue;
             }
             if (trimmed && !trimmed.startsWith('-')) {
@@ -1910,8 +2127,11 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
         if (trimmed.startsWith('tools:')) {
             if (isAgent) {
                 const toolsValue = trimmed.substring(6).trim();
-                if (toolsValue) {
-                    const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
+                // A comment-only value (`tools: # note`) is not real inline content —
+                // fall through to the block-list scan (`inAgentTools`) instead of
+                // decoding the comment as a bogus tool name and dropping the list.
+                if (toolsValue && !toolsValue.startsWith('#')) {
+                    const tools = splitToolScalars(toolsValue).map(decodeToolScalar).filter((tool) => tool !== null);
                     agentTools.push(...tools);
                 }
                 else {
@@ -1973,7 +2193,9 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
             if (trimmed.startsWith('- ')) {
                 const tool = trimmed.substring(2).trim();
                 if (isAgent) {
-                    agentTools.push(tool);
+                    const decoded = decodeToolScalar(tool);
+                    if (decoded !== null)
+                        agentTools.push(decoded);
                 }
                 else {
                     allowedTools.push(tool);
@@ -1999,7 +2221,7 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
         // model emission exactly (#2093 UPGRADE 2 / ADR-1239; Kilo is an OpenCode
         // fork with the same static-frontmatter model constraint). See #2256.
         if (modelOverride) {
-            newLines.push(['model:', modelOverride].join(' '));
+            newLines.push(frontmatterScalar('model:', modelOverride));
         }
         newLines.push(...buildKiloAgentPermissionBlock(agentTools));
     }
@@ -2306,11 +2528,16 @@ function convertClaudeAgentToQwenAgent(content) {
  * Byte-identical for an agent with no `mcp__*` grants (the common case) and
  * for an agent with no frontmatter at all.
  */
+/** Fail-closed: an undecodable scalar is dropped, never kept (ZCode's contract is "never emit mcp__*"). */
+function zcodeKeepsGrant(rawTool) {
+    const decoded = decodeToolScalar(rawTool);
+    return decoded !== null && !decoded.startsWith('mcp__');
+}
 function convertClaudeAgentToZcodeAgent(content) {
-    // Fast path: no MCP grant token anywhere means nothing to strip. (A body
-    // mention alone is not a grant — the line scan below finds no tools-line
-    // change and returns `content` unchanged anyway; this just skips the scan.)
-    if (!content.includes('mcp__'))
+    // A double-quoted YAML scalar may encode the leading "m" in mcp__ as an
+    // escape, so only skip the shared scalar-decoder scan when neither form is
+    // present. The unchanged scan below still preserves byte-identical content.
+    if (!content.includes('mcp__') && !content.includes('\\'))
         return content;
     const lines = content.split('\n');
     if (lines[0] !== '---')
@@ -2330,9 +2557,14 @@ function convertClaudeAgentToZcodeAgent(content) {
     while (i < fmEnd) {
         const line = lines[i];
         const inlineTools = /^tools:[ \t]*(.+)$/.exec(line);
-        if (inlineTools) {
-            const grants = inlineTools[1].split(',').map((tool) => tool.trim()).filter((tool) => tool !== '');
-            const kept = grants.filter((tool) => !tool.startsWith('mcp__'));
+        // A header that is ONLY a comment (`tools: # note`) is not real inline
+        // content — fall through to the block-list scan below instead of
+        // matching here, or a following block list's mcp__* items never get
+        // scanned and leak through unstripped.
+        const commentOnlyHeader = inlineTools !== null && inlineTools[1].trim().startsWith('#');
+        if (inlineTools && !commentOnlyHeader) {
+            const grants = splitToolScalars(inlineTools[1]).map((tool) => tool.trim()).filter((tool) => tool !== '');
+            const kept = grants.filter((tool) => zcodeKeepsGrant(tool));
             if (kept.length === grants.length) {
                 out.push(line); // no mcp__* grants — keep the line byte-identical
             }
@@ -2346,7 +2578,7 @@ function convertClaudeAgentToZcodeAgent(content) {
             i++;
             continue;
         }
-        if (/^tools:[ \t]*$/.test(line)) {
+        if (/^tools:[ \t]*$/.test(line) || commentOnlyHeader) {
             // Block-list form: collect the following `- item` lines.
             const items = [];
             let j = i + 1;
@@ -2356,7 +2588,7 @@ function convertClaudeAgentToZcodeAgent(content) {
             }
             const kept = items.filter((item) => {
                 const name = /^([ \t]*)-[ \t]*(\S.*)$/.exec(item)[2].trim();
-                return !name.startsWith('mcp__');
+                return zcodeKeepsGrant(name);
             });
             if (kept.length !== items.length) {
                 changed = true;
@@ -2692,7 +2924,13 @@ function restoreClaudeGlobalAtRefTilde(content, pathPrefix) {
         return content;
     const tildeEquivalent = '~' + pathPrefix.slice('$HOME'.length);
     const atRefRe = new RegExp(`(?<!["'])@${(0, pattern_cjs_1.escapeRegex)(pathPrefix)}`, 'g');
-    return content.replace(atRefRe, `@${tildeEquivalent}`);
+    // Function replacement, not a string. A string replacement treats `$&` and the
+    // backtick-dollar form in the SUBSTITUTION as special patterns, so a --config-dir
+    // containing either corrupts output: `$HOME/.cl$&ude/` yielded
+    // `@~/.cl@$HOME/.cl$&ude/ude/x`, and the backtick form silently DROPPED text.
+    // Pre-existing, and #3719 adds a THIRD call site to this sink — which is how the
+    // previous two came to share the defect in the first place.
+    return content.replace(atRefRe, () => `@${tildeEquivalent}`);
 }
 /**
  * Apply the per-runtime rewrite table to a single content string.
@@ -2885,6 +3123,20 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, a
             content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
             content = processAttribution(content, attribution);
             break;
+        case 'zcode':
+            // #4002: ZCode is a Claude-Code-shaped host (dot-home `.zcode`, `@~`-ref
+            // expansion, `~/.zcode/...` documented paths) whose commands install with
+            // `converter: null` — this pass is their only chance to receive
+            // runtime-correct paths. Same shape as `claude`, including the tilde
+            // restore: the tilde form is what ZCode expands and what its docs use.
+            // `${_GSD_RUNTIME_ROOT}/.claude/…` matches none of these regexes and
+            // survives as the project-local fallback, exactly as on every sibling.
+            content = content.replace(/~\/\.claude\//g, pathPrefix);
+            content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
+            content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+            content = restoreClaudeGlobalAtRefTilde(content, pathPrefix);
+            content = processAttribution(content, attribution);
+            break;
         default:
             // Unknown runtime — no rewrites (OpenCode/Kilo handled by their own install path).
             break;
@@ -3124,8 +3376,34 @@ function applyAgentPathRewrites(content, runtime, pathPrefix) {
     const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-    content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-    content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
+    // #3719 review (MAJOR): a bare `\b` is satisfied by ANY non-word character,
+    // including '-' — for a --config-dir whose name EXTENDS '.claude' (e.g.
+    // '.claude-work'), this re-matched the '.claude' PREFIX of the emitted
+    // '.claude-work' path and corrupted it to '.claude-work-work'. Guard with
+    // the SAME negative-lookahead convention already used at
+    // copyWithPathReplacement's call site (bin/install.js:7729-7730).
+    content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+    content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+    // #3719: the THIRD emit path that needed this restore. #3133 added it to the
+    // skill/command pipeline (`_applyRuntimeRewrites` case 'claude') and #3544 to
+    // bin/install.js's spec-tree copy; the agents pipeline never got it, so every
+    // `@~/.claude/...` include in a global Claude install shipped as `@$HOME/...`
+    // and resolved to NOTHING (27 of 34 emitted agents, 103 lines).
+    //
+    // Guarded on `claude` for the same reason the sibling call site lives inside
+    // `case 'claude'`: the helper self-guards only on the `$HOME` PREFIX, and every
+    // runtime's global prefix is a `$HOME` form (`$HOME/.cursor/`, ...), so an
+    // unguarded call would rewrite `@`-refs for runtimes whose resolver has no
+    // documented `~` expansion at all.
+    //
+    // Passed the NORMALIZED prefix, not `pathPrefix`. The two word-boundary
+    // replaces above emit the trailing-slash-free form, and the helper's regex is
+    // anchored to the exact prefix string it is handed — so `restore(pathPrefix)`
+    // fixes `@$HOME/.claude/x` and leaves a bare `@$HOME/.claude` broken. The
+    // normalized form is a PREFIX of both, so one call covers both.
+    if (runtime === 'claude') {
+        content = restoreClaudeGlobalAtRefTilde(content, normalizedPathPrefix);
+    }
     return content;
 }
 // ── End rewrite engine ────────────────────────────────────────────────────────
@@ -3243,7 +3521,14 @@ function applyAgentFrontmatterExtensions(content, { runtime, agentName, targetDi
     // effort key, so skipping injection is the whole job.
     if (universalEffort !== 'inherit') {
         const renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime(runtime, universalEffort).value;
-        result = injectEffortFrontmatter(result, renderedEffort);
+        // #3007: `value` is `string | null` — a rejected/unrenderable level (e.g.
+        // 'ultra', or a catalog with no advertised level at or above the request)
+        // renders null. Same posture as the 'inherit' case above: omit the key
+        // entirely rather than writing a literal `effort: null`, so the host
+        // falls back to its own default instead of failing to parse.
+        if (renderedEffort !== null) {
+            result = injectEffortFrontmatter(result, renderedEffort);
+        }
     }
     const disallowedTools = READONLY_AGENT_DISALLOWED_TOOLS[agentName];
     if (disallowedTools)
@@ -3276,6 +3561,7 @@ function processAttribution(content, attribution) {
 }
 module.exports = {
     processAttribution,
+    appendAgentTools,
     // #2103: public accessor for hostBehaviors.agentFileExtension, exported so
     // surface.cts's _syncGsdDir can derive the .agent.md rename from the SAME
     // descriptor read as install-engine.cts (folds a duplicated hardcoded
@@ -3332,6 +3618,8 @@ module.exports = {
     // opencode/kilo command install through the engine instead of the bespoke path).
     convertClaudeToOpencodeFrontmatter,
     convertClaudeToKiloFrontmatter,
+    _decodeToolScalar: decodeToolScalar,
+    _splitToolScalars: splitToolScalars,
     readGsdCommandNames,
     transformContentToHyphen,
     // #1383: version resolver (exported for regression test of the Codex

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -51,7 +51,7 @@ function addCleanupDir(cleanupDirs, stagedDir, rewrittenDir) {
     return sourceDir;
 }
 function createRuntimeArtifactInstallPlan(args) {
-    const { layout, resolvedProfile, homedir, platform, resolveAttribution, deps = {}, } = args;
+    const { layout, resolvedProfile, homedir, platform, resolveAttribution, projectDir, deps = {}, } = args;
     const conversionExports = _require('./runtime-artifact-conversion.cjs');
     const rewriteStagedSkillBodies = deps.rewriteStagedSkillBodies ?? conversionExports.rewriteStagedSkillBodies;
     const rewriteStagedCommandBodies = deps.rewriteStagedCommandBodies ?? conversionExports.rewriteStagedCommandBodies;
@@ -66,11 +66,10 @@ function createRuntimeArtifactInstallPlan(args) {
         platform,
         resolveAttribution,
     };
-    // ADR-1235 §1: build agentCtx once per plan so agents kind entries can apply
-    // the CORRECT pre-converter cross-cutting (path rewrites → attribution → converter
-    // → normalize). This mirrors the exact per-file order in the inline agent loop
-    // in bin/install.js (lines 9330-9415). agentCtx is passed as the second arg
-    // to kind.stage() for agents kind entries with a converter (convertedAgentsKind).
+    // ADR-1235 §1: build the staging context once per plan. Agent kinds apply
+    // the CORRECT pre-converter cross-cutting (path rewrites → attribution →
+    // converter → normalize). This
+    // mirrors the exact per-file order in the former inline agent loop.
     // NO _stampNonClaudeRuntimeDefaults — agents are NOT stamped in the inline loop.
     const os = _require('node:os');
     const { posixNormalize } = _require('./shell-command-projection.cjs');
@@ -88,19 +87,19 @@ function createRuntimeArtifactInstallPlan(args) {
     const attribution = resolveAttribution ? resolveAttribution(layout.runtime) : undefined;
     // #2875 Part 2 (row I1): layout.configDir IS the install root the inline
     // agent loop called `targetDir` — same value, same resolution.
-    const agentCtx = { runtime: layout.runtime, pathPrefix, attribution, targetDir: layout.configDir };
+    const agentCtx = {
+        runtime: layout.runtime,
+        pathPrefix,
+        attribution,
+        targetDir: layout.configDir,
+        projectDir: projectDir ?? layout.configDir,
+    };
     for (const kind of layout.kinds) {
         let stagedDir;
         try {
-            if (kind.kind === 'agents') {
-                // ADR-1235 §1: pass agentCtx so stageAgentsForRuntimeWithConverter applies
-                // the full inline-loop order: pathRewrites → attribution → converter → normalize.
-                // The cross-cutting is now PRE-converter (inside staging), not POST.
-                stagedDir = kind.stage(resolvedProfile, agentCtx);
-            }
-            else {
-                stagedDir = kind.stage(resolvedProfile);
-            }
+            // Agent kinds use the context for their pre-converter cross-cutting
+            // sequence; other kinds ignore it.
+            stagedDir = kind.stage(resolvedProfile, agentCtx);
         }
         catch (err) {
             return { ok: false, kind: 'stage_failed', message: errorMessage(err), cleanupDirs, failedKind: kind.kind };
@@ -115,7 +114,7 @@ function createRuntimeArtifactInstallPlan(args) {
                 const rewrittenDir = rewriteStagedSkillBodies(stagedDir, rewriteOpts);
                 sourceDir = addCleanupDir(cleanupDirs, stagedDir, rewrittenDir);
             }
-            // agents kind: cross-cutting already applied INSIDE kind.stage() via agentCtx.
+            // Agent kinds: cross-cutting already applied INSIDE kind.stage() via agentCtx.
             // No POST-step needed. sourceDir stays as stagedDir.
         }
         catch (err) {