@yagni-app/code-staging 1.1.1-staging.1358.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

package/dist/extension/index.js

@@ -15,7 +15,7 @@ import { registerCmuxBridge } from "./cmux/index.js";
 import { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
-import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA } from "./branding.js";
+import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_DRIVER_GROUNDING_FREE, YAGNI_IDENTITY_GROUNDING_FREE, YAGNI_IDENTITY_ULTRA, YAGNI_IDENTITY_ULTRA_GROUNDING_FREE } from "./branding.js";
 import { claudeRulesSection } from "./claudeRules.js";
 import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadSection } from "./scratchpad.js";
 import { registerCostCommand } from "./costHud.js";
@@ -47,6 +47,7 @@ import { createUltraHolder, registerUltraCommand } from "./ultra.js";
 import { registerTodos } from "./todos.js";
 import { registerDecisionCommands } from "./decisions.js";
 import { makeDecisionCapture } from "./decisionCapture.js";
+import { loadGroundingEnabled } from "./grounding.js";
 import { registerAmbientRecall } from "./recall.js";
 import { resilientFetch } from "./resilientFetch.js";
 import { installUncaughtExceptionMonitor, makeCrashReporter, runningUnderTest } from "./crashReport.js";
@@ -146,6 +147,27 @@ export async function registerYagni(pi, deps = {}) {
     const fetchCatalog = deps.fetchCatalog ?? defaultFetchCatalog;
     const env = deps.env ?? process.env;
     const evalMode = isEvalMode(env);
+    // The grounding settings switch (the judgment-loop kill switch): resolved
+    // ONCE at boot from the USER-tier config (default on; a malformed config
+    // fails soft to on with a sink warn). Eval mode is its own carve-out and
+    // stays orthogonal — a scoping/eval session keeps its measured behavior.
+    const groundingLoad = deps.grounding !== undefined
+        ? { enabled: deps.grounding }
+        : loadGroundingEnabled(codeStateHome(null, env), env);
+    const grounding = groundingLoad.enabled;
+    if (!grounding) {
+        logEvent({
+            source: "grounding",
+            level: "info",
+            event: "grounding_disabled",
+            sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            fields: {},
+        });
+    }
+    // The fail-soft warn half (a malformed config silently ignored the user's
+    // switch): keep it for the session_start surface below — the local sink
+    // alone is invisible to the developer who asked for the switch.
+    const groundingConfigWarning = groundingLoad.warning;
     // The refreshing TokenProvider replaces the old boot-time token snapshot:
     // tools read the CURRENT token per call, a proactive unref'd timer rotates
     // it near expiry, and `authedFetch` gives every tool's 401 path a single
@@ -220,7 +242,12 @@ export async function registerYagni(pi, deps = {}) {
     // in_progress (Claude's currentTodo?.activeForm pattern). TUI-gated
     // internally (agent_start checks ctx.mode).
     const workingLine = registerWorkingLine(pi, { todoVerb: todosHandle.activeVerb });
-    pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
+    // The grounding read gate: with `grounding: false`, the judgment loop is
+    // severed in both directions — ask_yagni (the consultation read) is never
+    // registered, so no recorded decision reaches the model through it.
+    if (grounding) {
+        pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
+    }
     // WebFetch (YAG-578): read an arbitrary URL as clean markdown + a
     // standard-tier extraction, replacing the bash + curl + python dance.
     pi.registerTool(makeWebFetchTool(toolOpts));
@@ -241,20 +268,27 @@ export async function registerYagni(pi, deps = {}) {
     // tasks, advisor consults, Guardian reviews, /go runs) lands here so the
     // footer's session totals include what the per-child receipts print.
     const childUsage = makeChildUsageState();
-    const askAdvisorTool = makeAskAdvisorTool({ state: advisorState, workingLine, childUsage });
+    // The advisor consult itself stays available with grounding off (it is
+    // model escalation, not a judgment read); the consult just runs BLIND —
+    // the existing grounding-free advisor persona + the ask_yagni-free tool
+    // list — so no recorded decision reaches the consult either.
+    const askAdvisorTool = makeAskAdvisorTool({ state: advisorState, workingLine, childUsage, grounded: grounding });
     pi.registerTool(askAdvisorTool);
     // /advise runs the SAME tool, sharing the state handle, so a manual consult
     // draws on the same cap rather than opening a side channel around it.
     registerAdviseCommand(pi, askAdvisorTool);
     // Structured human questions: the model poses a closed 2-4-option question
     // and gets a clean machine-readable answer via ctx.ui.custom.
-    pi.registerTool(makeAskUserQuestionTool());
+    pi.registerTool(makeAskUserQuestionTool({ grounded: grounding }));
     // The differentiated business-grounded tools (loop bricks): review a change
     // for business fit, rank the next work by business priority, and record the
-    // engineering rationale back onto the work-item.
-    pi.registerTool(makeReviewBusinessMatchTool(toolOpts));
-    pi.registerTool(makeSuggestNextWorkTool(toolOpts));
-    if (!evalMode) {
+    // engineering rationale back onto the work-item. All three read the recorded
+    // judgment, so they join the grounding gate.
+    if (grounding) {
+        pi.registerTool(makeReviewBusinessMatchTool(toolOpts));
+        pi.registerTool(makeSuggestNextWorkTool(toolOpts));
+    }
+    if (!evalMode && grounding) {
         pi.registerTool(makeRecordEngineeringContextTool(toolOpts));
         // The capture half of the judgment loop: bank a product-intent decision so
         // ask_yagni answers the same question next time instead of interrupting a human.
@@ -282,7 +316,7 @@ export async function registerYagni(pi, deps = {}) {
     // driver's delegation identity for the diamond directive (see the
     // before_agent_start handler below) and widens the tool's fan-out ceiling.
     const ultraHolder = createUltraHolder();
-    registerSubagents(pi, { isUltra: () => ultraHolder.get(), workingLine, childUsage });
+    registerSubagents(pi, { isUltra: () => ultraHolder.get(), workingLine, childUsage, grounded: grounding });
     // /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 });
@@ -296,6 +330,11 @@ export async function registerYagni(pi, deps = {}) {
     // map → plan → implement → review → fix, each child grounded by inheritance.
     registerGoCommand(pi, {
         childUsage,
+        // The grounding switch threads into every /go run: `grounded: false`
+        // selects the existing blind personas + blind lens clauses (the M6
+        // eval lane's machinery — see pipeline/personas.ts) and strips the
+        // grounding tools from the stage whitelists via the orchestrator.
+        grounded: grounding,
         // /ultra is one dial for the whole session: the same holder the subagent
         // tool reads widens the implement diamond's parallel ceiling (4 -> 8) for
         // the fan and its fix turns. Read per run, so a toggle lands on the next /go.
@@ -320,7 +359,10 @@ export async function registerYagni(pi, deps = {}) {
     });
     // M6 eval (report-only): /go-compare runs a ticket grounded vs blind and reports
     // the business-fit delta. Never wired to routing.
-    registerGoCompareCommand(pi);
+    // /go-compare measures grounded-vs-blind; with grounding off both lanes
+    // would be blind and its delta would lie. Don't register it.
+    if (grounding)
+        registerGoCompareCommand(pi);
     // YAG-580: /feedback (alias /bug) + /diagnostics. The capture/upload is the
     // whole point, so it is gated to non-eval mode like every external side
     // effect; the command's deps (doctor report, git state, child transcripts)
@@ -338,8 +380,8 @@ export async function registerYagni(pi, deps = {}) {
     // bless-with-remember capture are the same product-intent write as the record
     // tools, so both are gated together (skipped in eval mode).
     const decisionClientOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
-    const decisionCapture = evalMode ? undefined : makeDecisionCapture(decisionClientOpts);
-    if (!evalMode)
+    const decisionCapture = !evalMode && grounding ? makeDecisionCapture(decisionClientOpts) : undefined;
+    if (!evalMode && grounding)
         registerDecisionCommands(pi, decisionClientOpts);
     // Local MCP servers (standard client, replaces the backend-proxy /mcp of
     // the YAG-446 era): load user/project/local config, approval-gate project
@@ -973,18 +1015,25 @@ export async function registerYagni(pi, deps = {}) {
     // 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
-    // (<3 active decisions from /context.counts) or in eval mode.
-    registerAmbientRecall(pi, {
-        baseUrl,
-        getToken: getTokenFn,
-        fetchImpl: authedFetch,
-        decisionsCount: briefResult?.counts?.decisions ?? 0,
-        evalMode,
-    });
+    // (<3 active decisions from /context.counts) or in eval mode — and never
+    // registered at all under `grounding: false` (recorded decisions must not
+    // reach the model through any seam).
+    if (grounding) {
+        registerAmbientRecall(pi, {
+            baseUrl,
+            getToken: getTokenFn,
+            fetchImpl: authedFetch,
+            decisionsCount: briefResult?.counts?.decisions ?? 0,
+            evalMode,
+        });
+    }
     // ADR-0033: the Team-drafting flow is an explicit command, never a first-run
     // ceremony. /setup-team drafts the Engineering Team + engineering brief from
-    // the repo and banks the brief as one decision on approval.
-    registerTeamSetupCommand(pi, { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // the repo and banks the brief as one decision on approval — a judgment WRITE,
+    // so it joins the grounding gate.
+    if (grounding) {
+        registerTeamSetupCommand(pi, { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    }
     // Onramp Door B (spec §5B/§7, as amended by ADR-0033): on a FRESH workspace
     // (empty/thin grounding corpus), the first run shows a short welcome + one
     // next-work offer, with free text first-class — instead of a bare prompt. It
@@ -1088,12 +1137,21 @@ export async function registerYagni(pi, deps = {}) {
         ? undefined
         : {
             systemPrompt: brandSystemPrompt(event.systemPrompt, {
-                contextBrief,
-                identity: isDriver
-                    ? ultraHolder.get()
-                        ? YAGNI_IDENTITY_ULTRA
-                        : YAGNI_IDENTITY_DRIVER
-                    : undefined,
+                // Grounding gate: the boot fetch still ran (fresh-workspace
+                // detection), but with the switch off its text never reaches the
+                // model — no brief block, no ask_yagni nudge.
+                contextBrief: grounding ? contextBrief : undefined,
+                identity: !grounding
+                    ? isDriver
+                        ? ultraHolder.get()
+                            ? YAGNI_IDENTITY_ULTRA_GROUNDING_FREE
+                            : YAGNI_IDENTITY_DRIVER_GROUNDING_FREE
+                        : YAGNI_IDENTITY_GROUNDING_FREE
+                    : isDriver
+                        ? ultraHolder.get()
+                            ? YAGNI_IDENTITY_ULTRA
+                            : YAGNI_IDENTITY_DRIVER
+                        : undefined,
                 rulesSection,
                 scratchpadSection: scratchpadSectionText,
             }),
@@ -1336,12 +1394,33 @@ export async function registerYagni(pi, deps = {}) {
             catch {
                 // A notice must never disrupt session start.
             }
+            // A malformed user config silently forced the grounding default — the
+            // one surface where the user's kill switch was ignored. Same one-shot
+            // notify posture as the expiry notice; never breaks session start.
+            if (groundingConfigWarning) {
+                try {
+                    ctx.ui.notify(groundingConfigWarning, "warning");
+                }
+                catch {
+                    // A notice must never disrupt session start — but the sink line is
+                    // then the ONLY surviving trace of the ignored switch, so record
+                    // that the notify itself failed (content-free: the event name).
+                    logEvent({
+                        source: "grounding",
+                        level: "warn",
+                        event: "config_warning_notify_failed",
+                        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                        fields: {},
+                    });
+                }
+            }
         }
         // R4 write half: drain any judgment writes spooled by a previous session
         // (transport/5xx failures of record_decision / record_engineering_context).
         // Fire-and-forget and fail-soft — a flush must never delay or break session
         // start; honest notices (replays, expiry drops) surface when it finishes.
-        if (!evalMode) {
+        // A replay IS a capture write, so the grounding switch skips it entirely.
+        if (!evalMode && grounding) {
             void flushSpoolFn({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch })
                 .then((outcome) => {
                 if (!ctx.hasUI)
@@ -1361,6 +1440,7 @@ export async function registerYagni(pi, deps = {}) {
                     getToken: getTokenFn,
                     fetchImpl: authedFetch,
                     brief: briefResult,
+                    grounding,
                 });
                 // F2a: mark the workspace init-done on any real run (ran === true — thin
                 // or not), so it never re-seeds. A skip (not_fresh / non_interactive) is
@@ -1375,8 +1455,9 @@ export async function registerYagni(pi, deps = {}) {
         // Run 7: the opt-in repo seeding beat. Fires only on a genuine startup
         // when /context reported an explicitly-empty repo-scoped ledger, once per
         // repo (marker store). Fully fail-soft — a beat failure never blocks the
-        // session.
-        if (event.reason === "startup" && !evalMode) {
+        // session. Never offered under `grounding: false` — mining banks decisions
+        // (a judgment write).
+        if (event.reason === "startup" && !evalMode && grounding) {
             try {
                 const offerBeat = deps.offerMiningBeat ?? defaultMaybeOfferMiningBeat;
                 const markers = deps.mineBeatMarkers ?? fileMineBeatMarkers(codeStateHome(null, env));

package/dist/extension/initPass.d.ts

@@ -96,6 +96,13 @@ export interface RunInitPassDeps {
     baseUrl: string;
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
+    /**
+     * The boot-time grounding switch: with grounding off the welcome stays (it
+     * records nothing) but skips the next-work offer — `suggest_next_work` is
+     * unregistered, so the offer would steer to a dead surface — and shows a
+     * grounding-free notice. Defaults grounded.
+     */
+    grounding?: boolean;
     /**
      * A pre-fetched context brief (the caller usually already fetched it to boot
      * grounded). When `undefined`, the pass fetches it itself. Pass `null`

package/dist/extension/initPass.js

@@ -231,6 +231,10 @@ const WELCOME_NOTICE = "First run in this repo. Just type to start working. Ask
     "context (tickets, docs, decisions), or run /go <ticket> for a ticket-to-PR run.";
 /** The free-text choice: an untouched editor, ready for whatever they want to build. */
 const FREE_TEXT_LABEL = "Just start typing";
+/** The grounding-free welcome: no company-context advertising (the switch
+ * turned that surface off), just the doors that still exist. */
+const WELCOME_NOTICE_GROUNDING_FREE = "First run in this repo. Just type to start working, or run /go <ticket> " +
+    "for a ticket-to-PR run.";
 /**
  * Run the first-run welcome (ADR-0033). Guards on fresh-workspace detection
  * (defensive — the caller also guards), shows a short how-to-work-with-YAGNI
@@ -256,8 +260,14 @@ export async function runInitPass(pi, ctx, deps) {
     const ui = (ctx.hasUI ? ctx.ui : undefined);
     if (!ui)
         return { ran: false, reason: "non_interactive" };
+    const grounding = deps.grounding !== false;
     const notify = safeNotify(ui);
-    notify(WELCOME_NOTICE, "info");
+    notify(grounding ? WELCOME_NOTICE : WELCOME_NOTICE_GROUNDING_FREE, "info");
+    if (!grounding) {
+        // The offer's primary action is `suggest_next_work` — unregistered under
+        // the switch. Skip the offer; the editor stays ready for free text.
+        return { ran: true, chosenAction: "free_text" };
+    }
     // 2. Offer the ONE default next action (spec §7.3: defaults over choices),
     //    with free text as a first-class door. Everything here is best-effort:
     //    whatever happens, the user ends at a prompt they can just type into.

package/dist/extension/pipeline/goCommand.d.ts

@@ -136,6 +136,14 @@ export interface RegisterGoDeps {
      * test) simply means "not ultra", which is today's behavior.
      */
     isUltra?: () => boolean;
+    /**
+     * The boot-time `grounding` settings switch, threaded into the orchestrator's
+     * `grounded` flag: false runs the whole pipeline on the existing blind
+     * personas + blind lens clauses (the M6 eval lane's machinery) with the
+     * grounding tools stripped from the stage whitelists. Defaults true — an
+     * unwired embedder or test keeps today's grounded behavior.
+     */
+    grounded?: boolean;
     baseUrl?: string;
     getToken?: () => string | undefined;
     /**

package/dist/extension/pipeline/goCommand.js

@@ -432,6 +432,9 @@ export function registerGoCommand(pi, deps = {}) {
     // The dial is held, never its value: /ultra can be toggled between runs, so
     // the pipeline calls it when it needs the ceiling rather than reading it here.
     const isUltra = deps.isUltra;
+    // The boot-time grounding switch (defaults grounded): false runs the
+    // pipeline on the blind personas via the orchestrator's `grounded` flag.
+    const goGrounded = deps.grounded !== false;
     // Task 8: no default — see the RegisterGoDeps doc comment for why (only
     // index.ts's real wiring makes sense here; absent, `resolveCostText` falls
     // back to the local client estimate).
@@ -448,7 +451,9 @@ export function registerGoCommand(pi, deps = {}) {
             getToken: deps.getToken ?? defaultGetToken,
         });
     pi.registerCommand("go", {
-        description: "Run the grounded multi-agent pipeline (map → plan → implement → review → fix) on a ticket and produce a reviewed change.",
+        description: goGrounded
+            ? "Run the grounded multi-agent pipeline (map → plan → implement → review → fix) on a ticket and produce a reviewed change."
+            : "Run the multi-agent pipeline (map → plan → implement → review → fix) on a ticket and produce a reviewed change.",
         handler: async (args, ctx) => {
             const notify = (message, type) => {
                 if (ctx.hasUI)
@@ -910,6 +915,7 @@ export function registerGoCommand(pi, deps = {}) {
                         cwd: runCwd,
                         signal: runSignal,
                         fanout: fanoutMode,
+                        grounded: goGrounded,
                         ...(isUltra ? { isUltra } : {}),
                         ...(ticketBrief ? { ticketBrief } : {}),
                         onProgress: (p) => {

package/dist/extension/pipeline/headlessGo.js

@@ -52,6 +52,8 @@ import { resolveFanoutMode } from "./fanout.js";
 import { makeFanoutBeats } from "./fanoutBeats.js";
 import { normalizeMission } from "./mission.js";
 import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
+import { loadGroundingEnabled } from "../grounding.js";
+import { codeStateHome } from "../stateHome.js";
 import { parseTierCap, TIER_CAP_ENV } from "./tierCap.js";
 /** One-line usage copy, shared by every argument error. */
 export const HEADLESS_GO_USAGE = "Usage: yagni go --headless --ticket-file <path> [--plan-file <path>] [--memo-file <path>] [--run-id <id>] [--cwd <path>] [--json]";
@@ -202,6 +204,11 @@ export async function runHeadlessGo(argv, deps = {}) {
     const readFile = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
     const runPipeline = deps.runPipeline ?? defaultRunPipeline;
     const env = deps.env ?? process.env;
+    // The grounding switch's default for a headless run: the user-tier config
+    // (the same key the interactive extension reads at boot). An explicit
+    // deps.grounded (an eval lane pinning its lane) always wins — the eval's
+    // measurement determinism is untouched.
+    const grounding = deps.grounded ?? loadGroundingEnabled(codeStateHome(null, env), env).enabled;
     const args = parseHeadlessGoArgs(argv);
     const problem = validateHeadlessGoArgs(args);
     if (problem) {
@@ -278,7 +285,7 @@ export async function runHeadlessGo(argv, deps = {}) {
         ...(deps.signal ? { signal: deps.signal } : {}),
         ...(deps.budget ? { budget: deps.budget } : {}),
         ...(deps.stages ? { stages: deps.stages } : {}),
-        ...(deps.grounded !== undefined ? { grounded: deps.grounded } : {}),
+        grounded: deps.grounded ?? grounding,
         ...(mission ? { mission } : {}),
         onEvent: (ev, tag) => {
             deps.onEvent?.(ev, tag);

package/dist/extension/subagents.d.ts

@@ -72,12 +72,9 @@ export interface DiscoverDeps {
  */
 export declare function discoverSubagents(deps: DiscoverDeps): SubagentDef[];
 export declare function formatAgentList(agents: SubagentDef[]): string;
-/**
- * A subagent invocation is a synthetic pipeline stage: the task rides in as
- * `{ticket}` verbatim, and the agent's body replaces the /go persona through
- * the runner's personaBody seam.
- */
-export declare function buildSubagentStage(def: SubagentDef, task: string): {
+export declare function buildSubagentStage(def: SubagentDef, task: string, opts?: {
+    grounded?: boolean;
+}): {
     stage: PipelineStage;
     ctx: {
         ticket: string;
@@ -98,6 +95,13 @@ export interface MakeSubagentToolDeps {
     homeDir?: string;
     /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
     isUltra?: () => boolean;
+    /**
+     * The boot-time grounding switch (defaults grounded): false spawns every
+     * subagent with the grounding read stripped from its tool list and the
+     * grounding-free twin body for BUILTIN agents (user/project bodies ride
+     * verbatim — they are the user's own content).
+     */
+    grounded?: boolean;
     /**
      * The session working-line manager (workingLine.ts). When present, live
      * progress goes through it (so the elapsed/token suffix survives); absent,
@@ -157,6 +161,8 @@ export interface RegisterSubagentsDeps {
     homeDir?: string;
     /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
     isUltra?: () => boolean;
+    /** The boot-time grounding switch; false spawns blind subagents. */
+    grounded?: boolean;
     /** Session working-line manager; see MakeSubagentToolDeps.workingLine. */
     workingLine?: WorkingLineHandle;
     /** Session child-usage accumulator; see MakeSubagentToolDeps.childUsage. */

package/dist/extension/subagents.js

@@ -318,16 +318,98 @@ export function formatAgentList(agents) {
  * `{ticket}` verbatim, and the agent's body replaces the /go persona through
  * the runner's personaBody seam.
  */
-export function buildSubagentStage(def, task) {
+/**
+ * Grounding-free twins of the four builtin bodies: the same capable roles
+ * with the "You are grounded in how THIS company works: call ask_yagni…"
+ * clause removed (the blind-lane pattern — separate constants, so the
+ * grounded prompt text stays byte-identical). Only BUILTIN agents have
+ * twins; user/project-defined bodies are the user's own content and ride
+ * verbatim.
+ */
+const GENERAL_BODY_GROUNDING_FREE = `You are a capable software-engineering subagent with a fresh context window. Complete the task you are given end to end, autonomously.
+
+Never fabricate file paths, contents, or findings. If you cannot find something, say so.
+
+Complete the task fully — do not gold-plate, but do not leave it half-done. Your final message is your report back to the driving agent, which has NOT seen what you read or did: make it a concise report of what was done and the key findings, since the caller relays it to the user and it only needs the essentials. Cover what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
+const SEARCHER_BODY_GROUNDING_FREE = `You are a repo scout. Your job is wide, mechanical reconnaissance:
+find files, map structure, trace usages, and summarize what is there. You do
+not write code and you do not run commands; you read and report.
+
+Never fabricate file paths, contents, or code. Every path you cite must be
+one you actually read with a tool. If you cannot find something, say "not
+found" — a plausible-sounding invention is worse than no answer because the
+driving agent trusts your report.
+
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
+Your final message is your report back to the driving agent, which has NOT
+seen what you read. Make it compressed and complete: exact file paths, the
+key excerpts, and a one-paragraph map of how the pieces relate. Say what you
+did NOT find as plainly as what you found.`;
+const IMPLEMENTER_BODY_GROUNDING_FREE = `You are a mechanical implementer. You execute a
+well-specified change: apply an edit across files, fix a failing test, rename
+carefully, wire a defined seam. The judgment calls were made before you were
+spawned; if the task turns out to require one, STOP and report the fork in
+your final message instead of guessing.
+
+Never fabricate file paths or results. Report what you actually did and what
+you actually found.
+
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
+Your final message is your report back to the driving agent, which has NOT
+seen what you did. List every file you touched, what changed in each, the
+commands you ran with their outcomes, and anything you deliberately left
+undone.`;
+const VERIFICATION_BODY_GROUNDING_FREE = `You are an adversarial verifier. Another agent
+produced work — a change, a plan, or a claim — and your job is to try to
+BREAK it, not to summarize it. Default to skepticism: hunt for the concrete
+failure scenario (the inputs, state, or sequence that makes it wrong). Bash
+is read-only here (\`git diff\`, \`git log\`, \`git show\`); do NOT modify files
+or run builds.
+
+If your task names a lens (correctness, edge cases, codebase fit, security,
+…), judge ONLY through that lens and leave the rest to your sibling
+verifiers.
+
+Never fabricate file paths or findings. If you could not verify something,
+say exactly what you tried and why you could not.
+
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
+Your final message is your verdict back to the driving agent, which has NOT
+seen what you read. Format:
+## Verdict
+BROKEN or HOLDS, with one sentence why.
+## Findings
+Each real problem: file:line, the concrete failure scenario, severity. No
+style nits.
+## Not verified
+What you could not check, and why.
+
+A HOLDS after real digging is valuable; a rubber stamp is not. If you found
+nothing, say exactly what you tried to break and how.`;
+/** Builtin-body twins keyed by agent name; absent = not a builtin. */
+const BUILTIN_BLIND_BODIES = {
+    [GENERAL_AGENT_NAME]: GENERAL_BODY_GROUNDING_FREE,
+    searcher: SEARCHER_BODY_GROUNDING_FREE,
+    implementer: IMPLEMENTER_BODY_GROUNDING_FREE,
+    verification: VERIFICATION_BODY_GROUNDING_FREE,
+};
+/** The canonical grounding-strip filter lives in grounding.ts; one home,
+ * shared with the advisor consults. */
+import { stripGroundingTool } from "./grounding.js";
+export function buildSubagentStage(def, task, opts = {}) {
+    const grounded = opts.grounded !== false;
     return {
         stage: {
             id: "implement",
             agent: def.name,
             model: def.model,
-            tools: def.tools ?? DEFAULT_SUBAGENT_TOOLS,
+            tools: grounded ? def.tools ?? DEFAULT_SUBAGENT_TOOLS : stripGroundingTool(def.tools ?? DEFAULT_SUBAGENT_TOOLS),
             taskTemplate: "{ticket}",
         },
-        ctx: { ticket: task, grounded: true },
+        ctx: { ticket: task, grounded },
     };
 }
 const parameters = Type.Object({
@@ -351,6 +433,15 @@ export function makeSubagentTool(deps = {}) {
     // landed a partial edit.
     const run = deps.runStageImpl ?? withResilience(runStage, DEFAULT_RESILIENCE_POLICY);
     const discover = deps.discover ?? discoverSubagents;
+    const grounded = deps.grounded !== false;
+    // Resolve the effective body for a spawned subagent: the grounding-free
+    // twin for builtins under `grounding: false`; the definition's own body
+    // everywhere else (user/project content rides verbatim).
+    const bodyFor = (def) => {
+        if (grounded || def.source !== "builtin")
+            return def.body;
+        return BUILTIN_BLIND_BODIES[def.name] ?? def.body;
+    };
     return {
         name: SUBAGENT_TOOL_NAME,
         label: "Subagent",
@@ -423,11 +514,11 @@ export function makeSubagentTool(deps = {}) {
             try {
                 outcomes = await Promise.all(resolved.map(async ({ def, task }, index) => {
                     const progress = progresses[index];
-                    const { stage, ctx: stageCtx } = buildSubagentStage(def, task);
+                    const { stage, ctx: stageCtx } = buildSubagentStage(def, task, { grounded });
                     const result = await run(stage, stageCtx, {
                         cwd,
                         signal,
-                        personaBody: () => def.body,
+                        personaBody: () => bodyFor(def),
                         // YAG-471: attribute this child's completions to the specific
                         // subagent, not the generic /go stage label the runner would
                         // otherwise derive from stage.id ("implement", reused as the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.1-staging.1358.1",
+  "version": "1.1.1-staging.1359.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "d3f818e827670951d1a080060578f482cbdd9fbc"
+  "yagniSourceSha": "beb4c9e3abfde8628b72e5b434d05ee2835f4bfc"
 }