@yagni-app/code-staging 1.1.1-staging.1355.1 → 1.1.1-staging.1359.1

package/dist/extension/askAdvisorTool.d.ts

@@ -40,6 +40,9 @@ import { type RenderTheme, type SubagentTaskProgress } from "./subagentRender.js
  * single `read`. No `bash`.
  */
 export declare const ADVISOR_TOOLS: string[];
+/** The consult's tool list under `grounding: false` — grounding read
+ * stripped via the canonical filter (grounding.ts). */
+export declare const ADVISOR_TOOLS_GROUNDING_FREE: string[];
 declare const parameters: Type.TObject<{
     question: Type.TString;
     tried: Type.TOptional<Type.TString>;
@@ -49,6 +52,13 @@ export interface MakeAskAdvisorToolOptions {
     /** Per-session consult accounting. Created once per session in index.ts. */
     state: AdvisorStateHandle;
     limits?: AdvisorLimits;
+    /**
+     * The boot-time grounding switch: false runs consults on the BLIND advisor
+     * persona (the existing ADVISOR_BLIND body in pipeline/personas.ts — the
+     * M6 eval lane's machinery) with the grounding-free tool list and metadata
+     * that no longer nudges ask_yagni / record_decision. Defaults grounded.
+     */
+    grounded?: boolean;
     /** Injectable so tests never spawn a child. */
     runStage?: typeof defaultRunStage;
     /**
@@ -81,7 +91,7 @@ export declare function buildConsultBrief(params: {
  * feed/activity reducers that switch over it. `agent` is what selects the
  * persona, and that is the advisor's own.
  */
-export declare function advisorStage(): PipelineStage;
+export declare function advisorStage(grounded?: boolean): PipelineStage;
 /** The ask_advisor result details: consult accounting plus the live progress
  * record the subagent renderers paint (one task, the consult itself). */
 export interface AdvisorToolDetails {

package/dist/extension/askAdvisorTool.js

@@ -30,6 +30,7 @@ import { Type } from "typebox";
 import { ADVISOR_MODEL_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatConsultCost, } from "./advisor.js";
 import { SPINNER_FRAMES } from "./pipeline/activityFeed.js";
 import { withResilience } from "./pipeline/resilience.js";
+import { stripGroundingTool } from "./grounding.js";
 import { runStage as defaultRunStage } from "./pipeline/runner.js";
 import { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
 import { logEvent } from "./errorSink.js";
@@ -40,6 +41,9 @@ import { applyChildEvent, finalizeTask, formatWorkingMessage, newTaskProgress, p
  * single `read`. No `bash`.
  */
 export const ADVISOR_TOOLS = ["read", "grep", "find", "ls", "ask_yagni"];
+/** The consult's tool list under `grounding: false` — grounding read
+ * stripped via the canonical filter (grounding.ts). */
+export const ADVISOR_TOOLS_GROUNDING_FREE = stripGroundingTool(ADVISOR_TOOLS);
 const parameters = Type.Object({
     question: Type.String({
         description: "The single judgment call you want a second opinion on. Be specific.",
@@ -68,12 +72,12 @@ export function buildConsultBrief(params) {
  * feed/activity reducers that switch over it. `agent` is what selects the
  * persona, and that is the advisor's own.
  */
-export function advisorStage() {
+export function advisorStage(grounded = true) {
     return {
         id: "plan",
         agent: "advisor",
         model: ADVISOR_MODEL_TIER,
-        tools: ADVISOR_TOOLS,
+        tools: grounded ? ADVISOR_TOOLS : ADVISOR_TOOLS_GROUNDING_FREE,
         taskTemplate: "{ticket}",
     };
 }
@@ -97,17 +101,12 @@ export function renderAdvisorCall(args, theme, _context) {
 }
 export function makeAskAdvisorTool(opts) {
     const limits = opts.limits ?? DEFAULT_ADVISOR_LIMITS;
-    // The default runner rides the /go pipeline's resilience wrapper, exactly
-    // like the subagent tool: idle + wall-clock ceilings and transient-only
-    // retry, so a stalled consult child aborts honestly instead of hanging the
-    // driver's tool call until the user presses Esc. The synthetic stage id is
-    // "plan" (read-only tools, no bash), so the wrapper's write-gate never
-    // blocks a retry — re-running a consult cannot double-apply anything.
-    const runStage = opts.runStage ?? withResilience(defaultRunStage, DEFAULT_RESILIENCE_POLICY);
-    return {
-        name: "ask_advisor",
-        label: "Ask the advisor",
-        description: "Escalate ONE hard judgment call to the peak-tier advisor — the strongest " +
+    const grounded = opts.grounded !== false;
+    // Metadata variants: the description/promptGuidelines reach the model as
+    // tool metadata even when the consult runs blind — with grounding off they
+    // must not nudge ask_yagni (unregistered) or record_decision (unregistered).
+    const description = grounded
+        ? "Escalate ONE hard judgment call to the peak-tier advisor — the strongest " +
             "model available, which reads the code itself and returns a recommendation. " +
             "Available only on the Advanced tier, and capped per session, so use it for " +
             "calls that are genuinely worth it: an architectural fork with no obvious " +
@@ -115,15 +114,43 @@ export function makeAskAdvisorTool(opts) {
             "a change whose blast radius you are unsure of, or a second opinion before " +
             "committing to an approach you would have to unwind. Do NOT use it for " +
             "lookups (use ask_yagni), for anything you can settle by reading the code, " +
-            "or to review work you have already finished. Pass a sharp question plus the " +
-            "relevant excerpts — never a conversation transcript.",
-        promptSnippet: "ask_advisor: escalate one hard judgment call to the peak-tier advisor (Advanced sessions, capped).",
-        promptGuidelines: [
+            "or to review work you have already finished. Pass a sharp question plus " +
+            "the relevant excerpts — never a conversation transcript."
+        : "Escalate ONE hard judgment call to the peak-tier advisor — the strongest " +
+            "model available, which reads the code itself and returns a recommendation. " +
+            "Available only on the Advanced tier, and capped per session, so use it for " +
+            "calls that are genuinely worth it: an architectural fork with no obvious " +
+            "right answer, a subtle correctness question you cannot settle by reading, " +
+            "a change whose blast radius you are unsure of, or a second opinion before " +
+            "committing to an approach you would have to unwind. Do NOT use it for " +
+            "anything you can settle by reading the code, or to review work you have " +
+            "already finished. Pass a sharp question plus the relevant excerpts — never " +
+            "a conversation transcript.";
+    const promptGuidelines = grounded
+        ? [
             "Call ask_advisor only for a genuine judgment fork — an architectural choice, a subtle correctness question, or a second opinion before an approach you would have to unwind. Reading the code is cheaper; do that first.",
             "Ask ONE specific question per consult, and include the excerpts that matter. The advisor reads the repo itself, so point it at the right place rather than pasting everything.",
             "Consults are capped per session. Spend them on the calls you would otherwise get wrong.",
             "The advice comes back as plain text: act on it, and call record_decision when it settles a product-intent call so the next agent inherits it.",
-        ],
+        ]
+        : [
+            "Call ask_advisor only for a genuine judgment fork — an architectural choice, a subtle correctness question, or a second opinion before an approach you would have to unwind. Reading the code is cheaper; do that first.",
+            "Ask ONE specific question per consult, and include the excerpts that matter. The advisor reads the repo itself, so point it at the right place rather than pasting everything.",
+            "Consults are capped per session. Spend them on the calls you would otherwise get wrong.",
+        ];
+    // The default runner rides the /go pipeline's resilience wrapper, exactly
+    // like the subagent tool: idle + wall-clock ceilings and transient-only
+    // retry, so a stalled consult child aborts honestly instead of hanging the
+    // driver's tool call until the user presses Esc. The synthetic stage id is
+    // "plan" (read-only tools, no bash), so the wrapper's write-gate never
+    // blocks a retry — re-running a consult cannot double-apply anything.
+    const runStage = opts.runStage ?? withResilience(defaultRunStage, DEFAULT_RESILIENCE_POLICY);
+    return {
+        name: "ask_advisor",
+        label: "Ask the advisor",
+        description,
+        promptSnippet: "ask_advisor: escalate one hard judgment call to the peak-tier advisor (Advanced sessions, capped).",
+        promptGuidelines,
         parameters,
         // Self-framed: the condensed transcript look has no tinted tool boxes.
         renderShell: "self",
@@ -172,7 +199,10 @@ export function makeAskAdvisorTool(opts) {
             emit();
             let result;
             try {
-                result = await runStage(advisorStage(), { ticket: buildConsultBrief(params) }, {
+                result = await runStage(advisorStage(grounded), 
+                // `grounded` selects the persona body in the runner's personaBody
+                // seam: false = ADVISOR_BLIND (the M6 blind lane's body).
+                { ticket: buildConsultBrief(params), grounded }, {
                     cwd: ctx?.cwd ?? process.cwd(),
                     ...(signal ? { signal } : {}),
                     // YAG-471: attribute the consult's completions to the advisor, not

package/dist/extension/askUserQuestionTool.d.ts

@@ -48,7 +48,14 @@ type AskDetails = {
     questions: Question[];
     answers: Record<string, string>;
 };
-/** Build the ask_user_question tool. Register it unconditionally (like ask_advisor). */
-export declare function makeAskUserQuestionTool(): ToolDefinition<typeof parameters, AskDetails>;
+/**
+ * Build the ask_user_question tool. Registered unconditionally (like
+ * ask_advisor): the tool itself is not a grounding surface, but its metadata
+ * references the recorded-answer lookup, so `grounded: false` swaps in the
+ * reference-free variants.
+ */
+export declare function makeAskUserQuestionTool(opts?: {
+    grounded?: boolean;
+}): ToolDefinition<typeof parameters, AskDetails>;
 export {};
 //# sourceMappingURL=askUserQuestionTool.d.ts.map

package/dist/extension/askUserQuestionTool.js

@@ -70,6 +70,9 @@ const PROMPT_GUIDELINES = [
     "If you recommend a specific option, make it the first one and append '(Recommended)' to its label.",
     "Do not use this tool for feedback like 'does the plan look good?' — ask a real choice with real options.",
 ];
+/** The grounding-free guideline list: the recorded-answer clause drops its
+ * ask_yagni reference (the tool is unregistered under `grounding: false`). */
+const PROMPT_GUIDELINES_GROUNDING_FREE = PROMPT_GUIDELINES.map((g) => g.replace(" — and the answer is not already recorded (check ask_yagni first)", ""));
 /**
  * Whether any option in the question has a preview. Drives the two-column
  * layout (Claude switches to side-by-side only when previews exist).
@@ -566,15 +569,19 @@ async function askOne(ctx, q, qIndex) {
     logAskQuestion({ event: "resolved", status: "selected", detail: `values:${resolution.values.length}`, qIndex });
     return { answer: resolution.values.join(", "), cancelled: false };
 }
-function buildTool() {
+function buildTool(grounded = true) {
     return {
         name: TOOL_NAME,
         label: "Ask user a question",
-        description: "Pose a structured multiple-choice question to the user during execution and get back a clean machine-readable answer. " +
-            "Use when you genuinely need a human decision (an architectural fork, a product-intent call with no recorded answer, or a choice between approaches)." +
-            "Each question has 2-4 mutually exclusive options, each with a description of its tradeoff and an optional preview.",
+        description: grounded
+            ? "Pose a structured multiple-choice question to the user during execution and get back a clean machine-readable answer. " +
+                "Use when you genuinely need a human decision (an architectural fork, a product-intent call with no recorded answer, or a choice between approaches)." +
+                "Each question has 2-4 mutually exclusive options, each with a description of its tradeoff and an optional preview."
+            : "Pose a structured multiple-choice question to the user during execution and get back a clean machine-readable answer. " +
+                "Use when you genuinely need a human decision (an architectural fork, a product-intent call, or a choice between approaches)." +
+                "Each question has 2-4 mutually exclusive options, each with a description of its tradeoff and an optional preview.",
         promptSnippet: PROMPT_SNIPPET,
-        promptGuidelines: PROMPT_GUIDELINES,
+        promptGuidelines: grounded ? PROMPT_GUIDELINES : PROMPT_GUIDELINES_GROUNDING_FREE,
         parameters,
         async execute(_toolCallId, params, _signal, onUpdate, ctx) {
             onUpdate?.({ content: [{ type: "text", text: "Asking you…" }], details: { questions: [], answers: {} } });
@@ -636,8 +643,13 @@ function buildTool() {
         },
     };
 }
-/** Build the ask_user_question tool. Register it unconditionally (like ask_advisor). */
-export function makeAskUserQuestionTool() {
-    return buildTool();
+/**
+ * Build the ask_user_question tool. Registered unconditionally (like
+ * ask_advisor): the tool itself is not a grounding surface, but its metadata
+ * references the recorded-answer lookup, so `grounded: false` swaps in the
+ * reference-free variants.
+ */
+export function makeAskUserQuestionTool(opts = {}) {
+    return buildTool(opts.grounded !== false);
 }
 //# sourceMappingURL=askUserQuestionTool.js.map

package/dist/extension/branding.d.ts

@@ -100,6 +100,21 @@ export declare const COMMUNICATION_CONTRACT: string;
 export declare const WRITE_FINDINGS_DOWN: string;
 /** The driver identity while /ultra is on: base identity + the diamond directive. */
 export declare const YAGNI_IDENTITY_ULTRA = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation (ultra mode): the user has switched this session to ultra mode \u2014 aggressive multi-agent orchestration. Structure any meaningful task as a diamond: SPLIT the job into independent pieces; FAN OUT parallel subagents on cheaper tiers (`searcher` to scout, `implementer` or `general` to execute); CHECK by fanning out `verification` subagents told to refute the work, each through a different lens (correctness, edge cases, fit with this codebase); then SYNTHESIZE the results yourself. Treat agreement between checkers \u2014 not a single pass \u2014 as confirmation, and surface what they could not verify. Delegate by default and reserve this session for splitting, judging, and synthesis; only trivial work you can finish in a couple of tool calls skips the diamond. Subagents cannot touch your TodoWrite checklist, so keep it current yourself: update it when you split the job and again as each fanned-out piece lands, not only at the end.";
+/**
+ * The grounding-FREE identity for `grounding: false` boots: the role and
+ * anti-confusion sentences of {@link YAGNI_IDENTITY} with the grounding
+ * sentence ("Uniquely, you are connected to the YAGNI app… Use the ask_yagni
+ * tool…") removed. The `grounding` settings switch severs the judgment loop
+ * in both directions; an identity that still instructs the model to consult
+ * ask_yagni (an unregistered tool) would be friction and influence referencing
+ * a surface the user turned off. Kept as a SEPARATE constant so the grounded
+ * prompt text stays byte-identical (the blind-lane pattern).
+ */
+export declare const YAGNI_IDENTITY_GROUNDING_FREE: string;
+/** The grounding-free driver identity (base + delegation, verbatim). */
+export declare const YAGNI_IDENTITY_DRIVER_GROUNDING_FREE = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation: fan codebase mapping, wide searches, and mechanical multi-file work out to subagents (they run on cheaper tiers). Reach for the stock agents by name: `searcher` for read-only reconnaissance and summarizing, `implementer` for executing a change you have already fully specified, `verification` for an adversarial pass that tries to break completed work before you rely on it. Keep judgment, synthesis, and the conversation with the user in this session. Do not spawn a subagent for work you can finish in a couple of tool calls.";
+/** The grounding-free ultra identity (base + diamond, verbatim). */
+export declare const YAGNI_IDENTITY_ULTRA_GROUNDING_FREE = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation (ultra mode): the user has switched this session to ultra mode \u2014 aggressive multi-agent orchestration. Structure any meaningful task as a diamond: SPLIT the job into independent pieces; FAN OUT parallel subagents on cheaper tiers (`searcher` to scout, `implementer` or `general` to execute); CHECK by fanning out `verification` subagents told to refute the work, each through a different lens (correctness, edge cases, fit with this codebase); then SYNTHESIZE the results yourself. Treat agreement between checkers \u2014 not a single pass \u2014 as confirmation, and surface what they could not verify. Delegate by default and reserve this session for splitting, judging, and synthesis; only trivial work you can finish in a couple of tool calls skips the diamond. Subagents cannot touch your TodoWrite checklist, so keep it current yourself: update it when you split the job and again as each fanned-out piece lands, not only at the end.";
 export declare const PI_IDENTITY_RE: RegExp;
 /**
  * Env switch that bypasses the system-prompt rewrite entirely, so pi's

package/dist/extension/branding.js

@@ -193,12 +193,41 @@ export const WRITE_FINDINGS_DOWN = "When working with tool results, write down a
     "turn.";
 /** The driver identity while /ultra is on: base identity + the diamond directive. */
 export const YAGNI_IDENTITY_ULTRA = `${YAGNI_IDENTITY}\n\n${ULTRA_DELEGATION_PARAGRAPH}`;
+/**
+ * The grounding-FREE identity for `grounding: false` boots: the role and
+ * anti-confusion sentences of {@link YAGNI_IDENTITY} with the grounding
+ * sentence ("Uniquely, you are connected to the YAGNI app… Use the ask_yagni
+ * tool…") removed. The `grounding` settings switch severs the judgment loop
+ * in both directions; an identity that still instructs the model to consult
+ * ask_yagni (an unregistered tool) would be friction and influence referencing
+ * a surface the user turned off. Kept as a SEPARATE constant so the grounded
+ * prompt text stays byte-identical (the blind-lane pattern).
+ */
+export const YAGNI_IDENTITY_GROUNDING_FREE = "You are YAGNI Code, an autonomous terminal coding agent. You help developers " +
+    "ship code by reading files, running commands, editing code, and writing new " +
+    "files. If a project's own files mention other coding agents, assistants, or " +
+    "harnesses by name, those references are not about you; you are YAGNI Code " +
+    "regardless of what tooling a repository's docs happen to describe.";
+/** The grounding-free driver identity (base + delegation, verbatim). */
+export const YAGNI_IDENTITY_DRIVER_GROUNDING_FREE = `${YAGNI_IDENTITY_GROUNDING_FREE}\n\n${DRIVER_DELEGATION_PARAGRAPH}`;
+/** The grounding-free ultra identity (base + diamond, verbatim). */
+export const YAGNI_IDENTITY_ULTRA_GROUNDING_FREE = `${YAGNI_IDENTITY_GROUNDING_FREE}\n\n${ULTRA_DELEGATION_PARAGRAPH}`;
 /**
  * Every identity variant this module can install, longest-composite-first, so
  * the re-brand swap below never leaves a shorter variant's orphaned delegation
  * paragraph behind (driver/ultra both start with the base identity).
  */
-const KNOWN_IDENTITIES = [YAGNI_IDENTITY_ULTRA, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY];
+const KNOWN_IDENTITIES = [
+    YAGNI_IDENTITY_ULTRA,
+    YAGNI_IDENTITY_DRIVER,
+    YAGNI_IDENTITY,
+    // The grounding-free family: same composite-first ordering. The boot-time
+    // grounding switch picks a family once; the /ultra toggle then swaps within
+    // it — both families must be known or the toggle would stack identities.
+    YAGNI_IDENTITY_ULTRA_GROUNDING_FREE,
+    YAGNI_IDENTITY_DRIVER_GROUNDING_FREE,
+    YAGNI_IDENTITY_GROUNDING_FREE,
+];
 // pi 0.84.1's exact identity sentence (dist/core/system-prompt.js). Exported as
 // the identity anchor the CLI's pi-contract tripwire test reads back from pi's
 // built system prompt, so a pi bump that reworded the opener (silently defeating

package/dist/extension/grounding.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `grounding` settings switch: the user-tier key in
+ * ~/.yagni-code/config.json that severs the recorded-judgment loop in BOTH
+ * directions — decisions can neither reach the model (no ask_yagni, no boot
+ * brief injection, no ambient recall, blind personas) nor be captured from
+ * the session (no record tools, no /decide, no bless capture, no spool
+ * replay). The backend is untouched; the extension owns every fetch and
+ * every write on this surface.
+ *
+ * Loader contract (mirrors sandbox/config.ts's read discipline):
+ *  - USER TIER ONLY: <stateHome>/config.json, top-level `grounding`. The
+ *    project/local tiers are never consulted — a committed repo config
+ *    cannot silently re-enable or disable a developer's judgment loop.
+ *  - default ON: absent key, absent file, malformed JSON, or a non-boolean
+ *    value all mean grounded (today's behavior). Fail-soft by design: a
+ *    corrupt config must not wedge the agent's boot.
+ *  - a malformed/invalid config warns to the error sink (source "grounding")
+ *    with the error CLASS only — never the parse message, which embeds a
+ *    snippet of the file's own content.
+ */
+export interface GroundingLoad {
+    /** False = the judgment loop is severed for this boot. */
+    enabled: boolean;
+    /** Present only when a config problem forced the default (fail-soft). */
+    warning?: string;
+}
+/**
+ * Read the `grounding` key from the user-tier config. Pure-ish (one file
+ * read + an optional sink warn); returns the resolved switch plus any
+ * fail-soft warning so callers and tests can assert both halves.
+ */
+/**
+ * The path a config warning names. The warn tier is upload-surfaceable
+ * (readSessionTrail keeps warn lines and /feedback binds them), and
+ * scrubSecrets redacts credentials, not paths — so the operator's personal
+ * default home collapses to ~. An OVERRIDDEN state home (YAGNI_CODE_HOME, an
+ * explicit env pin) is not personal — and the warning must name the file
+ * that is actually broken — so it stays literal there. PURE, exported for
+ * tests.
+ */
+export declare function displayConfigPath(stateHome: string): string;
+export declare function loadGroundingEnabled(stateHome: string, env?: NodeJS.ProcessEnv): GroundingLoad;
+/**
+ * The canonical "strip the grounding read tool" filter — one home for the
+ * rule so subagent spawns and advisor consults can't drift apart.
+ */
+export declare function stripGroundingTool(tools: readonly string[]): string[];
+//# sourceMappingURL=grounding.d.ts.map

package/dist/extension/grounding.js

@@ -0,0 +1,91 @@
+/**
+ * The `grounding` settings switch: the user-tier key in
+ * ~/.yagni-code/config.json that severs the recorded-judgment loop in BOTH
+ * directions — decisions can neither reach the model (no ask_yagni, no boot
+ * brief injection, no ambient recall, blind personas) nor be captured from
+ * the session (no record tools, no /decide, no bless capture, no spool
+ * replay). The backend is untouched; the extension owns every fetch and
+ * every write on this surface.
+ *
+ * Loader contract (mirrors sandbox/config.ts's read discipline):
+ *  - USER TIER ONLY: <stateHome>/config.json, top-level `grounding`. The
+ *    project/local tiers are never consulted — a committed repo config
+ *    cannot silently re-enable or disable a developer's judgment loop.
+ *  - default ON: absent key, absent file, malformed JSON, or a non-boolean
+ *    value all mean grounded (today's behavior). Fail-soft by design: a
+ *    corrupt config must not wedge the agent's boot.
+ *  - a malformed/invalid config warns to the error sink (source "grounding")
+ *    with the error CLASS only — never the parse message, which embeds a
+ *    snippet of the file's own content.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { logEvent } from "./errorSink.js";
+/**
+ * Read the `grounding` key from the user-tier config. Pure-ish (one file
+ * read + an optional sink warn); returns the resolved switch plus any
+ * fail-soft warning so callers and tests can assert both halves.
+ */
+/**
+ * The path a config warning names. The warn tier is upload-surfaceable
+ * (readSessionTrail keeps warn lines and /feedback binds them), and
+ * scrubSecrets redacts credentials, not paths — so the operator's personal
+ * default home collapses to ~. An OVERRIDDEN state home (YAGNI_CODE_HOME, an
+ * explicit env pin) is not personal — and the warning must name the file
+ * that is actually broken — so it stays literal there. PURE, exported for
+ * tests.
+ */
+export function displayConfigPath(stateHome) {
+    const defaultHome = join(homedir(), ".yagni-code");
+    return stateHome === defaultHome ? "~/.yagni-code/config.json" : join(stateHome, "config.json");
+}
+export function loadGroundingEnabled(stateHome, env) {
+    const displayPath = displayConfigPath(stateHome);
+    const path = join(stateHome, "config.json");
+    if (!existsSync(path))
+        return { enabled: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        const warning = `grounding: could not parse ${displayPath}: ${err instanceof Error ? err.constructor.name : typeof err} — staying grounded`;
+        warnConfig(warning, env);
+        return { enabled: true, warning };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const warning = `grounding: config at ${displayPath} is not an object — staying grounded`;
+        warnConfig(warning, env);
+        return { enabled: true, warning };
+    }
+    const value = parsed.grounding;
+    if (value === undefined)
+        return { enabled: true };
+    if (typeof value !== "boolean") {
+        const warning = `grounding: "grounding" in ${displayPath} must be a boolean — staying grounded`;
+        warnConfig(warning, env);
+        return { enabled: true, warning };
+    }
+    return { enabled: value };
+}
+/**
+ * The canonical "strip the grounding read tool" filter — one home for the
+ * rule so subagent spawns and advisor consults can't drift apart.
+ */
+export function stripGroundingTool(tools) {
+    return tools.filter((t) => t !== "ask_yagni");
+}
+function warnConfig(warning, env) {
+    // The warning carries only the file path + the error CLASS — never a parse
+    // message (those embed the file's own content). Same posture as the sandbox
+    // loader's config warnings.
+    logEvent({
+        source: "grounding",
+        level: "warn",
+        event: "config_warning",
+        sessionId: env?.YAGNI_SESSION_ID,
+        fields: { warning },
+    });
+}
+//# sourceMappingURL=grounding.js.map

package/dist/extension/index.d.ts

@@ -88,6 +88,13 @@ export interface RegisterYagniDeps {
     tokenProvider?: TokenProvider;
     /** The spool flush (R4 write half), injectable so tests never touch disk. */
     flushSpool?: (opts: SpoolClientOpts) => Promise<FlushOutcome>;
+    /**
+     * The `grounding` settings switch seam. Defaults to the real user-config
+     * read (top-level `grounding` in ~/.yagni-code/config.json, default true).
+     * Inject `false` in tests to assert the gated wiring; inject nothing and
+     * the factory never touches disk beyond that one read.
+     */
+    grounding?: boolean;
     /**
      * Non-fatal auth-event reporter (YAG-500 Fix E). Defaults to
      * `makeCrashReporter` gated on `!evalMode`; inject a spy in tests to assert