@cleocode/core 2026.9.20 → 2026.9.22

package/dist/orchestration/spawn-prompt.js

@@ -13,7 +13,7 @@
  * |------|---------|
  * | 0    | Minimal: task metadata + return-format contract + evidence-gate commands |
  * | 1    | Standard (DEFAULT): tier 0 + CLEO-INJECTION.md embed + stage-specific guidance + quality-gate commands + absolute paths + session linkage |
- * | 2    | Full: tier 1 + ct-cleo + ct-orchestrator skill excerpts + SUBAGENT-PROTOCOL-BLOCK + anti-pattern reference |
+ * | 2    | Full: tier 1 + CLEO-REFERENCE.md embed + ct-cleo + ct-orchestrator skill excerpts + SUBAGENT-PROTOCOL-BLOCK + anti-pattern reference |
  *
  * ## Protocol phases (RCASD-IVTR+C)
  *
@@ -40,9 +40,12 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getProviderAskTool } from '@cleocode/caamp';
 import { normalizeSlug } from '../docs/slug-normalize.js';
-import { ISOLATION_ENV_KEYS, provisionIsolatedShell } from '../sdk/isolation.js';
-import { resolveSkillPath } from '../skills/skill-paths.js';
+import { provisionIsolatedShell } from '../sdk/isolation.js';
+import { resolveSkillLocation, resolveSkillPath } from '../skills/skill-paths.js';
+import { buildBudgetedPsycheMemoryBlock, relevanceContextFromTask, } from './psyche-memory-budget.js';
+import { coordinationTopic, waveTopic as waveTopicName } from './wave-topic.js';
 /**
  * Locate `packages/core/templates/CLEO-INJECTION.md` at runtime.
  *
@@ -62,15 +65,18 @@ import { resolveSkillPath } from '../skills/skill-paths.js';
  * Returns the absolute path to CLEO-INJECTION.md, or `null` if no layout
  * contains the file. The cached string in {@link loadCleoInjection} degrades
  * gracefully on `null`.
+ *
+ * @param fileName - Template file name; `CLEO-REFERENCE.md` locates the
+ *   on-demand reference that ships beside the core (T12580).
  */
