@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/install-engine.cjs

@@ -23,6 +23,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
+const security_cjs_1 = require("./security.cjs");
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
@@ -55,6 +56,148 @@ const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
 const { getDirName } = runtimeNamePolicy;
+function withInstallerPackageSource(configDir, fn) {
+    // Reuse the existing compatibility-marker contract through the existing fs
+    // seam. The marker exists only in this synchronous call tree: no disk state,
+    // layout export, stage argument, or caller-settable authority flag is added.
+    const markerPath = node_path_1.default.resolve(configDir, '.gsd-source');
+    const packageCommandsRoot = runtimeArtifactLayout.findInstallSourceRoot();
+    const markerBytes = Buffer.from(packageCommandsRoot + '\n');
+    const base = installFs();
+    const overlay = {
+        ...base,
+        existsSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath || base.existsSync(candidate),
+        lstatSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath
+            ? { isFile: () => true, isDirectory: () => false, isSymbolicLink: () => false }
+            : base.lstatSync(candidate),
+        readFileSync: ((candidate, encoding) => {
+            if (node_path_1.default.resolve(candidate) !== markerPath) {
+                return encoding ? base.readFileSync(candidate, encoding) : base.readFileSync(candidate);
+            }
+            return encoding ? markerBytes.toString(encoding) : Buffer.from(markerBytes);
+        }),
+    };
+    return withInstallFs(overlay, fn);
+}
+function isRuntimeSurfaceSourceUnavailable(message) {
+    return message.startsWith('Runtime Surface source is unavailable or incomplete for ') &&
+        message.endsWith('install or upgrade gsd-core before materializing this surface.');
+}
+function assertCorpusTreeHasNoSymlinks(root) {
+    if (!installFs().existsSync(root))
+        return;
+    const stat = installFs().lstatSync(root);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Runtime Surface corpus path is a symlink: ${root}`);
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const name of installFs().readdirSync(root)) {
+        assertCorpusTreeHasNoSymlinks(node_path_1.default.join(root, name));
+    }
+}
+function previousOwnedCorpusFiles(configDir, prefix) {
+    try {
+        const files = installerMigrations.readInstallManifest(configDir).files;
+        return Object.keys(files)
+            .filter((entry) => entry.startsWith(prefix))
+            .map((entry) => entry.slice(prefix.length))
+            .filter((entry) => entry !== '' && !node_path_1.default.posix.isAbsolute(entry) && !entry.split('/').some((part) => part === '' || part === '.' || part === '..'));
+    }
+    catch {
+        // An absent or unreadable prior manifest provides no ownership evidence.
+        // Preserve existing entries rather than guessing that they are stale.
+        return [];
+    }
+}
+function pruneEmptyCorpusParents(start, stop) {
+    let current = node_path_1.default.dirname(start);
+    while (current !== stop && current.startsWith(stop + node_path_1.default.sep)) { // allow-handrolled-containment: ancestor-walk loop condition, not a containment gate
+        if (installFs().readdirSync(current).length > 0)
+            return;
+        installFs().rmdirSync(current);
+        current = node_path_1.default.dirname(current);
+    }
+}
+function syncRuntimeSurfaceCorpus(source, destination, configDir, manifestPrefix) {
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), destination, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+        throw new Error(`syncRuntimeSurfaceCorpus: destination "${destination}" contains a symlink the install root "${configDir}" does not trust — refusing to write.`);
+    }
+    assertCorpusTreeHasNoSymlinks(destination);
+    // Remove only paths the previous manifest proves GSD owned and which the
+    // executing package no longer ships. Unknown neighbouring files survive.
+    for (const relative of previousOwnedCorpusFiles(configDir, manifestPrefix)) {
+        const sourceEntry = node_path_1.default.join(source, ...relative.split('/'));
+        let sourceIsFile = false;
+        try {
+            sourceIsFile = installFs().lstatSync(sourceEntry).isFile();
+        }
+        catch {
+            sourceIsFile = false;
+        }
+        if (sourceIsFile)
+            continue;
+        const target = node_path_1.default.join(destination, ...relative.split('/'));
+        if (!installFs().existsSync(target))
+            continue;
+        const targetStat = installFs().lstatSync(target);
+        if (!targetStat.isFile()) {
+            throw new Error(`Runtime Surface corpus ownership conflict at ${target}`);
+        }
+        installFs().rmSync(target, { force: true });
+        pruneEmptyCorpusParents(target, destination);
+    }
+    installFs().mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
+    installFs().cpSync(source, destination, { recursive: true });
+}
+/**
+ * Provision the raw, installation-owned input needed to re-materialize a
+ * global Runtime Surface after the executing package tree disappears.
+ *
+ * The corpus deliberately lives below the already-installed `gsd-core/`
+ * tree and is accepted only after its manifest ownership and hashes verify.
+ * The compatibility marker does not replace that installed-corpus authority.
+ */
+function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
+    const required = new Set();
+    if ((0, install_scope_cjs_1.isGlobalScope)(scope)) {
+        for (const kind of layout.kinds) {
+            if (kind.kind === 'commands' || kind.kind === 'skills')
+                required.add('commands');
+            if (kind.kind === 'agents' || kind.kind === 'kimi-agents')
+                required.add('agents');
+        }
+    }
+    if (required.size === 0)
+        return;
+    const corpusRoot = node_path_1.default.join(configDir, 'gsd-core');
+    if (required.has('commands')) {
+        const source = runtimeArtifactLayout.findInstallSourceRoot();
+        const destination = node_path_1.default.join(corpusRoot, 'commands', 'gsd');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/commands/gsd/');
+    }
+    if (required.has('agents')) {
+        const source = node_path_1.default.join(executingPackageRoot(), 'agents');
+        const destination = node_path_1.default.join(corpusRoot, 'agents');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/agents/');
+    }
+    const markerFile = _hostBehaviors(layout.runtime).sourceMarkerFile;
+    if (typeof markerFile === 'string' && markerFile !== '' && required.has('commands')) {
+        try {
+            const markerPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, markerFile);
+            if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), markerPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+                throw new Error(`compatibility marker "${markerPath}" contains an untrusted symlink`);
+            }
+            installFs().writeFileSync(markerPath, node_path_1.default.join(corpusRoot, 'commands', 'gsd') + '\n', 'utf8');
+        }
+        catch {
+            // The existing installer marker writer owns the user-facing warning and
+            // keeps marker failure non-fatal. The installed corpus remains usable
+            // without the compatibility marker.
+        }
+    }
+}
+function executingPackageRoot() { return node_path_1.default.dirname(node_path_1.default.dirname(runtimeArtifactLayout.findInstallSourceRoot())); }
 // ---------------------------------------------------------------------------
 // USER_OWNED_ARTIFACTS
 // ---------------------------------------------------------------------------
@@ -205,8 +348,11 @@ function hasExistingSymlinkBetween(root, fullPath, options = {}) {
     const resolvedFullPath = node_path_1.default.resolve(fullPath);
     // (a) Path-traversal refusal — ALWAYS enforced, even with opt-in. An untrusted
     // destSubpath string that escapes the install root via '..' is rejected
-    // regardless of user opt-in state (ADR-1239 Phase B threat (a)).
-    if (resolvedFullPath !== resolvedRoot && !resolvedFullPath.startsWith(resolvedRoot + node_path_1.default.sep)) {
+    // regardless of user opt-in state (ADR-1239 Phase B threat (a)). Lexical
+    // (ADR-4650 decision 6): this function's whole purpose is to DETECT
+    // symlinks between root and target, so resolving them here would erase what
+    // it measures.
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedFullPath, resolvedRoot) === null) {
         return true;
     }
     // #2393 (security-review finding): realpathSync fully resolves all symlink
@@ -977,6 +1123,7 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, capabilityRegistry, deps = {}) {
     return withInstallFs(deps.fs, () => {
+        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
         // A removed descriptor kind is no longer visited by the layout loop, so it
         // cannot prune its own previous output. Clean manifest-proven retired files
         // before materializing the current layout (#2644).
@@ -986,6 +1133,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // generic layout-driven loop below, mirroring the bespoke install path that
         // previously lived inline in bin/install.js.
         const behaviors = _hostBehaviors(runtime);
+        const projectDir = scope === 'global' ? process.cwd() : configDir;
         if (behaviors.combinedFamilyInstall) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
             // _runLegacyInstallMigrations below entirely (early return), so their
@@ -994,17 +1142,24 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             // #2874 design row 2: this early return must ALSO return an executed
             // plan — installOpencodeFamilyArtifacts reports what it wrote, so a
             // whole runtime family returning undefined is no longer a hole.
-            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry);
+            // An injected filesystem supplies its own hermetic corpus fixture. The
+            // real installer is the authority that refreshes package bytes into the
+            // durable installed corpus; attempting that cross-filesystem copy through
+            // an in-memory destination adapter would read from the wrong filesystem.
+            if (!deps.fs)
+                provisionRuntimeSurfaceCorpus(layout, configDir, scope);
+            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry, deps.packageRoot, projectDir);
         }
         // Legacy cleanup before layout-driven writes
         _runLegacyInstallMigrations(runtime, configDir, scope);
-        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
+        if (!deps.fs)
+            provisionRuntimeSurfaceCorpus(layout, configDir, scope);
         // #3712: a global `home` override escapes the sandboxed configDir. Refuse to
         // execute when a test run would land that escape in the developer's real home.
         testHomeGuard.assertTestHomeSandboxed('installRuntimeArtifacts', runtime, layout?.kinds, {
             os: deps.os, env: deps.env,
         });
-        const planResult = runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
+        const createPlan = () => runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
             // `Layout` is structurally identical across the layout/install-plan .cjs
             // modules but nominally distinct to tsc (untyped .cjs boundary) — bridge it.
             layout: layout,
@@ -1012,7 +1167,16 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             homedir: () => node_os_1.default.homedir(),
             platform: process.platform,
             resolveAttribution,
+            projectDir,
         });
+        let planResult = createPlan();
+        if (scope === 'global' &&
+            !planResult.ok &&
+            planResult.kind === 'stage_failed' &&
+            planResult.cleanupDirs.length === 0 &&
+            isRuntimeSurfaceSourceUnavailable(planResult.message)) {
+            planResult = withInstallerPackageSource(configDir, createPlan);
+        }
         const cleanupDirs = planResult.ok ? planResult.plan.cleanupDirs : planResult.cleanupDirs;
         // #2874 row 1/4/5: per-kind executed-plan entries, appended only as the
         // loop below actually finishes writing each kind — a kind that throws
@@ -1176,8 +1340,10 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
         let nativePluginInstalled = false;
         if (behaviors.nativePlugin) {
-            const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-            const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+            // Native plugin sources live only in the executing package, never in the
+            // durable Runtime Surface corpus. Do not derive this package root from a
+            // config-scoped provider that may now correctly resolve installed input.
+            const src = deps.packageRoot ?? executingPackageRoot();
             _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
             nativePluginInstalled = true;
         }
@@ -1330,6 +1496,15 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
             content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
             content = processAttribution(content, resolveAttribution(runtime));
             const skillDir = node_path_1.default.join(dest, skillName);
+            // isPathConfined is lexical and cannot see a symlink. mkdirSync({recursive:true})
+            // does NOT throw when skillDir already exists as a symlink to a directory, so a
+            // pre-planted link would redirect the SKILL.md write outside `dest`. Refuse to
+            // write through a link (epic #4636; mirrors retired-artifact-cleanup.cts:77).
+            try {
+                if (installFs().lstatSync(skillDir).isSymbolicLink())
+                    continue;
+            }
+            catch { /* ENOENT: not created yet — the normal case */ }
             installFs().mkdirSync(skillDir, { recursive: true });
             installFs().writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
             // #2322 HIGH-3 parity: persist the capability-owned marker so a later
@@ -1388,12 +1563,13 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
  * @param capabilityRegistry - #2362: optional composed capability registry, threaded
  *   straight through to resolveRuntimeArtifactLayout (unused by the agents kind today,
  *   but kept for signature parity with the skills/commands siblings on this call tree)
+ * @param projectDir - project/config discovery root, distinct from the artifact destination
  * @returns `{ sourceDir, destDir }` describing what was written, or `null` when the
  *   runtime's layout declares no `agents` kind.
  */
-function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry) {
+function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry, projectDir) {
     const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope, capabilityRegistry);
-    const agentsKindEntry = layout.kinds.find((k) => k.kind === 'agents');
+    const agentsKindEntry = layout.kinds.find((kind) => kind.kind === 'agents');
     if (!agentsKindEntry)
         return null;
     // #3712: this writer selects `agentsKindEntry.home` over targetDir below and then
@@ -1408,8 +1584,16 @@ function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile,
     // for the generic layout-driven loop (runtime-artifact-install-plan.cts) —
     // targetDir IS the install root the inline agent loop called `targetDir`.
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
-    const agentCtx = { runtime, pathPrefix, attribution, targetDir };
-    const stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    const agentCtx = { runtime, pathPrefix, attribution, targetDir, projectDir: projectDir ?? targetDir };
+    let stagedDir;
+    try {
+        stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    }
+    catch (err) {
+        if (scope !== 'global' || !isRuntimeSurfaceSourceUnavailable(err.message))
+            throw err;
+        stagedDir = withInstallerPackageSource(targetDir, () => agentsKindEntry.stage(resolvedProfile, agentCtx));
+    }
     const stagedAgentFiles = installFs().existsSync(stagedDir)
         ? installFs().readdirSync(stagedDir).filter((f) => f.endsWith('.md'))
         : [];
@@ -1670,12 +1854,13 @@ function _migrateLegacyOpencodeCommandDir(runtime, configDir, behaviors) {
  *   installOpencodeFamilySkills so an installed third-party capability skill
  *   materializes for this combined-family (OpenCode/Kilo) install path too.
  *   Absent -> no third-party skills staged (fail closed).
+ * @param projectDir - project/config discovery root, distinct from configDir for global installs
  * @returns #2874 design row 2: an executed-plan value, same top-level shape
  *   (`runtime`/`scope`/`kinds`/`cleanup`/`postSteps`) as the generic
  *   `installRuntimeArtifacts` branch — this was the one early return a
  *   `void`-shaped hole survived unnoticed in.
  */
-function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry) {
+function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry, packageRoot, projectDir) {
     // #2870: `scope` keeps its exported required `string` signature (no
     // signature change). It is always the `installRuntimeArtifacts`-forwarded
     // 'global' | 'local' literal produced by bin/install.js's scope-resolution
@@ -1688,7 +1873,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // into stageSkillsForProfile/stageSkillsForRuntimeAsSkills. The repo/package
     // root (needed below for the native plugin source) is two levels up.
     const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-    const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+    const src = packageRoot ?? executingPackageRoot();
     const rawCommandsDir = installProfiles.stageSkillsForProfile(commandsGsdDir, resolvedProfile);
     const pathPrefix = runtimeArtifactConversion._computePathPrefix({
         isGlobal,
@@ -1711,7 +1896,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // generic layout-driven loop uses (see installAgentsKindStandalone's own
     // doc). A `null` result means this runtime's layout declares no `agents`
     // kind — nothing written, nothing reported (no #1879-F15 inert claim).
-    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry);
+    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry, projectDir);
     _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
     // #2874 design row 2: report what this combined-family install wrote,
     // mirroring the generic branch's top-level shape. `cleanup` is `[]` — this

package/gsd-core/bin/lib/install-model-override-resolver.cjs

@@ -114,6 +114,50 @@ function readGsdEffectiveModelOverrides(targetDir = null, options = {}) {
     // Per-project wins on conflict; preserve non-conflicting global keys.
     return { ...(global || {}), ...(projectOverrides || {}) };
 }
+function readGsdAgentTools(config) {
+    const raw = config?.agent_tools;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const result = {};
+    for (const [selector, value] of Object.entries(raw)) {
+        // An explicitly present selector always has a verdict. Invalid values are
+        // empty so a project config cannot accidentally restore a global grant.
+        result[selector] = Array.isArray(value)
+            ? value.filter((entry) => typeof entry === 'string')
+                .map((entry) => entry.trim())
+                .filter((entry) => entry.length > 0
+                && !entry.endsWith(':')
+                && !/[\s\u0000-\u001F\u007F-\u009F,#"'\u2028\u2029]/.test(entry))
+            : [];
+    }
+    return result;
+}
+/**
+ * Resolve valid install-time `agent_tools` grants from global defaults and
+ * the nearest project config. Project selectors replace only matching global
+ * selectors; malformed whole files remain harmless absence like the existing
+ * model override resolver.
+ */
+function readGsdEffectiveAgentTools(targetDir = null, options = {}) {
+    const home = options.homedir ? options.homedir() : node_os_1.default.homedir();
+    const globalConfig = _readGsdConfigFile(node_path_1.default.join(home, '.gsd', 'defaults.json'), 'global defaults');
+    let projectConfig = null;
+    if (targetDir) {
+        const candidate = _findAncestorGsdConfigPath(targetDir);
+        if (candidate) {
+            projectConfig = _readGsdConfigFile(candidate, 'project config');
+        }
+    }
+    const global = readGsdAgentTools(globalConfig);
+    const project = readGsdAgentTools(projectConfig);
+    if (projectConfig
+        && Object.prototype.hasOwnProperty.call(projectConfig, 'agent_tools')
+        && project === null)
+        return {};
+    if (!global && !project)
+        return null;
+    return { ...(global || {}), ...(project || {}) };
+}
 /**
  * Build a runtime-aware tier resolver for the install path (#2517).
  *
@@ -230,6 +274,7 @@ function resolveAgentModelOverride(agentName, modelOverrides, runtimeResolver) {
 module.exports = {
     readGsdGlobalModelOverrides,
     readGsdEffectiveModelOverrides,
+    readGsdEffectiveAgentTools,
     readGsdRuntimeProfileResolver,
     resolveAgentModelOverride,
 };

package/gsd-core/bin/lib/install-profiles.cjs

@@ -32,7 +32,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
-const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, } = conversionModule;
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, } = conversionModule;
 // #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
 // stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
 // `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
@@ -40,6 +40,8 @@ const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _pr
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const workflowFragmentsModule = require("./workflow-fragments.cjs");
 const { composeWorkflow: _composeWorkflow } = workflowFragmentsModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installModelOverrideResolver = require("./install-model-override-resolver.cjs");
 // ---------------------------------------------------------------------------
 // Profile definitions
 // ---------------------------------------------------------------------------
@@ -738,6 +740,11 @@ function readInstalledCapabilitySkill(stem, registry) {
         return null;
     const skillPath = node_path_1.default.join(capDir, relSkillPath);
     try {
+        // statSync follows symlinks; isPathConfined is lexical and cannot see one.
+        // Refuse to read through a link so an outside file's content cannot be
+        // installed as a capability skill (epic #4636).
+        if (node_fs_1.default.lstatSync(skillPath).isSymbolicLink())
+            return null;
         if (!node_fs_1.default.statSync(skillPath).isFile())
             return null;
         return { capId, content: node_fs_1.default.readFileSync(skillPath, 'utf8') };
@@ -856,6 +863,15 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
                 if (!(0, external_descriptor_trust_cjs_1.isPathConfined)(skillName, stageDir))
                     continue; // defense-in-depth
                 const destDir = node_path_1.default.join(stageDir, skillName);
+                // isPathConfined is lexical and cannot see a symlink. mkdirSync({recursive:true})
+                // does NOT throw when destDir already exists as a symlink to a directory, so a
+                // pre-planted link would redirect the SKILL.md write outside `stageDir`. Refuse
+                // to write through a link (epic #4636; mirrors retired-artifact-cleanup.cts:77).
+                try {
+                    if (installFs().lstatSync(destDir).isSymbolicLink())
+                        continue;
+                }
+                catch { /* ENOENT: not created yet — the normal case */ }
                 installFs().mkdirSync(destDir, { recursive: true });
                 installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), found.content);
                 // #2322 HIGH-3: persist the capability-owned marker so a later prune
@@ -896,14 +912,14 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  * agent loop in bin/install.js exactly:
  *   1. applyAgentPathRewrites   (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
  *   2. processAttribution       (Co-Authored-By policy)
- *   3. converter                (runtime-specific frontmatter/body transform)
- *   4. applyAgentFrontmatterExtensions (#2875 Part 2: effort/disallowedTools,
+ *   3. appendAgentTools         (#4032: validated agent_tools grants, before host conversion)
+ *   4. converter                (runtime-specific frontmatter/body transform)
+ *   5. applyAgentFrontmatterExtensions (#2875 Part 2: effort/disallowedTools,
  *      gated by hostBehaviors.agentFrontmatterExtensions — no-op for a runtime
  *      that declares nothing, e.g. every non-Claude runtime today)
- *   5. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
- * When `agentCtx` is absent, only the converter is applied (backward-compat for
- * the feat-1173 synthetic-descriptor tests and the copilot/antigravity paths
- * that handle cross-cutting inside their converters).
+ *   6. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
+ * When `agentCtx` is absent, only global `agent_tools` augmentation and the
+ * converter run; other cross-cutting remains absent for backward compatibility.
  *
  * @param srcAgentsDir    source agents directory (e.g. agents/)
  * @param resolvedProfile profile filter from resolveProfile()
@@ -917,8 +933,7 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  *                        every OTHER converter's contract — converters that don't declare a
  *                        3rd parameter simply never read it.
  * @param isGlobal        install scope passed through to the converter
- * @param agentCtx        optional cross-cutting context (ADR-1235 §1); when absent,
- *                        only the converter is applied (backward compat)
+ * @param agentCtx        optional cross-cutting context (ADR-1235 §1)
  */
 function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx) {
     if (!installFs().existsSync(srcAgentsDir))
@@ -950,6 +965,7 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
     try {
         // Resolve cmdNames once per staging call (not per file) for performance.
         const cmdNames = agentCtx ? _readGsdCommandNames() : [];
+        const agentTools = installModelOverrideResolver.readGsdEffectiveAgentTools(agentCtx?.projectDir ?? agentCtx?.targetDir ?? null);
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -969,25 +985,31 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
             // throws loudly naming the file for a malformed marker, never emitting a
             // half-composed agent.
             content = _composeWorkflow(content, { sourcePath: agentSourcePath });
+            const agentName = _deriveAgentName(entry.name);
+            const grants = [
+                ...(agentTools?.['*'] || []),
+                ...(agentTools?.[agentName] || []),
+            ];
             if (agentCtx) {
                 // #2875 Part 2 / row I3: derived exactly as the inline loop does —
                 // single-sourced via deriveAgentName (runtime-artifact-conversion.cts).
-                const agentName = _deriveAgentName(entry.name);
                 // ADR-1235 §1: pre-converter cross-cutting (matches inline loop order exactly)
                 // Step 1: path rewrites (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
                 content = _applyAgentPathRewrites(content, agentCtx.runtime, agentCtx.pathPrefix);
                 // Step 2: attribution
                 content = _processAttribution(content, agentCtx.attribution);
-                // Step 3: converter (runtime-specific frontmatter/body transform)
+                // Step 3: validated canonical grants, before host conversion.
+                content = _appendAgentTools(content, grants);
+                // Step 4: converter (runtime-specific frontmatter/body transform)
                 content = converter(content, isGlobal, { agentName });
-                // Step 4: frontmatter extensions (effort/disallowedTools; no-op unless
+                // Step 5: frontmatter extensions (effort/disallowedTools; no-op unless
                 // the runtime declares hostBehaviors.agentFrontmatterExtensions)
                 content = _applyAgentFrontmatterExtensions(content, { runtime: agentCtx.runtime, agentName, targetDir: agentCtx.targetDir });
-                // Step 5: normalize colon→hyphen refs (no-op for trivial group)
+                // Step 6: normalize colon→hyphen refs (no-op for trivial group)
                 content = _normalizeAgentBodyForRuntime(content, agentCtx.runtime, cmdNames);
             }
             else {
-                // Backward-compat: only apply the converter (no cross-cutting)
+                content = _appendAgentTools(content, grants);
                 content = converter(content, isGlobal);
             }
             installFs().writeFileSync(node_path_1.default.join(stageDir, entry.name), content, 'utf8');

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -55,6 +55,7 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-prompt-guard.js',
     'hooks/gsd-read-guard.js',
     'hooks/gsd-read-injection-scanner.js',
+    'hooks/gsd-secret-read-guard.js',
     'hooks/gsd-session-state.sh',
     'hooks/gsd-statusline.js',
     'hooks/gsd-update-banner.js',

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -17,6 +17,7 @@ const installer_migration_authoring_cjs_1 = require("./installer-migration-autho
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 const install_scope_cjs_1 = require("./install-scope.cjs");
+const security_cjs_1 = require("./security.cjs");
 // #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
 // plan/apply/rollback/lock/journal engine — almost none of it is on the
 // installRuntimeArtifacts call tree. Only `readInstallManifest` and
@@ -122,8 +123,17 @@ function evaluateRemoveEmptyDir(configDir, fullPath) {
     catch {
         return 'left-in-place';
     }
-    if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(resolvedRoot + node_path_1.default.sep)) {
-        // Refuses both "target IS configDir" and "target escaped configDir".
+    // `resolvedTarget === resolvedRoot` is a DELIBERATE ADDITIONAL rejection,
+    // separate from the containment decision: `tryWithinRootLexical` treats
+    // target === root as CONTAINED, but removing the config root itself is
+    // never in scope for this action (see the doc comment above) — this arm
+    // prevents `rmdirSync` from ever being asked to remove `configDir` itself.
+    // Kept as its own check per ADR-4650 decision 6 (a wrapper may add its own
+    // conditions on top of the canonical predicate, never invert it).
+    if (resolvedTarget === resolvedRoot)
+        return 'left-in-place';
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedTarget, resolvedRoot) === null) {
+        // Refuses "target escaped configDir".
         return 'left-in-place';
     }
     let entries;
@@ -598,11 +608,30 @@ function acquireInstallMigrationLock(configDir, { timeoutMs = DEFAULT_LOCK_TIMEO
         }
     }
 }
+// DELIBERATELY LEXICAL — the RESOLUTION policy stays lexical, never realpath
+// (`assertWithinRoot` / `tryWithinRoot`, src/security.cts).
+//
+// Reviewed under epic #4636 Phase 3 and reverted after the remote matrix proved
+// the realpath collapse wrong. This module's contract is that a symlinked
+// managed path is treated AS A LINK and never dereferenced — it is snapshotted
+// as a link, restored as a link, and backed up as a link. The realpath-based
+// predicate dereferences exactly the symlinks this module exists to preserve
+// and then rejects them for escaping configDir
+// ("migration path escapes configDir: extensions/gsd.cjs"). Four tests in
+// tests/installer-migrations.test.cjs pin that behavior.
+//
+// The containment DECISION now routes through the canonical LEXICAL predicate
+// (`tryWithinRootLexical`, ADR-4650 decision 6) — only the comparison moved;
+// the lexical policy itself remains this module's own required choice, and
+// the thrown message / returned `fullPath` are unchanged.
+//
+// `normalizeRelPath` is the pre-gate: it throws on absolute paths and on any
+// '..' segment BEFORE this runs, so the check below is defense-in-depth over
+// already-traversal-free input rather than the primary boundary.
 function ensureInsideConfig(configDir, relPath) {
     const normalized = normalizeRelPath(relPath);
     const fullPath = node_path_1.default.resolve(configDir, normalized);
-    const root = node_path_1.default.resolve(configDir);
-    if (fullPath !== root && !fullPath.startsWith(root + node_path_1.default.sep)) {
+    if ((0, security_cjs_1.tryWithinRootLexical)(fullPath, configDir) === null) {
         throw new Error(`migration path escapes configDir: ${relPath}`);
     }
     return { normalized, fullPath };

package/gsd-core/bin/lib/io.cjs

@@ -205,6 +205,40 @@ function output(result, raw, rawValue) {
     // and skipping process.exit() lets the event loop drain naturally.
     writeAllSync(1, data);
 }
+/**
+ * Single owner of the "a no-op decline reports the real condition" pairing:
+ * a `[gsd-tools] WARNING:` stderr disclosure plus the matching
+ * `{ [flagKey]: false, ...computed, reason }` JSON payload (#3957, epic
+ * #3473 B9). Before this helper, each CLI command's no-op arm hand-wrote
+ * both halves independently, and #3957's own sweep found sites where one
+ * half drifted: a decline that discarded values it had already computed, a
+ * `reason` string naming a condition that hadn't actually fired, or no
+ * stderr disclosure at all (missing the `[gsd-tools] WARNING:` convention
+ * #3217, ADR-3180 §7.6 rule 4, established for exactly this situation —
+ * a JSON `reason` field alone is easy for a caller piping stdout through
+ * `--json` to never read). Routing every no-op decline through one call
+ * site makes the convention structural — a call site, not a habit a fifth
+ * arm can independently forget — rather than leaving it to per-site
+ * discipline.
+ *
+ * `disclosure` is written to stderr VERBATIM. Like `error()`'s `message`
+ * argument (see that function's own doc comment above `formatDiagnosticToken`),
+ * this function stays a dumb, faithful writer and does not sanitize it — a
+ * caller that interpolates an UNTRUSTED substring (a caller-supplied
+ * blocker/session-field string, an argv token) into `disclosure` MUST pass
+ * that substring through `formatDiagnosticToken` first. Skipping that step
+ * lets an embedded `\n` forge a second, attacker-authored
+ * `[gsd-tools] WARNING:` line — the same risk `error()`'s doc comment
+ * documents for its own stderr write.
+ */
+function declineNoOp(raw, flagKey, reason, disclosure, computed = {}) {
+    // `process.stderr.write`, matching the `[gsd-tools] WARNING:` call sites
+    // this helper replaces (state.cts's stateReplaceFieldWithFallback and the
+    // cmdStateUpdateProgress decline arms) — not the `writeAllSync(2, …)`
+    // primitive `error()` uses, which is reserved for the fatal-exit path.
+    process.stderr.write(`[gsd-tools] WARNING: ${disclosure}\n`);
+    output({ [flagKey]: false, ...computed, reason }, raw, 'false');
+}
 /**
  * Frozen enum of typed reason codes used by error() for structured errors.
  * Each subcommand contributes its own codes; the enum exists so tests can
@@ -392,6 +426,7 @@ module.exports = {
     ensureGsdTempDir,
     reapStaleTempFiles,
     output,
+    declineNoOp,
     serializeForOutput,
     ERROR_REASON,
     setJsonErrorMode,