cclaw-cli 0.51.25 → 0.51.26

package/dist/content/core-agents.js

@@ -30,6 +30,24 @@ const DOC_RETURN_SCHEMA = {
     requiredFields: ["status", "filesUpdated", "summary", "evidenceRefs", "openQuestions"],
     evidenceFields: ["filesUpdated", "evidenceRefs"]
 };
+function workerAckContract() {
+    return `## Worker ACK Contract
+
+Before doing substantive work, return an ACK object that the parent can record:
+
+\`\`\`json
+{
+  "status": "ACK",
+  "spanId": "<parent spanId>",
+  "dispatchId": "<parent dispatchId or workerRunId>",
+  "dispatchSurface": "claude-task|cursor-task|opencode-agent|codex-agent|generic-task|role-switch",
+  "agentDefinitionPath": ".cclaw/agents/<agent>.md or harness generated path",
+  "ackTs": "<ISO timestamp>"
+}
+\`\`\`
+
+Finish with the required return schema plus the same \`spanId\` and \`dispatchId\`. The parent must not claim isolated completion unless ACK/result proof matches the ledger/event span.`;
+}
 function formatReturnSchema(schema) {
     return [
         `- Status field: \`${schema.statusField}\``,
@@ -446,9 +464,11 @@ ${agent.body}
 - Mode: ${agent.activation}
 - Related stages: ${relatedStages}
 
+${workerAckContract()}
+
 ## Required Return Schema
 
-STRICT_RETURN_SCHEMA: return a structured object matching this contract before any narrative when delegated.
+STRICT_RETURN_SCHEMA: return a structured object matching this contract before any narrative when delegated. Include \`spanId\`, \`dispatchId\` or \`workerRunId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and lifecycle timestamps when provided by the parent.
 
 ${formatReturnSchema(agent.returnSchema)}
 

package/dist/content/harness-doc.d.ts

@@ -0,0 +1 @@
+export declare function harnessIntegrationDocMarkdown(): string;

package/dist/content/harness-doc.js

@@ -0,0 +1,3 @@
+export function harnessIntegrationDocMarkdown() {
+    return "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings. For the end-to-end subagent dispatch model, proof sequence, controller/worker responsibilities, and future roadmap, see [`docs/subagent-flow.md`](./subagent-flow.md).\n\n## Capability tiers\n\n| Harness | ID | Tier | declaredSupport | runtimeLaunch | Fallback | proofRequired | proofSource | Hook surface | Structured ask |\n|---|---|---|---|---|---|---|---|---|---|\n| Claude Code | `claude` | `tier1` (full native automation) | full | native Task launch | native | spanId+dispatchId or workerRunId+ACK | `.cclaw/state/delegation-events.jsonl` + ledger | full | AskUserQuestion |\n| Cursor | `cursor` | `tier2` (supported with fallback paths) | generic | generic Task/Subagent role prompt | generic-dispatch | spanId+dispatchId/evidenceRefs | events + artifact evidenceRefs | full | AskQuestion |\n| OpenCode | `opencode` | `tier2` hooks, native dispatch declared | full | prompt-level launch via Task / `@agent` against `.opencode/agents` | native | spanId+dispatchId+ackTs+completedTs | `.opencode/agents/<agent>.md` + events | plugin | question |\n| OpenAI Codex | `codex` | `tier2` hooks, native dispatch declared | full | prompt-level request to spawn `.codex/agents` custom agents | native | spanId+dispatchId+ackTs+completedTs | `.codex/agents/<agent>.toml` + events | limited | request_user_input |\n\nFallback legend:\n\n- `native` \u2014 first-class named subagent dispatch (Claude).\n- `generic-dispatch` \u2014 generic Task dispatcher mapped to cclaw roles (Cursor).\n- `role-switch` \u2014 degraded fallback for a runtime where declared native/generic dispatch is unavailable; explicit role headers, artifact outputs, and non-empty delegation-log evidenceRefs are required.\n- `waiver` \u2014 no parity path; reserved for harnesses that cannot role-switch (none shipped).\n\n## Stage-Aware Native Dispatch Workflow\n\nOpenCode and Codex receive generated native isolated subagents. Use them before considering role-switch fallback:\n\n1. Use the active stage skill's generated dispatch table as the source of truth.\n2. OpenCode: invoke `.opencode/agents/<agent>.md` via Task or `@<agent>`; Codex: ask Codex to spawn `.codex/agents/<agent>.toml` by name, in parallel when lanes are independent.\n3. Load `.cclaw/agents/<agent>.md`, execute only that role's stage task, and write outputs into the active stage artifact.\n4. Append `.cclaw/state/delegation-events.jsonl` for scheduled/launched/acknowledged/completed/failed/waived/stale, then mirror current state in `.cclaw/state/delegation-log.json`. The ledger is current state; the event log is proof/audit.\n5. Treat completed role-switch rows without `evidenceRefs` as unresolved; treat native isolated completion without matching `spanId` + `dispatchId`/`workerRunId` + `ackTs` + `completedTs` as fake isolated completion. Native isolated rows are not a role-switch substitute and should reflect a real dispatched worker.\n\nThis is staged agent work backed by the harness-native subagent surfaces. Role-switch remains only a degraded fallback when that surface is unavailable in the active runtime.\n\n## Parallel research dispatch semantics\n\nDesign-stage research fleet uses the same parity model:\n\n- **Claude / Cursor**: dispatch all four research lenses in one turn\n  (stack, features, architecture, pitfalls) and synthesize into\n  `.cclaw/artifacts/02a-research.md`.\n- **OpenCode / Codex**: dispatch generated native subagents for the same\n  four lenses and run independent lanes in parallel where the active runtime\n  permits. Use role-switch with evidence only as a degraded fallback.\n\n## Semantic hook event coverage\n\n| Event | Claude | Cursor | OpenCode | Codex |\n|---|---|---|---|---|\n| `session_rehydrate` | SessionStart matcher startup|resume|clear|compact | sessionStart/sessionResume/sessionClear/sessionCompact | plugin event handlers + transform rehydration | SessionStart matcher startup|resume |\n| `pre_tool_prompt_guard` | PreToolUse -> prompt-guard | preToolUse -> prompt-guard | plugin tool.execute.before -> prompt-guard | PreToolUse matcher Bash -> prompt-guard (plus UserPromptSubmit for non-Bash prompts) |\n| `pre_tool_workflow_guard` | PreToolUse -> workflow-guard | preToolUse -> workflow-guard | plugin tool.execute.before -> workflow-guard | PreToolUse matcher Bash -> workflow-guard (Bash-only) |\n| `post_tool_context_monitor` | PostToolUse -> context-monitor | postToolUse -> context-monitor | plugin tool.execute.after -> context-monitor | PostToolUse matcher Bash -> context-monitor (Bash-only) |\n| `stop_handoff` | Stop -> stop-handoff | stop -> stop-handoff | plugin session.idle -> stop-handoff | Stop -> stop-handoff |\n| `precompact_compat` | PreCompact -> pre-compact | sessionCompact -> pre-compact | plugin session.compacted -> pre-compact | missing |\n| `strict_state_verify` | missing | missing | missing | UserPromptSubmit -> verify-current-state (blocks only in strict mode) |\n\n## Hook lifecycle aliases\n\nThe generated Node dispatcher accepts a small compatibility alias set for lifecycle names: `stop` and `stop-checkpoint` route to `stop-handoff`, `precompact` routes to `pre-compact`, and `session-rehydrate` routes to `session-start`. The `pre-compact` handler is intentionally a no-op compatibility marker; rehydration remains the `session-start` responsibility after compact events. Harness JSON should still emit the canonical handler names from `src/content/hook-manifest.ts`.\n\n## Hook event casing\n\nHook keys are intentionally harness-native and must not be normalized:\n\n| Harness | ID | Event key casing |\n|---|---|---|\n| Claude Code | `claude` | PascalCase (`SessionStart`, `PreToolUse`) |\n| Cursor | `cursor` | camelCase (`sessionStart`, `preToolUse`) |\n| OpenCode | `opencode` | camelCase (`sessionStart`, `preToolUse`) |\n| OpenAI Codex | `codex` | PascalCase (`SessionStart`, `PreToolUse`) |\n\nUse the exact event names from each harness schema. Treating all hooks as one\nshared casing silently breaks generated wiring.\n\n## Interpretation\n\n- `tier1`: full native delegation + structured asks + full hook surface.\n- `tier2`: usable flow with capability gaps; mandatory delegation can require waivers.\n- Codex-specific ceiling: `PreToolUse` can only intercept `Bash`. Direct\n  `Write`/`Edit` to `.cclaw/state/flow-state.json` cannot be hard-blocked\n  at hook level, so the canonical path is\n  `node .cclaw/hooks/stage-complete.mjs <stage>` plus the non-blocking\n  `UserPromptSubmit` state nudge.\n- In `strict` mode, Codex additionally runs the generated Node/runtime `verify-current-state` path on `UserPromptSubmit` as a fail-closed check. Advisory mode remains non-blocking, including when the generated local Node entrypoint is missing; doctor reports that install drift separately. This strict-only coverage is represented explicitly by the `strict_state_verify` semantic row above.\n\n## Shared command contract\n\nAll harnesses receive the same utility commands:\n\n- `/cc` - flow entry and resume\n- `/cc-next` - stage progression and post-ship closeout\n- `/cc-ideate` - ideate mode for ranked repo-improvement backlog\n- `/cc-view` - read-only router for status/tree/diff\n\nRead-only subcommands:\n- `/cc-view status` - visual flow snapshot\n- `/cc-view tree` - deep flow tree (stages, artifacts, stale markers)\n- `/cc-view diff` - before/after flow-state diff map\n\nOperational work is handled by `/cc`, `/cc-next`, `/cc-ideate`, `/cc-view`, and `node .cclaw/hooks/stage-complete.mjs <stage>` inside the installed harness runtime. `npx cclaw-cli` is the installer/support surface for init, sync, upgrade, doctor, and explicit/manual archive; the normal stage flow must not depend on a runtime `cclaw` binary in PATH.\n\nCritical-path stage order remains canonical:\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nEvery track then closes out through:\n`retro -> compound -> archive`\n\n## Stage -> skill folder mapping\n\n| Stage | Skill folder |\n|---|---|\n| `brainstorm` | `brainstorming` |\n| `scope` | `scope-shaping` |\n| `design` | `engineering-design-lock` |\n| `spec` | `specification-authoring` |\n| `plan` | `planning-and-task-breakdown` |\n| `tdd` | `test-driven-development` |\n| `review` | `two-layer-review` |\n| `ship` | `shipping-and-handoff` |\n\nThis map is generated from `src/constants.ts::STAGE_TO_SKILL_FOLDER` so\nskill-path naming stays explicit and stable even when stage ids differ from\nfolder names.\n\n## Install surfaces\n\nAlways generated:\n\n- `.cclaw/commands/*.md`\n- `.cclaw/skills/*/SKILL.md`\n- `.cclaw/state/*.json|*.jsonl`\n- `AGENTS.md` managed block\n\nHarness-specific additions:\n\n- `claude`: `.claude/commands/cc*.md`, `.claude/hooks/hooks.json`\n- `cursor`: `.cursor/commands/cc*.md`, `.cursor/hooks.json`, `.cursor/rules/cclaw-workflow.mdc`\n- `opencode`: `.opencode/commands/cc*.md`, `.opencode/plugins/cclaw-plugin.mjs`, opencode plugin registration with `permission.question: \"allow\"`; set `OPENCODE_ENABLE_QUESTION_TOOL=1` for ACP clients so structured asks can route through question tooling. Doctor validates the config permission and warns when the environment hint is absent.\n- `codex`: `.agents/skills/cc/SKILL.md`, `.agents/skills/cc-next/SKILL.md`, `.agents/skills/cc-ideate/SKILL.md`, `.agents/skills/cc-view/SKILL.md`, `.codex/hooks.json` (Codex CLI reads `.agents/skills/` for custom skills and consumes `.codex/hooks.json` on v0.114+ when `[features] codex_hooks = true` is set in `~/.codex/config.toml`. `.codex/commands/` and the legacy `.agents/skills/cclaw-cc*/` layout from v0.39.x are auto-cleaned on sync.)\n\n## Runtime observability\n\n- `npx cclaw-cli doctor` validates shim, hook, and lifecycle surfaces against this capability model.\n- `/cc-view status` and `/cc-view tree` surface the same harness tier/fallback facts from the generated runtime metadata.\n\n## Delegation Proof Model\n\nRuntime state is split deliberately:\n\n- `.cclaw/state/delegation-log.json` is the compact current ledger used by stage gates and `/cc-view` summaries.\n- `.cclaw/state/delegation-events.jsonl` is append-only audit proof for `scheduled`, `launched`, `acknowledged`, `completed`, `failed`, `waived`, and `stale` lifecycle transitions.\n- `.cclaw/state/subagents.json` is a lightweight active-worker tracker for status/tree/doctor surfaces.\n- `.cclaw/hooks/delegation-record.mjs` is the generated helper for lifecycle rows/events. It validates required fields and emits JSON diagnostics with `--json`.\n\nIsolated completion requires `spanId`, `dispatchId` or `workerRunId`, `dispatchSurface`, `agentDefinitionPath`, `ackTs`, `launchedTs`, and `completedTs`. Cursor/generic dispatch and role-switch also require evidence refs when artifact evidence is the proof source. Legacy inferred completions remain readable, but doctor reports them as warnings because they predate event-log proof.\n\n## Reference Audit Appendix\n\nStatus meanings: `deep` = read for transferable implementation contract; `targeted` = inspected the relevant files only; `skimmed` = searched/read enough to classify; `not relevant` = intentionally excluded from implementation influence.\n\n| Reference path under `/Users/zuevrs/Downloads/references` | Status | Findings preserved |\n|---|---|---|\n| `evanklem-evanflow/skills/evanflow-coder-overseer/SKILL.md` | deep | Contract-first coder/overseer loop, reviewer reads code rather than worker narrative, and integration overseer pattern map cleanly onto cclaw subagent guidance. |\n| `evanklem-evanflow/agents/evanflow-coder.md` | targeted | Worker role is narrow: implement the pasted contract, avoid broad orchestration, and return evidence for overseer verification. |\n| `evanklem-evanflow/agents/evanflow-overseer.md` | targeted | Overseer validates actual code and acceptance evidence before controller marks work complete. |\n| `oh-my-codex/src/agents/native-config.ts` | deep | Native agent config shape supports explicit metadata/model/tool posture; cclaw should validate generated `.codex/agents/*.toml` shape instead of trusting file presence. |\n| `oh-my-codex/src/team/state/events.ts` and `src/team/state/workers.ts` | targeted | Append-only events plus worker state are useful as separate audit/current-state layers; cclaw mirrors that with `delegation-events.jsonl` and `subagents.json`. |\n| `oh-my-openagent/src/tools/delegate-task/tools.ts` | deep | Delegation should have an explicit dispatch surface and mode instead of relying on a prose claim that an agent was launched. |\n| `oh-my-openagent/src/tools/delegate-task/subagent-resolver.ts` | targeted | Agent discovery should be checked by doctor so missing/corrupt generated agent definitions are visible before dispatch. |\n| `oh-my-openagent/src/tools/delegate-task/prompt-builder.ts` | targeted | Prompt builders should include exact invocation/return contracts; cclaw generated worker prompts now carry ACK/result schemas. |\n| `giancarloerra-socraticode/**` | skimmed | Useful for workflow/e2e and graph-oriented contract testing, but not a subagent dispatch implementation reference; no runtime pattern imported. |\n| unrelated large reference trees not named above | not relevant | Searched/skipped because they did not contain flow/subagent/harness dispatch patterns relevant to this plan. |\n";
+}

package/dist/content/hooks.d.ts

@@ -1,5 +1,6 @@
 export declare function startFlowScript(): string;
 export declare function stageCompleteScript(): string;
+export declare function delegationRecordScript(): string;
 export declare function runHookCmdScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -260,6 +260,195 @@ async function main() {
   });
 }
 
+void main();
+`;
+}
+export function delegationRecordScript() {
+    return `#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const VALID_STATUSES = new Set(["scheduled", "launched", "acknowledged", "completed", "failed", "waived", "stale"]);
+const TERMINAL = new Set(["completed", "failed", "waived", "stale"]);
+
+function parseArgs(argv) {
+  const args = {};
+  for (const raw of argv) {
+    const valueMatch = /^--([^=]+)=(.*)$/u.exec(raw);
+    if (valueMatch) {
+      args[valueMatch[1]] = valueMatch[2];
+      continue;
+    }
+    const flagMatch = /^--([^=]+)$/u.exec(raw);
+    if (flagMatch) args[flagMatch[1]] = true;
+  }
+  return args;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectRoot() {
+  const candidates = [
+    process.env.CCLAW_PROJECT_ROOT,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_ROOT,
+    process.env.OPENCODE_PROJECT_DIR,
+    process.env.OPENCODE_PROJECT_ROOT,
+    process.cwd()
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  for (const candidate of candidates) {
+    if (await exists(path.join(candidate, RUNTIME_ROOT))) return candidate;
+  }
+  return candidates[0] || process.cwd();
+}
+
+async function readRunId(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "flow-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.activeRunId === "string" ? parsed.activeRunId : "unknown-run";
+  } catch {
+    return "unknown-run";
+  }
+}
+
+async function readDelegationEvents(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-events.jsonl"), "utf8");
+    return raw
+      .split(/\\r?\\n/u)
+      .filter((line) => line.trim().length > 0)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter((event) => event && typeof event === "object");
+  } catch {
+    return [];
+  }
+}
+
+function hasPriorAck(events, args, runId) {
+  return events.some((event) =>
+    event.runId === runId &&
+    event.stage === args.stage &&
+    event.agent === args.agent &&
+    event.spanId === args["span-id"] &&
+    event.event === "acknowledged" &&
+    typeof event.ackTs === "string" &&
+    event.ackTs.length > 0
+  );
+}
+
+function usage() {
+  process.stderr.write("Usage: node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--json]\\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const json = args.json !== undefined;
+  const problems = [];
+  if (!args.stage) problems.push("missing --stage");
+  if (!args.agent) problems.push("missing --agent");
+  if (args.mode !== "mandatory" && args.mode !== "proactive") problems.push("--mode must be mandatory or proactive");
+  if (!VALID_STATUSES.has(args.status)) problems.push("invalid --status");
+  if (!args["span-id"]) problems.push("missing --span-id");
+  if (args.status === "waived" && !args["waiver-reason"]) problems.push("waived status requires --waiver-reason");
+  if (args.status === "completed" && args["dispatch-surface"] !== "role-switch") {
+    for (const key of ["dispatch-id", "dispatch-surface", "agent-definition-path"]) {
+      if (!args[key]) problems.push("completed isolated/generic status requires --" + key);
+    }
+  }
+  if (args.status === "completed" && args["dispatch-surface"] === "role-switch" && !args["evidence-ref"]) {
+    problems.push("completed role-switch status requires --evidence-ref");
+  }
+  if (problems.length > 0) {
+    if (json) process.stdout.write(JSON.stringify({ ok: false, problems }, null, 2) + "\\n");
+    else {
+      usage();
+      process.stderr.write("[cclaw] delegation-record: " + problems.join("; ") + "\\n");
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const root = await detectRoot();
+  const now = new Date().toISOString();
+  const runId = await readRunId(root);
+  if (args.status === "completed" && args["dispatch-surface"] !== "role-switch" && !args["ack-ts"]) {
+    const priorEvents = await readDelegationEvents(root);
+    if (!hasPriorAck(priorEvents, args, runId)) {
+      const ackProblem = "completed isolated/generic status requires prior acknowledged event for same span or --ack-ts";
+      if (json) process.stdout.write(JSON.stringify({ ok: false, problems: [ackProblem] }, null, 2) + "\\n");
+      else {
+        usage();
+        process.stderr.write("[cclaw] delegation-record: " + ackProblem + "\\n");
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const status = args.status;
+  const row = {
+    stage: args.stage,
+    agent: args.agent,
+    mode: args.mode,
+    status,
+    spanId: args["span-id"],
+    dispatchId: args["dispatch-id"],
+    workerRunId: args["worker-run-id"],
+    dispatchSurface: args["dispatch-surface"],
+    agentDefinitionPath: args["agent-definition-path"],
+    fulfillmentMode: args["dispatch-surface"] === "role-switch" ? "role-switch" : args["dispatch-surface"] === "cursor-task" || args["dispatch-surface"] === "generic-task" ? "generic-dispatch" : "isolated",
+    waiverReason: args["waiver-reason"],
+    evidenceRefs: args["evidence-ref"] ? [args["evidence-ref"]] : [],
+    runId,
+    startTs: now,
+    ts: now,
+    launchedTs: args["launched-ts"] || (status === "launched" ? now : undefined),
+    ackTs: args["ack-ts"] || (status === "acknowledged" ? now : undefined),
+    completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
+    endTs: TERMINAL.has(status) ? now : undefined,
+    schemaVersion: 1
+  };
+  const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
+  const event = { ...clean, event: status, eventTs: now };
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
+  await fs.mkdir(stateDir, { recursive: true });
+  await fs.appendFile(path.join(stateDir, "delegation-events.jsonl"), JSON.stringify(event) + "\\n", { encoding: "utf8", mode: 0o600 });
+
+  const ledgerPath = path.join(stateDir, "delegation-log.json");
+  let ledger = { runId, entries: [] };
+  try {
+    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+    if (!Array.isArray(ledger.entries)) ledger.entries = [];
+  } catch {
+    ledger = { runId, entries: [] };
+  }
+  if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+    ledger.entries.push(clean);
+    ledger.runId = runId;
+    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  }
+
+  const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));
+  await fs.writeFile(path.join(stateDir, "subagents.json"), JSON.stringify({ active, updatedAt: now }, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
+}
+
 void main();
 `;
 }

package/dist/content/skills.js

@@ -67,14 +67,14 @@ function autoSubagentDispatchBlock(stage, track) {
     const mandatory = schema.mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "none";
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
+    const delegationEventsRel = `${RUNTIME_ROOT}/state/delegation-events.jsonl`;
     const artifactRef = `${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}`;
     return `## Automatic Subagent Dispatch
 | Agent | Mode | Class | Return Schema | User Gate | Trigger | Purpose |
 |---|---|---|---|---|---|---|
 ${rows}
-Mandatory: ${mandatoryList}. Record scheduled/completed/waived lifecycle rows in \`${delegationLogRel}\` before completion.
-### Harness Dispatch Contract
-Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Each dispatched worker should have a scheduled row and a terminal row sharing \`spanId\`; stale scheduled spans block completion. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
+Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.
+### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Helper: \`.cclaw/hooks/delegation-record.mjs --status=<status> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. Exact recipe: scheduled -> launched -> acknowledged -> completed with the same span; completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`.
 `;
 }
 function researchPlaybooksBlock(playbooks) {
@@ -248,8 +248,9 @@ function completionParametersBlock(schema, track) {
 - \`completion helper\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage}\`
 - \`completion helper with evidence\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage} --evidence-json '{"<gate_id>":"<evidence note>"}' --passed=<gate_id>[,<gate_id>]\`
 - \`completion helper JSON diagnostics\`: append \`--json\` to receive a machine-readable validation failure summary.
+- \`delegation record helper\`: \`node .cclaw/hooks/delegation-record.mjs --stage=${schema.stage} --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. \`delegation helper recipe\`: call \`--status=scheduled\`, then \`--status=launched\`, then \`--status=acknowledged\`, then \`--status=completed\` with the same \`--span-id\`, \`--dispatch-id\`, \`--dispatch-surface\`, and \`--agent-definition-path\`; completed isolated/generic rows fail unless that same span already has an acknowledged event or the completed call includes \`--ack-ts=<iso>\`. For role-switch fallback, use \`--dispatch-surface=role-switch --evidence-ref=<artifact#anchor>\` instead of pretending isolated completion.
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
-- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""}
+- Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""}
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;

package/dist/content/status-command.js

@@ -5,6 +5,12 @@ function flowStatePath() {
 function delegationLogPath() {
     return `${RUNTIME_ROOT}/state/delegation-log.json`;
 }
+function delegationEventsPath() {
+    return `${RUNTIME_ROOT}/state/delegation-events.jsonl`;
+}
+function subagentsPath() {
+    return `${RUNTIME_ROOT}/state/subagents.json`;
+}
 function knowledgePath() {
     return `${RUNTIME_ROOT}/knowledge.jsonl`;
 }
@@ -27,7 +33,7 @@ advancing or mutating anything. Safe to run at any point. The snapshot reflects:
 - progress across stages with per-stage markers,
 - gate coverage,
 - mandatory delegations with **fulfillmentMode** (isolated / generic-dispatch /
-  role-switch) plus explicit waived status and evidence gate,
+  role-switch), dispatch proof fields, explicit waived status, and evidence gate,
 - **closeout substate** after ship (retro → compound → archive),
 - **harness parity row** (tier + fallback) for the active harness set.
 
@@ -85,7 +91,7 @@ a read-only command.
   \`Current\`, \`Stage\`, \`Gates\`, \`Delegations\`, \`Blocked by\`, \`Next\`, \`Evidence needed\`.
 - When blocked, include a plain-English action block:
   \`Current: <stage or closeout substate>\`; \`Blocked by: <gate/delegation/blocker code>\`; \`Next: <exact command or managed remediation>\`; \`Evidence needed: <artifact/test/review/delegation evidence>\`.
-- Report counts, not full artifact contents.
+- Report counts, not full artifact contents. Include active subagent count from \`${subagentsPath()}\` and proof gaps from \`${delegationEventsPath()}\` when present.
 - If any data source is missing or corrupt, say so explicitly rather than guessing.
 - Include \`/cc-view tree\` for deep structure and \`/cc-view diff\` for before/after map in the final line.
 

package/dist/content/subagents.js

@@ -175,6 +175,10 @@ Borrow the good part of Team/Ruflo-style orchestration without adding a swarm ru
 - **Checkpoint before synthesis.** Each agent returns status, files inspected/changed, evidence, and blockers before the parent acts.
 - **Consensus is for hard calls only.** Use two reviewers when severity or architecture is disputed; otherwise one evidence-backed reviewer is enough.
 
+## Parallelization Decision Gate
+
+Before parallel dispatch, answer yes to all gates: tasks are independent, write sets do not overlap, outputs can be reconciled by evidence, and failure in one lane will not invalidate hidden assumptions in another. If any answer is no, serialize. Coder/overseer work is contract-first: the coder implements only the pasted contract, the overseer reads code and verifies acceptance evidence before the controller marks work complete.
+
 ## When to Use
 
 - Mid/large plans with multiple discrete tasks, dependencies, or risky overlap.
@@ -1013,9 +1017,9 @@ Two patterns (skills under \`.cclaw/skills/\`):
 - **SDD** (subagent-driven-development): sequential implementer→reviewer loops. Paste self-contained task text; never point subagents at plan files.
 - **Parallel Agents** (dispatching-parallel-agents): parallel review/analysis lenses. Never parallelize implementers on same codebase.
 
-Status contract: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED. Worker returns must use the strict JSON schemas in \`subagent-driven-development\`.
+Status contract: ACK first, then DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED. Worker returns must use the strict JSON schemas in \`subagent-driven-development\` and include matching spanId+dispatchId proof.
 
-- Controller sequentially dispatches **implementer → reviewer** loops per task.
+- Controller sequentially dispatches **implementer → reviewer** loops per task and records lifecycle events in \`.cclaw/state/delegation-events.jsonl\`.
 - HARD-GATE: paste **self-contained task text**; never point subagents at plan files to “discover” scope.
 - **Review fixers** are **fresh agents** after failed review passes — avoids parent-context pollution.
 - **Machine-only flow checks auto-dispatch** by stage (design/plan/tdd/review/ship) without asking the user to trigger each specialist manually.

package/dist/content/tree-command.js

@@ -5,6 +5,12 @@ function flowStatePath() {
 function delegationLogPath() {
     return `${RUNTIME_ROOT}/state/delegation-log.json`;
 }
+function delegationEventsPath() {
+    return `${RUNTIME_ROOT}/state/delegation-events.jsonl`;
+}
+function subagentsPath() {
+    return `${RUNTIME_ROOT}/state/subagents.json`;
+}
 function artifactsPath() {
     return `${RUNTIME_ROOT}/artifacts`;
 }
@@ -30,7 +36,7 @@ Do not modify state in this command. It is a pure read/render operation.
    - stage marker: passed/current/pending/skipped/stale,
    - gates summary,
    - artifact summary,
-   - delegation branch for current stage with fulfillmentMode labels,
+   - delegation branch for current stage with fulfillmentMode, dispatchSurface, proof status, and active tracker labels,
 6. When \`closeout.shipSubstate !== "idle"\` or \`currentStage === "ship"\`, add
    a closeout sub-tree:
    - \`retro:\` line derived from \`closeout.retroDraftedAt\` /

package/dist/delegation.d.ts

@@ -1,7 +1,9 @@
 import { type SubagentFallback } from "./harness-adapters.js";
 import type { FlowStage } from "./types.js";
 export type DelegationMode = "mandatory" | "proactive";
-export type DelegationStatus = "scheduled" | "completed" | "failed" | "waived";
+export type DelegationStatus = "scheduled" | "launched" | "acknowledged" | "completed" | "failed" | "waived" | "stale";
+export type DelegationDispatchSurface = "claude-task" | "cursor-task" | "opencode-agent" | "codex-agent" | "generic-task" | "role-switch" | "manual";
+export type DelegationEventType = DelegationStatus;
 /**
  * How a delegation was actually fulfilled. Advisory — mirrors the harness
  * `subagentFallback` that was in effect when the entry was recorded.
@@ -53,6 +55,20 @@ export type DelegationEntry = {
     retryCount?: number;
     /** Optional references to evidence anchors in artifacts. */
     evidenceRefs?: string[];
+    /** Dispatch proof id from the parent/controller side. */
+    dispatchId?: string;
+    /** Worker-reported run id or task id returned by the harness. */
+    workerRunId?: string;
+    /** Concrete runtime surface used to launch the worker. */
+    dispatchSurface?: DelegationDispatchSurface;
+    /** Path to the generated or canonical agent definition used for dispatch. */
+    agentDefinitionPath?: string;
+    /** ISO timestamp when the worker was acknowledged by the harness/worker. */
+    ackTs?: string;
+    /** ISO timestamp when the worker was launched. */
+    launchedTs?: string;
+    /** ISO timestamp when the worker completed. */
+    completedTs?: string;
     /** Optional skill marker used for role-specific mandatory checks. */
     skill?: string;
     /**
@@ -68,6 +84,11 @@ export type DelegationLedger = {
     runId: string;
     entries: DelegationEntry[];
 };
+export type DelegationEvent = DelegationEntry & {
+    event: DelegationEventType;
+    eventTs: string;
+    schemaVersion: 1;
+};
 /**
  * Heuristic: does a changed file path strongly imply a trust-boundary
  * surface? Used by tests and prompt guidance for risk-triggered review.
@@ -79,6 +100,10 @@ export type DelegationLedger = {
  */
 export declare function isTrustBoundaryPath(filePath: string): boolean;
 export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
+export declare function readDelegationEvents(projectRoot: string): Promise<{
+    events: DelegationEvent[];
+    corruptLines: number[];
+}>;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
 /**
  * Aggregate the fulfillment mode cclaw expects for the active harness set.
@@ -96,6 +121,12 @@ export declare function checkMandatoryDelegations(projectRoot: string, stage: Fl
     staleIgnored: string[];
     /** Delegation rows missing required evidence under a role-switch fallback. */
     missingEvidence: string[];
+    /** Native isolated completion rows that lack dispatch proof. */
+    missingDispatchProof: string[];
+    /** Legacy inferred isolated completions accepted only as migration warnings. */
+    legacyInferredCompletions: string[];
+    /** Current-run event log lines that could not be parsed. */
+    corruptEventLines: number[];
     /** Current-run scheduled rows with no terminal row sharing the same spanId. */
     staleWorkers: string[];
     /** Expected fulfillment mode for the active harness set. */

package/dist/delegation.js

@@ -9,13 +9,19 @@ import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
 const execFileAsync = promisify(execFile);
-const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived"]);
+const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
 function delegationLockPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", ".delegation.lock");
 }
+function delegationEventsPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-events.jsonl");
+}
+function subagentsStatePath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "subagents.json");
+}
 function createSpanId() {
     return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -131,13 +137,16 @@ function isDelegationEntry(value) {
     const o = value;
     const modeOk = o.mode === "mandatory" || o.mode === "proactive";
     const statusOk = o.status === "scheduled" ||
+        o.status === "launched" ||
+        o.status === "acknowledged" ||
         o.status === "completed" ||
         o.status === "failed" ||
-        o.status === "waived";
+        o.status === "waived" ||
+        o.status === "stale";
     const timestampOk = typeof o.ts === "string" ||
         typeof o.startTs === "string";
-    const terminalStatus = o.status === "completed" || o.status === "failed" || o.status === "waived";
-    const lifecycleOk = o.status !== "scheduled" || o.endTs === undefined;
+    const terminalStatus = o.status === "completed" || o.status === "failed" || o.status === "waived" || o.status === "stale";
+    const lifecycleOk = (o.status !== "scheduled" && o.status !== "launched" && o.status !== "acknowledged") || o.endTs === undefined;
     const terminalLifecycleOk = !terminalStatus ||
         o.endTs === undefined ||
         typeof o.endTs === "string";
@@ -168,12 +177,53 @@ function isDelegationEntry(value) {
             o.fulfillmentMode === "role-switch" ||
             o.fulfillmentMode === "harness-waiver") &&
         (o.conditionTrigger === undefined || typeof o.conditionTrigger === "string") &&
+        (o.dispatchId === undefined || typeof o.dispatchId === "string") &&
+        (o.workerRunId === undefined || typeof o.workerRunId === "string") &&
+        (o.dispatchSurface === undefined || isDelegationDispatchSurface(o.dispatchSurface)) &&
+        (o.agentDefinitionPath === undefined || typeof o.agentDefinitionPath === "string") &&
+        (o.ackTs === undefined || typeof o.ackTs === "string") &&
+        (o.launchedTs === undefined || typeof o.launchedTs === "string") &&
+        (o.completedTs === undefined || typeof o.completedTs === "string") &&
         (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
         retryOk &&
         (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
         (o.skill === undefined || typeof o.skill === "string") &&
         (o.schemaVersion === undefined || o.schemaVersion === 1));
 }
+function isDelegationDispatchSurface(value) {
+    return (value === "claude-task" ||
+        value === "cursor-task" ||
+        value === "opencode-agent" ||
+        value === "codex-agent" ||
+        value === "generic-task" ||
+        value === "role-switch" ||
+        value === "manual");
+}
+function statusTimestampPatch(entry, ts) {
+    const patch = { ...entry };
+    if (patch.status === "launched")
+        patch.launchedTs = patch.launchedTs ?? ts;
+    if (patch.status === "acknowledged")
+        patch.ackTs = patch.ackTs ?? ts;
+    if (patch.status === "completed")
+        patch.completedTs = patch.completedTs ?? patch.endTs ?? ts;
+    return patch;
+}
+function eventFromEntry(entry) {
+    const eventTs = entry.completedTs ?? entry.ackTs ?? entry.launchedTs ?? entry.endTs ?? entry.startTs ?? entry.ts ?? new Date().toISOString();
+    return {
+        ...entry,
+        event: entry.status,
+        eventTs,
+        schemaVersion: 1
+    };
+}
+function isDelegationEvent(value) {
+    if (!isDelegationEntry(value))
+        return false;
+    const o = value;
+    return o.event === o.status && typeof o.eventTs === "string";
+}
 function parseLedger(raw, runId) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         return { runId, entries: [] };
@@ -195,6 +245,9 @@ function parseLedger(raw, runId) {
                     startTs: ts,
                     endTs: TERMINAL_DELEGATION_STATUSES.has(item.status) ? (item.endTs ?? ts) : undefined,
                     ts,
+                    launchedTs: item.launchedTs ?? (item.status === "launched" ? ts : undefined),
+                    ackTs: item.ackTs ?? (item.status === "acknowledged" ? ts : undefined),
+                    completedTs: item.completedTs ?? (item.status === "completed" ? (item.endTs ?? ts) : undefined),
                     retryCount: typeof item.retryCount === "number" && Number.isInteger(item.retryCount) && item.retryCount >= 0
                         ? item.retryCount
                         : 0,
@@ -222,6 +275,57 @@ export async function readDelegationLedger(projectRoot) {
         return { runId: activeRunId, entries: [] };
     }
 }
+export async function readDelegationEvents(projectRoot) {
+    const filePath = delegationEventsPath(projectRoot);
+    if (!(await exists(filePath))) {
+        return { events: [], corruptLines: [] };
+    }
+    const events = [];
+    const corruptLines = [];
+    const text = await fs.readFile(filePath, "utf8").catch(() => "");
+    const lines = text.split(/\r?\n/gu);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isDelegationEvent(parsed)) {
+                events.push(parsed);
+            }
+            else {
+                corruptLines.push(index + 1);
+            }
+        }
+        catch {
+            corruptLines.push(index + 1);
+        }
+    }
+    return { events, corruptLines };
+}
+async function appendDelegationEvent(projectRoot, event) {
+    const filePath = delegationEventsPath(projectRoot);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+async function writeSubagentTracker(projectRoot, entries) {
+    const active = entries
+        .filter((entry) => entry.status === "scheduled" || entry.status === "launched" || entry.status === "acknowledged")
+        .map((entry) => ({
+        spanId: entry.spanId,
+        dispatchId: entry.dispatchId,
+        workerRunId: entry.workerRunId,
+        stage: entry.stage,
+        agent: entry.agent,
+        status: entry.status,
+        dispatchSurface: entry.dispatchSurface,
+        agentDefinitionPath: entry.agentDefinitionPath,
+        startedAt: entry.startTs,
+        launchedAt: entry.launchedTs,
+        acknowledgedAt: entry.ackTs
+    }));
+    await writeFileSafe(subagentsStatePath(projectRoot), `${JSON.stringify({ active, updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+}
 export async function appendDelegation(projectRoot, entry) {
     const { activeRunId } = await readFlowState(projectRoot);
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
@@ -231,13 +335,16 @@ export async function appendDelegation(projectRoot, entry) {
         if (entry.status === "waived" && !hasValidWaiverReason(entry.waiverReason)) {
             throw new Error("waived delegation entries require a non-empty waiverReason");
         }
-        const stamped = { ...entry, runId: entry.runId ?? activeRunId };
+        const stamped = statusTimestampPatch({ ...entry, runId: entry.runId ?? activeRunId }, startTs);
         stamped.spanId = entry.spanId ?? createSpanId();
         stamped.startTs = startTs;
         stamped.ts = startTs;
         if (TERMINAL_DELEGATION_STATUSES.has(stamped.status) && !stamped.endTs) {
             stamped.endTs = new Date().toISOString();
         }
+        if (stamped.status === "completed") {
+            stamped.completedTs = stamped.completedTs ?? stamped.endTs ?? new Date().toISOString();
+        }
         if (stamped.status === "scheduled") {
             delete stamped.endTs;
         }
@@ -268,11 +375,13 @@ export async function appendDelegation(projectRoot, entry) {
         if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
+        await appendDelegationEvent(projectRoot, eventFromEntry(stamped));
         const ledger = {
             runId: activeRunId,
             entries: [...prior.entries, stamped]
         };
         await writeFileSafe(filePath, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+        await writeSubagentTracker(projectRoot, ledger.entries);
     });
 }
 /**
@@ -299,6 +408,7 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const mandatory = stageSchema(stage, flowState.track).mandatoryDelegations;
     const { activeRunId } = flowState;
     const ledger = await readDelegationLedger(projectRoot);
+    const events = await readDelegationEvents(projectRoot);
     const forStage = ledger.entries.filter((e) => e.stage === stage);
     const forRun = forStage.filter((e) => e.runId === activeRunId);
     const staleIgnored = forStage
@@ -307,6 +417,8 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const missing = [];
     const waived = [];
     const missingEvidence = [];
+    const missingDispatchProof = [];
+    const legacyInferredCompletions = [];
     const terminalSpanIds = new Set(forRun
         .filter((entry) => TERMINAL_DELEGATION_STATUSES.has(entry.status) && entry.spanId)
         .map((entry) => entry.spanId));
@@ -342,13 +454,40 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {
             missingEvidence.push(agent);
         }
+        for (const row of completedRows) {
+            const mode = row.fulfillmentMode ?? "isolated";
+            if (mode === "isolated") {
+                const spanEvents = events.events.filter((event) => event.runId === activeRunId &&
+                    event.stage === stage &&
+                    event.agent === agent &&
+                    event.spanId === row.spanId);
+                const dispatchId = row.dispatchId ?? row.workerRunId ?? spanEvents.find((event) => event.dispatchId || event.workerRunId)?.dispatchId ?? spanEvents.find((event) => event.workerRunId)?.workerRunId;
+                const dispatchSurface = row.dispatchSurface ?? spanEvents.find((event) => event.dispatchSurface)?.dispatchSurface;
+                const agentDefinitionPath = row.agentDefinitionPath ?? spanEvents.find((event) => event.agentDefinitionPath)?.agentDefinitionPath;
+                const hasAck = Boolean(row.ackTs || spanEvents.some((event) => event.event === "acknowledged" && event.ackTs));
+                const hasCompleted = Boolean(row.completedTs || spanEvents.some((event) => event.event === "completed" && event.completedTs));
+                const hasDispatchProof = Boolean(row.spanId && dispatchId && dispatchSurface && agentDefinitionPath && hasAck && hasCompleted);
+                if (!hasDispatchProof) {
+                    const proofEraSignal = Boolean(row.dispatchId || row.workerRunId || row.dispatchSurface || row.agentDefinitionPath || spanEvents.some((event) => event.dispatchId || event.workerRunId || event.dispatchSurface || event.agentDefinitionPath || event.event === "acknowledged" || event.event === "launched"));
+                    if (proofEraSignal) {
+                        missingDispatchProof.push(agent);
+                    }
+                    else {
+                        legacyInferredCompletions.push(`${agent}(spanId=${row.spanId ?? "unknown"})`);
+                    }
+                }
+            }
+        }
     }
     return {
-        satisfied: missing.length === 0 && missingEvidence.length === 0 && staleWorkers.length === 0,
+        satisfied: missing.length === 0 && missingEvidence.length === 0 && missingDispatchProof.length === 0 && staleWorkers.length === 0 && events.corruptLines.length === 0,
         missing,
         waived,
         staleIgnored,
         missingEvidence,
+        missingDispatchProof,
+        legacyInferredCompletions,
+        corruptEventLines: events.corruptLines,
         staleWorkers,
         expectedMode
     };

package/dist/doctor-registry.js

@@ -107,6 +107,15 @@ const RULES = [
             docRef: ref("harnesses.md")
         }
     },
+    {
+        test: /^harness:reality:/,
+        metadata: {
+            severity: "info",
+            summary: "Harness reality label for dispatch/proof support.",
+            fix: "No action required; use this label to interpret native/generic/role-switch proof requirements.",
+            docRef: ref("harnesses.md")
+        }
+    },
     {
         test: /^delegation:/,
         metadata: {

package/dist/doctor.js

@@ -13,7 +13,7 @@ import { policyChecks } from "./policy.js";
 import { CorruptFlowStateError, readFlowState } from "./runs.js";
 import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
-import { checkMandatoryDelegations } from "./delegation.js";
+import { checkMandatoryDelegations, readDelegationEvents } from "./delegation.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -305,6 +305,20 @@ function normalizeOpenCodePluginEntry(entry) {
     }
     return null;
 }
+function generatedAgentShape(content, kind, agentName) {
+    if (kind === "opencode") {
+        return content.includes("mode: subagent") && content.includes(`# ${agentName}`) && content.includes("STRICT_RETURN_SCHEMA");
+    }
+    return content.includes(`name = "${agentName}"`) && content.includes("developer_instructions") && content.includes("STRICT_RETURN_SCHEMA");
+}
+function harnessRealityLabel(harness) {
+    const adapter = HARNESS_ADAPTERS[harness];
+    const declaredSupport = adapter.capabilities.nativeSubagentDispatch;
+    const runtimeLaunch = harness === "opencode" || harness === "codex" ? "prompt-level launch" : declaredSupport === "generic" ? "generic Task launch" : "native tool launch";
+    const proofRequired = adapter.capabilities.subagentFallback === "native" ? "dispatchId+spanId+ack" : "evidenceRefs";
+    const proofSource = harness === "opencode" ? ".opencode/agents + delegation-events.jsonl" : harness === "codex" ? ".codex/agents + delegation-events.jsonl" : ".cclaw/state/delegation-log.json";
+    return `declaredSupport=${declaredSupport}; runtimeLaunch=${runtimeLaunch}; proofRequired=${proofRequired}; proofSource=${proofSource}`;
+}
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 function opencodeConfigCandidates(projectRoot) {
     return [
@@ -780,6 +794,14 @@ export async function doctorChecks(projectRoot, options = {}) {
             }
         }
     }
+    for (const harness of configuredHarnesses) {
+        checks.push({
+            name: `harness:reality:${harness}`,
+            ok: true,
+            severity: "info",
+            details: harnessRealityLabel(harness)
+        });
+    }
     const agentsFile = path.join(projectRoot, "AGENTS.md");
     let agentsBlockOk = false;
     if (await exists(agentsFile)) {
@@ -884,12 +906,39 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: agentPath
         });
     }
