@opengsd/gsd-core 1.16.0 → 1.18.0

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

@@ -295,6 +295,61 @@ function buildKiloAgentPermissionBlock(claudeTools) {
     }
     return lines;
 }
+// OpenCode agent tool restrictions (#5338, ADR-5331 D4). Claude's `tools:` allowlist and
+// `disallowedTools:` denylist become OpenCode `permission:` entries. The V1 `permission` form is the one
+// written because OpenCode 2.x translates it automatically ("legacy agent frontmatter … is translated"),
+// so one form serves both generations — verified: a `permission: {edit: deny, bash: deny}` agent drops the
+// edit/write/shell tools from the model's tool list on 1.18.29 and 2.0.27. Only denials are emitted: an
+// allowed tool keeps the user's own configured default instead of being forced to `allow`, and MCP tool
+// entries are not restricted.
+const claudeToOpencodePermission = {
+    Read: 'read',
+    Write: 'edit',
+    Edit: 'edit',
+    MultiEdit: 'edit',
+    NotebookEdit: 'edit',
+    Bash: 'bash',
+    Grep: 'grep',
+    Glob: 'glob',
+    WebFetch: 'webfetch',
+    WebSearch: 'websearch',
+    Task: 'task',
+    Agent: 'task',
+    Skill: 'skill',
+    SlashCommand: 'skill',
+    TodoWrite: 'todowrite',
+};
+const opencodeAgentPermissionOrder = ['read', 'edit', 'bash', 'grep', 'glob', 'webfetch', 'websearch', 'task', 'skill', 'todowrite'];
+/**
+ * `permission:` frontmatter lines for an OpenCode agent, or `[]` when the agent declares no tool
+ * restriction (an agent with neither `tools` nor `disallowedTools` inherits everything, as in Claude).
+ */
+function buildOpencodeAgentPermissionBlock(allowedTools, disallowedTools) {
+    const allowed = new Set();
+    for (const tool of allowedTools) {
+        const mapped = claudeToOpencodePermission[tool];
+        if (mapped)
+            allowed.add(mapped);
+    }
+    const denied = new Set();
+    if (allowedTools.length > 0) {
+        for (const permission of opencodeAgentPermissionOrder) {
+            if (!allowed.has(permission))
+                denied.add(permission);
+        }
+    }
+    for (const tool of disallowedTools) {
+        const mapped = claudeToOpencodePermission[tool];
+        if (mapped)
+            denied.add(mapped);
+    }
+    const lines = [];
+    for (const permission of opencodeAgentPermissionOrder) {
+        if (denied.has(permission))
+            lines.push(`  ${permission}: deny`);
+    }
+    return lines.length > 0 ? ['permission:', ...lines] : [];
+}
 function replaceRelativePathReference(content, fromPath, toPath) {
     const escapedPath = (0, pattern_cjs_1.escapeRegex)(fromPath);
     return content.replace(new RegExp(`(^|[^A-Za-z0-9_./-])${escapedPath}`, 'g'), (_, prefix) => `${prefix}${toPath}`);
@@ -1953,7 +2008,11 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
     const newLines = [];
     let inAllowedTools = false;
     let inSkippedArray = false;
+    let inAgentTools = false;
+    let inDisallowedTools = false;
     const allowedTools = [];
+    const agentTools = [];
+    const agentDisallowed = [];
     for (const line of lines) {
         const trimmed = line.trim();
         // For agents: skip commented-out lines (e.g. hooks blocks)
@@ -1965,11 +2024,31 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
             inAllowedTools = true;
             continue;
         }
+        // Agents: collect the `tools:` allowlist and `disallowedTools:` denylist (block-list continuation
+        // lines) so they can be rendered as `permission:` entries below.
+        if (isAgent && (inAgentTools || inDisallowedTools)) {
+            if (trimmed.startsWith('- ')) {
+                const tool = decodeToolScalar(trimmed.substring(2));
+                if (tool !== null)
+                    (inAgentTools ? agentTools : agentDisallowed).push(tool);
+                continue;
+            }
+            if (trimmed && !trimmed.startsWith('-')) {
+                inAgentTools = false;
+                inDisallowedTools = false;
+            }
+        }
         // Detect inline tools: field (comma-separated string)
         if (trimmed.startsWith('tools:')) {
             if (isAgent) {
-                // Agents: strip tools entirely (not supported in OpenCode agent frontmatter)
-                inSkippedArray = true;
+                const toolsValue = trimmed.substring(6).trim();
+                // A comment-only value (`tools: # note`) is not inline content: read the block list instead.
+                if (toolsValue && !toolsValue.startsWith('#')) {
+                    agentTools.push(...splitToolScalars(toolsValue).map(decodeToolScalar).filter((tool) => tool !== null));
+                }
+                else {
+                    inAgentTools = true;
+                }
                 continue;
             }
             const toolsValue = trimmed.substring(6).trim();
@@ -1980,8 +2059,18 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
             }
             continue;
         }
