@veewo/claw 0.1.77 → 0.1.79

package/dist/cli.js

@@ -5,14 +5,18 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { buildDirectWorkflowGuidance, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolveProjectContext, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemory, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, tryCleanupKnowledgeFinalizationReport, writeKnowledgeFinalizationJob, unbindSession, writePlan, } from "@veewo/claw-core";
+import { buildDirectWorkflowGuidance, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemory, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, tryCleanupKnowledgeFinalizationReport, writeKnowledgeFinalizationJob, unbindSession, writePlan, } from "@veewo/claw-core";
 import { buildCodexDriverEnvelope } from "./codex-driver.js";
 import { checkCodexRuntime, resolveCodexSdkEntryPath } from "./codex-runtime.js";
 import { extractLatestFinalAssistantMessage } from "./codex-transcript.js";
+import { consumeBufferedHookInput } from "./knowledge-hook-preflight.js";
+import { resolveInvocationHost, withoutInvocationHost } from "./invocation-host.js";
+import { runOpencodeKnowledgeWriter } from "./opencode-runner.js";
 const CLI_VERSION = readCliVersion();
 const TOP_LEVEL_COMMANDS = [
     { name: "init [options]", summary: "Initialize and normalize the .claw project surface." },
     { name: "context [--task <name>]", summary: "Resolve project context, auto-initializing or correcting .claw state." },
+    { name: "session clean [--expired]", summary: "Remove current or expired session workflow state." },
     { name: "check", summary: "Check and auto-correct .claw project protocol fields." },
     { name: "plan <subcommand> [options]", summary: "Plan lifecycle: create, start, edit, remove, wait, resume, show, done." },
     { name: "codex driver", summary: "Return the versioned code-mode driver used by the Codex adapter." },
@@ -33,7 +37,7 @@ const COMMAND_HELP = {
             { flag: "--name <project-name>", detail: "Human-readable project name." },
             { flag: "--context-path <file>", detail: "Extra context path to track (repeatable)." },
             { flag: "--ext-path <path>", detail: "External doc path to index (repeatable)." },
-            { flag: "--external-writer-skill <skill>", detail: "Skill id for the combined knowledge writer." },
+            { flag: "--external-writer-skill <skill>", detail: "Skill id override for the combined knowledge-writer pass." },
             { flag: "--planning true|false", detail: "Enable planning-aware default template behavior (default true)." },
             { flag: "--external-planning-skill <skill>", detail: "Skill id for an external planning skill." },
             { flag: "--gitnexus true|false", detail: "Enable GitNexus integration (default false)." },
@@ -48,6 +52,10 @@ const COMMAND_HELP = {
             { flag: "--task <name>", detail: "Resolve context scoped to a specific task." },
         ],
     },
+    session: {
+        usage: ["{script} session clean", "{script} session clean --expired"],
+        description: "Clean ephemeral session-scoped workflow state without touching a project .claw directory.",
+    },
     check: {
         usage: ["{script} check"],
         description: "Check the .claw project protocol and auto-correct any missing or malformed fields in project.json. Returns issues found and the paths that were fixed.",
@@ -58,14 +66,15 @@ const COMMAND_HELP = {
         subcommands: {
             create: {
                 usage: [
-                    "{script} plan create \"<title>\" [--goal <text>]",
-                    "{script} plan create --title <text> [--goal <text>] [--template <name>]",
+                    "{script} plan create \"<title>\" [--goal <text>] [--scope session]",
+                    "{script} plan create --title <text> [--goal <text>] [--template <name>] [--scope session]",
                 ],
                 description: "Create the task scope and initial plan from a template. Uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default`; planning-enabled projects start in process.discussing with the default planning bridge tasks, while planning-disabled projects start directly in process.active with one executable task.",
                 summary: "Create the task scope and initial plan.",
                 options: [
                     { flag: "--title <text>", detail: "Task title (required unless a positional title is given)." },
                     { flag: "--goal <text>", detail: "Optional goal text." },
+                    { flag: "--scope session", detail: "Use ephemeral per-session storage and disable project knowledge side effects." },
                     { flag: "--template <name>", detail: "Optional plan template name. Overrides the project's configured default template." },
                 ],
             },
@@ -328,19 +337,20 @@ const COMMAND_HELP = {
     },
     "internal-knowledge-finalize": {
         usage: ["{script} internal-knowledge-finalize --job <path>"],
-        description: "Internal: runs one queued knowledge deposition job through the Codex SDK.",
+        description: "Internal: runs one queued knowledge deposition job through the host-aware finalization runner (Codex SDK for codex host, opencode run for opencode host).",
         options: [{ flag: "--job <path>", detail: "(required) Finalization job JSON path." }],
     },
 };
 async function main() {
     const args = process.argv.slice(2);
     const explicitHost = readOptionalFlag(args, "--host");
-    if (explicitHost) {
-        if (!new Set(["codex", "opencode"]).has(explicitHost)) {
-            handleError(new ClawError("PROJECT_CONFIG_INVALID", `Unsupported host "${explicitHost}".`));
-            return;
-        }
-        process.env.CLAW_HOST = explicitHost;
+    let effectiveHost;
+    try {
+        effectiveHost = resolveInvocationHost(explicitHost, process.env.CLAW_HOST);
+    }
+    catch (error) {
+        handleError(error);
+        return;
     }
     const command = args.shift();
     if (command === "--help" || command === "-h") {
@@ -382,7 +392,10 @@ async function main() {
                 printJson(initProject(initInput));
                 return;
             case "context":
-                printJson(buildPublicContextOutput(await runContextCommand(args)));
+                printJson(buildPublicContextOutput(await runContextCommand(args, process.cwd(), resolveOwnerSessionKey(), effectiveHost)));
+                return;
+            case "session":
+                runSession(args);
                 return;
             case "check":
                 const checkResult = ensureProjectProtocol(process.cwd());
@@ -397,7 +410,7 @@ async function main() {
                 });
                 return;
             case "plan":
-                await runPlan(args);
+                await runPlan(args, effectiveHost);
                 return;
             case "codex":
                 runCodex(args);
@@ -406,10 +419,10 @@ async function main() {
                 await runTemplate(args);
                 return;
             case "task":
-                await runTask(args);
+                await runTask(args, effectiveHost);
                 return;
             case "subplan":
-                await runSubplan(args);
+                await runSubplan(args, effectiveHost);
                 return;
             case "switch-task":
                 printJson(switchTask({
@@ -425,13 +438,13 @@ async function main() {
                 runSearch(args);
                 return;
             case "direct":
-                runDirect(args);
+                runDirect(args, effectiveHost);
                 return;
             case "truth":
                 runTruth(args);
                 return;
             case "hook":
-                await runHook(args);
+                await runHook(args, effectiveHost);
                 return;
             case "help":
                 printHelp(args);
@@ -459,13 +472,36 @@ function runCodex(args) {
     assertNoRemainingArgs(args, "codex driver");
     printJson(buildCodexDriverEnvelope(CLI_VERSION));
 }
-async function runPlan(args) {
+function runSession(args) {
+    const subcommand = args.shift();
+    if (subcommand !== "clean") {
+        throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown session subcommand "${subcommand ?? ""}".`);
+    }
+    const expired = readBooleanFlag(args, "--expired");
+    assertNoRemainingArgs(args, "session clean");
+    if (expired) {
+        const removed = sweepExpiredSessionWorkflows();
+        printJson({ ok: true, command: "session.clean", expired: true, removedCount: removed.length, removed });
+        return;
+    }
+    const ownerSessionKey = resolveOwnerSessionKey();
+    if (!ownerSessionKey) {
+        throw new ClawError("PROJECT_CONFIG_INVALID", "session clean requires a platform session id.");
+    }
+    printJson({
+        ok: true,
+        command: "session.clean",
+        removed: deleteSessionWorkflow(ownerSessionKey),
+    });
+}
+async function runPlan(args, effectiveHost) {
     const subcommand = args.shift();
     switch (subcommand) {
         case "create":
             rejectFlags(args, ["--task", "--plan", "--content", "--status", "--parent-task-id", "--description"]);
             const explicitTitle = readOptionalFlag(args, "--title");
             const explicitTemplate = readOptionalFlag(args, "--template");
+            const scope = readWorkflowScope(args);
             const title = explicitTitle ?? readOptionalPositionalArg(args);
             const templateName = explicitTemplate;
             if (!title) {
@@ -473,14 +509,15 @@ async function runPlan(args) {
             }
             const result = await writePlan({
                 cwd: process.cwd(),
+                scope,
                 templateName,
                 title,
                 goalText: readOptionalFlag(args, "--goal"),
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
             });
             assertNoRemainingArgs(args, "plan create");
-            printJson(compactPlanCommandResult("plan.create", result));
+            printJson(compactPlanCommandResult("plan.create", result, effectiveHost));
             return;
         case "edit": {
             const target = readPlanMutationTarget(args);
@@ -493,10 +530,10 @@ async function runPlan(args) {
                 ...target,
                 operations,
                 commandSource: "plan.edit",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("plan.edit", result));
+            printJson(compactPlanCommandResult("plan.edit", result, effectiveHost));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -513,17 +550,17 @@ async function runPlan(args) {
                 ...target,
                 updates,
                 commandSource: "plan.edit",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("plan.remove", result));
+            printJson(compactPlanCommandResult("plan.remove", result, effectiveHost));
             return;
         }
         case "wait":
-            await runPlanStatusAlias(args, "process.wait", "plan.wait");
+            await runPlanStatusAlias(args, "process.wait", "plan.wait", effectiveHost);
             return;
         case "resume":
-            await runPlanStatusAlias(args, "process.active", "plan.resume");
+            await runPlanStatusAlias(args, "process.active", "plan.resume", effectiveHost);
             return;
         case "start": {
             const updates = readPlanFieldUpdates(args);
@@ -541,10 +578,10 @@ async function runPlan(args) {
                 planStatus: "process.active",
                 completeLifecycleBridge: true,
                 commandSource: "plan.start",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("plan.start", result));
+            printJson(compactPlanCommandResult("plan.start", result, effectiveHost));
             return;
         }
         case "done": {
@@ -561,22 +598,28 @@ async function runPlan(args) {
             };
             const target = readPlanMutationTarget(args);
             assertNoRemainingArgs(args, "plan done");
-            const gitNexusPreflightAnalyzed = ensureGitNexusReadyForPlanDone(process.cwd());
+            const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
+            const workflowProject = resolveWorkflowProjectContext(process.cwd(), ownerSessionKey);
+            const gitNexusPreflightAnalyzed = workflowProject.scope === "project"
+                ? ensureGitNexusReadyForPlanDone(process.cwd())
+                : false;
             const result = await editPlan({
                 cwd: process.cwd(),
                 ...target,
                 updates,
                 planStatus: "end.completed",
                 commandSource: "plan.done",
-                host: process.env.CLAW_HOST ?? undefined,
-                ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
-            });
-            const completionRefresh = queueCompletionRefresh({
-                cwd: process.cwd(),
-                taskName: result.taskName,
-                skipGitNexusRefresh: gitNexusPreflightAnalyzed,
+                host: effectiveHost,
+                ownerSessionKey,
             });
-            printJson(compactPlanCommandResult("plan.done", result, completionRefresh));
+            const completionRefresh = workflowProject.scope === "project"
+                ? queueCompletionRefresh({
+                    cwd: process.cwd(),
+                    taskName: result.taskName,
+                    skipGitNexusRefresh: gitNexusPreflightAnalyzed,
+                })
+                : undefined;
+            printJson(compactPlanCommandResult("plan.done", result, effectiveHost, completionRefresh));
             return;
         }
         case "show": {
@@ -585,6 +628,7 @@ async function runPlan(args) {
             const result = showPlan({
                 cwd: process.cwd(),
                 ...target,
+                ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
             printJson({
                 ok: true,
@@ -602,17 +646,17 @@ async function runPlan(args) {
             throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown plan subcommand "${subcommand ?? ""}".`);
     }
 }
-async function runPlanStatusAlias(args, planStatus, command) {
+async function runPlanStatusAlias(args, planStatus, command, effectiveHost) {
     const result = await editPlan({
         cwd: process.cwd(),
         ...readPlanMutationTarget(args),
         planStatus,
         commandSource: "plan.edit",
-        host: process.env.CLAW_HOST ?? undefined,
+        host: effectiveHost,
         ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
     });
     assertNoRemainingArgs(args, command);
-    printJson(compactPlanCommandResult(command, result));
+    printJson(compactPlanCommandResult(command, result, effectiveHost));
 }
 async function runTemplate(args) {
     const subcommand = args.shift();
@@ -642,6 +686,7 @@ async function runTemplate(args) {
                 command: "template.validate",
                 ok: true,
                 templateId: template.id,
+                ...(template.scope ? { scope: template.scope } : {}),
                 source: template.source,
                 ...(template.templatePath ? { templatePath: template.templatePath } : {}),
                 status: template.status,
@@ -659,7 +704,7 @@ async function runTemplate(args) {
             });
     }
 }
-async function runTask(args) {
+async function runTask(args, effectiveHost) {
     const subcommand = args.shift();
     switch (subcommand) {
         case "add": {
@@ -670,10 +715,10 @@ async function runTask(args) {
                 ...target,
                 operations,
                 commandSource: "plan.edit",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("task.add", result));
+            printJson(compactPlanCommandResult("task.add", result, effectiveHost));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -686,10 +731,10 @@ async function runTask(args) {
                 ...target,
                 operations,
                 commandSource: "plan.edit",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("task.edit", result));
+            printJson(compactPlanCommandResult("task.edit", result, effectiveHost));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -702,10 +747,10 @@ async function runTask(args) {
                 ...target,
                 operations,
                 commandSource: "plan.edit",
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("task.remove", result));
+            printJson(compactPlanCommandResult("task.remove", result, effectiveHost));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -717,10 +762,10 @@ async function runTask(args) {
                 cwd: process.cwd(),
                 ...target,
                 operations,
-                host: process.env.CLAW_HOST ?? undefined,
+                host: effectiveHost,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
-            printJson(compactPlanCommandResult("task.done", result));
+            printJson(compactPlanCommandResult("task.done", result, effectiveHost));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -762,7 +807,7 @@ function runSearch(args) {
         }),
     });
 }
-function runDirect(args) {
+function runDirect(args, effectiveHost) {
     assertNoRemainingArgs(args, "direct");
     const completionRefresh = queueCompletionRefresh({
         cwd: process.cwd(),
@@ -773,14 +818,29 @@ function runDirect(args) {
     });
     printJson(compactDirectCommandResult("direct", buildDirectWorkflowGuidance({
         projectConfig: resolveProjectContext(process.cwd()).projectConfig,
-        host: process.env.CLAW_HOST ?? undefined,
+        host: effectiveHost,
     }), completionRefresh));
 }
-async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = resolveOwnerSessionKey()) {
+async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = resolveOwnerSessionKey(), effectiveHost) {
     const taskName = readOptionalFlag(args, "--task");
     let initialized = false;
     let corrected = false;
     let fixedPaths = [];
+    const sessionProject = resolveSessionWorkflowContext(ownerSessionKey ?? undefined);
+    if (sessionProject) {
+        const activeWorkflow = !taskName && ownerSessionKey
+            ? await tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveHost)
+            : null;
+        const codexRuntime = effectiveHost === "codex" ? checkCodexRuntime() : null;
+        const codexRuntimeError = codexRuntime && !codexRuntime.ok
+            ? buildCodexRuntimeError(codexRuntime.detail)
+            : null;
+        return {
+            project: sessionProject,
+            ...(activeWorkflow ? { activeWorkflow } : {}),
+            ...(codexRuntimeError ? { error: codexRuntimeError } : {}),
+        };
+    }
     try {
         const ensureResult = ensureProjectProtocol(cwd);
         corrected = ensureResult.changed;
@@ -803,9 +863,9 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
         resolved = resolveContext(cwd, taskName);
     }
     const activeWorkflow = !taskName && ownerSessionKey
-        ? await tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey)
+        ? await tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveHost)
         : null;
-    const codexRuntime = process.env.CLAW_HOST === "codex" ? checkCodexRuntime() : null;
+    const codexRuntime = effectiveHost === "codex" ? checkCodexRuntime() : null;
     const codexRuntimeError = codexRuntime && !codexRuntime.ok
         ? buildCodexRuntimeError(codexRuntime.detail)
         : null;
@@ -839,6 +899,7 @@ function buildPublicContextOutput(context) {
     const output = {};
     if (project) {
         output.project = {
+            ...(project.scope === "session" ? { scope: "session" } : {}),
             projectRoot: project.projectRoot,
             clawDir: project.clawDir,
             projectId: project.projectId,
@@ -853,6 +914,12 @@ function buildPublicContextOutput(context) {
     if (context.activeWorkflow !== undefined) {
         output.activeWorkflow = context.activeWorkflow;
     }
+    else {
+        output.session = {
+            boundPlan: false,
+            note: "No plan is bound to this session yet. Ask the user for the task scope, or run `claw plan create` when ready to start one.",
+        };
+    }
     if (context.error !== undefined) {
         output.error = context.error;
     }
@@ -1010,17 +1077,17 @@ function runTruth(args) {
             throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown truth subcommand "${subcommand ?? ""}".`);
     }
 }
-async function runHook(args) {
+async function runHook(args, effectiveHost) {
     const eventName = args.shift();
     if (!eventName) {
         throw new ClawError("PROJECT_CONFIG_INVALID", "claw hook requires an event name.");
     }
     if (eventName === "SessionStart" || eventName === "auto-claw") {
-        await runSessionStartHook();
+        await runSessionStartHook(effectiveHost);
         return;
     }
     if (eventName === "Stop" || eventName === "auto-doc") {
-        await runStopHook();
+        await runStopHook(effectiveHost);
         return;
     }
     const project = tryResolveHookProject(process.cwd());
@@ -1057,7 +1124,7 @@ async function runHook(args) {
         logPath,
     });
 }
-async function runStopHook() {
+async function runStopHook(effectiveHost) {
     if (process.env.CLAW_KNOWLEDGE_FINALIZER === "1") {
         return;
     }
@@ -1066,12 +1133,15 @@ async function runStopHook() {
     const sessionId = resolveOwnerSessionKey(payload);
     const turnId = readHookString(payload, "turn_id");
     const transcriptPath = readHookString(payload, "transcript_path");
-    if (!hookCwd || !sessionId || !turnId || !transcriptPath || !containsClawDir(hookCwd)) {
+    const payloadMessage = readHookString(payload, "message");
+    if (!hookCwd || !sessionId || !turnId || !containsClawDir(hookCwd)) {
         return;
     }
     try {
         const project = resolveProjectContext(hookCwd);
-        const message = extractLatestFinalAssistantMessage(transcriptPath);
+        // 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) : null);
         if (!message) {
             return;
         }
@@ -1080,6 +1150,7 @@ async function runStopHook() {
             sessionId,
             turnId,
             message,
+            host: effectiveHost,
         });
         if (result.ok && result.jobPath && process.env.CLAW_KNOWLEDGE_FINALIZER_DISABLE_LAUNCH !== "1") {
             launchKnowledgeFinalizationWorker(result.jobPath, project.projectRoot);
@@ -1096,27 +1167,8 @@ async function runInternalKnowledgeFinalize(args) {
         return;
     }
     try {
-        const sdk = await import(pathToFileURL(resolveCodexSdkEntryPath()).href);
-        const Codex = sdk.Codex;
-        const codex = new Codex({
-            env: knowledgeFinalizerEnvironment(),
-            ...(process.env.CLAW_CODEX_PATH_OVERRIDE
-                ? { codexPathOverride: process.env.CLAW_CODEX_PATH_OVERRIDE }
-                : {}),
-        });
-        const writer = running.writer ?? { model: null, reasoningEffort: "medium" };
-        const thread = codex.startThread({
-            workingDirectory: running.projectRoot,
-            sandboxMode: "workspace-write",
-            approvalPolicy: "never",
-            networkAccessEnabled: false,
-            ...(writer.model ? { model: writer.model } : {}),
-            ...(writer.reasoningEffort
-                ? { modelReasoningEffort: writer.reasoningEffort }
-                : {}),
-        });
-        const turn = await thread.run(buildKnowledgeWriterPrompt(running));
         const project = resolveProjectContext(running.projectRoot);
+        const writerRun = await runKnowledgeWriterForJob(running);
         const truthEncoding = normalizeTruthMarkdownEncoding(project);
         queueCompletionRefresh({
             cwd: running.projectRoot,
@@ -1130,8 +1182,8 @@ async function runInternalKnowledgeFinalize(args) {
             ...running,
             status: "succeeded",
             finishedAt: new Date().toISOString(),
-            ...(thread.id ? { sdkThreadId: thread.id } : {}),
-            finalResponse: turn.finalResponse,
+            ...(writerRun.threadId ? { sdkThreadId: writerRun.threadId } : {}),
+            finalResponse: writerRun.finalResponse,
             truthEncoding,
         });
         tryCleanupKnowledgeFinalizationReport(project, running.reportPath);
@@ -1149,9 +1201,57 @@ async function runInternalKnowledgeFinalize(args) {
         }
     }
 }
+/**
+ * Pick the host-aware finalization runner. The opencode host never assumes a Codex SDK
+ * runtime is installed and runs the writer through `opencode run`; the Codex host and
+ * legacy jobs without a host field keep using the versioned Codex SDK runtime.
+ */
+async function runKnowledgeWriterForJob(running) {
+    if (running.host === "opencode") {
+        const result = runOpencodeKnowledgeWriter({
+            prompt: buildKnowledgeWriterPrompt(running),
+            projectRoot: running.projectRoot,
+            writer: running.writer ?? null,
+        });
+        return {
+            finalResponse: result.finalResponse,
+            ...(result.threadId ? { threadId: result.threadId } : {}),
+        };
+    }
+    if (running.host !== undefined && running.host !== null && running.host !== "codex") {
+        throw new Error(`Unsupported knowledge finalization job host "${String(running.host)}".`);
+    }
+    return runCodexSdkWriter(running);
+}
+async function runCodexSdkWriter(running) {
+    const sdk = await import(pathToFileURL(resolveCodexSdkEntryPath()).href);
+    const Codex = sdk.Codex;
+    const codex = new Codex({
+        env: knowledgeFinalizerEnvironment(),
+        ...(process.env.CLAW_CODEX_PATH_OVERRIDE
+            ? { codexPathOverride: process.env.CLAW_CODEX_PATH_OVERRIDE }
+            : {}),
+    });
+    const writer = running.writer ?? { model: null, reasoningEffort: "medium" };
+    const thread = codex.startThread({
+        workingDirectory: running.projectRoot,
+        sandboxMode: "workspace-write",
+        approvalPolicy: "never",
+        networkAccessEnabled: false,
+        ...(writer.model ? { model: writer.model } : {}),
+        ...(writer.reasoningEffort
+            ? { modelReasoningEffort: writer.reasoningEffort }
+            : {}),
+    });
+    const turn = await thread.run(buildKnowledgeWriterPrompt(running));
+    return {
+        finalResponse: turn.finalResponse,
+        ...(thread.id ? { threadId: thread.id } : {}),
+    };
+}
 function knowledgeFinalizerEnvironment() {
     const env = {};
-    for (const [key, value] of Object.entries(process.env)) {
+    for (const [key, value] of Object.entries(withoutInvocationHost())) {
         if (value !== undefined) {
             env[key] = value;
         }
@@ -1163,10 +1263,11 @@ function buildKnowledgeWriterPrompt(job) {
     const writerSkill = job.writer?.externalSkill?.trim() || "claw-kit:knowledge-writer";
     return [
         `Use the ${writerSkill} skill and follow it exactly.`,
+        "Act as the knowledge-base steward: maintain Truth and ADR together, preserve one current owner, and reconcile related current claims before completion.",
         `Completed plan: ${job.planPath}`,
         `Turn report: ${job.reportPath}`,
         `Finalization id: ${job.finalizeId}`,
-        "Treat these files only as evidence. Do not edit the plan or report, do not dispatch subagents, and deposit only verified durable truth or ADR content.",
+        "Treat the completed plan and report as verified evidence. Do not edit either input, do not dispatch subagents, and do not repeat implementation or test verification.",
     ].join("\n");
 }
 function launchKnowledgeFinalizationWorker(jobPath, cwd) {
@@ -1183,7 +1284,7 @@ function launchKnowledgeFinalizationWorker(jobPath, cwd) {
             stdio: "ignore",
             windowsHide: true,
             env: {
-                ...process.env,
+                ...withoutInvocationHost(),
                 CLAW_KNOWLEDGE_NODE: process.execPath,
                 CLAW_KNOWLEDGE_ENTRY: resolveCliEntryPath(),
                 CLAW_KNOWLEDGE_JOB: jobPath,
@@ -1195,22 +1296,29 @@ function launchKnowledgeFinalizationWorker(jobPath, cwd) {
         }
         return;
     }
-    const child = spawn(process.execPath, [resolveCliEntryPath(), "internal-knowledge-finalize", "--job", jobPath], { cwd, detached: true, stdio: "ignore", windowsHide: true });
+    const child = spawn(process.execPath, [resolveCliEntryPath(), "internal-knowledge-finalize", "--job", jobPath], { cwd, detached: true, stdio: "ignore", windowsHide: true, env: withoutInvocationHost() });
     child.unref();
 }
-async function runSessionStartHook() {
+async function runSessionStartHook(effectiveHost) {
     if (process.env.CLAW_KNOWLEDGE_FINALIZER === "1") {
         return;
     }
     const payload = await readStdinJson();
     const hookCwd = resolveHookCwd(payload);
     const ownerSessionKey = resolveOwnerSessionKey(payload);
-    if (!hookCwd || !containsClawDir(hookCwd)) {
+    if (!hookCwd) {
+        return;
+    }
+    const sessionProject = resolveSessionWorkflowContext(ownerSessionKey ?? undefined);
+    if (!containsClawDir(hookCwd) && !sessionProject) {
         return;
     }
     try {
-        const context = await runContextCommand([], hookCwd, ownerSessionKey);
-        if (!context.error && process.env.CLAW_KNOWLEDGE_FINALIZER_DISABLE_LAUNCH !== "1") {
+        const context = await runContextCommand([], hookCwd, ownerSessionKey, effectiveHost);
+        const contextProject = asJsonRecord(context.project);
+        if (contextProject?.scope !== "session"
+            && !context.error
+            && process.env.CLAW_KNOWLEDGE_FINALIZER_DISABLE_LAUNCH !== "1") {
             const project = resolveProjectContext(hookCwd);
             for (const jobPath of listRetryableKnowledgeFinalizationJobs(project)) {
                 try {
@@ -1349,7 +1457,6 @@ function buildRecoveredWorkflowAdditionalContext(activeWorkflow, versionSyncProm
     const workflowGuidance = activeWorkflow.workflowGuidance;
     const nextsteps = toStringList(workflowGuidance?.nextsteps);
     const recommendedCommands = toStringList(workflowGuidance?.recommendedCommands);
-    const delegateSubagents = toDelegateNames(workflowGuidance?.delegateSubagents);
     const notes = typeof workflowGuidance?.notes === "string" ? workflowGuidance.notes.trim() : "";
     const askUser = summarizeAskUser(workflowGuidance?.askUser);
     const goalMode = summarizeGoalMode(workflowGuidance?.goalMode);
@@ -1361,7 +1468,6 @@ function buildRecoveredWorkflowAdditionalContext(activeWorkflow, versionSyncProm
         planSummary,
         nextsteps,
         recommendedCommands,
-        delegateSubagents,
         notes,
         askUser: askUser ?? "",
         goalMode: goalMode ?? "",
@@ -1470,8 +1576,8 @@ function summarizeRecoveredPlanContent(planContent) {
     }
     return lines.length > 0 ? lines : ["- plan content present in activeWorkflow.planContent JSON."];
 }
-async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey) {
-    const project = resolveProjectContext(cwd);
+async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveHost) {
+    const project = resolveWorkflowProjectContext(cwd, ownerSessionKey);
     const planPath = resolveSessionBoundPlan(project, ownerSessionKey);
     if (!planPath) {
         return null;
@@ -1489,6 +1595,7 @@ async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey) {
             cwd,
             taskName,
             planFile,
+            ownerSessionKey,
         });
         if (result.plan.status.startsWith("end.")) {
             unbindSession(project, ownerSessionKey);
@@ -1507,6 +1614,7 @@ async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey) {
                 plan: result.plan,
                 projectRoot: project.projectRoot,
                 projectConfig: project.projectConfig,
+                host: effectiveHost,
             }),
         };
     }
@@ -1515,7 +1623,7 @@ async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey) {
         return null;
     }
 }
-async function runSubplan(args) {
+async function runSubplan(args, effectiveHost) {
     const subcommand = args.shift();
     switch (subcommand) {
         case "create": {
@@ -1525,9 +1633,10 @@ async function runSubplan(args) {
                 parentTaskId: readOptionalNumber(args, "--task-id") ?? failMissingNumericFlag("--task-id"),
                 templateName: readOptionalFlag(args, "--template") ?? undefined,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
+                host: effectiveHost,
             });
             assertNoRemainingArgs(args, "subplan create");
-            printJson(compactPlanCommandResult("subplan.create", result));
+            printJson(compactPlanCommandResult("subplan.create", result, effectiveHost));
             return;
         }
         default:
@@ -1559,16 +1668,6 @@ function toStringList(value) {
             .map((item) => item.trim())
         : [];
 }
-function toDelegateNames(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map((entry) => (entry && typeof entry === "object" && typeof entry.name === "string"
-        ? entry.name.trim()
-        : ""))
-        .filter((entry) => Boolean(entry));
-}
 function summarizeAskUser(value) {
     if (!value || typeof value.reason !== "string" || !value.reason.trim()) {
         return null;
@@ -1582,11 +1681,14 @@ function summarizeGoalMode(value) {
     return value.recommendedObjective.trim();
 }
 async function readStdinJson() {
+    const bufferedInput = consumeBufferedHookInput();
     const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+    if (bufferedInput === null) {
+        for await (const chunk of process.stdin) {
+            chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        }
     }
-    const raw = chunks.join("").trim();
+    const raw = (bufferedInput ?? chunks.join("")).trim();
     if (!raw) {
         return null;
     }
@@ -1603,14 +1705,14 @@ function readJson(filePath) {
 function stripBom(content) {
     return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
 }
-function compactPlanCommandResult(command, result, completionRefresh) {
+function compactPlanCommandResult(command, result, effectiveHost, completionRefresh) {
     const archivedPlanPath = completionRefresh?.taskRetention.archivedCurrentTask?.taskName === result.taskName &&
         completionRefresh.taskRetention.archivedCurrentTask.archivedPlanPath
         ? completionRefresh.taskRetention.archivedCurrentTask.archivedPlanPath
         : undefined;
     const resolvedPlanPath = archivedPlanPath ?? result.planPath;
-    const hostActions = buildHostActions(result);
-    const codexResult = process.env.CLAW_HOST === "codex";
+    const codexResult = effectiveHost === "codex";
+    const hostActions = codexResult ? buildHostActions(result) : [];
     return {
         ok: true,
         command,
@@ -1618,17 +1720,12 @@ function compactPlanCommandResult(command, result, completionRefresh) {
         ...(archivedPlanPath ? { archivedPlanPath } : {}),
         planStatus: result.planStatus,
         ...(!codexResult && result.previousPlanStatus ? { previousPlanStatus: result.previousPlanStatus } : {}),
-        ...(!codexResult && result.emittedEvents?.length ? { emittedEvents: result.emittedEvents } : {}),
-        ...(!codexResult && result.events?.length ? { events: result.events } : {}),
         ...(hostActions.length ? { hostActions } : {}),
         ...(!codexResult && result.changedTaskIds?.length ? { changedTaskIds: result.changedTaskIds } : {}),
         ...(!codexResult && result.appendedTaskIds?.length ? { appendedTaskIds: result.appendedTaskIds } : {}),
         ...(codexResult ? { stage: result.workflowGuidance.stage } : {}),
         ...(!codexResult ? { nextsteps: result.workflowGuidance.nextsteps } : {}),
         ...(result.workflowGuidance.nextTask ? { nextTask: result.workflowGuidance.nextTask } : {}),
-        ...(result.workflowGuidance.delegateSubagents?.length
-            ? { delegateSubagents: result.workflowGuidance.delegateSubagents }
-            : {}),
         ...(result.workflowGuidance.notes?.trim() && !codexResult
             ? { notes: result.workflowGuidance.notes }
             : {}),
@@ -1730,9 +1827,6 @@ function compactDirectCommandResult(command, workflowGuidance, completionRefresh
         command,
         summary: workflowGuidance.summary,
         nextsteps: workflowGuidance.nextsteps,
-        ...(workflowGuidance.delegateSubagents?.length
-            ? { delegateSubagents: workflowGuidance.delegateSubagents }
-            : {}),
         ...(workflowGuidance.notes?.trim() ? { notes: workflowGuidance.notes } : {}),
         ...(workflowGuidance.recommendedCommands?.length
             ? { recommendedCommands: workflowGuidance.recommendedCommands }
@@ -1931,7 +2025,7 @@ function readPlanMutationTarget(args) {
             ...(explicitPlanFile ? { planFile: explicitPlanFile } : {}),
         };
     }
-    const project = resolveProjectContext(process.cwd());
+    const project = resolveWorkflowProjectContext(process.cwd(), resolveOwnerSessionKey() ?? undefined);
     const boundPlanPath = resolveSessionBoundPlan(project, resolveOwnerSessionKey() ?? undefined);
     if (!boundPlanPath) {
         throw new ClawError("PROJECT_CONFIG_INVALID", "No plan is bound to the current session. Create or recover a plan first, or use --task-name and optional --plan-file as an advanced override.");
@@ -2085,7 +2179,7 @@ function launchCompletionRefreshWorker(input) {
             stdio: "ignore",
             windowsHide: true,
             env: {
-                ...process.env,
+                ...withoutInvocationHost(),
                 CLAW_COMPLETION_NODE: process.execPath,
                 CLAW_COMPLETION_ENTRY: resolveCliEntryPath(),
                 CLAW_COMPLETION_CWD: input.cwd,
@@ -2121,6 +2215,7 @@ function launchCompletionRefreshWorker(input) {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
+        env: withoutInvocationHost(),
     });
     child.unref();
 }
@@ -2763,6 +2858,18 @@ function normalizeVersionString(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed : null;
 }
+function readWorkflowScope(args) {
+    const value = readOptionalFlag(args, "--scope");
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "session") {
+        return "session";
+    }
+    throw new ClawError("PROJECT_CONFIG_INVALID", "--scope currently accepts only session; omit it for project scope.", {
+        scope: value,
+    });
+}
 function readOptionalFlag(args, flag) {
     const index = args.indexOf(flag);
     if (index === -1) {