+    for (const agent of CCLAW_AGENTS) {
+        if (configuredHarnesses.includes("opencode")) {
+            const agentPath = path.join(projectRoot, ".opencode", "agents", `${agent.name}.md`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "opencode", agent.name);
+            }
+            checks.push({
+                name: `agent:opencode:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated OpenCode subagent with mode: subagent and strict return schema`
+            });
+        }
+        if (configuredHarnesses.includes("codex")) {
+            const agentPath = path.join(projectRoot, ".codex", "agents", `${agent.name}.toml`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "codex", agent.name);
+            }
+            checks.push({
+                name: `agent:codex:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated Codex custom agent TOML with developer_instructions and strict return schema`
+            });
+        }
+    }
     // Hook scripts
     for (const script of [
         "run-hook.mjs",
         "run-hook.cmd",
         "stage-complete.mjs",
         "start-flow.mjs",
+        "delegation-record.mjs",
         "opencode-plugin.mjs"
     ]) {
         const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);
@@ -1774,6 +1823,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
         repairFeatureSystem: false
     });
+    const delegationEvents = await readDelegationEvents(projectRoot);
     const delegationSatisfiedForDoctor = currentStageUntouched || delegation.satisfied;
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
@@ -1785,7 +1835,30 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? `mandatory delegation check deferred for untouched stage "${flowState.currentStage}"; stage-complete enforces it when work begins`
             : delegation.satisfied
                 ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
