@veewo/claw 0.2.3 → 0.2.4

package/dist/cli.js

@@ -2,16 +2,19 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { buildDirectWorkflowGuidance, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, shouldUsePlanHostIntegration, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, recordKnowledgeFinalizationResult, unbindSession, writePlan, } from "@veewo/claw-core";
+import { buildDirectWorkflowGuidance, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findKnowledgeFinalizationJobPath, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listKnowledgeFinalizationJobs, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, 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, } from "./codex-transcript.js";
 import { consumeBufferedHookInput } from "./knowledge-hook-preflight.js";
 import { resolveInvocationHost, withoutInvocationHost } from "./invocation-host.js";
 import { runOpencodeKnowledgeWriter } from "./opencode-runner.js";
+import { ClawClient, ClawSessionError, } from "@veewo/claw-client";
 const CLI_VERSION = readCliVersion();
 const TOP_LEVEL_COMMANDS = [
     { name: "init [options]", summary: "Initialize and normalize the .claw project surface." },
@@ -54,8 +57,12 @@ const COMMAND_HELP = {
         ],
     },
     session: {
-        usage: ["{script} session clean", "{script} session clean --expired"],
-        description: "Clean ephemeral session-scoped workflow state without touching a project .claw directory.",
+        usage: [
+            "{script} session open <dir> <session-id>",
+            "{script} session clean",
+            "{script} session clean --expired",
+        ],
+        description: "Open a persistent claw command session or clean legacy ephemeral session workflow state.",
     },
     check: {
         usage: ["{script} check"],
@@ -160,10 +167,11 @@ const COMMAND_HELP = {
                 ],
             },
             show: {
-                usage: ["{script} plan show"],
+                usage: ["{script} plan show", "{script} plan show --simple"],
                 description: "Show the session-bound current plan, including archived plans through an explicit override.",
                 summary: "Show the current plan for a task.",
                 options: [
+                    { flag: "--simple", detail: "Return only status, goal.text, tasks[].title, and rules." },
                     { flag: "--task-name <name>", detail: "Advanced: override the session-bound task scope." },
                     { flag: "--plan-file <relative-path>", detail: "Advanced: override the session-bound plan file." },
                 ],
@@ -295,10 +303,11 @@ const COMMAND_HELP = {
         ],
     },
     search: {
-        usage: ["{script} search [<query>] [--limit <n>]", "{script} search index --refresh"],
+        usage: ["{script} search [<query>] [--dir <dir>] [--limit <n>]", "{script} search index --refresh"],
         description: "Project-scoped recall over .claw memory, truth, ADR, and declared markdown docs. Use a positional query or --query. Task-local scope (--task/--scope) is rejected; put task materials in plan.references instead.",
         options: [
             { flag: "--query <text>", detail: "Search query (or pass the query positionally)." },
+            { flag: "--dir <dir>", detail: "Override the project directory for this search only." },
             { flag: "--limit <n>", detail: "Max number of results." },
         ],
         subcommands: {
@@ -471,7 +480,7 @@ async function main() {
                 printJson(buildPublicContextOutput(await runContextCommand(args, process.cwd(), resolveOwnerSessionKey(), effectiveHost)));
                 return;
             case "session":
-                runSession(args);
+                await runSession(args, effectiveHost);
                 return;
             case "check":
                 const checkResult = ensureProjectProtocol(process.cwd());
@@ -489,7 +498,7 @@ async function main() {
                 await runPlan(args, effectiveHost);
                 return;
             case "codex":
-                runCodex(args);
+                await runCodex(args);
                 return;
             case "template":
                 await runTemplate(args);
@@ -567,16 +576,55 @@ async function main() {
         handleError(error);
     }
 }
-function runCodex(args) {
+async function runCodex(args) {
     const subcommand = args.shift();
-    if (subcommand !== "driver") {
-        throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown codex subcommand "${subcommand ?? ""}".`);
+    if (subcommand === "driver") {
+        assertNoRemainingArgs(args, "codex driver");
+        printJson(buildCodexDriverEnvelope(CLI_VERSION));
+        return;
     }
-    assertNoRemainingArgs(args, "codex driver");
-    printJson(buildCodexDriverEnvelope(CLI_VERSION));
+    if (subcommand === "invoke") {
+        const encoded = args.shift();
+        assertNoRemainingArgs(args, "codex invoke");
+        if (!encoded || !/^(?:[a-f0-9]{4})+$/i.test(encoded)) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", "codex invoke requires one UTF-16 hex argv payload.");
+        }
+        let json = "";
+        for (let index = 0; index < encoded.length; index += 4) {
+            json += String.fromCharCode(Number.parseInt(encoded.slice(index, index + 4), 16));
+        }
+        const invocation = JSON.parse(json);
+        if (!Array.isArray(invocation)
+            || invocation.length === 0
+            || invocation.some((value) => typeof value !== "string")
+            || !["plan", "task", "subplan"].includes(invocation[0])
+            || invocation.some((value) => value === "--host")) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", "codex invoke accepts only a structured plan, task, or subplan argv without --host.");
+        }
+        const originalArgv = process.argv;
+        try {
+            process.argv = [originalArgv[0], originalArgv[1], ...invocation, "--host", "codex"];
+            await main();
+        }
+        finally {
+            process.argv = originalArgv;
+        }
+        return;
+    }
+    throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown codex subcommand "${subcommand ?? ""}".`);
 }
-function runSession(args) {
+async function runSession(args, effectiveHost) {
     const subcommand = args.shift();
+    if (subcommand === "open") {
+        const workdir = args.shift();
+        const agentSessionId = args.shift();
+        assertNoRemainingArgs(args, "session open");
+        if (!workdir || !agentSessionId) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", "session open requires <dir> <session-id> in that order.");
+        }
+        await runPersistentSession(workdir, agentSessionId, effectiveHost);
+        return;
+    }
     if (subcommand !== "clean") {
         throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown session subcommand "${subcommand ?? ""}".`);
     }
@@ -597,19 +645,390 @@ function runSession(args) {
         removed: deleteSessionWorkflow(ownerSessionKey),
     });
 }
+async function runPersistentSession(workdir, agentSessionId, effectiveHost) {
+    const opened = await new ClawClient({
+        clientKind: "terminal",
+        ...(effectiveHost ? { host: effectiveHost } : {}),
+    }).open(agentSessionId, path.resolve(workdir));
+    writeSessionOutput({
+        ok: true,
+        command: "session.open",
+        ...opened.openResult,
+    });
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        prompt: "claw> ",
+    });
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        readline.prompt();
+    try {
+        for await (const line of readline) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                if (process.stdin.isTTY && process.stdout.isTTY)
+                    readline.prompt();
+                continue;
+            }
+            try {
+                const command = parsePersistentSessionCommand(trimmed);
+                if (command.kind === "close") {
+                    await opened.close();
+                    writeSessionOutput({ ok: true, command: "session.close" });
+                    return;
+                }
+                if (command.kind === "status") {
+                    writeSessionOutput({ ok: true, command: "session.status", ...await opened.status() });
+                }
+                else {
+                    const envelope = await opened.commandEnvelope(command.request);
+                    writeSessionOutput({
+                        ok: true,
+                        command: command.request.operation,
+                        ...envelope,
+                    });
+                }
+            }
+            catch (error) {
+                writeSessionOutput({ ok: false, error: serializeSessionError(error) });
+                if (error instanceof ClawSessionError && error.code === "SESSION_CONNECTION_LOST")
+                    return;
+            }
+            if (process.stdin.isTTY && process.stdout.isTTY)
+                readline.prompt();
+        }
+    }
+    finally {
+        readline.close();
+        try {
+            await opened.close();
+        }
+        catch {
+            // EOF is a soft close; retained state survives a lost daemon connection.
+        }
+    }
+}
+function parsePersistentSessionCommand(line) {
+    if (line.startsWith("{")) {
+        const request = JSON.parse(line);
+        if (typeof request.operation !== "string") {
+            throw new ClawError("PROJECT_CONFIG_INVALID", "JSON session commands require operation.");
+        }
+        return {
+            kind: "command",
+            request: { operation: request.operation, input: request.input ?? {} },
+        };
+    }
+    const tokens = tokenizeSessionLine(line);
+    const group = tokens.shift();
+    const action = tokens.shift();
+    if ((group === "session" && action === "close") || group === "exit" || group === "quit") {
+        return { kind: "close" };
+    }
+    if ((group === "session" && action === "status") || group === "status") {
+        return { kind: "status" };
+    }
+    if (group === "plan" && action === "show") {
+        const simple = consumeSessionBoolean(tokens, "--simple");
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: { operation: "plan.show", input: { simple } },
+        };
+    }
+    if (group === "plan" && action === "leave") {
+        assertSessionTokensConsumed(tokens, line);
+        return { kind: "command", request: { operation: "plan.leave", input: {} } };
+    }
+    if (group === "plan" && action === "resume") {
+        const planId = tokens.shift();
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: { operation: "plan.resume", input: planId ? { planId } : {} },
+        };
+    }
+    if (group === "plan" && action === "create") {
+        const title = consumeSessionFlag(tokens, "--title") ?? tokens.shift();
+        if (!title)
+            throw new ClawError("PROJECT_CONFIG_INVALID", "plan create requires a title.");
+        const goalText = consumeSessionFlag(tokens, "--goal");
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: {
+                operation: "plan.create",
+                input: { title, ...(goalText ? { goalText } : {}) },
+            },
+        };
+    }
+    if (group === "plan" && action === "wait") {
+        assertSessionTokensConsumed(tokens, line);
+        return { kind: "command", request: { operation: "plan.wait", input: {} } };
+    }
+    if (group === "plan" && action === "edit") {
+        const operations = parseSessionPlanEditOperations(tokens, line);
+        return {
+            kind: "command",
+            request: { operation: "plan.edit", input: { operations } },
+        };
+    }
+    if (group === "plan" && action === "done") {
+        const retrospectiveSummary = consumeSessionFlag(tokens, "--retrospective");
+        if (!retrospectiveSummary) {
+            throw new ClawError("RETROSPECTIVE_REQUIRED", "plan done requires --retrospective.");
+        }
+        const keyDecisions = consumeAllSessionFlags(tokens, "--key-decision");
+        const whatWorked = consumeAllSessionFlags(tokens, "--what-worked");
+        const issues = consumeAllSessionFlags(tokens, "--issue");
+        const followUps = consumeAllSessionFlags(tokens, "--follow-up");
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: {
+                operation: "plan.done",
+                input: {
+                    retrospectiveSummary,
+                    ...(keyDecisions.length ? { keyDecisions } : {}),
+                    ...(whatWorked.length ? { whatWorked } : {}),
+                    ...(issues.length ? { issues } : {}),
+                    ...(followUps.length ? { followUps } : {}),
+                },
+            },
+        };
+    }
+    if (group === "task" && action === "add") {
+        const tasks = [];
+        while (tokens.length > 0) {
+            if (tokens.shift() !== "--title") {
+                throw new ClawError("PROJECT_CONFIG_INVALID", "task add expects --title to start each task.");
+            }
+            const title = tokens.shift();
+            if (!title)
+                throw new ClawError("PROJECT_CONFIG_INVALID", "task add requires a title.");
+            let detail;
+            if (tokens[0] === "--detail") {
+                tokens.shift();
+                detail = tokens.shift();
+                if (!detail)
+                    throw new ClawError("PROJECT_CONFIG_INVALID", "task add --detail requires a value.");
+            }
+            tasks.push({ title, ...(detail ? { detail } : {}) });
+        }
+        if (!tasks.length)
+            throw new ClawError("PROJECT_CONFIG_INVALID", "task add requires at least one task.");
+        return { kind: "command", request: { operation: "task.add", input: { tasks } } };
+    }
+    if (group === "task" && action === "edit") {
+        const id = Number(consumeSessionFlag(tokens, "--id"));
+        if (!Number.isInteger(id))
+            throw new ClawError("PROJECT_CONFIG_INVALID", "task edit requires integer --id.");
+        const taskTitle = consumeSessionFlag(tokens, "--title");
+        const taskDetail = consumeSessionFlag(tokens, "--detail");
+        const taskStatus = consumeSessionFlag(tokens, "--status");
+        const taskChoiceId = consumeSessionFlag(tokens, "--choice");
+        if (!taskTitle && !taskDetail && !taskStatus && !taskChoiceId) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", "task edit requires a field to change.");
+        }
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: {
+                operation: "task.edit",
+                input: {
+                    taskId: id,
+                    ...(taskTitle ? { taskTitle } : {}),
+                    ...(taskDetail ? { taskDetail } : {}),
+                    ...(taskStatus ? { taskStatus } : {}),
+                    ...(taskChoiceId ? { taskChoiceId } : {}),
+                },
+            },
+        };
+    }
+    if (group === "task" && action === "done") {
+        const tasks = [];
+        while (tokens.length > 0) {
+            if (tokens.shift() !== "--id") {
+                throw new ClawError("PROJECT_CONFIG_INVALID", "task done expects --id to start each task.");
+            }
+            const id = Number(tokens.shift());
+            if (!Number.isInteger(id))
+                throw new ClawError("PROJECT_CONFIG_INVALID", "task done requires integer ids.");
+            let choiceId;
+            if (tokens[0] === "--choice") {
+                tokens.shift();
+                choiceId = tokens.shift();
+                if (!choiceId)
+                    throw new ClawError("PROJECT_CONFIG_INVALID", "task done --choice requires a value.");
+            }
+            tasks.push({ id, ...(choiceId ? { choiceId } : {}) });
+        }
+        if (!tasks.length)
+            throw new ClawError("PROJECT_CONFIG_INVALID", "task done requires at least one task.");
+        return { kind: "command", request: { operation: "task.done", input: { tasks } } };
+    }
+    if (group === "search") {
+        const query = consumeSessionFlag(tokens, "--query") ?? action;
+        if (!query)
+            throw new ClawError("MEMORY_QUERY_REQUIRED", "search requires a query.");
+        const dir = consumeSessionFlag(tokens, "--dir");
+        const limitRaw = consumeSessionFlag(tokens, "--limit");
+        assertSessionTokensConsumed(tokens, line);
+        return {
+            kind: "command",
+            request: {
+                operation: "search",
+                input: {
+                    query,
+                    ...(dir ? { dir } : {}),
+                    ...(limitRaw ? { limit: Number(limitRaw) } : {}),
+                },
+            },
+        };
+    }
+    throw new ClawError("SESSION_OPERATION_UNSUPPORTED", `Unsupported persistent session command: ${line}`);
+}
+function tokenizeSessionLine(line) {
+    const tokens = [];
+    const pattern = /"((?:\\.|[^"])*)"|'((?:\\.|[^'])*)'|(\S+)/g;
+    for (const match of line.matchAll(pattern)) {
+        tokens.push((match[1] ?? match[2] ?? match[3] ?? "").replace(/\\(["'\\])/g, "$1"));
+    }
+    return tokens;
+}
+function consumeSessionFlag(tokens, flag) {
+    const index = tokens.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    const value = tokens[index + 1];
+    if (!value)
+        throw new ClawError("PROJECT_CONFIG_INVALID", `Missing value for ${flag}.`);
+    tokens.splice(index, 2);
+    return value;
+}
+function consumeAllSessionFlags(tokens, flag) {
+    const values = [];
+    while (tokens.includes(flag)) {
+        values.push(consumeSessionFlag(tokens, flag));
+    }
+    return values;
+}
+function parseSessionPlanEditOperations(tokens, line) {
+    const operations = [];
+    const updateFlags = {
+        "--goal": "goalText",
+        "--requirements": "requirementsSummary",
+        "--summary": "planSummary",
+        "--rule": "rules",
+        "--key-decision": "keyDecisions",
+    };
+    while (tokens.length > 0) {
+        const flag = tokens.shift();
+        const value = tokens.shift();
+        if (!value)
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Missing value for ${flag}.`);
+        if (flag === "--status") {
+            operations.push({ type: "plan.status", status: value });
+            continue;
+        }
+        const field = updateFlags[flag];
+        if (!field) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown plan edit argument in "${line}": ${flag}`);
+        }
+        const listField = field === "rules" || field === "keyDecisions";
+        operations.push({
+            type: "plan.update",
+            updates: { [field]: listField ? [value] : value },
+        });
+    }
+    if (!operations.length)
+        throw new ClawError("PROJECT_CONFIG_INVALID", "plan edit requires a field to change.");
+    return operations;
+}
+function consumeSessionBoolean(tokens, flag) {
+    const index = tokens.indexOf(flag);
+    if (index < 0)
+        return false;
+    tokens.splice(index, 1);
+    return true;
+}
+function assertSessionTokensConsumed(tokens, line) {
+    if (tokens.length > 0) {
+        throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown session command arguments in "${line}": ${tokens.join(" ")}`);
+    }
+}
+function writeSessionOutput(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function serializeSessionError(error) {
+    if (error instanceof ClawSessionError) {
+        return {
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+            outcome: error.outcome,
+            ...(error.recoveryCommand ? { recoveryCommand: error.recoveryCommand } : {}),
+            ...(error.details ? { details: error.details } : {}),
+        };
+    }
+    if (error instanceof ClawError) {
+        return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
+    }
+    return { code: "SESSION_COMMAND_FAILED", message: error instanceof Error ? error.message : String(error) };
+}
 function runKnowledge(args) {
     const subcommand = args.shift();
     switch (subcommand) {
+        case "list": {
+            const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
+            const sessionKey = readOptionalFlag(args, "--session-key");
+            const host = readOptionalFlag(args, "--job-host");
+            assertNoRemainingArgs(args, "knowledge list");
+            const sessionProject = sessionKey ? resolveSessionWorkflowContext(sessionKey) : null;
+            const project = resolveProjectContext(projectRoot);
+            const candidates = sessionProject && sessionProject.clawDir !== project.clawDir
+                ? [sessionProject, project]
+                : [sessionProject ?? project];
+            const jobs = candidates.flatMap((candidate) => listKnowledgeFinalizationJobs(candidate))
+                .map((jobPath) => ({ jobPath, job: readKnowledgeFinalizationJob(jobPath) }))
+                .filter(({ job }) => (job.status === "running"
+                || ((job.status === "queued" || job.status === "failed") && job.attempts < 3)) && (!host || job.host === host))
+                .map(({ jobPath, job }) => ({
+                jobPath,
+                finalizeId: job.finalizeId,
+                status: job.status,
+                attempts: job.attempts,
+            }));
+            printJson({ ok: true, command: "knowledge.list", jobs });
+            return;
+        }
         case "wait": {
             const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
             const finalizeId = readRequiredFlag(args, "--finalize-id");
+            const sessionKey = readOptionalFlag(args, "--session-key");
             const timeoutMs = readOptionalNumber(args, "--timeout-ms") ?? 300_000;
             assertNoRemainingArgs(args, "knowledge wait");
-            const { jobPath, job } = waitForKnowledgeFinalizationJobReady({
-                project: resolveProjectContext(projectRoot),
-                finalizeId,
-                timeoutMs,
-            });
+            const sessionProject = sessionKey ? resolveSessionWorkflowContext(sessionKey) : null;
+            const project = resolveProjectContext(projectRoot);
+            const candidates = sessionProject && sessionProject.clawDir !== project.clawDir
+                ? [sessionProject, project]
+                : [sessionProject ?? project];
+            let located = candidates
+                .map((candidate) => findKnowledgeFinalizationJobPath(candidate, finalizeId))
+                .find((candidate) => Boolean(candidate));
+            if (!located && timeoutMs > 0) {
+                located = waitForKnowledgeFinalizationJobReady({
+                    project: candidates[0],
+                    finalizeId,
+                    timeoutMs,
+                }).jobPath;
+            }
+            if (!located) {
+                throw new Error(`Knowledge finalization ${finalizeId} is unavailable.`);
+            }
+            const jobPath = located;
+            const job = readKnowledgeFinalizationJob(jobPath);
             printJson({
                 ok: true,
                 command: "knowledge.wait",
@@ -715,11 +1134,11 @@ async function runPlan(args, effectiveHost) {
                 throw new ClawError("PROJECT_CONFIG_INVALID", "plan edit requires at least one plan field or --status.");
             }
             const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
-            const entersEndState = requestsPlanEndState(operations);
-            const current = entersEndState
+            const entersEndTerminal = requestsPlanEndTerminal(operations);
+            const current = entersEndTerminal
                 ? showPlan({ cwd: process.cwd(), ...target, ownerSessionKey })
                 : undefined;
-            const project = entersEndState ? tryResolveHookProject(process.cwd()) : null;
+            const project = entersEndTerminal ? tryResolveHookProject(process.cwd()) : null;
             const effectiveWriter = current && project
                 ? resolvePlanEffectiveConfig(project.projectConfig, current.plan)?.knowledgeWriter
                 : undefined;
@@ -729,7 +1148,7 @@ async function runPlan(args, effectiveHost) {
                 && effectiveHost !== "codex") {
                 throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex host.', { host: effectiveHost ?? null });
             }
-            const queuePlanEndFinalization = entersEndState
+            const queuePlanEndFinalization = entersEndTerminal
                 ? preparePlanEndFinalization(process.cwd(), ownerSessionKey)
                 : undefined;
             const result = await editPlan({
@@ -857,6 +1276,7 @@ async function runPlan(args, effectiveHost) {
             return;
         }
         case "show": {
+            const simple = readBooleanFlag(args, "--simple");
             const target = readPlanMutationTarget(args);
             assertNoRemainingArgs(args, "plan show");
             const result = showPlan({
@@ -864,6 +1284,10 @@ async function runPlan(args, effectiveHost) {
                 ...target,
                 ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
             });
+            if (simple) {
+                printJson(result.simplePlanView);
+                return;
+            }
             printJson({
                 ok: true,
                 command: "plan.show",
@@ -1052,11 +1476,12 @@ async function runSearch(args) {
     if (args.includes("--scope") || args.includes("--task")) {
         throw new ClawError("PROJECT_CONFIG_INVALID", "claw search is project-scoped only. Put task-specific materials in plan.references instead of using task-local search.");
     }
+    const dir = readOptionalFlag(args, "--dir");
     printJson({
         ok: true,
         command: "search",
         ...await searchMemoryAsync({
-            cwd: process.cwd(),
+            cwd: dir ? path.resolve(process.cwd(), dir) : process.cwd(),
             limit: readOptionalNumber(args, "--limit"),
             query: readRequiredSearchQuery(args),
             scope: "project",
@@ -1269,7 +1694,7 @@ function buildPublicContextOutput(context) {
     if (Object.keys(compactRecovery).length > 0) {
         output.startupRecovery = compactRecovery;
     }
-    const searchGuidance = buildContextSearchGuidance(context);
+    const searchGuidance = buildContextSearchGuidance(context, "rg");
     if (searchGuidance) {
         output.searchGuidance = searchGuidance;
     }
@@ -1281,20 +1706,26 @@ function shouldExposeVersionSync(versionSync) {
         || versionSync.updateAvailable === true
         || versionSync.projectVersion !== versionSync.cliVersion;
 }
-function buildContextSearchGuidance(context) {
+function buildContextSearchGuidance(context, style = "default") {
     const project = asJsonRecord(context.project);
     const projectConfig = asJsonRecord(project?.projectConfig);
     const memory = asJsonRecord(projectConfig?.memory);
     const embeddingEnabled = memory?.enabled === true && asJsonRecord(memory.embedding) !== null;
     const gitnexusEnabled = projectConfig?.gitnexus === true;
     if (embeddingEnabled && gitnexusEnabled) {
-        return "When useful, use `claw search` to narrow the document search scope and GitNexus to narrow the code search scope, then use the default search to locate exact files or symbols.";
+        return style === "rg"
+            ? "Before using `rg`, use `claw search --query` to narrow the document search scope and GitNexus to narrow the code search scope, then use `rg` to locate exact files or symbols."
+            : "When useful, use `claw search` to narrow the document search scope and GitNexus to narrow the code search scope, then use the default search to locate exact files or symbols.";
     }
     if (embeddingEnabled) {
-        return "When useful, use `claw search` to narrow the document search scope, then use the default search to locate exact files or symbols.";
+        return style === "rg"
+            ? "Before using `rg`, use `claw search --query` to narrow the document search scope, then use `rg` to locate exact files or symbols."
+            : "When useful, use `claw search` to narrow the document search scope, then use the default search to locate exact files or symbols.";
     }
     if (gitnexusEnabled) {
-        return "When useful, use GitNexus to narrow the code search scope, then use the default search to locate exact files or symbols.";
+        return style === "rg"
+            ? "Before using `rg`, use GitNexus to narrow the code search scope, then use `rg` to locate exact files or symbols."
+            : "When useful, use GitNexus to narrow the code search scope, then use the default search to locate exact files or symbols.";
     }
     return null;
 }
@@ -1505,12 +1936,12 @@ async function runInternalKnowledgeCapture(args, effectiveHost) {
     const turnId = readHookString(payload, "turn_id");
     const message = readHookString(payload, "message");
     const taskConclusions = readHookTaskConclusions(payload, turnId);
-    if (!hookCwd || !sessionId || !turnId || !message || !containsClawDir(hookCwd)) {
+    if (!hookCwd || !sessionId || !turnId || !message) {
         printJson({ ok: true, captured: false });
         return;
     }
     try {
-        const project = resolveProjectContext(hookCwd);
+        const project = resolveWorkflowProjectContext(hookCwd, sessionId);
         const result = tryCaptureKnowledgeStop({
             project,
             sessionId,
@@ -1592,7 +2023,7 @@ function completeKnowledgeFinalizationJob(jobPath, result, claimToken) {
     if (running.claimToken !== claimToken) {
         throw new Error("Knowledge finalization completion does not match the active claim.");
     }
-    const project = resolveProjectContext(running.projectRoot);
+    const project = resolveKnowledgeJobProject(jobPath, running);
     const finishedAt = new Date().toISOString();
     const truthEncoding = normalizeTruthMarkdownEncoding(project);
     recordKnowledgeFinalizationResult(project, running.reportPath, {
@@ -1626,6 +2057,17 @@ function completeKnowledgeFinalizationJob(jobPath, result, claimToken) {
     });
     printJson({ ok: true, completed: true, alreadyDone: terminal.alreadyDone, finalizeId: running.finalizeId });
 }
+function resolveKnowledgeJobProject(jobPath, job) {
+    const project = resolveProjectContext(job.projectRoot);
+    const sessionProject = resolveSessionWorkflowContext(job.sessionId);
+    for (const candidate of sessionProject ? [sessionProject, project] : [project]) {
+        const relative = path.relative(candidate.clawDir, path.resolve(jobPath));
+        if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+            return candidate;
+        }
+    }
+    throw new Error("Knowledge finalization job is outside its project or session workflow.");
+}
 function failKnowledgeFinalizationJob(jobPath, message, claimToken) {
     const terminal = doneKnowledgeFinalizationJob({
         jobPath,
@@ -1677,7 +2119,7 @@ function runInternalKnowledgeSweep(args) {
         printJson({ command: "internal-knowledge-sweep", ok: true, launched: 0, skipped: true });
         return;
     }
-    const jobs = listRetryableKnowledgeFinalizationJobs(project);
+    const jobs = listRetryableKnowledgeFinalizationJobs(project, { excludeHosts: ["cindy"] });
     let launched = 0;
     for (const jobPath of jobs) {
         try {
@@ -1714,7 +2156,7 @@ async function runInternalBackgroundMaintenance(args) {
     let launched = 0;
     const knowledgeProject = project ?? sessionProject;
     if (knowledgeProject) {
-        const jobs = listRetryableKnowledgeFinalizationJobs(knowledgeProject);
+        const jobs = listRetryableKnowledgeFinalizationJobs(knowledgeProject, { excludeHosts: ["cindy"] });
         discovered = jobs.length;
         for (const jobPath of jobs) {
             try {
@@ -1914,7 +2356,7 @@ async function runSessionStartHook(effectiveHost) {
         const context = await runContextCommand([], hookCwd, ownerSessionKey, effectiveHost);
         const contextProject = asJsonRecord(context.project);
         const retryableJobs = effectiveHost !== "cindy" && contextProject?.scope !== "session" && !context.error
-            ? listRetryableKnowledgeFinalizationJobs(resolveProjectContext(hookCwd))
+            ? listRetryableKnowledgeFinalizationJobs(resolveProjectContext(hookCwd), { excludeHosts: ["cindy"] })
             : [];
         if (contextProject?.scope !== "session"
             && !context.error
@@ -2071,31 +2513,21 @@ function buildSessionStartAdditionalContext(context, sessionCwd, effectiveHost)
  * supplies project identity or a recovered workflow snapshot. Goal Mode is
  * intentionally omitted because Cindy does not expose that Host surface.
  */
-function buildCindySessionStartContext(context, sessionCwd, versionSyncPrompt) {
-    const activeWorkflow = asJsonRecord(context.activeWorkflow);
-    if (activeWorkflow) {
-        return stripCindyGoalModeLines(buildRecoveredWorkflowAdditionalContext(activeWorkflow, versionSyncPrompt));
+function buildCindySessionStartContext(context, _sessionCwd, versionSyncPrompt) {
+    const lines = [];
+    const startupRecovery = asJsonRecord(context.startupRecovery);
+    const fixedPaths = Array.isArray(startupRecovery?.fixedPaths)
+        ? startupRecovery.fixedPaths.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        : [];
+    if (startupRecovery?.corrected === true) {
+        lines.push(`claw-kit repaired the project configuration${fixedPaths.length > 0 ? `: ${fixedPaths.join(", ")}` : "."}`);
     }
-    const project = asJsonRecord(context.project);
-    if (!project)
-        return null;
-    const projectName = typeof project.projectName === "string" && project.projectName.trim()
-        ? project.projectName.trim()
-        : typeof project.projectId === "string" && project.projectId.trim()
-            ? project.projectId.trim()
-            : path.basename(String(project.projectRoot ?? sessionCwd ?? "project"));
-    const projectRoot = typeof project.projectRoot === "string" ? project.projectRoot : sessionCwd;
-    const projectId = typeof project.projectId === "string" ? project.projectId : projectName;
-    const clawDir = typeof project.clawDir === "string" ? project.clawDir : path.join(projectRoot, ".claw");
-    const prompt = [
-        `This session started inside a .claw project: ${projectName} (${projectId}).`,
-        `.claw directory: ${clawDir}`,
-    ].join("\n");
-    if (!versionSyncPrompt)
-        return prompt;
-    return versionSyncPrompt.placement === "prefix"
-        ? `${versionSyncPrompt.lines.join("\n")}\n${prompt}`
-        : `${prompt}\n${versionSyncPrompt.lines.join("\n")}`;
+    if (versionSyncPrompt?.placement === "prefix")
+        lines.push(...versionSyncPrompt.lines);
+    lines.push("Before using `rg`, use `claw search --query` to narrow the document search scope and GitNexus to narrow the code search scope, then use `rg` to locate exact files or symbols.");
+    if (versionSyncPrompt?.placement === "suffix")
+        lines.push(...versionSyncPrompt.lines);
+    return lines.length > 0 ? lines.join("\n") : null;
 }
 function stripCindyGoalModeLines(prompt) {
     return prompt
@@ -2386,7 +2818,7 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
     const resolvedPlanPath = archivedPlanPath ?? result.planPath;
     const codexResult = effectiveHost === "codex";
     const cindyResult = effectiveHost === "cindy";
-    const hostActions = codexResult ? buildHostActions(result, { forceProjectionSync, actionIdPrefix: command === "plan.sync" ? `plan.sync:${createHash("sha256").update(result.planPath).digest("hex").slice(0, 16)}` : undefined }) : [];
+    const hostActions = codexResult ? buildCodexHostActions(result, { forceProjectionSync, actionIdPrefix: command === "plan.sync" ? `plan.sync:${createHash("sha256").update(result.planPath).digest("hex").slice(0, 16)}` : undefined }) : [];
     const nextsteps = codexResult
         && result.planStatus === "end.completed"
         && result.workflowGuidance.goalTool?.tool === "update_goal"
@@ -2461,87 +2893,6 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
         ...(!codexResult || !includePlan ? { planSummary } : {}),
     };
 }
-function buildHostActions(result, options = {}) {
-    const latestEvent = result.events?.at(-1);
-    const actionIdPrefix = options.actionIdPrefix ?? latestEvent?.mutationId;
-    if (!actionIdPrefix) {
-        return [];
-    }
-    const actions = [];
-    const goalTool = result.workflowGuidance.goalTool;
-    const isSubplanGoalHandoff = Boolean(result.plan?.parentPlan
-        && goalTool?.tool === "update_goal"
-        && goalTool.status === "complete");
-    if (isSubplanGoalHandoff && goalTool?.tool === "update_goal") {
-        actions.push({
-            schemaVersion: 1,
-            id: `${actionIdPrefix}:update_goal`,
-            tool: "update_goal",
-            input: {
-                status: "complete",
-            },
-        });
-    }
-    if (result.plan
-        && shouldUsePlanHostIntegration(result.plan)
-        && result.plan.tasks.length > 0
-        && (options.forceProjectionSync || codexPlanProjectionChanged(result.previousPlan, result.plan, result.planStatus))) {
-        const plan = buildCodexPlanProjection(result.plan, result.planStatus);
-        actions.push({
-            schemaVersion: 1,
-            id: `${actionIdPrefix}:update_plan`,
-            tool: "update_plan",
-            input: {
-                explanation: result.workflowGuidance.summary,
-                plan,
-            },
-        });
-    }
-    if (goalTool && !isSubplanGoalHandoff) {
-        if (goalTool.tool === "create_goal") {
-            actions.push({
-                schemaVersion: 1,
-                id: `${actionIdPrefix}:create_goal`,
-                tool: "create_goal",
-                input: {
-                    objective: goalTool.objective,
-                },
-            });
-        }
-        else {
-            const codexStatus = result.planStatus === "process.wait" || result.planStatus === "process.discussing"
-                ? "complete"
-                : goalTool.status;
-            actions.push({
-                schemaVersion: 1,
-                id: `${actionIdPrefix}:update_goal`,
-                tool: "update_goal",
-                input: {
-                    status: codexStatus,
-                },
-            });
-        }
-    }
-    return actions;
-}
-function codexPlanProjectionChanged(previousPlan, plan, planStatus) {
-    if (!previousPlan)
-        return true;
-    return JSON.stringify(buildCodexPlanProjection(previousPlan, previousPlan.status))
-        !== JSON.stringify(buildCodexPlanProjection(plan, planStatus));
-}
-function buildCodexPlanProjection(plan, planStatus) {
-    const activeTask = plan.tasks.find((task) => task.status === "in_progress" || task.status === "subagent_running") ?? (planStatus === "process.active"
-        ? plan.tasks.find((task) => task.status !== "done")
-        : undefined);
-    return plan.tasks.map((task) => {
-        let status = task.status === "done" ? "completed" : "pending";
-        if (task.id === activeTask?.id) {
-            status = "in_progress";
-        }
-        return { step: task.title, status };
-    });
-}
 function compactDirectCommandResult(command, workflowGuidance, completionRefresh) {
     return {
         ok: true,
@@ -2629,7 +2980,7 @@ function readOrderedPlanEditOperations(args) {
     }
     return operations;
 }
-function requestsPlanEndState(operations) {
+function requestsPlanEndTerminal(operations) {
     return operations.some((operation) => operation.type === "plan.status" && operation.status.startsWith("end."));
 }
 function planCompletionOperations(updates) {