-function locateCleoInjectionTemplate() {
+function locateCleoInjectionTemplate(fileName = 'CLEO-INJECTION.md') {
     const thisFile = fileURLToPath(import.meta.url);
     const candidates = [];
     // Layout 1 + 2: walk up from this file until we find a `templates/` sibling
     // of our own package (or hit filesystem root).
     let dir = dirname(thisFile);
     for (let i = 0; i < 8; i++) {
-        const direct = join(dir, 'templates', 'CLEO-INJECTION.md');
+        const direct = join(dir, 'templates', fileName);
         if (existsSync(direct))
             return direct;
         candidates.push(direct);
@@ -83,7 +89,7 @@ function locateCleoInjectionTemplate() {
     // few ancestor directories of the bundle.
     let baseDir = dirname(thisFile);
     for (let i = 0; i < 8; i++) {
-        const nm = join(baseDir, 'node_modules', '@cleocode', 'core', 'templates', 'CLEO-INJECTION.md');
+        const nm = join(baseDir, 'node_modules', '@cleocode', 'core', 'templates', fileName);
         if (existsSync(nm))
             return nm;
         const parent = resolve(baseDir, '..');
@@ -145,6 +151,7 @@ export const ALL_SPAWN_PROTOCOL_PHASES = [
 ];
 const CACHE = {
     cleoInjection: null,
+    cleoReference: null,
     ctCleoExcerpt: null,
     ctOrchestratorExcerpt: null,
     ctLeadExcerpt: null,
@@ -158,6 +165,7 @@ const CACHE = {
  */
 export function resetSpawnPromptCache() {
     CACHE.cleoInjection = null;
+    CACHE.cleoReference = null;
     CACHE.ctCleoExcerpt = null;
     CACHE.ctOrchestratorExcerpt = null;
     CACHE.ctLeadExcerpt = null;
@@ -186,30 +194,57 @@ function loadCleoInjection() {
     }
     return null;
 }
+/**
+ * Load the on-demand protocol reference (`CLEO-REFERENCE.md`) that ships
+ * beside CLEO-INJECTION.md. Returns `null` when absent so tier-2 assembly
+ * degrades to the core embed plus its `cleo briefing inject` pointers.
+ *
+ * @task T12580
+ */
+function loadCleoReference() {
+    if (CACHE.cleoReference !== null)
+        return CACHE.cleoReference;
+    try {
+        const templatePath = locateCleoInjectionTemplate('CLEO-REFERENCE.md');
+        if (templatePath) {
+            CACHE.cleoReference = readFileSync(templatePath, 'utf-8');
+            return CACHE.cleoReference;
+        }
+    }
+    catch {
+        // fall-through
+    }
+    return null;
+}
 /**
  * Load an excerpt from a skill's SKILL.md file.
  *
  * Excerpts are trimmed to the first N characters so that tier 2 prompts do
  * not balloon. If the skill is not found (CAAMP not installed, filesystem
- * error) returns `null` and the caller omits the excerpt.
+ * error) returns `null` and the caller omits the excerpt. A skill read from
+ * the bundled `@cleocode/skills` copy because it is not installed is prefixed
+ * with a notice saying so (T12646).
  */
 function loadSkillExcerpt(skillName, maxChars, projectRoot) {
-    const skillDir = resolveSkillPath(skillName, projectRoot);
-    if (!skillDir)
+    const location = resolveSkillLocation(skillName, projectRoot);
+    if (!location)
         return null;
-    const skillFile = join(skillDir, 'SKILL.md');
+    const skillFile = join(location.path, 'SKILL.md');
     if (!existsSync(skillFile))
         return null;
+    const notice = location.origin === 'bundled'
+        ? `> [${skillName} is not installed in this environment — excerpt read from the \`@cleocode/skills\` package]\n\n`
+        : '';
     try {
         const content = readFileSync(skillFile, 'utf-8');
         if (content.length <= maxChars)
-            return content;
+            return `${notice}${content}`;
         // Truncate at a newline boundary for readability.
         const sliced = content.slice(0, maxChars);
         const lastNewline = sliced.lastIndexOf('\n');
         return lastNewline > 0
-            ? `${sliced.slice(0, lastNewline)}\n\n> [excerpt — full skill at ${skillFile}]`
-            : `${sliced}\n\n> [excerpt — full skill at ${skillFile}]`;
+            ? `${notice}${sliced.slice(0, lastNewline)}\n\n> [excerpt — full skill at ${skillFile}]`
+            : `${notice}${sliced}\n\n> [excerpt — full skill at ${skillFile}]`;
     }
     catch {
         return null;
@@ -248,19 +283,20 @@ function loadSubagentProtocolBlock(projectRoot) {
  * Emitted when the orchestrate engine has pre-provisioned a git worktree for
  * the task (worktree-by-default per T1140 / ADR-055). The section:
  *
- * - Names the worktree absolute path and branch.
- * - States the context-isolation constraint so the agent knows it is
- *   authorized only within the worktree boundary.
- * - Provides the `FIRST ACTION` directive so the agent initializes its cwd.
- * - Warns that each Bash tool call starts a fresh shell — cwd does NOT persist
- *   between calls (T1758). Agents MUST re-cd at the start of every Bash call.
- * - Embeds the utility preamble from {@link provisionIsolatedShell} as the
- *   single source of truth for the cd-guard + env-export snippet, so the
- *   isolation contract is never duplicated (T1758).
+ * - Names the branch and task, and states the context-isolation constraint so
+ *   the agent knows it is authorized only within the worktree boundary.
+ * - Provides the `FIRST ACTION` directive and warns that each Bash tool call
+ *   starts a fresh shell — cwd does NOT persist between calls (T1758).
+ * - Embeds the preamble from {@link provisionIsolatedShell} as the ONE cd
+ *   guard and the only shell rendering of the worktree path (T12520). The
+ *   preamble single-quotes every path, so the commands survive a path with
+ *   spaces such as macOS `~/Library/Application Support/...`. Earlier versions
+ *   also emitted an unquoted `WORKTREE=<path>` snippet and a bare
+ *   `cd <path>` FIRST ACTION (both broke on every macOS worktree) plus a
+ *   stale `/mnt/projects/cleocode` example; all three are gone.
  *
- * When `--no-worktree` is passed at spawn time this function is not called
- * and the section is absent. Agents that encounter a prompt without this
- * section may still run on the primary worktree (backward compat).
+ * When there is no worktree (`--no-worktree`, or provisioning skipped) this
+ * function is not called and the section is absent.
  *
  * The `projectHash` is derived from the worktree path (second-to-last path
  * component per the canonical XDG layout: `.../worktrees/<hash>/<taskId>`).
@@ -272,6 +308,7 @@ function loadSubagentProtocolBlock(projectRoot) {
  *
  * @task T1140 — worktree-by-default spawn prompt
  * @task T1758 — harden tier-1 spawn prompt: cwd-reset warning + cd guard
+ * @task T12520 — quoted paths, one cd guard, no stale literal
  */
 function buildWorktreeSetupBlock(worktreePath, worktreeBranch, taskId, identity = {}) {
     // Derive projectHash from the canonical path layout:
@@ -294,58 +331,23 @@ function buildWorktreeSetupBlock(worktreePath, worktreeBranch, taskId, identity
         ...(identity.sessionId ? { sessionId: identity.sessionId } : {}),
         ...(identity.agentId ? { agentId: identity.agentId } : {}),
     });
-    // The cd guard snippet in a copy-pastable form for the CRITICAL section.
-    const cdGuardSnippet = `WORKTREE=${worktreePath}; cd "$WORKTREE" || exit 1; pwd | grep -q "$WORKTREE" || exit 1`;
-    // Enumerate the injected env keys for the note at the bottom.
-    const envKeyList = ISOLATION_ENV_KEYS.join(', ');
+    // T12520 — the preamble is the ONE cd guard and the only place a path is
+    // rendered as shell text; `provisionIsolatedShell` single-quotes every path,
+    // so the block stays valid under `~/Library/Application Support/...`. The
+    // prose below deliberately names no path (it would need its own quoting and
+    // would be a second, drifting copy of the guard).
     return [
-        '## Worktree Setup (REQUIRED) — STRICT ISOLATION',
-        '',
-        `> Authorized only within \`${worktreePath}\`.`,
+        '## Worktree Setup (REQUIRED)',
         '',
-        `- **Worktree**: \`${worktreePath}\``,
-        `- **Branch**: \`${worktreeBranch}\``,
-        `- **Task**: \`${taskId}\``,
+        `Authorized only within this worktree (branch \`${worktreeBranch}\`, task \`${taskId}\`). Never read or write the main checkout or any path outside the worktree in Edit/Write.`,
         '',
-        `**FIRST ACTION**: \`cd ${worktreePath}\``,
-        '',
-        '**CRITICAL — WORKTREE ISOLATION**:',
-        '1. After initial `cd`, `pwd` must show worktree path',
-        '2. Each Bash call starts a fresh shell. Re-`cd` at start of EVERY Bash call: `cd <worktree> && <command>`',
-        `3. NEVER \`cd /mnt/projects/cleocode\`. NEVER use absolute paths outside the worktree in Edit/Write`,
-        `4. Read merged branches via your worktree (it tracks \`main\`'s latest)`,
-        '',
-        '**WARNING — cwd does NOT persist between Bash calls**:',
-        'Each Bash tool invocation starts a new shell process. Your working directory',
-        'resets to the default every call. You MUST prefix every Bash call with the',
-        'worktree cd-guard below — failure to do so is the leading cause of agents',
-        'accidentally writing files to the wrong location.',
-        '',
-        'Ready-to-use cd-guard snippet (copy-paste to start every Bash call):',
-        '```bash',
-        cdGuardSnippet,
-        '```',
+        '**FIRST ACTION**: run the block below. Each Bash call starts a new shell and cwd does NOT persist between Bash calls, so begin EVERY Bash call with its `cd ... || exit 1` line.',
         '',
-        'Shell isolation preamble (single-source-of-truth from `provisionIsolatedShell`):',
         '```bash',
         isolation.preamble.trimEnd(),
         '```',
         '',
-        `Injected env vars: \`${envKeyList}\``,
-        '',
-        'Forbidden git ops: `git checkout, git switch, git branch -b/-D, git reset --hard, git worktree add/remove, git rebase, git stash pop, git push --force`',
-        '',
-        'All commits MUST land on YOUR branch only. The orchestrator integrates via `git merge --no-ff` (ADR-062), preserving your commit SHAs and authorship.',
-        '',
-        '**BRANCH PROVENANCE (T1927)**:',
-        `The orchestrator provisioned \`${worktreeBranch}\` cleanly from the integration base.`,
-        'If you ever need to manually create a task branch (e.g. in a fallback flow), ALWAYS run:',
-        '```bash',
-        `git branch -D ${worktreeBranch} 2>/dev/null || true`,
-        `git branch ${worktreeBranch} <base-ref>`,
-        '```',
-        'NEVER use `git worktree add -b` on a branch that may already exist — it silently reuses',
-        'orphan history from prior sessions or test fixtures and will corrupt the merge on completion.',
+        `**CRITICAL — WORKTREE ISOLATION**: commit only to \`${worktreeBranch}\`; the orchestrator integrates with \`git merge --no-ff\` (ADR-062). Forbidden: \`git checkout\`, \`git switch\`, \`git branch -b/-D\`, \`git reset --hard\`, \`git worktree add/remove\`, \`git rebase\`, \`git stash pop\`, \`git push --force\`.`,
     ].join('\n');
 }
 /**
@@ -769,8 +771,25 @@ function buildQualityGateBlock() {
         'If ANY gate fails, fix it before completing. Do not bypass. Do not `--no-verify`. Do not amend published commits.',
     ].join('\n');
 }
+/**
+ * Build the one-line HITL rule for a SUBAGENT (T12482).
+ *
+ * Spawned agents never ask the human: harness ask tools are unavailable to
+ * subagents (Claude Code's `AskUserQuestion` included), and the owner
+ * directive routes every decision through the orchestrator. The subagent
+ * returns `blocked` with the question + options in the manifest; the line
+ * names the tool the ORCHESTRATOR asks with, or the `hitl.request` fallback.
+ *
+ * @param type - Return-contract type word (e.g. `Implementation`).
+ * @param askProviderId - Orchestrator's CAAMP provider id, if known.
+ */
+function buildHitlLine(type, askProviderId) {
+    const tool = askProviderId ? getProviderAskTool(askProviderId).toolName : null;
+    const how = tool ? `asks via \`${tool}\`` : 'emits one `hitl.request` LAFS envelope';
+    return `HITL: never ask the human. Return \`${type} blocked.\` with {question, options[{label,description}], recommended} in the manifest; the orchestrator ${how}.`;
+}
 /** Build the return-format contract — exact strings the subagent may return. */
-function buildReturnFormatBlock(protocol) {
+function buildReturnFormatBlock(protocol, askProviderId) {
     const type = protocol === 'research'
         ? 'Research'
         : protocol === 'consensus'
@@ -806,6 +825,8 @@ function buildReturnFormatBlock(protocol) {
         '1. The `pipeline_manifest` table via `cleo manifest append` (see **Manifest Protocol** below)',
         '2. The task record itself (gates, status, notes)',
         '3. Files committed to your branch',
+        '',
+        buildHitlLine(type, askProviderId),
     ].join('\n');
 }
 /**
@@ -894,7 +915,8 @@ function buildManifestProtocolBlock(taskId, protocol) {
  * The legacy flat-file manifest row was removed when `pipeline_manifest`
  * (SQLite) became the canonical manifest store (ADR-027 §6.2, T1096). Subagents append
  * manifest entries via `cleo manifest append` — see the Manifest Protocol block
- * rendered alongside this one.
+ * rendered alongside this one. T12482 dropped this block's restatement of that
+ * rule (the Manifest Protocol block already says it) to fund the HITL line.
  */
 function buildFilePathsBlock(taskId, outputDir, rcasdDir, testRunsDir) {
     return [
@@ -905,10 +927,6 @@ function buildFilePathsBlock(taskId, outputDir, rcasdDir, testRunsDir) {
         `| Agent output directory | \`${outputDir}\` |`,
         `| RCASD workspace (${taskId}) | \`${rcasdDir}\` |`,
         `| Test-run captures | \`${testRunsDir}\` |`,
-        '',
-        '> Manifest entries are stored in `pipeline_manifest` (tasks.db) and MUST be',
-        '> written via `cleo manifest append` (see **Manifest Protocol**). Never',
-        '> create a flat `.jsonl` manifest file — the legacy sink was retired (ADR-027).',
     ].join('\n');
 }
 /** Build the session-linkage block — thread orchestrator session id to subagent. */
@@ -940,6 +958,8 @@ function buildTier0ProtocolPointer() {
         'Full protocol reference: `~/.cleo/templates/CLEO-INJECTION.md` (global) or `packages/core/templates/CLEO-INJECTION.md` (source).',
         '',
         'Cheapest-first discovery: `cleo session status` → `cleo dash` → `cleo current` → `cleo next` → `cleo show <id>`.',
+        '',
+        'On-demand protocol sections: `cleo briefing inject --section <name>`.',
     ].join('\n');
 }
 /** Build the tier 1 CLEO-INJECTION embed. */
@@ -956,7 +976,32 @@ function buildTier1InjectionEmbed() {
     return [
         '## CLEO Protocol (embedded — tier 1)',
         '',
-        '<details><summary>Click to expand full protocol</summary>',
+        '<details><summary>Click to expand core protocol</summary>',
+        '',
+        content,
+        '',
+        '</details>',
+    ].join('\n');
+}
+/**
+ * Build the tier 2 protocol-reference embed.
+ *
+ * CLEO-INJECTION.md is only the always-loaded core; its reference sections
+ * live in CLEO-REFERENCE.md. Tier-2 workers run autonomously, so they get the
+ * reference resolved in full rather than a `cleo briefing inject` round-trip
+ * per section. Emitted even when the core embed is deduplicated, because no
+ * harness auto-loads the reference.
+ *
+ * @task T12580
+ */
+function buildTier2ReferenceEmbed() {
+    const content = loadCleoReference();
+    if (!content)
+        return null;
+    return [
+        '## CLEO Protocol Reference (embedded — tier 2)',
+        '',
+        '<details><summary>Click to expand on-demand reference sections</summary>',
         '',
         content,
         '',
@@ -1075,8 +1120,8 @@ function buildDashboardContextBlock(summary) {
 }
 function buildConduitSubscriptionBlock(config) {
     const { epicId, waveId, peerId } = config;
-    const waveTopic = `epic-${epicId}.wave-${waveId}`;
-    const coordTopic = `epic-${epicId}.coordination`;
+    const waveTopic = waveTopicName(epicId, waveId);
+    const coordTopic = coordinationTopic(epicId);
     return [
         '## CONDUIT Subscription (A2A Wave Coordination · T1252)',
         '',
@@ -1172,114 +1217,28 @@ function buildAntiPatternBlock() {
  * the spawned agent its user profile, peer memory, and session context.
  * Mirrors the `computeBriefing` path in `briefing.ts` (M1 parity).
  *
+ * T12519: the block is budgeted. Operation receipts and dispatch traces are
+ * excluded. The rest is ranked by relevance to `task` and capped at
+ * `PSYCHE_MEMORY_TOKEN_BUDGET` tokens, admitting whole entries only. See
+ * `psyche-memory-budget.ts`.
+ *
  * Called only when `tier >= 1` and `retrievalBundle` is set.
- * Callers MUST NOT crash if the bundle is empty (all arrays may be empty
- * until T1147 W7 sweep ships in .132).
+ * Callers MUST NOT crash if the bundle is empty.
  *
  * @param bundle - The retrieval bundle from `buildRetrievalBundle`.
+ * @param task - The task being spawned (relevance ranking source).
+ * @param attentionDigestLines - Pre-rendered Tier-2 attention lines (T11374).
  * @returns Markdown string for the `## PSYCHE-MEMORY` section.
  *
  * @task T1260 PSYCHE E3
+ * @task T12519
  */
-function buildPsycheMemoryBlock(bundle, attentionDigestLines) {
-    const lines = ['## PSYCHE-MEMORY'];
-    lines.push('');
-    lines.push(`> Token budget used: ${bundle.tokenCounts.total} (cold=${bundle.tokenCounts.cold}, warm=${bundle.tokenCounts.warm}, hot=${bundle.tokenCounts.hot})`);
-    // -- Tier-2 attention digest (T11374) — budget-bounded MVI lines from the
-    //    open working-memory jots visible to the spawned task's scope. Empty when
-    //    there are no open items (the empty-attention contract: inject nothing).
-    if (attentionDigestLines && attentionDigestLines.length > 0) {
-        lines.push('');
-        lines.push(...attentionDigestLines);
-    }
-    // -- Cold: user profile --
-    if (bundle.cold.userProfile.length > 0) {
-        lines.push('');
-        lines.push('### User Profile');
-        for (const trait of bundle.cold.userProfile) {
-            lines.push(`- **${trait.traitKey}**: ${trait.traitValue}`);
-        }
-    }
-    // -- Cold: sigil card (Wave 8 T1148) --
-    if (bundle.cold.sigilCard) {
-        const s = bundle.cold.sigilCard;
-        lines.push('');
-        lines.push('### Active Peer Sigil');
-        if (s.displayName)
-            lines.push(`- **Name**: ${s.displayName}`);
-        if (s.role)
-            lines.push(`- **Role**: ${s.role}`);
-        if (s.cantFile)
-            lines.push(`- **CANT file**: ${s.cantFile}`);
-        if (s.capabilityFlags)
-            lines.push(`- **Capabilities**: ${s.capabilityFlags}`);
-    }
-    if (bundle.cold.peerInstructions) {
-        lines.push('');
-        lines.push('### Peer Instructions');
-        lines.push(bundle.cold.peerInstructions);
-    }
-    // -- Warm: peer memory --
-    if (bundle.warm.decisions.length > 0) {
-        lines.push('');
-        lines.push('### Key Decisions');
-        for (const d of bundle.warm.decisions) {
-            lines.push(`- [${d.id}] ${d.decision}`);
-        }
-    }
-    if (bundle.warm.peerPatterns.length > 0) {
-        lines.push('');
-        lines.push('### Patterns');
-        for (const p of bundle.warm.peerPatterns) {
-            lines.push(`- [${p.id}] ${p.pattern}`);
-        }
-    }
-    if (bundle.warm.peerLearnings.length > 0) {
-        lines.push('');
-        lines.push('### Learnings');
-        for (const l of bundle.warm.peerLearnings) {
-            lines.push(`- [${l.id}] ${l.insight}`);
-        }
-    }
-    // -- Hot: session state --
-    if (bundle.hot.sessionNarrative) {
-        lines.push('');
-        lines.push('### Session Narrative');
-        lines.push(bundle.hot.sessionNarrative);
-    }
-    if (bundle.hot.recentObservations.length > 0) {
-        lines.push('');
-        lines.push('### Recent Observations');
-        for (const o of bundle.hot.recentObservations) {
-            lines.push(`- [${o.id}] ${o.title}`);
-        }
-    }
-    if (bundle.hot.activeTasks.length > 0) {
-        lines.push('');
-        lines.push('### Active Tasks');
-        for (const t of bundle.hot.activeTasks) {
-            lines.push(`- ${t.id}: ${t.title} (${t.status})`);
-        }
-    }
-    // Empty bundle notice (expected until T1147 W7 sweep ships in .132).
-    // Tier-2 attention lines count as content — if the agent has open jots the
-    // block is non-empty even when the retrieval bundle is bare (T11374).
-    const hasContent = (attentionDigestLines !== undefined && attentionDigestLines.length > 0) ||
-        bundle.cold.userProfile.length > 0 ||
-        bundle.cold.peerInstructions ||
-        bundle.cold.sigilCard !== undefined ||
-        bundle.warm.decisions.length > 0 ||
-        bundle.warm.peerPatterns.length > 0 ||
-        bundle.warm.peerLearnings.length > 0 ||
-        bundle.hot.sessionNarrative ||
-        bundle.hot.recentObservations.length > 0 ||
-        bundle.hot.activeTasks.length > 0;
-    if (!hasContent) {
-        lines.push('');
-        lines.push('> No memory context available. All entries are pending the T1147 W7 sweep (.132) ' +
-            "to promote from 'unswept-pre-T1151' to 'swept-clean'. Proceed without memory context.");
-    }
-    return lines.join('\n');
+function buildPsycheMemoryBlock(bundle, task, attentionDigestLines) {
+    return buildBudgetedPsycheMemoryBlock({
+        bundle,
+        relevance: relevanceContextFromTask(task),
+        ...(attentionDigestLines !== undefined ? { attentionDigestLines } : {}),
+    }).block;
 }
 // ============================================================================
 // Public API
@@ -1353,7 +1312,8 @@ export function buildSpawnPrompt(input) {
     // 9. Quality Gates       — biome / build / test
     authoredSections.push(buildHeader(input.task, protocol, tier));
     authoredSections.push(buildTaskIdentity(input.task));
-    authoredSections.push(buildReturnFormatBlock(protocol));
+    const askProviderId = input.askProviderId ?? (input.harnessHint === 'claude-code' ? 'claude-code' : undefined);
+    authoredSections.push(buildReturnFormatBlock(protocol, askProviderId));
     authoredSections.push(buildManifestProtocolBlock(taskId, protocol));
     authoredSections.push(buildSessionBlock(input.sessionId));
     // Worktree Setup (T1140) — only emitted when the engine provisioned one.
@@ -1397,7 +1357,7 @@ export function buildSpawnPrompt(input) {
     // legacy entries; callers must not crash on an empty bundle. T11374 threads
     // the Tier-2 attention digest lines into the same block (budget-bounded).
     if (tier >= 1 && input.retrievalBundle) {
-        authoredSections.push(buildPsycheMemoryBlock(input.retrievalBundle, input.attentionDigestLines));
+        authoredSections.push(buildPsycheMemoryBlock(input.retrievalBundle, input.task, input.attentionDigestLines));
     }
     authoredSections.push(buildFilePathsBlock(taskId, outputDir, rcasdDir, testRunsDir));
     // Task Documents (T1614) — only emitted when the task has attachments.
@@ -1446,6 +1406,9 @@ export function buildSpawnPrompt(input) {
         else {
             embeddedSections.push(buildTier1InjectionEmbed());
         }
+        const referenceEmbed = buildTier2ReferenceEmbed();
+        if (referenceEmbed)
+            embeddedSections.push(referenceEmbed);
         embeddedSections.push(buildTierSkillExcerpts(2, input.role ?? 'orchestrator', input.projectRoot));
         // The anti-patterns block is authored by us, so keep its tokens subject
         // to resolution (currently there are none — but structurally it belongs