@yagni-app/code 1.0.6 → 1.0.8

package/dist/extension/index.d.ts

@@ -2,6 +2,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type SpendResponse } from "./costHud.js";
 import { runInitPass as defaultRunInitPass } from "./initPass.js";
 import { startMcp as defaultStartMcp } from "./mcp/startup.js";
+import { type GuardianGateEvent } from "./permission/gate.js";
+import { registerTelemetry as defaultRegisterTelemetry } from "./telemetry/register.js";
+import { type PluginCliRunner } from "./plugins/panel.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
 import { type CatalogResult, type ContextBrief } from "./config.js";
@@ -58,11 +61,18 @@ export interface RegisterYagniDeps {
      * homes or spawning servers. Default runs the real startup.
      */
     startMcp?: typeof defaultStartMcp;
+    /** Test seam for the /plugin panel: runs `yagni plugin …` (defaults to spawning YAGNI_CLI_PATH). */
+    runPluginCli?: PluginCliRunner;
     /**
      * The CLI init pass (Onramp Door B). Injectable so tests assert it fires on a
      * fresh-workspace first-run and is skipped otherwise, without a network or disk.
      */
     runInitPass?: typeof defaultRunInitPass;
+    /**
+     * OTel export registration. Injectable so tests assert the boot handoff of
+     * the /context `userEmail` into the telemetry identity without an SDK.
+     */
+    registerTelemetry?: typeof defaultRegisterTelemetry;
     /** The workspace id the token is bound to (keys the one-time init marker). */
     getWorkspaceId?: () => string | undefined;
     /** Has the init pass already run once for this workspace? Injectable (no disk in tests). */
@@ -115,6 +125,15 @@ export declare function buildRunSpendUrl(baseUrl: string, runId: string): string
  * Returns null on anything that doesn't look like the real shape.
  */
 export declare function parseSpendResponse(data: unknown): SpendResponse | null;
+/**
+ * Local trail for EVERY terminal gate outcome (sandbox auto-allow included),
+ * always on so e2e and support can see what the gate did even when the
+ * storage tier is off. Decision K: the always-on line carries outcome
+ * metadata ONLY — no command content. The command prefix and the exec
+ * justification are command/model content and ride the debug tier (never
+ * uploaded by /feedback) plus the opt-in storage stream.
+ */
+export declare function logGateOutcomeTrail(ev: GuardianGateEvent, env: NodeJS.ProcessEnv): void;
 export declare function registerYagni(pi: ExtensionAPI, deps?: RegisterYagniDeps): Promise<void>;
 export default function (pi: ExtensionAPI): Promise<void>;
 export { makeAskYagniTool } from "./askYagniTool.js";

package/dist/extension/index.js

@@ -24,6 +24,7 @@ import { logEvent } from "./errorSink.js";
 import { registerFeedbackCommands } from "./feedbackCommand.js";
 import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
 import { codeStateHome } from "./stateHome.js";
+import { mutateLocalConfig } from "./settingsFiles.js";
 import { logTurnLifecycle } from "./turnLog.js";
 import { createYagniFooterFactory, cyclePermissionMode, formatCwd, GIT_MUTATING_PATTERN, isShiftTab } from "./footer.js";
 import { RerouteNotifier } from "./rerouteNotice.js";
@@ -34,7 +35,12 @@ import { startMcp as defaultStartMcp, wireShutdown, deriveStartupConnectivityNot
 import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission/gate.js";
+import { registerSandbox } from "./sandbox/session.js";
+import { sandboxAutoAllowDecision } from "./sandbox/bash.js";
+import { registerTelemetry as defaultRegisterTelemetry } from "./telemetry/register.js";
 import { loadHooksConfig, makeHookRunner, registerHooks } from "./hooks.js";
+import { loadPermissionRules } from "./permissionRules/loadConfig.js";
+import { registerPluginPanel } from "./plugins/panel.js";
 import { registerSubagents } from "./subagents.js";
 import { createUltraHolder, registerUltraCommand } from "./ultra.js";
 import { registerTodos } from "./todos.js";
@@ -99,6 +105,39 @@ export function parseSpendResponse(data) {
         return null;
     return d;
 }
+/**
+ * Local trail for EVERY terminal gate outcome (sandbox auto-allow included),
+ * always on so e2e and support can see what the gate did even when the
+ * storage tier is off. Decision K: the always-on line carries outcome
+ * metadata ONLY — no command content. The command prefix and the exec
+ * justification are command/model content and ride the debug tier (never
+ * uploaded by /feedback) plus the opt-in storage stream.
+ */
+export function logGateOutcomeTrail(ev, env) {
+    logEvent({
+        source: "guardian",
+        level: "info",
+        event: "gate_outcome",
+        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+        fields: {
+            outcome: ev.outcome,
+            mode: ev.mode,
+            consulted: ev.consulted,
+        },
+    });
+    if (isDebug(env)) {
+        logEvent({
+            source: "guardian",
+            level: "debug",
+            event: "gate_outcome",
+            sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            fields: {
+                commandPrefix: storagePrefix(ev.command),
+                ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+            },
+        });
+    }
+}
 export async function registerYagni(pi, deps = {}) {
     const baseUrl = deps.baseUrl ?? resolveBaseUrl();
     const now = deps.now ?? (() => Date.now());
@@ -239,6 +278,9 @@ export async function registerYagni(pi, deps = {}) {
     // before_agent_start handler below) and widens the tool's fan-out ceiling.
     const ultraHolder = createUltraHolder();
     registerSubagents(pi, { isUltra: () => ultraHolder.get(), workingLine, childUsage });
+    // /plugin + /reload-plugins: manage Claude Code marketplace plugins from the
+    // session, driving the launcher's `yagni plugin …` (YAGNI_CLI_PATH).
+    registerPluginPanel(pi, { env: deps.env, runCli: deps.runPluginCli });
     registerUltraCommand(pi, ultraHolder);
     // Shared fetch timeout for the small, interactive display-path reads below
     // (/cost's spend + headroom, and Task 8's per-run spend for /go's summary):
@@ -334,6 +376,8 @@ export async function registerYagni(pi, deps = {}) {
         // The static queue only carries non-connectivity notices (e.g. the
         // `.mcp.json` approval prompt), which stay one-shot.
         let connectivityNoticesFlushed = false;
+        // permission-rule notices are one-shot like connectivity notices.
+        let rulesNoticesFlushed = false;
         pi.on("after_provider_response", (_event, ctx) => {
             try {
                 if (!ctx.hasUI)
@@ -347,6 +391,21 @@ export async function registerYagni(pi, deps = {}) {
                 while (mcpApprovalNotices.length > 0) {
                     ctx.ui.notify(mcpApprovalNotices.shift(), "info");
                 }
+                // one-shot permission-rule config warnings (bad files,
+                // never-consulted tools). One consolidated line, never a wall.
+                if (!rulesNoticesFlushed) {
+                    rulesNoticesFlushed = true;
+                    const parts = [];
+                    if (loadedRules.diagnostics.warnings.length > 0) {
+                        parts.push(`${loadedRules.diagnostics.warnings.length} permission-rule config warning(s)`);
+                    }
+                    if (loadedRules.diagnostics.neverConsultedTools.length > 0) {
+                        parts.push(`rules for unknown tools: ${loadedRules.diagnostics.neverConsultedTools.join(", ")} (ignored)`);
+                    }
+                    if (parts.length > 0) {
+                        ctx.ui.notify(`Permission rules: ${parts.join(" · ")}`, "warning");
+                    }
+                }
             }
             catch {
                 // A notice must never break a turn.
@@ -359,6 +418,18 @@ export async function registerYagni(pi, deps = {}) {
     // Mutating MCP tools join write/edit/bash in the gate policy: plan mode
     // holds them, review mode confirms them.
     const modeHolder = createModeHolder();
+    // OTel export (traces, metrics, log events; Claude Code parity). A no-op
+    // unless the launcher's gate set YAGNI_OTEL_EXPORT=1 — see the CLI's
+    // otel.ts for the sources and src/telemetry for the exporter.
+    const telemetry = (deps.registerTelemetry ?? defaultRegisterTelemetry)(pi, { env });
+    {
+        let previousMode = modeHolder.get();
+        modeHolder.onSet((m) => {
+            if (m !== previousMode)
+                telemetry.permissionModeChanged(previousMode, m);
+            previousMode = m;
+        });
+    }
     const footerInvalidateHandle = { invalidateGit: () => { }, requestRender: () => { } };
     const guardianState = makeGuardianState();
     // Disabled by the local env override OR the workspace kill switch
@@ -408,6 +479,25 @@ export async function registerYagni(pi, deps = {}) {
     // the startup load is the trust boundary; live reload was reviewed and
     // rejected as a same-session self-authorization path, PR #1698).
     const sessionGrants = evalMode ? [] : loadGrants();
+    // settings-based permission rules, loaded once at startup (same
+    // trust-boundary posture as grants: no mid-session reload). User config
+    // (~/.yagni-code/config.json) + project config (.yagni-code/config.json);
+    // project allow rules are trust-gated at evaluation time, deny/ask always.
+    const loadedRules = evalMode
+        ? { rules: [], diagnostics: { warnings: [], neverConsultedTools: [] } }
+        : loadPermissionRules({ cwd: process.cwd() });
+    for (const w of loadedRules.diagnostics.warnings) {
+        logEvent({ source: "permission-rules", level: "warn", event: "config_warning", fields: { warning: w } });
+    }
+    if (loadedRules.diagnostics.neverConsultedTools.length > 0) {
+        logEvent({
+            source: "permission-rules",
+            level: "warn",
+            event: "never_consulted_tools",
+            fields: { tools: loadedRules.diagnostics.neverConsultedTools.join(", ") },
+        });
+    }
+    const rulesStateHome = codeStateHome(null, env);
     const GUARDIAN_EVENT_TIMEOUT_MS = 5_000;
     // YAG-506: load user-configurable lifecycle hooks config and create the
     // hook runner for the permission gate. Skipped in eval mode.
@@ -415,11 +505,56 @@ export async function registerYagni(pi, deps = {}) {
     const hookRunner = evalMode ? null : makeHookRunner({ config: hooksConfig });
     if (!evalMode)
         registerHooks(pi, { config: hooksConfig });
+    // OS-level bash sandboxing. Registers the sandbox-aware bash tool
+    // (dangerouslyDisableSandbox param + wrap + violation annotation) and the
+    // session lifecycle (init/reset, fail-soft unless failIfUnavailable).
+    // Null on unsupported platforms — stock bash stays. Shares the loaded
+    // permission rules so sandbox config and the gate read one rule source.
+    const sandboxHandle = evalMode
+        ? null
+        : registerSandbox(pi, {
+            cwd: process.cwd(),
+            env,
+            hasUI: (ctx) => ctx.hasUI,
+            // Anchors project-protected paths (.yagni-code + its config.json in
+            // denyWrite) and project-sourced permission rules to the repo the
+            // session runs in — same root the gate uses for its rule anchoring.
+            projectRoot: process.cwd(),
+        });
+    if (sandboxHandle)
+        sandboxHandle.setRules(loadedRules.rules);
     registerPermissionGate(pi, {
+        ...(sandboxHandle
+            ? {
+                sandboxAutoAllow: (toolName, params) => sandboxAutoAllowDecision(toolName, params, sandboxHandle.manager, sandboxHandle.settings()),
+            }
+            : {}),
         modeHolder,
         guardianState,
         guardianLimits,
         guardianTier,
+        onToolDecision: (ev) => telemetry.toolDecision(ev),
+        ...(loadedRules.rules.length > 0
+            ? {
+                permissionRules: loadedRules.rules,
+                rulesUserStateHome: rulesStateHome,
+                rulesProjectRoot: process.cwd(),
+                onRuleVerdict: (ev) => {
+                    logEvent({
+                        source: "permission-rules",
+                        level: "debug",
+                        event: `rule_${ev.verdict}`,
+                        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                        fields: {
+                            tool: ev.toolName,
+                            via: ev.matchedVia,
+                            source: ev.rule.source,
+                            rule: ev.rule.raw,
+                        },
+                    });
+                },
+            }
+            : {}),
         guardianDisabled,
         childUsage,
         guardianReview: (command, deps) => reviewCommand(command, { ...deps, modelTier: guardianTier }),
@@ -471,57 +606,91 @@ export async function registerYagni(pi, deps = {}) {
             if (!evalMode)
                 appendGrant(grant);
         },
+        // persist a project-local allow rule (Guardian ask dialog's third
+        // option — Claude Code's own default save destination for personal
+        // rules is localSettings; ours matches). Atomic write, never overwrites
+        // other keys. THROWS on failure — the gate's catch owns the fail-soft
+        // behavior (notify the user, record ask_approved not remembered); a
+        // catch HERE would swallow the throw and make that path unreachable,
+        // leaving the user believing a rule saved that will not survive restart.
+        // Local writes fire-and-forget the global gitignore helper so the file
+        // is never committed by accident.
+        //
+        // The cwd is the GATE's per-call session cwd (a session can switch
+        // directories; process.cwd() would silently land the rule in another
+        // project's local settings while the dialog claims this one). Not
+        // registered in eval mode: the gate hides the save option when the dep
+        // is absent, so a no-op implementation that would still emit
+        // ask_approved_remembered never exists.
+        ...(evalMode ? {} : {
+            persistUserRule: (ruleString, cwd) => {
+                mutateLocalConfig(cwd, (config) => {
+                    const perms = (config.permissions ?? {});
+                    const allow = Array.isArray(perms.allow) ? [...perms.allow] : [];
+                    if (!allow.includes(ruleString))
+                        allow.push(ruleString);
+                    perms.allow = allow;
+                    config.permissions = perms;
+                });
+                logEvent({
+                    source: "permission-rules",
+                    level: "info",
+                    event: "rule_saved",
+                    sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                    fields: { rule: ruleString, destination: "local" },
+                });
+            },
+        }),
         // Opt-in storage stream (YAG-510). Tier decides what leaves the machine:
         // "off" → nothing (not even sent); "hash" → sha256 + family prefix +
         // metadata, no command content; "raw" → adds client-REDACTED command and
         // rationale. Fire-and-forget: one attempt, short timeout, failures logged
         // fail-soft to the unified sink (source:"guardian") — a storage outage
         // never touches the session.
-        onGuardianEvent: guardianStorageTier === "off" || evalMode
-            ? undefined
-            : (ev) => {
-                void (async () => {
-                    try {
-                        const body = {
-                            sessionId: env.YAGNI_SESSION_ID ?? null,
-                            commandHash: createHash("sha256").update(ev.command).digest("hex"),
-                            commandPrefix: storagePrefix(ev.command),
-                            outcome: ev.outcome,
-                            mode: ev.mode,
-                            ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
-                            ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
-                            ...(ev.tier ? { tier: ev.tier } : {}),
-                            ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
-                        };
-                        if (guardianStorageTier === "raw") {
-                            body.command = redactCommand(ev.command);
-                            if (ev.rationale)
-                                body.rationale = redactCommand(ev.rationale);
-                        }
-                        const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
-                            method: "POST",
-                            headers: {
-                                "content-type": "application/json",
-                                authorization: `Bearer ${getTokenFn() ?? ""}`,
-                                ...attributionHeaders(deps.env),
-                            },
-                            body: JSON.stringify(body),
-                        }, {
-                            fetchImpl: authedFetch,
-                            policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
-                        });
-                        if (!res.ok) {
-                            guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
-                        }
+        onGuardianEvent: (ev) => {
+            logGateOutcomeTrail(ev, env);
+            // Opt-in storage stream (YAG-510): tier decides what leaves the machine.
+            if (guardianStorageTier === "off" || evalMode)
+                return;
+            void (async () => {
+                try {
+                    const body = {
+                        sessionId: env.YAGNI_SESSION_ID ?? null,
+                        commandHash: createHash("sha256").update(ev.command).digest("hex"),
+                        commandPrefix: storagePrefix(ev.command),
+                        outcome: ev.outcome,
+                        mode: ev.mode,
+                        ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+                        ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
+                        ...(ev.tier ? { tier: ev.tier } : {}),
+                        ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
+                    };
+                    if (guardianStorageTier === "raw") {
+                        body.command = redactCommand(ev.command);
+                        if (ev.rationale)
+                            body.rationale = redactCommand(ev.rationale);
                     }
-                    catch {
-                        guardianLogSink({
-                            event: "guardian_event_post_failed",
-                            kind: "network",
-                        });
+                    const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
+                        method: "POST",
+                        headers: {
+                            "content-type": "application/json",
+                            authorization: `Bearer ${getTokenFn() ?? ""}`,
+                            ...attributionHeaders(deps.env),
+                        },
+                        body: JSON.stringify(body),
+                    }, {
+                        fetchImpl: authedFetch,
+                        policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
+                    });
+                    if (!res.ok) {
+                        guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
                     }
-                })();
-            },
+                }
+                catch {
+                    guardianLogSink({ event: "guardian_event_post_failed", kind: "network" });
+                }
+            })();
+        },
         ...(mcpMutatingSet.size > 0 || mcpOutcome.manager
             ? {
                 policy: {
@@ -671,6 +840,29 @@ export async function registerYagni(pi, deps = {}) {
             contextBrief = undefined;
         }
     }
+    // The developer's account email for the OTel export (`user.email`), so a
+    // collector can attribute sessions per person. Set before session_start
+    // fires, so even the session.count metric carries it. No-op when export is
+    // off or the launcher already forwarded YAGNI_USER_EMAIL.
+    const bootUserEmail = typeof briefResult?.userEmail === "string" ? briefResult.userEmail : undefined;
+    telemetry.setUserEmail(bootUserEmail);
+    if (telemetry.enabled && !bootUserEmail && !telemetry.config.identity.userEmail) {
+        // Attribution would otherwise degrade silently: leave a trail in the local
+        // error sink so "why is user.email missing in the collector" is answerable.
+        // Info, not warn: one line per session start, and an account with no
+        // email hits it by design. The fields name each way the email can be
+        // absent — the boot fetch failed or lacked the field, and whether the
+        // launcher's YAGNI_USER_EMAIL was unset or forwarded blank.
+        logEvent({
+            source: "telemetry",
+            level: "info",
+            event: "user_email_missing",
+            fields: {
+                contextFetch: briefResult === null ? "failed_or_skipped" : "no_email_field",
+                launcherEmail: env.YAGNI_USER_EMAIL === undefined ? "unset" : "blank",
+            },
+        });
+    }
     // M1 ambient judgment recall: after a `read`, append the recorded judgment for
     // that path to the tool result (result modification is supported on pi's
     // `tool_result` event — verified against 0.80.2). No-op when the corpus is thin
@@ -753,12 +945,25 @@ export async function registerYagni(pi, deps = {}) {
         try {
             registerCondensedTools(pi, {
                 ...(scratchpadDirPath ? { scratchpadDir: scratchpadDirPath } : {}),
+                // condensed owns the FINAL bash registration (it re-registers
+                // built-ins last), so the sandbox composes INTO it here. Identity when
+                // the sandbox is off.
+                ...(sandboxHandle ? { wrapBash: sandboxHandle.composeBash } : {}),
             });
         }
         catch {
             // Rendering must never break activation; pi's built-ins remain.
         }
     }
+    else if (sandboxHandle && env.YAGNI_CLASSIC_TOOL_ROWS !== "1") {
+        // Condensed inactive (eval mode / desktop): the sandbox's own
+        // registration is the one that reaches the tool registry. NOT under the
+        // classic-rows escape hatch — classic bash must stay pi's stock
+        // registration (the hatch's contract); a competing one would replace
+        // classic rendering with the sandbox's wrap. Desktop/eval still need
+        // the sandbox to reach bash, so the hatch is the one carve-out.
+        sandboxHandle.registerOwnBash();
+    }
     // Own the identity + inject live company context (and repo rules) on every
     // turn. The extension loads identically in every pi process this app spawns —
     // the interactive driver AND every `/go` stage child, subagent, and advisor

package/dist/extension/mcp/cliConfig.d.ts

@@ -4,7 +4,7 @@
  * from its bundled copy). Pure config I/O — no pi imports, no TUI, no network —
  * so importing it from the launcher is side-effect-free.
  */
-export { McpServerConfig, McpScope, PROJECT_CONFIG_FILENAME, ScopedMcpServerConfig, expandEnvVarsInString, expandServerEnv, loadMcpServers, mcpConfigPath, readProjectMcpConfig, readUserMcpConfig, resolveProjectRoot, validateServerConfig, writeUserMcpConfig, } from "./config.js";
+export { McpServerConfig, McpScope, PLUGIN_MCP_ENV, PROJECT_CONFIG_FILENAME, ScopedMcpServerConfig, expandEnvVarsInString, expandServerEnv, loadMcpServers, mcpConfigPath, readPluginMcpServers, readProjectMcpConfig, readUserMcpConfig, resolveProjectRoot, validateServerConfig, writeUserMcpConfig, } from "./config.js";
 export { ProjectApprovalState, decisionFor, readProjectApproval, recordProjectDecision, resetProjectChoices, undecidedProjectServers, } from "./approval.js";
 export { McpAuthFile, StoredOAuthEntry, deleteStoredOAuthEntry, getServerKey, getStoredOAuthEntry, mcpAuthPath, readMcpAuth, updateStoredOAuthEntry, writeMcpAuth, } from "./authStore.js";
 export { revokeTokensOnRemove } from "./auth.js";

package/dist/extension/mcp/cliConfig.js

@@ -4,7 +4,7 @@
  * from its bundled copy). Pure config I/O — no pi imports, no TUI, no network —
  * so importing it from the launcher is side-effect-free.
  */
-export { PROJECT_CONFIG_FILENAME, expandEnvVarsInString, expandServerEnv, loadMcpServers, mcpConfigPath, readProjectMcpConfig, readUserMcpConfig, resolveProjectRoot, validateServerConfig, writeUserMcpConfig, } from "./config.js";
+export { PLUGIN_MCP_ENV, PROJECT_CONFIG_FILENAME, expandEnvVarsInString, expandServerEnv, loadMcpServers, mcpConfigPath, readPluginMcpServers, readProjectMcpConfig, readUserMcpConfig, resolveProjectRoot, validateServerConfig, writeUserMcpConfig, } from "./config.js";
 export { decisionFor, readProjectApproval, recordProjectDecision, resetProjectChoices, undecidedProjectServers, } from "./approval.js";
 export { deleteStoredOAuthEntry, getServerKey, getStoredOAuthEntry, mcpAuthPath, readMcpAuth, updateStoredOAuthEntry, writeMcpAuth, } from "./authStore.js";
 export { revokeTokensOnRemove } from "./auth.js";

package/dist/extension/mcp/config.d.ts

@@ -6,13 +6,18 @@
  *    A repo configured for Claude Code works here with zero changes.
  *  - user: top-level `mcpServers` in `~/.yagni-code/mcp.json`.
  *  - local: `projects[<absPath>].mcpServers` in the same file, keyed by cwd.
+ *  - plugin: servers bundled in Claude Code plugins (`.mcp.json` at the plugin
+ *    root), handed over by the yagni launcher as JSON in
+ *    `YAGNI_CLAUDE_PLUGIN_MCP` (see yagni-code-cli claudeCompat.ts). Entries
+ *    marked `gated` came from repo config and ride the project approval gate.
  *
- * Merge precedence (Claude Code parity): user < project < local — later wins.
+ * Merge precedence (Claude Code parity): plugin < user < project < local —
+ * later wins, so an explicit user entry beats a plugin's.
  * Writes are atomic (temp file + rename) so two concurrent sessions can never
  * interleave into a corrupt config. Validation errors are collected and
  * surfaced, never fatal: one malformed server entry must not hide the rest.
  */
-export type McpScope = "user" | "project" | "local";
+export type McpScope = "user" | "project" | "local" | "plugin";
 export interface McpStdioServerConfig {
     type?: "stdio";
     command: string;
@@ -39,7 +44,24 @@ export interface ScopedMcpServerConfig {
     scope: McpScope;
     /** Where this entry came from (file path) — surfaced in /mcp and `yagni mcp get`. */
     sourcePath: string;
+    /** `name@marketplace` of the plugin that bundles this server (plugin scope). */
+    plugin?: string;
+    /** Plugin server that came from repo config: needs the project approval gate. */
+    gated?: boolean;
 }
+/** Launcher → extension: plugin-bundled MCP servers (JSON array). */
+export declare const PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+export interface PluginMcpEnvEntry {
+    plugin: string;
+    sourcePath: string;
+    gated: boolean;
+    servers: Record<string, unknown>;
+}
+/** Parse the launcher's plugin MCP payload; malformed input degrades to errors, never a throw. */
+export declare function readPluginMcpServers(env?: NodeJS.ProcessEnv): {
+    servers: ScopedMcpServerConfig[];
+    errors: McpConfigError[];
+};
 export interface McpConfigError {
     /** File the problem was found in. */
     sourcePath: string;

package/dist/extension/mcp/config.js

@@ -6,8 +6,13 @@
  *    A repo configured for Claude Code works here with zero changes.
  *  - user: top-level `mcpServers` in `~/.yagni-code/mcp.json`.
  *  - local: `projects[<absPath>].mcpServers` in the same file, keyed by cwd.
+ *  - plugin: servers bundled in Claude Code plugins (`.mcp.json` at the plugin
+ *    root), handed over by the yagni launcher as JSON in
+ *    `YAGNI_CLAUDE_PLUGIN_MCP` (see yagni-code-cli claudeCompat.ts). Entries
+ *    marked `gated` came from repo config and ride the project approval gate.
  *
- * Merge precedence (Claude Code parity): user < project < local — later wins.
+ * Merge precedence (Claude Code parity): plugin < user < project < local —
+ * later wins, so an explicit user entry beats a plugin's.
  * Writes are atomic (temp file + rename) so two concurrent sessions can never
  * interleave into a corrupt config. Validation errors are collected and
  * surfaced, never fatal: one malformed server entry must not hide the rest.
@@ -15,6 +20,70 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { codeStateHome } from "../stateHome.js";
+/** Launcher → extension: plugin-bundled MCP servers (JSON array). */
+export const PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
+/** Parse the launcher's plugin MCP payload; malformed input degrades to errors, never a throw. */
+export function readPluginMcpServers(env = process.env) {
+    const disabled = env[CLAUDE_COMPAT_DISABLE_ENV];
+    if (disabled !== undefined && disabled !== "" && disabled !== "0")
+        return { servers: [], errors: [] };
+    const raw = env[PLUGIN_MCP_ENV];
+    if (!raw)
+        return { servers: [], errors: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            servers: [],
+            errors: [{ sourcePath: PLUGIN_MCP_ENV, message: `could not parse plugin MCP payload (${err instanceof Error ? err.message : String(err)})` }],
+        };
+    }
+    if (!Array.isArray(parsed))
+        return { servers: [], errors: [{ sourcePath: PLUGIN_MCP_ENV, message: "plugin MCP payload is not an array" }] };
+    const servers = [];
+    const errors = [];
+    const seen = new Map();
+    for (const item of parsed) {
+        if (!item || typeof item !== "object")
+            continue;
+        const entry = item;
+        if (typeof entry.plugin !== "string" || !entry.servers || typeof entry.servers !== "object")
+            continue;
+        const sourcePath = typeof entry.sourcePath === "string" ? entry.sourcePath : entry.plugin;
+        for (const [name, value] of Object.entries(entry.servers)) {
+            const validation = validateServerConfig(value);
+            if (!validation.ok) {
+                errors.push({ sourcePath, serverName: name, message: `${validation.message} (plugin ${entry.plugin})` });
+                continue;
+            }
+            const owner = seen.get(name);
+            if (owner) {
+                errors.push({
+                    sourcePath,
+                    serverName: name,
+                    message: `also defined by plugin ${owner} — keeping that one, skipping ${entry.plugin}'s`,
+                });
+                continue;
+            }
+            const config = value;
+            const expanded = expandServerEnv(config, env);
+            if (expanded.missingVars.length > 0) {
+                errors.push({
+                    sourcePath,
+                    serverName: name,
+                    message: `missing environment variable(s): ${expanded.missingVars.join(", ")} — server skipped`,
+                });
+                continue;
+            }
+            seen.set(name, entry.plugin);
+            servers.push({ name, config, scope: "plugin", sourcePath, plugin: entry.plugin, gated: entry.gated === true });
+        }
+    }
+    return { servers, errors };
+}
 export const PROJECT_CONFIG_FILENAME = ".mcp.json";
 /**
  * Expand `${VAR}` / `${VAR:-default}` in a config string (Claude Code parity —
@@ -239,7 +308,10 @@ function defaultExists(p) {
 export function loadMcpServers(cwd, env = process.env) {
     const repoRoot = resolveProjectRoot(cwd);
     const errors = [];
-    const byScope = { user: [], project: [], local: [] };
+    const byScope = { plugin: [], user: [], project: [], local: [] };
+    const pluginLoad = readPluginMcpServers(env);
+    errors.push(...pluginLoad.errors);
+    byScope.plugin.push(...pluginLoad.servers);
     const { file: userFile, errors: userErrors } = readUserMcpConfig();
     errors.push(...userErrors);
     const userServers = userFile.mcpServers ?? {};
@@ -300,7 +372,7 @@ export function loadMcpServers(cwd, env = process.env) {
         }
     }
     const merged = new Map();
-    for (const scope of ["user", "project", "local"]) {
+    for (const scope of ["plugin", "user", "project", "local"]) {
         for (const server of byScope[scope])
             merged.set(server.name, server);
     }

package/dist/extension/mcp/manager.d.ts

@@ -20,6 +20,8 @@ export interface ManagedServer {
     scope: McpScope;
     config: McpStdioServerConfig | McpHttpServerConfig;
     status: McpServerStatus;
+    /** Plugin server sourced from repo config: rides the project approval gate. */
+    gated?: boolean;
     /** Failure detail for the failed/needs_auth states (panel + logs). */
     error?: string;
     client?: Client;
@@ -51,7 +53,7 @@ export declare class McpManager {
     list(): ManagedServer[];
     get(name: string): ManagedServer | undefined;
     /** Registers a server without connecting (panel listing, kill-switch states). */
-    register(name: string, scope: McpScope, config: McpStdioServerConfig | McpHttpServerConfig, status?: McpServerStatus): ManagedServer;
+    register(name: string, scope: McpScope, config: McpStdioServerConfig | McpHttpServerConfig, status?: McpServerStatus, gated?: boolean): ManagedServer;
     connect(name: string): Promise<ManagedServer | undefined>;
     disconnect(name: string): Promise<void>;
     /** Reconnect with bounded attempts, panel-visible progress. */

package/dist/extension/mcp/manager.js

@@ -47,11 +47,11 @@ export class McpManager {
         return this.servers.get(name);
     }
     /** Registers a server without connecting (panel listing, kill-switch states). */
-    register(name, scope, config, status = "disabled") {
+    register(name, scope, config, status = "disabled", gated = false) {
         const existing = this.servers.get(name);
         if (existing)
             return existing;
-        const server = { name, scope, config, status };
+        const server = { name, scope, config, status, ...(gated ? { gated } : {}) };
         this.servers.set(name, server);
         return server;
     }

package/dist/extension/mcp/panel.d.ts

@@ -21,7 +21,6 @@ export interface PanelServerInfo {
 }
 export declare function statusIcon(status: string): string;
 export declare function statusText(server: ManagedServer): string;
-/** Plain-text listing, mirroring CC's `claude mcp list` and panel states. */
 export declare function renderPanelListing(servers: ManagedServer[], errors: string[]): string;
 export interface PanelDeps {
     cwd: string;