-        // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:, disallowedTools:
-        if (isAgent && /^(skills|color|memory|maxTurns|permissionMode|disallowedTools):/.test(trimmed)) {
+        if (isAgent && trimmed.startsWith('disallowedTools:')) {
+            const value = trimmed.substring(16).trim();
+            if (value && !value.startsWith('#')) {
+                agentDisallowed.push(...splitToolScalars(value).map(decodeToolScalar).filter((tool) => tool !== null));
+            }
+            else {
+                inDisallowedTools = true;
+            }
+            continue;
+        }
+        // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:
+        if (isAgent && /^(skills|color|memory|maxTurns|permissionMode):/.test(trimmed)) {
             inSkippedArray = true;
             continue;
         }
@@ -2065,6 +2154,7 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
         if (variant) {
             newLines.push(frontmatterScalar('variant:', variant));
         }
+        newLines.push(...buildOpencodeAgentPermissionBlock(agentTools, agentDisallowed));
     }
     // For commands: add tools object if we had allowed-tools or tools
     if (!isAgent && allowedTools.length > 0) {
@@ -2833,8 +2923,13 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     // See DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT in CONTEXT.md.
     const posixTarget = (0, shell_command_projection_cjs_1.posixNormalize)(String(resolvedTarget));
     const posixHome = homeDir ? (0, shell_command_projection_cjs_1.posixNormalize)(String(homeDir)) : homeDir;
-    if (isGlobal && posixTarget.startsWith(posixHome) && !isOpencode) {
-        return '$HOME' + posixTarget.slice(posixHome.length) + '/';
+    // #5123: `startsWith` alone treats a SIBLING directory whose name begins with
+    // the home path (`/home/u2/cfg` under `/home/u`) as under home and yields the
+    // broken `$HOMEu2/cfg/`. Require a path boundary.
+    const underHome = typeof posixHome === 'string' && posixHome.length > 0
+        && (posixTarget === posixHome || posixTarget.startsWith(posixHome.endsWith('/') ? posixHome : `${posixHome}/`));
+    if (isGlobal && underHome && !isOpencode) {
+        return '$HOME' + posixTarget.slice(posixHome.length).replace(/^(?!\/)(?=.)/, '/') + '/';
     }
     if (!isGlobal && projectRelative) {
         // An explicit local config dir need not be the descriptor's conventional
@@ -2848,6 +2943,44 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     }
     return `${posixTarget}/`;
 }
+/**
+ * #5123: retarget an installed artifact's `@` includes to the REAL install root.
+ * Driven by the runtime descriptor's hostBehaviors, never by a runtime name:
+ *
+ * - `defaultHomeIncludeRoot` (Copilot, Antigravity): their converters hard-code
+ *   the DEFAULT home into includes, so with `--config-dir` the payload lives
+ *   elsewhere and `@~/<root>/gsd-core/…` points at nothing. `@~/<root>/` and
+ *   `@$HOME/<root>/` become `@<pathPrefix>`. A default install (pathPrefix is
+ *   already `$HOME/<root>/`) is returned unchanged, so it stays byte-identical.
+ * - `retargetsGsdCoreProsePath` (Kimi): Kimi has no `@` include, so its prompt
+ *   converter turns `~/.claude/gsd-core` into the prose "GSD core", leaving
+ *   `@GSD core/x.md` pointing nowhere. A `GSD core/<path>` reference followed
+ *   by a path segment becomes the real `<pathPrefix>gsd-core/<path>`, with the
+ *   unsupported `@` dropped. Bare prose "GSD core" is not followed by `/`.
+ *
+ * `pathPrefix` is the install root as computePathPrefix derives it
+ * (`$HOME/…/` under HOME, otherwise absolute), with a trailing slash. Pure and
+ * idempotent: a second pass finds none of the literals it rewrites.
+ */
+function retargetInstalledIncludes(content, behaviors, pathPrefix) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    if (typeof pathPrefix !== 'string' || !pathPrefix.endsWith('/'))
+        return content;
+    if (!behaviors)
+        return content;
+    let result = content;
+    if (behaviors.retargetsGsdCoreProsePath === true) {
+        result = result.replace(/@?GSD core\/(?=[a-z])/g, `${pathPrefix}gsd-core/`);
+    }
+    const home = behaviors.defaultHomeIncludeRoot;
+    if (typeof home === 'string' && home.length > 0 && pathPrefix !== `$HOME/${home}/`) {
+        result = result
+            .split(`@~/${home}/`).join(`@${pathPrefix}`)
+            .split(`@$HOME/${home}/`).join(`@${pathPrefix}`);
+    }
+    return result;
+}
 /** Return a safe project-relative prefix for a resolved install target. */
 function projectRelativePrefixFromProjectRoot(projectRoot, resolvedTarget) {
     if (typeof projectRoot !== 'string' || typeof resolvedTarget !== 'string')
@@ -3816,6 +3949,7 @@ module.exports = {
     convertClaudeToOpencodeFrontmatter,
     convertClaudeToKiloFrontmatter,
     _decodeToolScalar: decodeToolScalar,
+    _buildOpencodeAgentPermissionBlock: buildOpencodeAgentPermissionBlock,
     _splitToolScalars: splitToolScalars,
     readGsdCommandNames,
     transformContentToHyphen,
@@ -3883,4 +4017,6 @@ module.exports = {
     _negotiatedDispatchIsolation,
     // #1521: canonical non-Claude runtime list for test files and tooling
     NON_CLAUDE_RUNTIMES,
+    // #5123: post-install include retarget (config-dir aware; Kimi prose path)
+    retargetInstalledIncludes,
 };

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -40,6 +40,7 @@ exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
 exports.detectAntigravityDirAmbiguity = detectAntigravityDirAmbiguity;
 exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
+exports.resolveGsdHome = resolveGsdHome;
 exports.resolveKimiHooksTomlDir = resolveKimiHooksTomlDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
 exports.resolveSkillsBaseFromDescriptor = resolveSkillsBaseFromDescriptor;
@@ -403,6 +404,23 @@ exports.NON_REGISTRY_CONFIG_HOME_DESCRIPTORS = [
  * through resolveConfigHomeFromDescriptor and have no `kind`/`name` shape.
  */
 exports.GSD_LOCATION_ENV_KEYS = ['GSD_HOME', 'GSD_AGENTS_DIR'];
+/**
+ * #5017: the ONE rule for the root of the GSD-owned store (`$GSD_HOME/.gsd/`:
+ * defaults.json, consent.json, capability overlays) — `GSD_HOME` when set and
+ * non-blank, otherwise the home directory. The config loader, the install-time
+ * resolvers, the installer's defaults writer and capability staging all call
+ * this, so one configuration gives one answer at install time, at dispatch time
+ * and in the staged capabilities. The hooks (cold-tree, no lib import) and the
+ * settings / new-project workflows (shell) carry the same rule inline; a test
+ * pins each of them to it.
+ *
+ * `fallbackHome` lets a caller that already holds an injected home directory
+ * (the install-time resolvers' test seam) keep using it when GSD_HOME is unset.
+ * A blank `GSD_HOME` is "unset": `''` must never become a relative store path.
+ */
+function resolveGsdHome(fallbackHome = node_os_1.default.homedir()) {
+    return process.env['GSD_HOME'] || fallbackHome;
+}
 /**
  * Resolve the directory holding the Kimi product's OWN native config.toml —
  * the file that product itself reads for providers/models/hooks/etc, and the

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -992,7 +992,16 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
     const scriptQuoted = JSON.stringify(targetAbs);
     const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
     const hookCommand = JSON.stringify(shellCmdProjection.posixNormalize(cmdPath));
-    const runnerQuoted = JSON.stringify(interpreter);
+    // #4838: node is resolved when the hook fires. The install-time path dies when a
+    // version manager (WinGet) removes the versioned directory on upgrade, and a
+    // shim that only knew that path failed silently until the installer re-ran.
+    // Order: explicit GSD_NODE_PATH; the install-time path while it still exists
+    // (keeps the #3662 minimal-PATH guarantee); node.exe on PATH. `where $PATH:`
+    // searches PATH only, never the current directory, so repo content cannot
+    // become the runner. `%` is doubled so cmd.exe cannot expand a variable out
+    // of an install path.
+    const bakedBat = JSON.stringify(interpreter).slice(1, -1).replace(/%/g, '%%');
+    const scriptBat = scriptQuoted.replace(/%/g, '%%');
     return {
         invocation: { interpreter, target: scriptAbsPath },
         cmdPath,
@@ -1000,7 +1009,16 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
         eol: { cmd: '\r\n' },
         passthroughArgs: true,
         render: {
-            cmd: () => `@ECHO OFF\r\n@SETLOCAL\r\n@${runnerQuoted} ${scriptQuoted} %*\r\n`,
+            cmd: () => [
+                '@ECHO OFF',
+                '@SETLOCAL',
+                '@SET "GSD_NODE="',
+                '@IF DEFINED GSD_NODE_PATH IF EXIST "%GSD_NODE_PATH%" SET "GSD_NODE=%GSD_NODE_PATH%"',
+                `@IF NOT DEFINED GSD_NODE IF EXIST "${bakedBat}" SET "GSD_NODE=${bakedBat}"`,
+                '@IF NOT DEFINED GSD_NODE FOR /F "delims=" %%N IN (\'where $PATH:node.exe 2^>NUL\') DO @IF NOT DEFINED GSD_NODE SET "GSD_NODE=%%N"',
+                `@"%GSD_NODE%" ${scriptBat} %*`,
+                '',
+            ].join('\r\n'),
         },
     };
 }
@@ -2279,6 +2297,35 @@ function pushHookGroup(entries, matcher, command, timeout) {
         hook['timeout'] = timeout;
     entries.push(matcher === undefined ? { hooks: [hook] } : { matcher, hooks: [hook] });
 }
+/** #4840: the hook that reads the statusline's metrics bridge file. */
+const CONTEXT_MONITOR_HOOK = 'gsd-context-monitor.js';
+/**
+ * #4840: remove GSD-managed registrations of `stem` from one event's groups,
+ * leaving user-authored hooks (even in the same group) untouched. Returns
+ * whether anything was removed. A group left with no hooks is dropped.
+ */
+function stripManagedHookRegistrations(entries, stem) {
+    let removed = false;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!entry || !Array.isArray(entry.hooks))
+            continue;
+        const kept = entry.hooks.filter((h) => {
+            const managed = referencesHook(h, stem)
+                && isManagedHookCommand(h.command, { surface: 'settings-json', includeLegacyAliases: true });
+            if (managed)
+                removed = true;
+            return !managed;
+        });
+        if (kept.length === entry.hooks.length)
+            continue;
+        if (kept.length === 0)
+            entries.splice(i, 1);
+        else
+            entry.hooks = kept;
+    }
+    return removed;
+}
 function applySettingsJsonHookTables(settings, opts, tables) {
     const { runtime, postToolEvent, hookEvents, extendedHookEvents, hooksSurface, targetDir, hookOpts } = opts;
     // ADR-857 phase 5f-3: extended hook events are driven by the registry
@@ -2326,6 +2373,12 @@ function applySettingsJsonHookTables(settings, opts, tables) {
             settings.hooks[key] = [];
         }
         const entries = settings.hooks[key];
+        if (row.file === CONTEXT_MONITOR_HOOK && opts.contextWarnings === false) {
+            if (stripManagedHookRegistrations(entries, hookStem(row.file))) {
+                console.log(`  ${green}✓${reset} Removed stale context monitor hook (${_capabilityTitle(runtime)} has no context metrics writer, #4840)`);
+            }
+            continue;
+        }
         const command = resolveRowCommand(row, opts);
         if ('build' in row.command && row.command.build === 'sh')
             shellCommands[row.file] = command;
@@ -2468,7 +2521,8 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: kimiBlockingGuardTimeout('gsd-workflow-guard.js') },
         { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: kimiBlockingGuardTimeout('gsd-validate-commit.sh') },
         // PostToolUse
-        { event: 'PostToolUse', command: cmd('gsd-context-monitor.js'), timeout: 10 },
+        // #4840: no metrics writer on kimi, so the warning registration is skipped (a block from an earlier install is replaced wholesale).
+        { event: 'PostToolUse', command: opts.contextWarnings === false ? null : cmd('gsd-context-monitor.js'), timeout: 10 },
         { event: 'PostToolUse', command: cmd('gsd-phase-boundary.sh'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PostToolUse', command: cmd('gsd-read-injection-scanner.js'), matcher: 'ReadFile', timeout: 5 },
         { event: 'PostToolUse', command: cmd('gsd-graphify-update.sh'), matcher: 'Shell', timeout: 5 },
@@ -2541,6 +2595,7 @@ function stripKimiHooksTomlBlock(content) {
 function writeKimiHooksToml(configPath, targetDir, opts) {
     const configuredEntrypoints = [];
     const trackedOpts = {
+        contextWarnings: opts.contextWarnings,
         hookOpts: {
             ...opts.hookOpts,
             configPath,

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -36,6 +36,7 @@ exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
 exports.resolveActiveRuntime = resolveActiveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
+exports.runtimeCommand = runtimeCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
@@ -227,3 +228,15 @@ function resolveActiveRuntime(config, env = process.env) {
 function formatGsdSlashFor(projectDir, commandName) {
     return formatGsdSlash(commandName, resolveRuntime(projectDir));
 }
+/**
+ * #4859: the command as the project's runtime registers it, typed as a string —
+ * for runtime code that builds user-facing guidance. String literals in compiled
+ * runtime code are printed verbatim (the install-time conversion only rewrites
+ * markdown artifact bodies), so a hard-coded `/gsd:<cmd>` names a command no
+ * install route registers. Route every such reference through here:
+ * `runtimeCommand(cwd, 'plan-phase 3 --research')` → `/gsd-plan-phase 3 --research`
+ * (`$gsd-plan-phase …` on Codex). `commandName` is the bare name plus any argument tail.
+ */
+function runtimeCommand(projectDir, commandName) {
+    return String(formatGsdSlashFor(projectDir, commandName));
+}

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -1131,6 +1131,8 @@ function _normalizeMd(content) {
 }
 function normalizeContent(filePath, content, opts = {}) {
     const encoding = opts.encoding ?? 'utf-8';
+    if (opts.verbatim === true)
+        return { content: content ?? '', encoding };
     const isMd = node_path_1.default.extname(filePath).toLowerCase() === '.md';
     let normalized;
     if (isMd) {