@veewo/claw 0.2.24 → 0.2.26

package/README.md

@@ -1,141 +1,141 @@
-# @veewo/claw
-
-`@veewo/claw` is the CLI entrypoint for running the `.claw` workflow in a project.
-
-It gives agents and developers a concrete way to plan work, recall project knowledge, deposit truth and ADR notes, and close rounds out cleanly instead of leaving project state scattered across transient chats.
-
-## What the CLI is for
-
-- initialize and normalize the `.claw` project surface
-- run project-scoped planning and task lifecycle commands
-- index and query project documentation recall
-- support truth ingestion and closeout flows
-
-## Install
-
-```bash
-npm install -g @veewo/claw
-```
-
-After installing the CLI, project search still needs one-time setup inside each `.claw` project:
-
-1. Run `claw context` so `.claw/project.json` is normalized and the default local embedding config is present.
-2. Run `claw search index --refresh` once so the local embedding model can be downloaded or reused and the first vector index can be built.
-
-## Host startup context
-
-`claw context --host <host>` is the single structured startup-state entrypoint
-for host adapters. A host Hook owns its native event payload, validates its
-trusted cwd and session identity, invokes `context`, and maps the JSON result
-to its own prompt, card, or host-action surface. The CLI does not own platform
-Hook event names or Hook-output envelopes.
-
-The result may contain `activeWorkflow`, `error`, `startupRecovery.versionSync`,
-and `searchGuidance`, in addition to project and session state. Adapters must
-not accept cwd or session identity from model input. A missing `activeWorkflow`
-means the session has no bound plan; it does not authorize plan discovery by
-scanning unrelated project tasks.
-
-Then run:
-
-```bash
-claw init
-claw search index --refresh
-claw search "existing truth or ADR topic"
-claw plan create --title "My task" --goal "Define the first task"
-claw plan create "My templated task" --template default --goal "Route through the default template"
-claw plan create "Ephemeral harness" --scope session --goal "Use plan and Goal workflows without project deposition"
-```
-
-`claw plan create` uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default` template. You can select a template explicitly with `claw plan create "<title>" --template <name>` or `claw plan create --template <name> --title "<title>"`.
-
-New project tasks are grouped under `.claw/tasks/YYYY-MM-DD/`. On the first `claw context` call of each local calendar day, claw performs a lock-protected maintenance pass: it removes expired entries from `.claw/runtime/tmp/`, removes workflow task directories that exceed the task TTL even when incomplete, moves eligible date-scoped task folders into the archive, applies `maxTasksToKeep` and archive TTL, removes expired or invalid bindings, and sweeps expired session workflows. This is lazy maintenance, not a background scheduler.
-
-`--scope session` stores the workflow in a user-level directory keyed by the platform session id, so it works without a project `.claw` directory and recovers across cwd changes. It preserves plan/task/subplan/Goal behavior while disabling project knowledge capture and project retention. When the session's frozen origin belongs to a valid claw project, its terminal transition refreshes that project's memory and enabled GitNexus index; otherwise it creates no refresh state. Use `claw session clean` for the current session or `claw session clean --expired` for the seven-day TTL sweep.
-
-Projects can add reusable templates directly under `.claw/templates` with `.json`, `.js`, `.mjs`, or `.cjs` files. Put `defaultPlanTemplate` in `.claw/project.json` for a shared team default, or in `.claw/project-override.json` for a local personal override.
-
-When `.claw/project.json` has `planning: true`, the default `default` template seeds one planning task in `process.discussing`. It loads the effective `externalPlanningSkill`, falling back to `claw-kit:planning`, and stays open while the requirements and proposed solution are discussed and confirmed with the user. Use `plan start` when execution tasks remain; when planning itself resolves the request, complete task 1 and close the plan.
-
-When `planning: false`, `claw plan create` seeds the smallest executable plan directly in `process.active`.
-
-## Workflow shape
-
-In a typical round, the CLI helps land this loop in a project:
-
-`plan` -> `search and recall` -> `execute` -> `deposit truth / ADR` -> `close out`
-
-That project-level plan structure helps agents carry longer-running work more cleanly than leaving the task in loose chat state alone.
-
-## Persistent sessions
-
-Open a persistent terminal with:
-
-```bash
-claw session open <dir> <agent-session-id>
-```
-
-The workdir is immutable for the lifetime of that session. Opening another
-directory closes the prior live connection and opens the composite identity
-`(canonical workdir, agent session id)`; two directories with the same agent id
-remain isolated.
-
-Inside the terminal, these commands implicitly target `currentPlan`:
-
-```text
-plan show [--simple]
-plan edit ...
-plan wait
-plan done --retrospective "..."
-task add ...
-task edit --id ...
-task done --id ...
-```
-
-Use `plan resume` to resume the retained current plan, `plan resume <planId>` to
-make a specified resumable plan current, and `plan leave` to enter
-`end.leave` and clear focus. Every `end.*` triggers end-state finalization;
-`end.leave` remains resumable and does not set `completedAt`.
-
-`search --dir <dir> <query>` changes only that search operation. It never
-changes the session workdir or current plan.
-
-On an interrupted connection, mutations are never replayed automatically.
-Reopen with the exact command returned by the error, then inspect
-`plan show --simple`. Retained v2 state expires seven days after its last
-update. Legacy session caches are not migrated and canonical plans are never
-deleted by v2 cleanup.
-
-Host adapters remain compatible with the stateless CLI. They can adopt
-`@veewo/claw-client` incrementally once they consume the same structured
-post-commit effects; opening a persistent session does not change existing
-adapter behavior.
-
-Codex startup workflow should rely on the session hook or startup recovery path instead of treating any extra manual recovery step as required after plan creation.
-
-## Search and recall
-
-`claw search` is the project recall command for `.claw` memory, truth, ADR, and declared markdown docs. Use it for retained project context rather than code search.
-
-When a task needs deeper code investigation or relationship tracing, GitNexus can complement this workflow, but it is optional rather than required for using `claw` itself.
-
-Typical setup:
-
-```bash
-claw context
-claw search index --refresh
-```
-
-If you need deeper backup detail on config or recall behavior, use the adapter reference notes in [packages/codex-adapter/references/project-config-reference.md](../codex-adapter/references/project-config-reference.md) or [packages/opencode-adapter/references/project-config-reference.md](../opencode-adapter/references/project-config-reference.md).
-
-## Configuration
-
-If you need backup `.claw/project.json` detail, start with the adapter reference notes above and use [docs/project-json-reference.md](../../docs/project-json-reference.md) only for deeper canonical detail.
-
-`claw-kit` also stays usable alongside other harnesses or external skills, so the CLI does not assume a single host or investigation surface.
-
-The config model is team-friendly as well: `.claw/project.json` carries the shared canonical workflow, while `.claw/project-override.json` leaves room for personal runtime preferences.
-
-## Repository
-
-- [claw-kit](https://github.com/chanyuenpang/claw-kit)
+# @veewo/claw
+
+`@veewo/claw` is the CLI entrypoint for running the `.claw` workflow in a project.
+
+It gives agents and developers a concrete way to plan work, recall project knowledge, deposit truth and ADR notes, and close rounds out cleanly instead of leaving project state scattered across transient chats.
+
+## What the CLI is for
+
+- initialize and normalize the `.claw` project surface
+- run project-scoped planning and task lifecycle commands
+- index and query project documentation recall
+- support truth ingestion and closeout flows
+
+## Install
+
+```bash
+npm install -g @veewo/claw
+```
+
+After installing the CLI, project search still needs one-time setup inside each `.claw` project:
+
+1. Run `claw context` so `.claw/project.json` is normalized and the default local embedding config is present.
+2. Run `claw search index --refresh` once so the local embedding model can be downloaded or reused and the first vector index can be built.
+
+## Host startup context
+
+`claw context --host <host>` is the single structured startup-state entrypoint
+for host adapters. A host Hook owns its native event payload, validates its
+trusted cwd and session identity, invokes `context`, and maps the JSON result
+to its own prompt, card, or host-action surface. The CLI does not own platform
+Hook event names or Hook-output envelopes.
+
+The result may contain `activeWorkflow`, `error`, `startupRecovery.versionSync`,
+and `searchGuidance`, in addition to project and session state. Adapters must
+not accept cwd or session identity from model input. A missing `activeWorkflow`
+means the session has no bound plan; it does not authorize plan discovery by
+scanning unrelated project tasks.
+
+Then run:
+
+```bash
+claw init
+claw search index --refresh
+claw search "existing truth or ADR topic"
+claw plan create --title "My task" --goal "Define the first task"
+claw plan create "My templated task" --template default --goal "Route through the default template"
+claw plan create "Ephemeral harness" --scope session --goal "Use plan and Goal workflows without project deposition"
+```
+
+`claw plan create` uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default` template. You can select a template explicitly with `claw plan create "<title>" --template <name>` or `claw plan create --template <name> --title "<title>"`.
+
+New project tasks are grouped under `.claw/tasks/YYYY-MM-DD/`. On the first `claw context` call of each local calendar day, claw performs a lock-protected maintenance pass: it removes expired entries from `.claw/runtime/tmp/`, removes workflow task directories that exceed the task TTL even when incomplete, moves eligible date-scoped task folders into the archive, applies `maxTasksToKeep` and archive TTL, removes expired or invalid bindings, and sweeps expired session workflows. This is lazy maintenance, not a background scheduler.
+
+`--scope session` stores the workflow in a user-level directory keyed by the platform session id, so it works without a project `.claw` directory and recovers across cwd changes. It preserves plan/task/subplan/Goal behavior while disabling project knowledge capture and project retention. When the session's frozen origin belongs to a valid claw project, its terminal transition refreshes that project's memory and enabled GitNexus index; otherwise it creates no refresh state. Use `claw session clean` for the current session or `claw session clean --expired` for the seven-day TTL sweep.
+
+Projects can add reusable templates directly under `.claw/templates` with `.json`, `.js`, `.mjs`, or `.cjs` files. Put `defaultPlanTemplate` in `.claw/project.json` for a shared team default, or in `.claw/project-override.json` for a local personal override.
+
+When `.claw/project.json` has `planning: true`, the default `default` template seeds one planning task in `process.discussing`. It loads the effective `externalPlanningSkill`, falling back to `claw-kit:planning`, and stays open while the requirements and proposed solution are discussed and confirmed with the user. Use `plan start` when execution tasks remain; when planning itself resolves the request, complete task 1 and close the plan.
+
+When `planning: false`, `claw plan create` seeds the smallest executable plan directly in `process.active`.
+
+## Workflow shape
+
+In a typical round, the CLI helps land this loop in a project:
+
+`plan` -> `search and recall` -> `execute` -> `deposit truth / ADR` -> `close out`
+
+That project-level plan structure helps agents carry longer-running work more cleanly than leaving the task in loose chat state alone.
+
+## Persistent sessions
+
+Open a persistent terminal with:
+
+```bash
+claw session open <dir> <agent-session-id>
+```
+
+The workdir is immutable for the lifetime of that session. Opening another
+directory closes the prior live connection and opens the composite identity
+`(canonical workdir, agent session id)`; two directories with the same agent id
+remain isolated.
+
+Inside the terminal, these commands implicitly target `currentPlan`:
+
+```text
+plan show [--simple]
+plan edit ...
+plan wait
+plan done --retrospective "..."
+task add ...
+task edit --id ...
+task done --id ...
+```
+
+Use `plan resume` to resume the retained current plan, `plan resume <planId>` to
+make a specified resumable plan current, and `plan leave` to enter
+`end.leave` and clear focus. Every `end.*` triggers end-state finalization;
+`end.leave` remains resumable and does not set `completedAt`.
+
+`search --dir <dir> <query>` changes only that search operation. It never
+changes the session workdir or current plan.
+
+On an interrupted connection, mutations are never replayed automatically.
+Reopen with the exact command returned by the error, then inspect
+`plan show --simple`. Retained v2 state expires seven days after its last
+update. Legacy session caches are not migrated and canonical plans are never
+deleted by v2 cleanup.
+
+Host adapters remain compatible with the stateless CLI. They can adopt
+`@veewo/claw-client` incrementally once they consume the same structured
+post-commit effects; opening a persistent session does not change existing
+adapter behavior.
+
+Codex startup workflow should rely on the session hook or startup recovery path instead of treating any extra manual recovery step as required after plan creation.
+
+## Search and recall
+
+`claw search` is the project recall command for `.claw` memory, truth, ADR, and declared markdown docs. Use it for retained project context rather than code search.
+
+When a task needs deeper code investigation or relationship tracing, GitNexus can complement this workflow, but it is optional rather than required for using `claw` itself.
+
+Typical setup:
+
+```bash
+claw context
+claw search index --refresh
+```
+
+If you need deeper backup detail on config or recall behavior, use the adapter reference notes in [packages/codex-adapter/references/project-config-reference.md](../codex-adapter/references/project-config-reference.md) or [packages/opencode-adapter/references/project-config-reference.md](../opencode-adapter/references/project-config-reference.md).
+
+## Configuration
+
+If you need backup `.claw/project.json` detail, start with the adapter reference notes above and use [docs/project-json-reference.md](../../docs/project-json-reference.md) only for deeper canonical detail.
+
+`claw-kit` also stays usable alongside other harnesses or external skills, so the CLI does not assume a single host or investigation surface.
+
+The config model is team-friendly as well: `.claw/project.json` carries the shared canonical workflow, while `.claw/project-override.json` leaves room for personal runtime preferences.
+
+## Repository
+
+- [claw-kit](https://github.com/chanyuenpang/claw-kit)

package/dist/cli.js

@@ -6,13 +6,13 @@ import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { buildDirectWorkflowGuidance, appendKnowledgeTaskConclusions, buildKnowledgeAtomicDispatch, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildDirectKnowledgeAssignments, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, assertRootPlanCreateAllowedForPlan, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findKnowledgeFinalizationJobPath, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveThreadGoalPlan, resolveKnowledgeWriterForHost, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, createPlanRef, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listKnowledgeFinalizationJobs, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, governKnowledgeMarkdownPaths, resolveKnowledgeDocUpdateSnapshot, recordKnowledgeFinalizationResult, unbindSession, writePlan, } from "@veewo/claw-core";
+import { buildDirectWorkflowGuidance, buildKnowledgeAtomicDispatch, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildDirectKnowledgeAssignments, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, assertRootPlanCreateAllowedForPlan, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findKnowledgeFinalizationJobPath, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveThreadGoalPlan, resolveKnowledgeWriterForHost, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, createPlanRef, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listKnowledgeFinalizationJobs, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, governKnowledgeMarkdownPaths, resolveKnowledgeDocUpdateSnapshot, recordKnowledgeFinalizationResult, unbindSession, writePlan, } from "@veewo/claw-core";
 import { buildCodexDriverEnvelope } from "./codex-driver.js";
 import { buildCodexHostActions } from "./codex-host-actions.js";
 import { checkCodexRuntime, resolveCodexSdkEntryPath } from "./codex-runtime.js";
-import { extractLatestFinalAssistantMessage, extractTaskDoneConclusions, findCodexTranscriptPath, } from "./codex-transcript.js";
+import { collectReport, registerReportCollector } from "./report-collector-registry.js";
 import { consumeBufferedHookInput } from "./knowledge-hook-preflight.js";
-import { resolveInvocationHost, withoutInvocationHost } from "./invocation-host.js";
+import { isSubagentPolicyHost, resolveInvocationHost, withoutInvocationHost } from "./invocation-host.js";
 import { runOpencodeKnowledgeWriter } from "./opencode-runner.js";
 import { ClawClient, ClawSessionError, } from "@veewo/claw-client";
 const CLI_VERSION = readCliVersion();
@@ -563,6 +563,9 @@ async function main() {
             case "knowledge":
                 await runKnowledge(args);
                 return;
+            case "internal-report-collector-register":
+                runInternalReportCollectorRegister(args);
+                return;
             case "direct":
                 runDirect(args, effectiveHost);
                 return;
@@ -1012,34 +1015,18 @@ function serializeSessionError(error) {
     }
     return { code: "SESSION_COMMAND_FAILED", message: error instanceof Error ? error.message : String(error) };
 }
-function readCindyKnowledgeClaimCaptureInput() {
-    const raw = fs.readFileSync(0, "utf8").trim();
-    if (!raw) {
-        throw new ClawError("PROJECT_CONFIG_INVALID", "Cindy knowledge claim report input is empty.");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new ClawError("PROJECT_CONFIG_INVALID", "Cindy knowledge claim report input is invalid JSON.");
-    }
-    const sessionId = typeof parsed.session_id === "string" ? parsed.session_id.trim() : "";
-    const turnId = typeof parsed.turn_id === "string" ? parsed.turn_id.trim() : "";
-    const taskConclusions = Array.isArray(parsed.task_conclusions)
-        ? parsed.task_conclusions.flatMap((entry) => {
-            if (!entry || typeof entry !== "object" || Array.isArray(entry))
-                return [];
-            const item = entry;
-            const itemTurnId = typeof item.turnId === "string" ? item.turnId.trim() : "";
-            const message = typeof item.message === "string" ? item.message.trim() : "";
-            return itemTurnId && message ? [{ turnId: itemTurnId, message }] : [];
-        })
-        : [];
-    if (!sessionId || !turnId) {
-        throw new ClawError("PROJECT_CONFIG_INVALID", "Cindy knowledge claim report input requires session_id and turn_id.");
+/** Adapter-only registration. The descriptor contains no host history schema. */
+function runInternalReportCollectorRegister(args) {
+    const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
+    const host = readRequiredFlag(args, "--collector-host");
+    const executable = readRequiredFlag(args, "--executable");
+    const collectorArgs = readRepeatedFlag(args, "--arg");
+    assertNoRemainingArgs(args, "internal-report-collector-register");
+    if (host !== "codex" && host !== "dsh" && host !== "cindy") {
+        throw new ClawError("PROJECT_CONFIG_INVALID", "report collector host must be codex, dsh, or cindy.");
     }
-    return { sessionId, turnId, taskConclusions };
+    registerReportCollector(projectRoot, { host, executable, args: collectorArgs });
+    printJson({ ok: true, command: "internal-report-collector-register", host });
 }
 async function runKnowledge(args) {
     const subcommand = args.shift();
@@ -1124,8 +1111,6 @@ async function runKnowledge(args) {
             const explicitJobPath = readOptionalFlag(args, "--job");
             const projectRoot = readOptionalFlag(args, "--project-root");
             const finalizeId = readOptionalFlag(args, "--finalize-id");
-            const captureCindyReport = readBooleanFlag(args, "--cindy-report-stdin");
-            const cindyCapture = captureCindyReport ? readCindyKnowledgeClaimCaptureInput() : undefined;
             if (explicitJobPath && (projectRoot || finalizeId)) {
                 throw new ClawError("PROJECT_CONFIG_INVALID", "knowledge claim accepts either --job or --project-root with --finalize-id.");
             }
@@ -1138,9 +1123,6 @@ async function runKnowledge(args) {
                 throw new Error(`Knowledge finalization ${finalizeId} is unavailable.`);
             }
             const queued = readKnowledgeFinalizationJob(jobPath);
-            if (queued.host === "codex" && queued.writer?.executionPolicy === "subagent" && queued.reportCapture?.mode === "claim" && queued.reportCapture.status !== "captured") {
-                await new Promise((resolve) => setTimeout(resolve, 10_000));
-            }
             const job = claimKnowledgeFinalizationJob(jobPath, {
                 prepare: (queued) => {
                     if (queued.writer?.executionPolicy !== "subagent"
@@ -1148,41 +1130,22 @@ async function runKnowledge(args) {
                         || queued.reportCapture.status === "captured") {
                         return;
                     }
-                    if (queued.host === "cindy") {
-                        if (!cindyCapture) {
-                            throw new Error(`Cindy report capture is unavailable for knowledge session ${queued.sessionId}.`);
-                        }
-                        if (cindyCapture.sessionId !== queued.sessionId) {
-                            throw new Error("Cindy report capture does not match the originating knowledge session.");
-                        }
-                        const capturedAt = new Date().toISOString();
-                        appendKnowledgeTaskConclusions(queued.reportPath, queued.sessionId, cindyCapture.taskConclusions, capturedAt);
-                        return {
-                            reportCapture: {
-                                ...queued.reportCapture,
-                                status: "captured",
-                                capturedAt,
-                                messageCount: cindyCapture.taskConclusions.length,
-                            },
-                        };
-                    }
-                    if (queued.host !== "codex") {
+                    if (queued.host !== "codex" && queued.host !== "dsh" && queued.host !== "cindy") {
                         throw new Error(`Claim-time report capture is unavailable for host ${queued.host ?? "unknown"}.`);
                     }
-                    const transcriptPath = findCodexTranscriptPath(queued.sessionId);
-                    if (!transcriptPath) {
-                        throw new Error(`Codex transcript is unavailable for knowledge session ${queued.sessionId}.`);
-                    }
-                    const conclusions = extractTaskDoneConclusions(transcriptPath, undefined, queued.reportCapture.startedAt, queued.planPath);
-                    const capturedAt = new Date().toISOString();
-                    appendKnowledgeTaskConclusions(queued.reportPath, queued.sessionId, conclusions, capturedAt);
+                    collectReport({
+                        host: queued.host,
+                        sessionId: queued.sessionId,
+                        projectRoot: queued.projectRoot,
+                        planPath: queued.planPath,
+                        canonicalReportPath: queued.reportPath,
+                        startedAt: queued.reportCapture.startedAt,
+                    });
                     return {
                         reportCapture: {
                             ...queued.reportCapture,
                             status: "captured",
-                            capturedAt,
-                            transcriptPath,
-                            messageCount: conclusions.length,
+                            capturedAt: new Date().toISOString(),
                         },
                     };
                 },
@@ -1395,9 +1358,8 @@ async function runPlan(args, effectiveHost) {
             if (current
                 && !current.plan.parentPlan
                 && effectiveWriter?.executionPolicy === "subagent"
-                && effectiveHost !== "codex"
-                && effectiveHost !== "cindy") {
-                throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex or Cindy host.', { host: effectiveHost ?? null });
+                && !isSubagentPolicyHost(effectiveHost)) {
+                throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex, Cindy, or DSH host.', { host: effectiveHost ?? null });
             }
             const terminalRefresh = entersEndTerminal
                 ? preparePlanTerminalRefresh(process.cwd(), ownerSessionKey)
@@ -1412,11 +1374,12 @@ async function runPlan(args, effectiveHost) {
             });
             const knowledgeDispatch = (current
                 && project
-                && (effectiveHost === "codex" || effectiveHost === "cindy")
+                && (isSubagentPolicyHost(effectiveHost))
                 && !current.plan.parentPlan
                 && effectiveWriter?.executionPolicy === "subagent"
                 && result.knowledgeFinalizeId)
                 ? buildKnowledgeDispatch({
+                    // The isSubagentPolicyHost gate above guarantees this is codex | cindy | dsh.
                     host: effectiveHost,
                     finalizeId: result.knowledgeFinalizeId,
                     writer: effectiveWriter,
@@ -1506,9 +1469,8 @@ async function runPlan(args, effectiveHost) {
                 : undefined, effectiveHost);
             if (!current.plan.parentPlan
                 && effectiveWriter?.executionPolicy === "subagent"
-                && effectiveHost !== "codex"
-                && effectiveHost !== "cindy") {
-                throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex or Cindy host.', { host: effectiveHost ?? null });
+                && !isSubagentPolicyHost(effectiveHost)) {
+                throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex, Cindy, or DSH host.', { host: effectiveHost ?? null });
             }
             const terminalRefresh = preparePlanTerminalRefresh(process.cwd(), ownerSessionKey);
             const result = await editPlan({
@@ -1519,11 +1481,12 @@ async function runPlan(args, effectiveHost) {
                 host: effectiveHost,
                 ownerSessionKey,
             });
-            const knowledgeDispatch = ((effectiveHost === "codex" || effectiveHost === "cindy")
+            const knowledgeDispatch = (isSubagentPolicyHost(effectiveHost)
                 && !current.plan.parentPlan
                 && effectiveWriter?.executionPolicy === "subagent"
                 && result.knowledgeFinalizeId)
                 ? buildKnowledgeDispatch({
+                    // The isSubagentPolicyHost gate above guarantees this is codex | cindy | dsh.
                     host: effectiveHost,
                     finalizeId: result.knowledgeFinalizeId,
                     writer: effectiveWriter,
@@ -2174,16 +2137,14 @@ async function runStopHook(effectiveHost) {
     const hookCwd = resolveHookCwd(payload);
     const sessionId = resolveOwnerSessionKey(payload);
     const turnId = readHookString(payload, "turn_id");
-    const transcriptPath = readHookString(payload, "transcript_path");
     const payloadMessage = readHookString(payload, "message");
     if (!hookCwd || !sessionId || !turnId || !containsClawDir(hookCwd)) {
         return;
     }
     try {
         const project = resolveProjectContext(hookCwd);
-        // Codex passes a transcript_path; opencode and other hosts without a file
-        // transcript pass the final assistant message inline. Either source is valid.
-        const message = payloadMessage ?? (transcriptPath ? extractLatestFinalAssistantMessage(transcriptPath, turnId) : null);
+        // Host adapters own history parsing and pass their current final inline.
+        const message = payloadMessage;
         if (!message) {
             return;
         }
@@ -2193,7 +2154,7 @@ async function runStopHook(effectiveHost) {
             turnId,
             message,
             host: effectiveHost,
-            taskConclusions: transcriptPath ? extractTaskDoneConclusions(transcriptPath, turnId) : [],
+            taskConclusions: [],
         });
         // Current named hosts own their runner in their adapters.  Keep the CLI
         // launcher only for jobs written by pre-adapter releases with no host.
@@ -3088,6 +3049,8 @@ function stripBom(content) {
     return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
 }
 function buildKnowledgeDispatch(input) {
+    // Cindy uses its Orca atomic dispatch; codex and dsh both dispatch through a
+    // native-subagent delegate (DSH: subagent / subagent_fork).
     if (input.host === "cindy") {
         return buildKnowledgeAtomicDispatch(input);
     }
@@ -3103,19 +3066,27 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
         ? completionRefresh.taskRetention.archivedCurrentTask.archivedPlanPath
         : undefined;
     const resolvedPlanPath = archivedPlanPath ?? result.planPath;
-    const codexResult = effectiveHost === "codex";
+    // codex and dsh share the same compact protocol and versioned hostActions
+    // (schemaVersion 1: update_plan / create_goal / update_goal). The Codex
+    // adapter consumes them via its fixed code-mode driver; the DSH adapter
+    // consumes them inside the claw_run tool's execute.
+    const hostActionsResult = effectiveHost === "codex" || effectiveHost === "dsh";
     const cindyResult = effectiveHost === "cindy";
-    const hostActions = codexResult ? buildCodexHostActions(result, { forceProjectionSync, actionIdPrefix: command === "plan.sync" ? `plan.sync:${createHash("sha256").update(result.planPath).digest("hex").slice(0, 16)}` : undefined }) : [];
+    const hostActions = hostActionsResult ? buildCodexHostActions(result, { forceProjectionSync, actionIdPrefix: command === "plan.sync" ? `plan.sync:${createHash("sha256").update(result.planPath).digest("hex").slice(0, 16)}` : undefined }) : [];
     const nextsteps = [
         ...result.workflowGuidance.nextsteps,
-        ...(knowledgeDispatch
+        // Manual-dispatch instruction for hosts WITHOUT automatic writer
+        // dispatch (codex/cindy/opencode). DSH's adapter auto-dispatches the
+        // writer subagent inside claw_run, so the model must NOT re-dispatch;
+        // injecting this line there would ask it to duplicate the dispatch.
+        ...(knowledgeDispatch && effectiveHost !== "dsh"
             ? ["A knowledgeDispatch is present: dispatch its unchanged prompt through the current Host's designated knowledge-finalizer now, then immediately end the Lead turn; do not wait for or poll that worker."]
             : []),
     ];
     const planSummary = result.planView.collapsedSummary;
     const includePlan = Boolean((command === "plan.create" || command === "subplan.create")
         && result.plan
-        && (!codexResult || result.workflowGuidance.stage === "discussion"));
+        && (!hostActionsResult || result.workflowGuidance.stage === "discussion"));
     const achievement = result.planStatus === "end.completed" && result.plan
         ? {
             status: result.planStatus,
@@ -3138,11 +3109,11 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
         ...(result.workflowGuidance.transition ? { transition: result.workflowGuidance.transition } : {}),
         ...(achievement ? { achievement } : {}),
         ...(knowledgeDispatch ? { knowledgeDispatch } : {}),
-        ...(!codexResult && result.previousPlanStatus ? { previousPlanStatus: result.previousPlanStatus } : {}),
+        ...(!hostActionsResult && result.previousPlanStatus ? { previousPlanStatus: result.previousPlanStatus } : {}),
         ...(hostActions.length ? { hostActions } : {}),
-        ...(!codexResult && result.changedTaskIds?.length ? { changedTaskIds: result.changedTaskIds } : {}),
-        ...(!codexResult && result.appendedTaskIds?.length ? { appendedTaskIds: result.appendedTaskIds } : {}),
-        ...(codexResult ? { stage: result.workflowGuidance.stage } : {}),
+        ...(!hostActionsResult && result.changedTaskIds?.length ? { changedTaskIds: result.changedTaskIds } : {}),
+        ...(!hostActionsResult && result.appendedTaskIds?.length ? { appendedTaskIds: result.appendedTaskIds } : {}),
+        ...(hostActionsResult ? { stage: result.workflowGuidance.stage } : {}),
         nextsteps,
         ...(result.workflowGuidance.nextTask ? { nextTask: result.workflowGuidance.nextTask } : {}),
         ...(result.workflowGuidance.notes?.trim() && !cindyResult
@@ -3160,8 +3131,8 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
                 failedOperation: result.operationChain.failedOperation,
             }
             : {}),
-        ...(!codexResult && !cindyResult && result.workflowGuidance.goalMode ? { goalMode: result.workflowGuidance.goalMode } : {}),
-        ...(!codexResult && !cindyResult && result.workflowGuidance.goalTool ? { goalTool: result.workflowGuidance.goalTool } : {}),
+        ...(!hostActionsResult && !cindyResult && result.workflowGuidance.goalMode ? { goalMode: result.workflowGuidance.goalMode } : {}),
+        ...(!hostActionsResult && !cindyResult && result.workflowGuidance.goalTool ? { goalTool: result.workflowGuidance.goalTool } : {}),
         ...(includePlan && result.plan ? { plan: result.plan } : {}),
         // Cindy's Ghost card is a Host-owned projection.  It needs the
         // canonical task list to render its expandable Todo view, but that
@@ -3177,7 +3148,7 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
                 },
             }
             : {}),
-        ...(!codexResult || !includePlan ? { planSummary } : {}),
+        ...(!hostActionsResult || !includePlan ? { planSummary } : {}),
     };
 }
 function compactDirectCommandResult(command, workflowGuidance, completionRefresh) {