-                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
+                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}; missingDispatchProof=${delegation.missingDispatchProof.join(", ")}; staleWorkers=${delegation.staleWorkers.join(", ")}; corruptEventLines=${delegation.corruptEventLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:events:parse",
+        ok: delegationEvents.corruptLines.length === 0,
+        details: delegationEvents.corruptLines.length === 0
+            ? `${RUNTIME_ROOT}/state/delegation-events.jsonl parsed successfully (${delegationEvents.events.length} event(s))`
+            : `corrupt delegation event line(s): ${delegationEvents.corruptLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:proof:current_stage",
+        ok: currentStageUntouched || delegation.missingDispatchProof.length === 0,
+        details: currentStageUntouched
+            ? `dispatch proof check deferred for untouched stage "${flowState.currentStage}"`
+            : delegation.missingDispatchProof.length === 0
+                ? `no dispatch proof gaps for current stage "${flowState.currentStage}"`
+                : `isolated completions missing dispatchId/dispatchSurface/agentDefinitionPath/ackTs/completedTs: ${delegation.missingDispatchProof.join(", ")}`
+    });
+    checks.push({
+        name: "warning:delegation:legacy_inferred_completions",
+        ok: true,
+        details: delegation.legacyInferredCompletions.length > 0
+            ? `warning: legacy inferred isolated completion rows lack event-log proof: ${delegation.legacyInferredCompletions.join(", ")}`
+            : "no legacy inferred isolated completions for current stage"
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/harness-adapters.d.ts

@@ -37,6 +37,12 @@ export type SubagentFallback =
 export type ShimKind = "command" | "skill";
 export interface HarnessAdapter {
     id: HarnessId;
+    reality: {
+        declaredSupport: "full" | "generic" | "partial" | "none";
+        runtimeLaunch: string;
+        proofRequired: string;
+        proofSource: string;
+    };
     /**
      * Root directory where cclaw writes `/cc*` entry points.
      *

package/dist/harness-adapters.js

@@ -71,6 +71,12 @@ export function harnessShimSkillNames() {
 export const HARNESS_ADAPTERS = {
     claude: {
         id: "claude",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "native Task launch",
+            proofRequired: "spanId+dispatchId or workerRunId+ACK for isolated completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus delegation-log.json"
+        },
         commandDir: ".claude/commands",
         shimKind: "command",
         capabilities: {
@@ -82,6 +88,12 @@ export const HARNESS_ADAPTERS = {
     },
     cursor: {
         id: "cursor",
+        reality: {
+            declaredSupport: "generic",
+            runtimeLaunch: "generic Task/Subagent launch with cclaw role prompt",
+            proofRequired: "spanId+dispatchId/evidenceRefs for generic-dispatch completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus artifact evidenceRefs"
+        },
         commandDir: ".cursor/commands",
         shimKind: "command",
         capabilities: {
@@ -97,6 +109,12 @@ export const HARNESS_ADAPTERS = {
     },
     opencode: {
         id: "opencode",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch via Task or @agent against generated .opencode/agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".opencode/agents/<agent>.md and .cclaw/state/delegation-events.jsonl"
+        },
         commandDir: ".opencode/commands",
         shimKind: "command",
         capabilities: {
@@ -119,6 +137,12 @@ export const HARNESS_ADAPTERS = {
     },
     codex: {
         id: "codex",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch by asking Codex to spawn generated custom agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".codex/agents/<agent>.toml and .cclaw/state/delegation-events.jsonl"
+        },
         // Codex CLI reads skills from the universal `.agents/skills/` path
         // (OpenAI Codex 0.89, Jan 2026). It does NOT have a native
         // `.codex/commands/*` slash-command discovery — cclaw installs
@@ -155,9 +179,9 @@ export function harnessDispatchSurface(harnessId) {
         case "cursor":
             return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
         case "opencode":
-            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>, run independent agents in parallel when safe, then record fulfillmentMode: \"isolated\".";
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
         case "codex":
-            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name, wait for all results, then record fulfillmentMode: \"isolated\".";
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
     }
 }
 export function harnessDispatchFallback(harnessId) {
@@ -597,7 +621,7 @@ async function cleanupLegacyCodexSurfaces(projectRoot) {
     }
 }
 function codexAgentToml(agent) {
-    const instructions = `${agent.body}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
+    const instructions = `${agentMarkdown(agent)}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
     const sandboxMode = agent.tools.some((tool) => ["Write", "Edit", "Bash"].includes(tool))
         ? "workspace-write"
         : "read-only";
@@ -625,7 +649,7 @@ permission:
 ${agentMarkdown(agent)}`;
 }
 function enhancedAgentInstruction(agentName) {
-    return `You are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary, produce evidence suitable for .cclaw/state/delegation-log.json, and do not recursively orchestrate other agents unless the parent explicitly asks.`;
+    return `## Worker ACK Contract\n\nYou are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary. ACK first with JSON containing spanId, dispatchId or workerRunId, dispatchSurface, agentDefinitionPath, ackTs, and status: "ACK". Finish with the strict return schema plus the same spanId+dispatchId proof so the parent can append .cclaw/state/delegation-events.jsonl and .cclaw/state/delegation-log.json. Do not let the parent claim isolated completion without matching ACK/result proof. Do not recursively orchestrate other agents unless the parent explicitly asks.`;
 }
 async function syncAgentFiles(projectRoot, harnesses) {
     const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");

package/dist/install.js

@@ -13,7 +13,7 @@ import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-co
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -884,6 +884,7 @@ async function writeHooks(projectRoot, config) {
         compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
     }));
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
+    await writeFileSafe(path.join(hooksDir, "delegation-record.mjs"), delegationRecordScript());
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
@@ -892,6 +893,7 @@ async function writeHooks(projectRoot, config) {
             "start-flow.mjs",
             "run-hook.mjs",
             "run-hook.cmd",
+            "delegation-record.mjs",
             "opencode-plugin.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.51.25",
+  "version": "0.51.26",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {