peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/dispatch-preflight.js

@@ -0,0 +1,105 @@
+// The `peaks sub-agent dispatch` preflight: every refusal that can be decided from
+// the argv alone, before the session id, the lease or the prompt blocks are touched.
+// Returns the prompt-size decision, or `null` when a refusal was already printed.
+import { printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+import { TEST_TOOL_DETECTION_BLOCK } from '../../services/dispatch/test-tool-detection.js';
+import { PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
+function rejectInvalidRole(io, role, validation, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'INVALID_ROLE', validation, { role, toolCall: null, dispatchRecordPath: null }, [
+        'Use a non-empty role string with no control characters.',
+        `Recommended: ${RECOMMENDED_ROLES}.`
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectRemovedAgentRole(io, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'ROLE_REMOVED', 'The agent role was removed in Slice 3', {
+        role,
+        reason: 'role-removed-in-slice-3',
+        toolCall: null,
+        dispatchRecordPath: null
+    }, []), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectMissingPrompt(io, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'MISSING_PROMPT', '--prompt is required when --from-dag is not provided', { role, toolCall: null, dispatchRecordPath: null }, [
+        'Re-run with either:',
+        '  • `--prompt <text>` for single-role dispatch, OR',
+        '  • `--from-dag <file>` for DAG-aware multi-slice dispatch (no --prompt needed; the per-slice prompt is generated from the DAG nodes).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+// DOGFOOD ONLY: --prompt-length overrides the actual prompt content with
+// a synthetic prompt of the given size in bytes. The original --prompt
+// is still required (commander needs it). This avoids ARG_MAX limits
+// on Windows when the dogfood prompt is > 200KB.
+function applyPromptLengthOverride(options) {
+    if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+        const len = Number.parseInt(options.promptLength, 10);
+        if (Number.isInteger(len) && len > 0) {
+            options.prompt = 'x'.repeat(len);
+        }
+    }
+}
+function rejectPromptTooLarge(io, role, promptLength, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'PROMPT_TOO_LARGE', `prompt exceeds ${PROMPT_LIMIT_BYTES} bytes (got ${promptLength})`, { role, toolCall: null, dispatchRecordPath: null }, [
+        'Truncate the prompt or split into multiple dispatches.',
+        'Pass --force to override the 80% threshold at CLI (NOT allowed at hook layer).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectGuardDecision(io, role, args, asJson) {
+    const { promptLength, decision } = args;
+    printResult(io, fail('sub-agent.dispatch', decision.code, `prompt size ${promptLength} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`, {
+        role,
+        toolCall: null,
+        dispatchRecordPath: null
+    }, [
+        decision.suggest ?? 'Trim prompt or pass --force to override at CLI.',
+        'PreToolUse hook layer will still reject regardless of --force (RL-30 strict).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+export function preflightDispatch(io, role, options, asJson) {
+    const validation = validateRole(role);
+    if (validation !== null) {
+        return rejectInvalidRole(io, role, validation, asJson);
+    }
+    // Slice 3 (on-demand-ecc) D-012: the `agent` role was removed in
+    // 4.0.0-beta.11 — there is no longer a subprocess path for it
+    // (the upstream ECC v2.0.0 ships no `ecc` binary). This guard
+    // sits AFTER role validation but BEFORE the missing-prompt
+    // check so an action-path dispatch with a valid prompt still
+    // returns a clear ROLE_REMOVED envelope + exit 1. Note that
+    // Commander short-circuits `--help` BEFORE `.action()` fires,
+    // so `peaks sub-agent dispatch agent --help` continues to
+    // exit 0 with the help text — that is intentional, not a bug.
+    if (role === 'agent') {
+        return rejectRemovedAgentRole(io, role, asJson);
+    }
+    if (!options.prompt || options.prompt.length === 0) {
+        return rejectMissingPrompt(io, role, asJson);
+    }
+    // Slice 4.0.8 RD §4 D4c required `--graph-node` here, before the session
+    // id existed, so the only recovery it could offer was prose. The node is
+    // now provisioned inside the try block below, once `sid` is known.
+    applyPromptLengthOverride(options);
+    if (options.prompt.length + TEST_TOOL_DETECTION_BLOCK.length > PROMPT_LIMIT_BYTES) {
+        return rejectPromptTooLarge(io, role, options.prompt.length, asJson);
+    }
+    // G9 CLI 兜底 — evaluate prompt size against the threshold table.
+    const decision = evaluatePromptSize(options.prompt.length, { force: options.force === true });
+    if (!decision.allow) {
+        return rejectGuardDecision(io, role, { promptLength: options.prompt.length, decision }, asJson);
+    }
+    // The prompt the caller composes with: the `--prompt` the caller passed, or the
+    // synthetic one `--prompt-length` substituted for it. Handed back explicitly so a
+    // caller that has only the argv cannot mistake an absent prompt for an empty one.
+    return { decision, prompt: options.prompt };
+}

package/dist/cli/commands/dispatch-prompt-blocks.d.ts

@@ -0,0 +1,10 @@
+import { type DispatchOptions } from './sub-agent-shared.js';
+export declare function buildIsolationBlock(isolationMode: 'worktree' | 'container' | 'vm' | null, leaseId: string | null, worktreePath: string | null, worktreeBranch: string | null): string;
+export declare function buildMustLsFilesBlock(options: DispatchOptions, projectRoot: string): {
+    mustLsFilesVerification: {
+        path: string;
+        exists: boolean;
+        files: readonly string[];
+    } | null;
+    mustLsFilesBlock: string;
+};

package/dist/cli/commands/dispatch-prompt-blocks.js

@@ -0,0 +1,56 @@
+// The two prompt blocks `composeDispatchPrompt` prepends: the Part 2.C worktree
+// isolation envelope and the F5 `must_ls_files` anti-fake-green enforcement
+// block. Split out of `dispatch-prompt-composition.ts` when compressing that
+// module's long function pushed it past the 300-line cap; both bodies are the
+// originals, moved verbatim.
+import { runGitLsFiles } from '../../services/dispatch/dispatch-sub-agent.js';
+// Part 2.C: when --isolation worktree, prepend an isolation envelope
+// block so the sub-agent sees the lease id + worktree path. The block
+// is short (a few lines). We deliberately do NOT set
+// process.env.PEAKS_WORKTREE_LEASE_ID here — sub-agents are spawned
+// by the LLM in its own environment, not as children of this CLI;
+// the lease id travels through the dispatch record + prompt body.
+export function buildIsolationBlock(isolationMode, leaseId, worktreePath, worktreeBranch) {
+    return isolationMode !== null && leaseId !== null
+        ? `\n## Worktree isolation (Part 2.C)\n` +
+            `leaseId: ${leaseId}\n` +
+            `worktreePath: ${worktreePath}\n` +
+            `branch: ${worktreeBranch}\n` +
+            `You MAY ` +
+            '`git worktree add` ' +
+            `and ` +
+            '`git worktree remove` ' +
+            `against this lease without a separate ` +
+            '`peaks worktree auth grant` ' +
+            `— the PreToolUse gate reads the lease file. Run ` +
+            '`peaks worktree release --lease-id ${leaseId}` ' +
+            `when done.\n`
+        : '';
+}
+// F5 follow-up: anti-fake-green gate. When `--must-ls-files <glob>`
+// is supplied, run `git ls-files <glob>` upfront, surface the
+// result in the envelope as `mustLsFilesVerification: { path,
+// exists, files }`, and prepend a `## must_ls_files enforcement`
+// frontmatter block to the sub-agent prompt that mandates the
+// file-existence verification as the LLM's FIRST action (before
+// any "completed"/"PASS" claim). When the flag is absent the
+// field is `null` and no block is injected — old call sites
+export function buildMustLsFilesBlock(options, projectRoot) {
+    let mustLsFilesVerification = null;
+    let mustLsFilesBlock = '';
+    if (typeof options.mustLsFiles === 'string' && options.mustLsFiles.length > 0) {
+        const glob = options.mustLsFiles;
+        const files = runGitLsFiles(projectRoot, glob);
+        const exists = files.length > 0;
+        mustLsFilesVerification = { path: glob, exists, files };
+        mustLsFilesBlock =
+            `\n## must_ls_files enforcement (F5 anti-fake-green)\n` +
+                `glob: ${glob}\n` +
+                `verification: ${exists ? `EXISTS (${files.length} file${files.length === 1 ? '' : 's'} found)` : 'MISSING (no files matched the glob)'}\n` +
+                (exists ? `first match: ${files[0] ?? ''}\n` : '') +
+                `BEFORE any claim that work is "completed" or "PASS", you MUST run \`git ls-files ${glob}\` from the project root and ` +
+                `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
+                `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
+    }
+    return { mustLsFilesVerification, mustLsFilesBlock };
+}

package/dist/cli/commands/dispatch-prompt-composition.d.ts

@@ -0,0 +1,30 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import type { ContextGuardDecision } from '../../services/context/context-guard.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+export interface ComposeDispatchPromptInput {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    options: DispatchOptions;
+    /** The prompt the sub-agent receives, as `preflightDispatch` resolved it. */
+    prompt: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    worktreePath: string | null;
+    worktreeBranch: string | null;
+    decision: ContextGuardDecision;
+    asJson: boolean;
+}
+export interface ComposedDispatchPrompt {
+    adapter: ReturnType<typeof getAdapter>;
+    effectivePrompt: string;
+    warnings: string[];
+    mustLsFilesVerification: {
+        path: string;
+        exists: boolean;
+        files: readonly string[];
+    } | null;
+}
+export declare function composeDispatchPrompt(io: ProgramIO, input: ComposeDispatchPromptInput): Promise<ComposedDispatchPrompt | null>;

package/dist/cli/commands/dispatch-prompt-composition.js

@@ -0,0 +1,171 @@
+// The prompt `peaks sub-agent dispatch` hands a sub-agent: the adapter check, the
+// optional preflight blocks (memory / codegraph / UI library / fresh context /
+// context probe / session capsule), the isolation and must-ls-files blocks, and the
+// warning list the envelope carries.
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+import { DEFAULT_PREFERENCES } from '../../services/preferences/preferences-types.js';
+import { MemoryPreflightService, deriveMemoryQuery } from '../../services/context/memory-preflight-service.js';
+import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch-system-prompt.js';
+import { readSessionCapsule } from '../../services/dispatch/session-capsule.js';
+import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-library-dispatch-block.js';
+import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
+import { deprecatedReviewerWarnings } from './sub-agent-shared.js';
+import { buildIsolationBlock, buildMustLsFilesBlock } from './dispatch-prompt-blocks.js';
+// loadPreferences can throw on schema mismatch; we fall back to defaults
+// to avoid breaking the dispatch on a stale preferences.json file.
+function loadProjectPreferences(projectRoot) {
+    try {
+        return loadPreferences(projectRoot);
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // Keep default preferences.
+        return DEFAULT_PREFERENCES;
+    }
+}
+function rejectUnsupportedIde(io, ide, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, ['Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.']), asJson);
+    process.exitCode = 1;
+    return null;
+}
+// memory preflight block (or silently skip when unavailable) via the
+// pure-function builder.
+function loadMemoryBlock(projectRoot, projectPrefs, role, prompt) {
+    const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
+    // task at hand (role + first line of the brief), not the bare role.
+    return preflightService.fetchBlock(deriveMemoryQuery(role, prompt));
+}
+// codegraph preflight for RD planning. BEFORE the RD sub-agent's
+// prompt is composed, ensure the index exists (init + index best-effort
+// when `.codegraph/` is absent) and read a BOUNDED structure summary.
+// `rd` only — other roles keep the legacy prompt byte-identical.
+// Fail-soft: any failure degrades and dispatch proceeds. On failure the
+// preflight's NOTE — the upstream cause — travels as the same value as
+// the block, so the reason cannot be dropped while the block survives.
+// The old `block : null` dropped it, so every degraded dispatch read as success.
+async function loadCodegraphBlock(projectRoot, role) {
+    let codegraphBlock;
+    if (role === 'rd') {
+        try {
+            const { buildCodegraphPreflightBlock } = await import('../../services/codegraph/codegraph-preflight-service.js');
+            const preflight = await buildCodegraphPreflightBlock(projectRoot);
+            codegraphBlock = preflight.available ? preflight.block : preflight.note;
+        }
+        catch (error) {
+            codegraphBlock = `codegraph preflight threw: ${getErrorMessage(error)}`;
+        }
+    }
+    return codegraphBlock;
+}
+// component library (+ CSS framework + build tool) in the RD/UI
+// dispatch system prompt so the sub-agent prefers the library over
+// hand-rolled native DOM. Only injected for frontend-generating roles
+// (rd + ui) — qa/sc/txt/prd keep the legacy prompt byte-identical.
+// Fail-soft inside the wrapper: a detection error degrades to null.
+function loadProjectStackBlock(projectRoot, role) {
+    let projectStackBlock;
+    if (role === 'rd' || role === 'ui') {
+        projectStackBlock = computeUiLibraryDispatchBlock(projectRoot);
+    }
+    return projectStackBlock;
+}
+// Slice 2026-09-07-search-first-preflight: read the orchestrator-
+// synthesized fresh-context block for rd + prd dispatches. The block
+// was written to .peaks/_runtime/<sid>/fresh-context.md when the
+// preflight triggered; it carries ≤5 binding directives that hedge
+// model training-data lag. Fail-soft: a missing / unreadable file, or
+// a file without the `## Fresh context` heading, degrades to null so
+// the prompt stays byte-identical to the legacy shape. Other roles
+// (qa/sc/txt/ui) keep the legacy prompt unchanged.
+function loadFreshContextBlock(projectRoot, sid, role) {
+    let freshContextBlock;
+    if (role === 'rd' || role === 'prd') {
+        freshContextBlock = readFreshContextBlock(projectRoot, sid);
+    }
+    return freshContextBlock;
+}
+// authoritative context-fill probe before composing the
+// dispatch prompt. The probe is token-counted (IDE adapter's
+// `compact` env-var), not a byte estimate. The composer
+// prepends a `## Context window` block so the dispatched
+// sub-agent reads the actual ratio instead of guessing
+// from message length (char/4 estimates diverge by 2-4x
+// and have caused false "context too low" reports at 60%+
+// free).
+async function loadContextProbe(projectRoot, sid) {
+    let contextProbe = null;
+    try {
+        const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+        const outerSessionId = resolveOuterSessionId(projectRoot, sid);
+        contextProbe = readContextPercent({
+            projectRoot,
+            sessionId: sid,
+            outerSessionId,
+            env: process.env
+        });
+    }
+    catch {
+        // Probe is best-effort; the composer renders a
+        // "no probe available" hint instead of failing the
+        // dispatch.
+    }
+    return contextProbe;
+}
+async function composeMemoryAugmentedBody(input, projectPrefs) {
+    const { projectRoot, sid, rid, role, prompt } = input;
+    const memoryBlock = await loadMemoryBlock(projectRoot, projectPrefs, role, prompt);
+    const codegraphBlock = await loadCodegraphBlock(projectRoot, role);
+    const projectStackBlock = loadProjectStackBlock(projectRoot, role);
+    const freshContextBlock = loadFreshContextBlock(projectRoot, sid, role);
+    const contextProbe = await loadContextProbe(projectRoot, sid);
+    // capsule published by the orchestrator via `peaks sub-agent share`.
+    // Absent capsule → no pointer and no precedence line (byte-identical
+    // legacy prompt).
+    const capsuleRef = readSessionCapsule({ projectRoot, sid, rid });
+    return buildDispatchSystemPrompt({
+        taskTitle: role,
+        taskBody: prompt,
+        memoryBlock,
+        // unified Test Tool Detection injection for every role.
+        contextProbe,
+        // exactOptionalPropertyTypes: only set codegraphBlock when the rd
+        // preflight actually produced a value (null = attempted-unavailable,
+        // undefined = not requested → legacy prompt unchanged).
+        ...(codegraphBlock !== undefined ? { codegraphBlock } : {}),
+        // Same optionality contract for the project-stack block: set only
+        // when the rd/ui detection ran (null = no library → no block,
+        // undefined = non-frontend role → legacy prompt unchanged).
+        ...(projectStackBlock !== undefined ? { projectStackBlock } : {}),
+        // Same optionality contract for the fresh-context block: set only
+        // when the rd/prd read ran (null = no block on disk → no block,
+        // undefined = non-rd/prd role → legacy prompt unchanged).
+        ...(freshContextBlock !== undefined ? { freshContextBlock } : {}),
+        // §4: advisory session capsule pointer + precedence line.
+        ...(capsuleRef !== null
+            ? {
+                capsule: { batchId: capsuleRef.batchId, key: capsuleRef.key, bytes: capsuleRef.bytes }
+            }
+            : {})
+    });
+}
+export async function composeDispatchPrompt(io, input) {
+    const { projectRoot, role, options, isolationMode, leaseId, worktreePath, worktreeBranch, decision, asJson } = input;
+    const projectPrefs = loadProjectPreferences(projectRoot);
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    const adapter = getAdapter(ide);
+    if (!adapter.subAgentDispatcher.supportsRole(role)) {
+        return rejectUnsupportedIde(io, ide, role, asJson);
+    }
+    const memoryAugmentedBody = await composeMemoryAugmentedBody(input, projectPrefs);
+    const isolationBlock = buildIsolationBlock(isolationMode, leaseId, worktreePath, worktreeBranch);
+    const { mustLsFilesVerification, mustLsFilesBlock } = buildMustLsFilesBlock(options, projectRoot);
+    const effectivePrompt = `${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
+    // + rerouted here, never refused — rationale on the helper itself.
+    const warnings = [...decision.warnings, ...deprecatedReviewerWarnings(role)];
+    return { adapter, effectivePrompt, warnings, mustLsFilesVerification };
+}

package/dist/cli/commands/dispatch-record-write.d.ts

@@ -0,0 +1,24 @@
+import { noteDispatched } from '../../services/dispatch/batch-counter.js';
+import { type ArtifactMeta } from '../../services/context/artifact-meta.js';
+import { type SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+export interface WriteDispatchRecordInput {
+    options: DispatchOptions;
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    effectivePrompt: string;
+    toolCall: SubAgentToolCall;
+    batchId: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    /** The dispatch's warning list — this function appends to it, as the inline block did. */
+    warnings: string[];
+}
+export interface DispatchRecordWrite {
+    artifactMeta: ArtifactMeta | null;
+    dispatchRecordPath: string;
+    counter: ReturnType<typeof noteDispatched>;
+}
+export declare function writeDispatchRecord(input: WriteDispatchRecordInput): DispatchRecordWrite;

package/dist/cli/commands/dispatch-record-write.js

@@ -0,0 +1,96 @@
+// The `peaks sub-agent dispatch` record write: the optional G7 artifact meta, the graph
+// node binding, the dispatch record itself, and the batch counter.
+import { existsSync } from 'node:fs';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { noteDispatched } from '../../services/dispatch/batch-counter.js';
+import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { provisionDispatchNode } from '../../services/workflow/provision-dispatch-node.js';
+import { buildArtifactMeta } from '../../services/context/artifact-meta.js';
+import { assertSafeArtifactPath } from 'peaks-loop-shared-channel';
+// G7 — optional --write-artifact: build ArtifactMeta, attach to record.
+function resolveArtifactMeta(input) {
+    const { options, projectRoot, rid, role, warnings } = input;
+    let artifactMeta = null;
+    if (typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0) {
+        try {
+            assertSafeArtifactPath(options.writeArtifact, projectRoot);
+            if (!existsSync(options.writeArtifact)) {
+                warnings.push('ARTIFACT_NOT_FOUND');
+            }
+            else {
+                artifactMeta = buildArtifactMeta({
+                    path: options.writeArtifact,
+                    rid,
+                    role,
+                    idx: 1, // single dispatch, idx=1
+                    summary: null
+                });
+            }
+        }
+        catch (err) {
+            warnings.push(`ARTIFACT_PATH_INVALID: ${getErrorMessage(err)}`);
+        }
+    }
+    return artifactMeta;
+}
+// Slice 4.0.8 RD §4 D4c: bind this dispatch to a graph node. When the
+// caller names none, provision one — that is what collapses the
+// documented three-step ritual (create graph -> `peaks workflow node
+// prepare` -> dispatch) into a single call. Those three fields were
+// also never passed to the writer, so the record's graph binding was
+// always null and the writer's transition never fired: the feature was
+// inert, and only its precondition (the required flag) was real.
+function resolveGraphBinding(options, projectRoot, sid, role) {
+    if (typeof options.graphNode === 'string' && options.graphNode.length > 0) {
+        return {
+            nodeId: options.graphNode,
+            workflowId: options.workflowId ?? null,
+            graphRef: options.graphRef ?? null
+        };
+    }
+    const provisioned = provisionDispatchNode({
+        projectRoot,
+        sessionId: sid,
+        role,
+        workflowId: options.workflowId,
+        graphRef: options.graphRef
+    });
+    return {
+        nodeId: provisioned.nodeId,
+        workflowId: provisioned.workflowId,
+        graphRef: provisioned.graphRef
+    };
+}
+export function writeDispatchRecord(input) {
+    const { options, projectRoot, sid, rid, role, effectivePrompt, toolCall, batchId, isolationMode, leaseId, warnings } = input;
+    const artifactMeta = resolveArtifactMeta(input);
+    const graphBinding = resolveGraphBinding(options, projectRoot, sid, role);
+    const { path: dispatchRecordPath } = writeInitialDispatchRecord({
+        projectRoot,
+        sessionId: sid,
+        requestId: rid,
+        role,
+        prompt: effectivePrompt,
+        workflowId: graphBinding.workflowId,
+        graphNodeId: graphBinding.nodeId,
+        graphRef: graphBinding.graphRef,
+        toolCall,
+        batchId,
+        // lease id on the dispatch record so the finalize-time
+        // release hook (markCompleted / heartbeat --status done) can
+        // auto-fire `peaks worktree release` when the sub-agent
+        // completes. Null when --isolation was not requested.
+        leaseId,
+        // ISO timestamp when the isolation mode was set up. Null
+        // when --isolation was not requested. The dashboard reads
+        // this directly off the dispatch record to compute
+        // isolation duration without cross-referencing the
+        // metrics stream.
+        isolationStartedAt: isolationMode !== null ? new Date().toISOString() : null
+    });
+    const counter = noteDispatched(projectRoot, sid, batchId);
+    if (counter.warning) {
+        warnings.push(counter.warning.message);
+    }
+    return { artifactMeta, dispatchRecordPath, counter };
+}

package/dist/cli/commands/dispatch-tool-call.d.ts

@@ -0,0 +1,15 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { type SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+export interface BuildDispatchToolCallInput {
+    adapter: ReturnType<typeof getAdapter>;
+    role: string;
+    effectivePrompt: string;
+    rid: string;
+    sid: string;
+    projectRoot: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    asJson: boolean;
+}
+export declare function buildDispatchToolCall(io: ProgramIO, input: BuildDispatchToolCallInput): SubAgentToolCall | null;

package/dist/cli/commands/dispatch-tool-call.js

@@ -0,0 +1,128 @@
+// The tool call `peaks sub-agent dispatch` returns: built by the active adapter, then
+// stamped with the isolation lease, the provenance token, the Playwright profile env
+// and the observability event.
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { SubAgentNotSupportedError } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { emitObservabilityEvent, OBSERVABILITY_SUBAGENT_ROLES } from '../../services/observability/observability-service.js';
+import { createDispatchProvenanceToken, DISPATCH_PROVENANCE_ENV, writeDispatchProvenance } from '../../services/worktree/dispatch-provenance.js';
+import { playwrightProfilePaths } from '../../services/worktree/playwright-profile.js';
+function writeWorktreeProvenance(input) {
+    const { projectRoot, sid, rid, leaseId, provenanceToken } = input;
+    writeDispatchProvenance({
+        projectRoot,
+        record: {
+            schemaVersion: 1,
+            token: provenanceToken,
+            sessionId: sid,
+            requestId: rid,
+            leaseId,
+            isolation: 'worktree',
+            issuedAt: new Date().toISOString()
+        }
+    });
+}
+// Part 2.C: stamp the toolCall with `isolation` + a sub-agent
+// env block so adapters that surface it (Claude Code's Task
+// tool) propagate the lease id to the spawned process. The
+// env block is the canonical hook the PreToolUse gate reads
+// (gate-commands.ts: process.env.PEAKS_WORKTREE_LEASE_ID).
+function applyIsolationStamp(toolCall, input) {
+    const { projectRoot, sid, rid, isolationMode, leaseId } = input;
+    if (isolationMode !== null && leaseId !== null) {
+        const existingEnv = toolCall.args['env'] ?? {};
+        const provenanceToken = createDispatchProvenanceToken({
+            sessionId: sid,
+            requestId: rid,
+            leaseId
+        });
+        if (isolationMode === 'worktree') {
+            writeWorktreeProvenance({ projectRoot, sid, rid, leaseId, provenanceToken });
+        }
+        // two Playwright profile-isolation env vars so the sub-agent's
+        // browser MCP session lands in a deterministic
+        // `.peaks/_runtime/<sid>/pw-profiles/<dispatchId>/` directory
+        // (see src/services/worktree/playwright-profile.ts). Without
+        // these, concurrent dispatches share the user's default
+        // Chromium profile and corrupt cookies / localStorage.
+        const profile = playwrightProfilePaths({
+            projectRoot,
+            sessionId: sid,
+            dispatchId: rid
+        });
+        toolCall = {
+            ...toolCall,
+            args: {
+                ...toolCall.args,
+                isolation: isolationMode,
+                env: {
+                    ...existingEnv,
+                    PEAKS_WORKTREE_LEASE_ID: leaseId,
+                    PEAKS_PLAYWRIGHT_USER_DATA_DIR: profile.userDataDir,
+                    PEAKS_PLAYWRIGHT_PROFILE_NAME: profile.profileName,
+                    ...(isolationMode === 'worktree' ? { [DISPATCH_PROVENANCE_ENV]: provenanceToken } : {})
+                }
+            }
+        };
+    }
+    return toolCall;
+}
+// Slice C of v2.11.1 — observability hook #2/7. Fire-and-forget
+// per PRD Q4 (full-auto must never fail-loud). The
+// synchronous emit returns {written:false} on disk-full; we
+// deliberately swallow the result so dispatch contract is
+// unchanged. role is only included when it matches the schema's
+// known sub-agent role set; otherwise it's omitted (non-standard
+// roles like 'qa-business' would otherwise drop the event
+// through schema rejection).
+function emitDispatchObservability(input) {
+    const { adapter, role, effectivePrompt, sid, rid, projectRoot } = input;
+    const KNOWN_ROLES = new Set(OBSERVABILITY_SUBAGENT_ROLES);
+    const knownRole = KNOWN_ROLES.has(role)
+        ? role
+        : null;
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: new Date().toISOString(),
+        sessionId: sid,
+        category: 'dispatch',
+        ...(knownRole !== null ? { role: knownRole } : {}),
+        detail: {
+            requestId: rid,
+            ide: adapter.subAgentDispatcher.label,
+            promptBytes: effectivePrompt.length
+        }
+    }, { projectRoot });
+}
+function rejectUnsupportedAdapter(io, role, error, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', error.message, { role, toolCall: null, dispatchRecordPath: null }, ['Switch IDE or pick a role the current IDE supports.']), asJson);
+    process.exitCode = 1;
+    return null;
+}
+export function buildDispatchToolCall(io, input) {
+    const { adapter, role, effectivePrompt, rid, sid, projectRoot, isolationMode, leaseId, asJson } = input;
+    let toolCall;
+    try {
+        toolCall = adapter.subAgentDispatcher.buildToolCall({
+            role,
+            prompt: effectivePrompt,
+            requestId: rid,
+            sessionId: sid
+        });
+        toolCall = applyIsolationStamp(toolCall, {
+            projectRoot,
+            sid,
+            rid,
+            isolationMode,
+            leaseId
+        });
+        emitDispatchObservability({ adapter, role, effectivePrompt, sid, rid, projectRoot });
+    }
+    catch (error) {
+        if (error instanceof SubAgentNotSupportedError) {
+            return rejectUnsupportedAdapter(io, role, error, asJson);
+        }
+        throw error;
+    }
+    return toolCall;
+}