@osovv/vv-opencode 1.3.8 → 1.4.1

package/dist/plugins/workflow/index.js

@@ -1,32 +1,35 @@
 // FILE: src/plugins/workflow/index.ts
-// VERSION: 0.5.1
+// VERSION: 0.6.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance.
-//   SCOPE: work_item_open/list/close registration, tracked launch validation, result normalization and repair, round aggregation with bounded excerpts, implementation round limits, persistence, and profile-selected chat.message guidance.
-//   DEPENDS: [@opencode-ai/plugin, src/lib/config-layers.ts, src/lib/orchestration.ts, src/lib/plugin-toggle-config.ts, src/plugins/workflow/persistence.ts, src/plugins/workflow/protocol.ts, src/plugins/workflow/repair.ts, src/plugins/workflow/state.ts, src/plugins/workflow/transitions.ts, src/plugins/workflow/tooling.ts]
-//   LINKS: M-PLUGIN-WORKFLOW, M-ORCHESTRATION-PROFILES, M-WORKFLOW-PROTOCOL, M-WORKFLOW-REPAIR, M-WORKFLOW-STATE, M-WORKFLOW-TRANSITIONS, M-WORKFLOW-TOOLING, M-WORKFLOW-PERSISTENCE, V-M-PLUGIN-WORKFLOW
+//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance, including delegated control tools, host-call-bound attempts, and checkpoint reviewer linkage.
+//   SCOPE: work_item_open/list/close registration, delegated-only work_item_decide and work_checkpoint registration with root-session authorization, tracked launch validation with delegated barriers and overlapping-write gates, live host-call bindings that convert supported foreground vv-implementer task launches into failed delegated attempts on confirmed host-terminal errors, result normalization and repair, callID-bound delegated attempt results and checkpoint reviewer bookkeeping, round aggregation with bounded excerpts, implementation round limits, checked persistence, and profile-selected chat.message guidance.
+//   DEPENDS: [@opencode-ai/plugin, src/lib/config-layers.ts, src/lib/orchestration.ts, src/lib/plugin-toggle-config.ts, src/plugins/workflow/checkpoint-io.ts, src/plugins/workflow/checkpoints.ts, src/plugins/workflow/delegated.ts, src/plugins/workflow/persistence.ts, src/plugins/workflow/protocol.ts, src/plugins/workflow/repair.ts, src/plugins/workflow/state.ts, src/plugins/workflow/tooling.ts, src/plugins/workflow/transitions.ts]
+//   LINKS: M-PLUGIN-WORKFLOW, M-ORCHESTRATION-PROFILES, M-WORKFLOW-PROTOCOL, M-WORKFLOW-REPAIR, M-WORKFLOW-STATE, M-WORKFLOW-TRANSITIONS, M-WORKFLOW-TOOLING, M-WORKFLOW-PERSISTENCE, M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS, V-M-PLUGIN-WORKFLOW
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   WorkflowPlugin - Registers workflow work-item tools, tracked task protocol enforcement, and primary-session workflow guidance injection.
+//   WorkflowPlugin - Registers workflow work-item tools, delegated control tools under the delegated profile, tracked task protocol enforcement with callID-bound delegated attempts, checkpoint linkage, and live host-call failure bindings, and primary-session workflow guidance injection.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.5.1 - Fixed session.deleted cleanup to read the session id from properties.info.id (per the SDK event shape), drop the in-memory store, and remove a duplicate directory deletion.]
+//   LAST_CHANGE: [direct fix inFlightAttempt after failed worker launch - Added live host-call launch bindings so a confirmed foreground vv-implementer task failure is recorded as a failed delegated attempt instead of stranding inFlightAttempt until restart, with sticky exclusions for background/resume/cancellation/after-hook paths and staged checked persistence before retry is exposed.]
 // END_CHANGE_SUMMARY
 import { tool } from "@opencode-ai/plugin";
 import { attemptTrackedResultRepair, isTrackedResultRepairEligible, unwrapResumableTaskResult, } from "./repair.js";
 import { parseResultBlock, parseWorkItemHeader, TRACKED_SUBAGENT_NAMES, } from "./protocol.js";
-import { applyTrackedResult, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
-import { getAllowedNextAgents, getAttemptedImplementationRound, shouldBlockRound, } from "./transitions.js";
-import { createWorkItemCloseTool, createWorkItemListTool, createWorkItemOpenTool, } from "./tooling.js";
+import { applyTrackedResult, createRecordLookupKey, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
+import { applyDelegatedLaunchFailure, applyDelegatedResult, beginDelegatedLaunch, revertInFlightDelegatedLaunches, } from "./delegated.js";
+import { checkpointBarrierUnsatisfied, findOverlappingInFlightReview, recordCheckpointReviewerLaunch, recordCheckpointReviewerResult, } from "./checkpoints.js";
+import { getAllowedNextAgents, getAttemptedImplementationRound, getReviewerRoleForAgent, shouldBlockRound, } from "./transitions.js";
+import { createWorkItemCloseTool, createWorkItemDecideTool, createWorkItemListTool, createWorkItemOpenTool, createWorkCheckpointTool, } from "./tooling.js";
 import workflowSystemInstructionTemplate from "./system-instruction.md?raw";
 import { loadVvocConfig } from "../../lib/config-layers.js";
 import { resolveOrchestrationPolicy, } from "../../lib/orchestration.js";
 import { isVvocPluginEnabled } from "../../lib/plugin-toggle-config.js";
-import { deleteWorkflowSessionDir, hydrateWorkflowState, snapshotWorkflowState, } from "./persistence.js";
+import { deleteWorkflowSessionDir, hydrateWorkflowStateChecked, snapshotWorkflowStateChecked, } from "./persistence.js";
+import { loadApprovedDelegatedPlan } from "./checkpoint-io.js";
 const z = tool.schema;
 const TRACKED_SUBAGENT_SET = new Set(TRACKED_SUBAGENT_NAMES);
 const WORK_ITEM_MISSING_MARKER = "__VVOC" + "_SECRET_BEARER_TOKEN_a6f582092f05__";
@@ -55,6 +58,28 @@ results are findings and do not route to an implementer. Treat BLOCKED and NEEDS
 stops, validate delegated results yourself, run fresh verification, and close completed work items.
 </workflow_protocol>
 `.trim();
+const DELEGATED_WORKFLOW_SYSTEM_INSTRUCTION = `
+<workflow_protocol>
+Delegated execution mechanics are available in this session. Open implementation tasks with
+work_item_open using mode "delegated" and an empty requiredReviewers array, then dispatch exactly
+one vv-implementer per task with a bounded task packet and the returned VVOC_WORK_ITEM_ID. Let the
+worker complete its local edit, test, and fix cycle before it reports.
+
+A DONE worker result waits in awaiting_acceptance: it never closes the work item and the worker
+never accepts its own result. Inspect the changed code and evidence yourself, then call
+work_item_decide with the attempt number to accept or request changes. DONE_WITH_CONCERNS requires
+an explicit concerns disposition. Controller retries are bounded to one correction attempt before
+explicit recovery; BLOCKED and NEEDS_CONTEXT remain hard stops.
+
+Register an approved plan once with work_checkpoint register, start each declared review checkpoint
+only after its prerequisite tasks are accepted, and run the due checkpoint before dependent waves.
+A checkpoint passes only when every declared reviewer passes against the pinned snapshot; a closed
+review-only FAIL report is a findings result, not approval. Do not write source files yourself:
+delegate implementation edits, including fixes requested by reviewers, through bounded task
+packets, while keeping planning artifacts, acceptance decisions, and verification commands in this
+session.
+</workflow_protocol>
+`.trim();
 /** Returns the exact workflow instruction compatible with one resolved policy. */
 function getWorkflowSystemInstruction(policy) {
     switch (policy.workflowGuidance) {
@@ -64,6 +89,8 @@ function getWorkflowSystemInstruction(policy) {
             return SELECTIVE_WORKFLOW_SYSTEM_INSTRUCTION;
         case "tracked":
             return workflowSystemInstructionTemplate.trim();
+        case "delegated":
+            return DELEGATED_WORKFLOW_SYSTEM_INSTRUCTION;
     }
 }
 function isTrackedSubagent(value) {
@@ -90,6 +117,46 @@ function readTaskPrompt(args) {
     }
     return value;
 }
+function delegatedLaunchBindingKey(sessionId, callId) {
+    return `${sessionId}::${callId}`;
+}
+/**
+ * Read the launch-critical task arguments that decide fresh-exclusive
+ * eligibility. Background, resume, and command/subtask launches are excluded;
+ * contradictory non-boolean or non-string values also fail closed.
+ */
+function readDelegatedLaunchEligibility(args) {
+    if (!args || typeof args !== "object") {
+        return { eligible: false, reason: "missing_launch_args" };
+    }
+    const record = args;
+    if ("background" in record && record.background !== false) {
+        return { eligible: false, reason: "requested_background" };
+    }
+    if ("task_id" in record && record.task_id !== undefined) {
+        const taskId = record.task_id;
+        if (typeof taskId !== "string" || taskId.trim() === "") {
+            return { eligible: false, reason: "invalid_task_id" };
+        }
+        return { eligible: false, reason: "resume_task_id", resumedTaskId: taskId.trim() };
+    }
+    // The host subtask path always supplies a `command` key (even when its value
+    // is undefined), and a slash-command launch always supplies a value, so key
+    // presence alone is the reliable command/subtask exclusion.
+    if ("command" in record) {
+        const command = record.command;
+        if (command !== undefined && command !== null && typeof command !== "string") {
+            return { eligible: false, reason: "invalid_command" };
+        }
+        return { eligible: false, reason: "command_or_subtask_launch" };
+    }
+    return { eligible: true };
+}
+/** Exact current-host wrapper that precedes a returned child task error. */
+function delegatedHostFailurePrefix(childSessionId) {
+    return `Subagent failed (task_id: ${childSessionId}): `;
+}
+// END_BLOCK_DELEGATED_FAILURE_BINDING_TYPES
 function canUseWorkflowTools(agentName) {
     return agentName === WORKFLOW_CONTROLLER_AGENT;
 }
@@ -177,36 +244,347 @@ function createHardStopMessage(options) {
         "Inspect work_item_list before retrying.",
     ].join("\n");
 }
-export const WorkflowPlugin = async ({ client, directory }) => {
+export const WorkflowPlugin = async ({ client, directory, worktree }) => {
     const vvoc = await loadVvocConfig({ cwd: directory });
     if (!isVvocPluginEnabled(vvoc.config, "workflow"))
         return {};
-    const workflowSystemInstruction = getWorkflowSystemInstruction(resolveOrchestrationPolicy(vvoc.config));
+    const resolvedPolicy = resolveOrchestrationPolicy(vvoc.config);
+    const workflowSystemInstruction = getWorkflowSystemInstruction(resolvedPolicy);
+    const delegatedProfileActive = resolvedPolicy.profile === "delegated";
+    const trustedWorkspaceRoot = worktree || directory;
     // START_BLOCK_PERSISTENCE_SETUP
     // Each session (main or subagent) gets its own isolated store.
     // This prevents subagent tool calls from interfering with the main session's work items.
+    // Hydration uses the checked loader: invalid persisted state is tracked so new
+    // control transactions and snapshot writes fail closed instead of silently
+    // resetting a malformed run.
     const stores = new Map();
+    const invalidHydrationSessions = new Set();
     function getOrCreateStore(sessionId) {
         let store = stores.get(sessionId);
         if (!store) {
-            const hydrated = hydrateWorkflowState(sessionId);
-            store = createWorkItemStore(hydrated);
+            const hydrated = hydrateWorkflowStateChecked(sessionId);
+            if (hydrated.status === "valid") {
+                store = createWorkItemStore(hydrated.data);
+                // A freshly hydrated session crossed a process-restart boundary: any
+                // persisted in-flight delegated attempt can never receive its host
+                // callback again, so reclaim it without consuming the attempt budget.
+                const reclaimed = revertInFlightDelegatedLaunches(store.getStoreData(), sessionId);
+                if (reclaimed.reverted > 0) {
+                    void client.app
+                        .log({
+                        body: {
+                            service: "workflow",
+                            level: "info",
+                            message: "[workflow][hydration][BLOCK_RECLAIM_ATTEMPTS] orphaned in-flight delegated attempts reverted",
+                            extra: { sessionID: sessionId, workItemIds: reclaimed.workItemIds },
+                        },
+                    })
+                        .catch(() => undefined);
+                }
+            }
+            else {
+                if (hydrated.status === "invalid") {
+                    invalidHydrationSessions.add(sessionId);
+                }
+                store = createWorkItemStore();
+            }
             stores.set(sessionId, store);
         }
         return store;
     }
     function snapshotSession(sessionId) {
         const store = stores.get(sessionId);
-        if (store) {
-            try {
-                snapshotWorkflowState(sessionId, store.getStoreData());
+        if (!store)
+            return { ok: true };
+        if (invalidHydrationSessions.has(sessionId)) {
+            return {
+                ok: false,
+                error: `persisted workflow state for session ${sessionId} is invalid; refusing to overwrite it`,
+            };
+        }
+        const result = snapshotWorkflowStateChecked(sessionId, store.getStoreData());
+        return result.ok ? { ok: true } : { ok: false, error: result.error };
+    }
+    // END_BLOCK_PERSISTENCE_SETUP
+    // START_BLOCK_DELEGATED_FAILURE_BINDING
+    // Live host-call bindings let the plugin consume confirmed host-terminal
+    // failures of foreground vv-implementer tasks without hydrating a store from
+    // an event. Every exclusion is sticky: once a binding is tainted it can never
+    // authorize a failure transition.
+    const delegatedLaunchBindings = new Map();
+    const resumedChildSessions = new Set();
+    const childPromptMessageIds = new Map();
+    function taintDelegatedLaunchBinding(binding, reason) {
+        if (binding.eligible) {
+            binding.eligible = false;
+            binding.ineligibleReason = reason;
+        }
+    }
+    function taintBindingsForChild(childSessionId, reason) {
+        for (const binding of delegatedLaunchBindings.values()) {
+            if (binding.childSessionId === childSessionId)
+                taintDelegatedLaunchBinding(binding, reason);
+        }
+    }
+    /**
+     * Track distinct user-prompt message ids per session: a child session
+     * prompted with more than one distinct message is shared or resumed, so it
+     * can no longer be a fresh-exclusive child.
+     */
+    function observeChildPrompt(sessionId, messageId) {
+        if (!messageId)
+            return;
+        let messageIds = childPromptMessageIds.get(sessionId);
+        if (!messageIds) {
+            messageIds = new Set();
+            childPromptMessageIds.set(sessionId, messageIds);
+        }
+        if (messageIds.has(messageId))
+            return;
+        messageIds.add(messageId);
+        if (messageIds.size > 1) {
+            resumedChildSessions.add(sessionId);
+            taintBindingsForChild(sessionId, "child_reprompted");
+        }
+    }
+    function observeTaskLaunchArgs(args) {
+        const launch = readDelegatedLaunchEligibility(args);
+        if (!launch.resumedTaskId)
+            return;
+        resumedChildSessions.add(launch.resumedTaskId);
+        taintBindingsForChild(launch.resumedTaskId, "child_resumed");
+    }
+    function observeAfterHookEntry(sessionId, callId) {
+        const binding = delegatedLaunchBindings.get(delegatedLaunchBindingKey(sessionId, callId));
+        if (binding) {
+            binding.afterHookEntered = true;
+        }
+    }
+    function observeAfterHookMetadata(sessionId, callId, metadata) {
+        const binding = delegatedLaunchBindings.get(delegatedLaunchBindingKey(sessionId, callId));
+        if (!binding || !metadata || typeof metadata !== "object")
+            return;
+        const record = metadata;
+        const child = record.sessionId;
+        if (typeof child === "string" && child.trim() !== "") {
+            if (binding.childSessionId === undefined) {
+                binding.childSessionId = child;
             }
-            catch {
-                // Snapshot failures are non-blocking
+            else if (binding.childSessionId !== child) {
+                taintDelegatedLaunchBinding(binding, "metadata_child_replaced");
             }
         }
+        if (record.background === true)
+            taintDelegatedLaunchBinding(binding, "metadata_background");
+        if (typeof record.jobId === "string" && record.jobId !== "") {
+            taintDelegatedLaunchBinding(binding, "metadata_job");
+        }
+        if (record.interrupted === true)
+            taintDelegatedLaunchBinding(binding, "metadata_interrupted");
     }
-    // END_BLOCK_PERSISTENCE_SETUP
+    /**
+     * Stage the failed-attempt transition, persist a checked snapshot of the
+     * staged state, and only then commit it in memory. There is no async yield
+     * between the final identity/exclusion check and the commit; a checked write
+     * failure leaves the live in-flight attempt (and retry block) intact.
+     */
+    function commitDelegatedLaunchFailure(sessionId, binding, failureExcerpt) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore || invalidHydrationSessions.has(sessionId))
+            return;
+        const liveData = liveStore.getStoreData();
+        const stagedStore = createWorkItemStore(liveData);
+        const applied = applyDelegatedLaunchFailure(stagedStore, {
+            sessionId,
+            workItemId: binding.workItemId,
+            callId: binding.callId,
+            failureExcerpt,
+        });
+        if (!applied.ok) {
+            // Stale, duplicate, or already-transitioned: settle without mutation.
+            binding.settled = true;
+            return;
+        }
+        const stagedData = stagedStore.getStoreData();
+        const persisted = snapshotWorkflowStateChecked(sessionId, stagedData);
+        if (!persisted.ok) {
+            // Keep the live in-flight attempt and evidence so an unpersisted retry
+            // is never authorized; a later authoritative event can retry safely.
+            void client.app
+                .log({
+                body: {
+                    service: "workflow",
+                    level: "error",
+                    message: "[workflow][delegatedFailure][BLOCK_DELEGATED_FAILURE] persistence failed",
+                    extra: {
+                        sessionID: sessionId,
+                        workItemId: binding.workItemId,
+                        attempt: binding.attempt,
+                        error: persisted.error.slice(0, 300),
+                    },
+                },
+            })
+                .catch(() => undefined);
+            return;
+        }
+        const lookupKey = createRecordLookupKey(sessionId, binding.workItemId);
+        const committed = stagedData.records.get(lookupKey);
+        if (!committed)
+            return;
+        liveData.records.set(lookupKey, committed);
+        binding.settled = true;
+        void client.app
+            .log({
+            body: {
+                service: "workflow",
+                level: "warn",
+                message: "[workflow][delegatedFailure][BLOCK_DELEGATED_FAILURE] host-terminal launch failure recorded",
+                extra: {
+                    sessionID: sessionId,
+                    workItemId: binding.workItemId,
+                    attempt: applied.attempt,
+                    consumedAttempts: applied.consumedAttempts,
+                    attemptBudget: applied.attemptBudget,
+                    retryAllowed: applied.retryAllowed,
+                },
+            },
+        })
+            .catch(() => undefined);
+    }
+    function handleDelegatedPartUpdated(properties) {
+        const part = properties.part;
+        if (!part || typeof part !== "object")
+            return;
+        if (part.type !== "tool" || part.tool !== "task")
+            return;
+        const parentSessionId = typeof part.sessionID === "string" ? part.sessionID : undefined;
+        const callId = typeof part.callID === "string" ? part.callID : undefined;
+        if (!parentSessionId || !callId)
+            return;
+        const binding = delegatedLaunchBindings.get(delegatedLaunchBindingKey(parentSessionId, callId));
+        if (!binding)
+            return;
+        const state = part.state;
+        if (!state || typeof state !== "object")
+            return;
+        const isError = state.status === "error";
+        const metadata = state.metadata && typeof state.metadata === "object"
+            ? state.metadata
+            : undefined;
+        if (!metadata) {
+            // A non-error part may simply not carry metadata yet; an error without
+            // metadata can never be bound and is latched blocked to stay fail-closed.
+            if (isError)
+                taintDelegatedLaunchBinding(binding, "metadata_missing_on_error");
+            return;
+        }
+        const metaParent = metadata.parentSessionId;
+        const metaChild = metadata.sessionId;
+        if (metaParent !== parentSessionId) {
+            taintDelegatedLaunchBinding(binding, "metadata_parent_mismatch");
+            return;
+        }
+        if (typeof metaChild !== "string" || metaChild.trim() === "") {
+            taintDelegatedLaunchBinding(binding, "metadata_child_missing");
+            return;
+        }
+        if (binding.childSessionId === undefined) {
+            binding.childSessionId = metaChild;
+        }
+        else if (binding.childSessionId !== metaChild) {
+            taintDelegatedLaunchBinding(binding, "metadata_child_replaced");
+            return;
+        }
+        if (metadata.background === true) {
+            taintDelegatedLaunchBinding(binding, "metadata_background");
+            return;
+        }
+        if (typeof metadata.jobId === "string" && metadata.jobId !== "") {
+            taintDelegatedLaunchBinding(binding, "metadata_job");
+            return;
+        }
+        if (metadata.interrupted === true) {
+            taintDelegatedLaunchBinding(binding, "metadata_interrupted");
+            return;
+        }
+        if (resumedChildSessions.has(metaChild)) {
+            taintDelegatedLaunchBinding(binding, "child_resumed");
+            return;
+        }
+        if (binding.afterHookEntered || !binding.eligible || binding.settled)
+            return;
+        if (!isError)
+            return;
+        const error = state.error;
+        if (typeof error !== "string")
+            return;
+        if (!error.startsWith(delegatedHostFailurePrefix(metaChild)))
+            return;
+        const failureExcerpt = createWorkflowResultExcerpt({
+            text: error,
+            source: "normalized_output",
+        });
+        if (!failureExcerpt)
+            return;
+        if (!stores.has(parentSessionId) || invalidHydrationSessions.has(parentSessionId))
+            return;
+        commitDelegatedLaunchFailure(parentSessionId, binding, failureExcerpt);
+    }
+    // END_BLOCK_DELEGATED_FAILURE_BINDING
+    // START_BLOCK_DELEGATED_AUTHORIZATION
+    // New control mutations require the primary vv-controller session: the calling
+    // agent must be vv-controller, the session must be a root session (no
+    // parentID), and the ToolContext workspace must match the plugin's trusted
+    // directory/worktree. None of this identity comes from tool arguments.
+    async function assertPrimaryControllerMutation(agent, sessionId, contextWorkspace, toolName) {
+        if (!canUseWorkflowTools(agent)) {
+            throw new Error(`CONTROL_DENIED: ${toolName} is only available to ${WORKFLOW_CONTROLLER_AGENT} sessions. Current agent: ${agent?.trim() || "unknown-agent"}.`);
+        }
+        if (contextWorkspace.worktree !== undefined &&
+            contextWorkspace.worktree !== worktree &&
+            contextWorkspace.worktree !== trustedWorkspaceRoot) {
+            throw new Error(`CONTROL_DENIED: ${toolName} workspace ${contextWorkspace.worktree} does not match the trusted plugin workspace.`);
+        }
+        if (contextWorkspace.worktree === undefined &&
+            contextWorkspace.directory !== undefined &&
+            contextWorkspace.directory !== directory) {
+            throw new Error(`CONTROL_DENIED: ${toolName} directory ${contextWorkspace.directory} does not match the trusted plugin directory.`);
+        }
+        if (invalidHydrationSessions.has(sessionId)) {
+            throw new Error(`CONTROL_DENIED: persisted workflow state for session ${sessionId} is invalid; resolve or remove it before new control mutations.`);
+        }
+        let parentID;
+        try {
+            const response = await client.session.get({ path: { id: sessionId } });
+            if (!response.data) {
+                throw new Error("missing session payload");
+            }
+            parentID = response.data.parentID;
+        }
+        catch (error) {
+            throw new Error(`CONTROL_DENIED: ${toolName} requires root-session identity for ${sessionId}, which could not be verified: ${error.message}`);
+        }
+        if (parentID !== undefined && parentID !== null && parentID !== "") {
+            throw new Error(`CONTROL_DENIED: ${toolName} may only run in the root session; session ${sessionId} is a child of ${parentID}.`);
+        }
+    }
+    // END_BLOCK_DELEGATED_AUTHORIZATION
+    // START_BLOCK_CHECKPOINT_LINKAGE
+    /** Find the in-flight checkpoint generation whose linked review item matches. */
+    function findCheckpointByReviewItem(sessionId, reviewWorkItemId) {
+        for (const run of getOrCreateStore(sessionId).getStoreData().planRuns.values()) {
+            if (run.sessionId !== sessionId)
+                continue;
+            for (const checkpoint of run.checkpoints.values()) {
+                if (checkpoint.currentReview?.reviewWorkItemId === reviewWorkItemId) {
+                    return { run, checkpointId: checkpoint.checkpointId };
+                }
+            }
+        }
+        return undefined;
+    }
+    // END_BLOCK_CHECKPOINT_LINKAGE
     // START_BLOCK_PLUGIN_ENTRY
     // Tool wrappers still need a store reference for description/args shape
     // but execute handlers resolve the right store per-call
@@ -214,6 +592,8 @@ export const WorkflowPlugin = async ({ client, directory }) => {
     const workItemOpenTool = createWorkItemOpenTool(dummyStore);
     const workItemListTool = createWorkItemListTool(dummyStore);
     const workItemCloseTool = createWorkItemCloseTool(dummyStore);
+    const workItemDecideTool = createWorkItemDecideTool(dummyStore);
+    const workCheckpointTool = createWorkCheckpointTool(dummyStore);
     return {
         tool: {
             work_item_open: tool({
@@ -224,6 +604,9 @@ export const WorkflowPlugin = async ({ client, directory }) => {
                         title: z.string(),
                         mode: z.string(),
                         requiredReviewers: z.array(z.string()),
+                        writeScope: z.array(z.string()).optional(),
+                        planRunId: z.string().optional(),
+                        planTaskId: z.string().optional(),
                     })),
                 },
                 async execute(args, context) {
@@ -258,11 +641,81 @@ export const WorkflowPlugin = async ({ client, directory }) => {
                     return stringifyToolOutput(closed);
                 },
             }),
+            // The delegated control tools are registered only under the delegated
+            // startup profile; other profiles keep their current tool-schema footprint.
+            ...(delegatedProfileActive
+                ? {
+                    work_item_decide: tool({
+                        description: workItemDecideTool.description,
+                        args: {
+                            workItemId: z.string(),
+                            attempt: z.number().int().min(1),
+                            decision: z.enum(["accept", "request_changes", "rework"]),
+                            rationale: z.string(),
+                            evidence: z.array(z.string()),
+                            concernsDisposition: z.string().optional(),
+                            runId: z.string().optional(),
+                            checkpointId: z.string().optional(),
+                        },
+                        async execute(args, context) {
+                            // Resolve the store first so invalid persisted state is detected
+                            // before the authorization check reports it as a control denial.
+                            const sessionStore = getOrCreateStore(context.sessionID);
+                            await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_item_decide");
+                            const decided = workItemDecideTool.execute(args, { sessionId: context.sessionID }, sessionStore);
+                            if (decided.ok) {
+                                const persisted = snapshotSession(context.sessionID);
+                                if (!persisted.ok) {
+                                    throw new Error(`PERSISTENCE_FAILED: decision applied in memory but could not be persisted: ${persisted.error}`);
+                                }
+                            }
+                            return stringifyToolOutput(decided);
+                        },
+                    }),
+                    work_checkpoint: tool({
+                        description: workCheckpointTool.description,
+                        args: {
+                            action: z.enum(["register", "start", "verify"]),
+                            planPath: z.string().optional(),
+                            runId: z.string().optional(),
+                            checkpointId: z.string().optional(),
+                            complete: z.boolean().optional(),
+                        },
+                        async execute(args, context) {
+                            // Resolve the store first so invalid persisted state is detected
+                            // before the authorization check reports it as a control denial.
+                            const sessionStore = getOrCreateStore(context.sessionID);
+                            await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_checkpoint");
+                            const toolContext = {
+                                sessionId: context.sessionID,
+                                workspaceRoot: trustedWorkspaceRoot,
+                                loadPlan: async (planPath, workspaceRoot) => {
+                                    const loaded = await loadApprovedDelegatedPlan({ workspaceRoot, planPath });
+                                    return loaded.ok
+                                        ? loaded.plan
+                                        : { loadError: `${loaded.code}: ${loaded.message}` };
+                                },
+                            };
+                            const result = await workCheckpointTool.execute({ ...args }, toolContext, sessionStore);
+                            if (result.ok) {
+                                const persisted = snapshotSession(context.sessionID);
+                                if (!persisted.ok) {
+                                    throw new Error(`PERSISTENCE_FAILED: checkpoint change applied in memory but could not be persisted: ${persisted.error}`);
+                                }
+                            }
+                            return stringifyToolOutput(result);
+                        },
+                    }),
+                }
+                : {}),
         },
         "tool.execute.before": async (input, output) => {
             if (input.tool !== "task") {
                 return;
             }
+            // Observe resume identities from every task launch, including untracked
+            // ones, before any early return so a resumed child cannot stay eligible.
+            observeTaskLaunchArgs(output.args);
             const subagentType = readTaskSubagentType(output.args);
             if (!isTrackedSubagent(subagentType)) {
                 return;
@@ -362,6 +815,90 @@ export const WorkflowPlugin = async ({ client, directory }) => {
                 });
                 throw new Error(`${INVALID_NEXT_AGENT_MARKER} LAUNCH_REJECTED_INVALID_TRANSITION: ${workItem.workItemId} in state ${workItem.state} only allows ${launched.allowedAgents.join(", ") || "no tracked agent"}. ${launched.message}`);
             }
+            // START_BLOCK_DELEGATED_LAUNCH_BINDING
+            // Delegated implementer launches consume a callID-bound attempt after the
+            // checkpoint barrier and overlapping-write gates pass. Reviewer launches
+            // on a checkpoint-linked review item bind their call identity to the
+            // current generation.
+            if (workItem.mode === "delegated" && subagentType === "vv-implementer") {
+                const data = sessionStore.getStoreData();
+                const planRunId = workItem.delegated?.planRunId;
+                if (planRunId) {
+                    const run = data.planRuns.get(planRunId);
+                    const binding = run
+                        ? [...run.tasks.values()].find((task) => task.workItemId === workItem.workItemId)
+                        : undefined;
+                    const taskDefinition = run?.definition.tasks.find((task) => task.taskId === binding?.taskId);
+                    if (run && taskDefinition) {
+                        const barrier = checkpointBarrierUnsatisfied(data, planRunId, taskDefinition.wave);
+                        if (barrier.ok && barrier.blockers.length > 0) {
+                            throw new Error(`LAUNCH_REJECTED_CHECKPOINT_BARRIER: ${workItem.workItemId} is in wave ${taskDefinition.wave} blocked by unpassed checkpoint(s) ${barrier.blockers.join(", ")}.`);
+                        }
+                    }
+                    const overlapping = findOverlappingInFlightReview(data, planRunId, workItem.delegated?.writeScope ?? []);
+                    if (overlapping) {
+                        throw new Error(`LAUNCH_REJECTED_OVERLAPPING_REVIEW: declared write scope overlaps checkpoint ${overlapping} currently in review.`);
+                    }
+                }
+                const delegatedLaunch = beginDelegatedLaunch(sessionStore, {
+                    sessionId: input.sessionID,
+                    workItemId: workItem.workItemId,
+                    callId: input.callID,
+                });
+                if (!delegatedLaunch.ok) {
+                    await client.app.log({
+                        body: {
+                            service: "workflow",
+                            level: "warn",
+                            message: "[workflow][launchValidation][BLOCK_VALIDATE_LAUNCH] launch rejected",
+                            extra: {
+                                sessionID: input.sessionID,
+                                agent: subagentType,
+                                workItemId: workItem.workItemId,
+                                reason: delegatedLaunch.errorCode,
+                            },
+                        },
+                    });
+                    throw new Error(`LAUNCH_REJECTED_DELEGATED_${delegatedLaunch.errorCode}: ${delegatedLaunch.message}`);
+                }
+                // Bind the successful launch so a later confirmed host-terminal error
+                // for this exact call can be consumed as a failed attempt. Eligibility
+                // captures background/resume/command exclusions up front.
+                const eligibility = readDelegatedLaunchEligibility(output.args);
+                delegatedLaunchBindings.set(delegatedLaunchBindingKey(input.sessionID, input.callID), {
+                    sessionId: input.sessionID,
+                    callId: input.callID,
+                    workItemId: workItem.workItemId,
+                    attempt: delegatedLaunch.attempt,
+                    eligible: eligibility.eligible,
+                    ineligibleReason: eligibility.reason,
+                    afterHookEntered: false,
+                    settled: false,
+                });
+            }
+            else {
+                const reviewerRole = getReviewerRoleForAgent(subagentType);
+                if (reviewerRole) {
+                    const linked = findCheckpointByReviewItem(input.sessionID, workItem.workItemId);
+                    if (linked) {
+                        const bound = recordCheckpointReviewerLaunch(sessionStore, {
+                            runId: linked.run.runId,
+                            checkpointId: linked.checkpointId,
+                            reviewer: reviewerRole,
+                            callId: input.callID,
+                        });
+                        if (!bound.ok) {
+                            revertReviewerLaunch(sessionStore, {
+                                sessionId: input.sessionID,
+                                workItemId: workItem.workItemId,
+                                agent: subagentType,
+                            });
+                            throw new Error(`LAUNCH_REJECTED_CHECKPOINT_REVIEW: ${bound.errorCode}: ${bound.message}`);
+                        }
+                    }
+                }
+            }
+            // END_BLOCK_DELEGATED_LAUNCH_BINDING
             snapshotSession(input.sessionID);
             await client.app.log({
                 body: {
@@ -381,6 +918,13 @@ export const WorkflowPlugin = async ({ client, directory }) => {
             });
         },
         "tool.execute.after": async (input, output) => {
+            // Latch the ambiguous after-hook path synchronously before any logging,
+            // parsing, or repair so a later error event for this call cannot be
+            // classified as a terminal launch failure.
+            if (input.tool === "task") {
+                observeAfterHookEntry(input.sessionID, input.callID);
+                observeAfterHookMetadata(input.sessionID, input.callID, output?.metadata);
+            }
             if (input.tool !== "task") {
                 return;
             }
@@ -540,6 +1084,99 @@ export const WorkflowPlugin = async ({ client, directory }) => {
                     formatResultExcerptForError(resultExcerpt),
                 ].join("\n"));
             }
+            // START_BLOCK_DELEGATED_RESULT_BINDING
+            // Delegated implementer results apply to their matching callID-bound
+            // attempt; reviewer results on checkpoint-linked review items are
+            // recorded into the current generation before the legacy round applies.
+            if (current.mode === "delegated" && subagentType === "vv-implementer") {
+                const appliedDelegated = applyDelegatedResult(sessionStore, {
+                    sessionId: input.sessionID,
+                    workItemId: parsed.value.workItemId,
+                    callId: input.callID,
+                    resultStatus: parsed.value.status,
+                    resultExcerpt,
+                });
+                if (!appliedDelegated.ok) {
+                    await client.app.log({
+                        body: {
+                            service: "workflow",
+                            level: "warn",
+                            message: "[workflow][resultParsing][BLOCK_PARSE_RESULT] protocol error",
+                            extra: {
+                                sessionID: input.sessionID,
+                                agent: subagentType,
+                                workItemId: parsed.value.workItemId,
+                                reason: appliedDelegated.errorCode,
+                            },
+                        },
+                    });
+                    throw new Error([
+                        `RESULT_PROTOCOL_ERROR: ${appliedDelegated.message}`,
+                        formatResultExcerptForError(resultExcerpt),
+                    ].join("\n"));
+                }
+                await client.app.log({
+                    body: {
+                        service: "workflow",
+                        level: "info",
+                        message: "[workflow][stateTransition][BLOCK_TRANSITION_STATE] state transitioned",
+                        extra: {
+                            sessionID: input.sessionID,
+                            agent: subagentType,
+                            workItemId: parsed.value.workItemId,
+                            fromState: appliedDelegated.fromState,
+                            toState: appliedDelegated.toState,
+                            mode: "delegated",
+                            attempt: appliedDelegated.attempt,
+                        },
+                    },
+                });
+                snapshotSession(input.sessionID);
+                if (appliedDelegated.record.state === "needs_context" ||
+                    appliedDelegated.record.state === "blocked") {
+                    throw new Error(createHardStopMessage({
+                        record: appliedDelegated.record,
+                        triggeringAgent: subagentType,
+                        triggeringStatus: parsed.value.status,
+                        triggeringExcerpt: resultExcerpt,
+                    }));
+                }
+                return;
+            }
+            const reviewerRoleForCheckpoint = getReviewerRoleForAgent(subagentType);
+            if (reviewerRoleForCheckpoint) {
+                const linked = findCheckpointByReviewItem(input.sessionID, parsed.value.workItemId);
+                if (linked) {
+                    const recorded = recordCheckpointReviewerResult(sessionStore, {
+                        runId: linked.run.runId,
+                        checkpointId: linked.checkpointId,
+                        reviewer: reviewerRoleForCheckpoint,
+                        callId: input.callID,
+                        status: parsed.value.status,
+                    });
+                    if (!recorded.ok) {
+                        await client.app.log({
+                            body: {
+                                service: "workflow",
+                                level: "warn",
+                                message: "[workflow][resultParsing][BLOCK_PARSE_RESULT] protocol error",
+                                extra: {
+                                    sessionID: input.sessionID,
+                                    agent: subagentType,
+                                    workItemId: parsed.value.workItemId,
+                                    reason: recorded.errorCode,
+                                },
+                            },
+                        });
+                        revertLaunch();
+                        throw new Error([
+                            `RESULT_PROTOCOL_ERROR: checkpoint ${linked.checkpointId} rejected the reviewer result: ${recorded.message}`,
+                            formatResultExcerptForError(resultExcerpt),
+                        ].join("\n"));
+                    }
+                }
+            }
+            // END_BLOCK_DELEGATED_RESULT_BINDING
             const applied = applyTrackedResult(sessionStore, {
                 sessionId: input.sessionID,
                 workItemId: parsed.value.workItemId,
@@ -601,8 +1238,26 @@ export const WorkflowPlugin = async ({ client, directory }) => {
             output.message.system = appendSystemInstruction(output.message.system, workflowSystemInstruction);
         },
         event: async (input) => {
-            const eventType = input.event.type;
-            const properties = input.event.properties ?? {};
+            const event = input.event;
+            const eventType = event.type;
+            const properties = event.properties ?? {};
+            // message.part.updated identifies its session through properties.part,
+            // not properties.sessionID, and must never hydrate a store.
+            if (eventType === "message.part.updated") {
+                handleDelegatedPartUpdated(properties);
+                return;
+            }
+            // A child session that receives more than one user prompt has been
+            // resumed or re-prompted and is no longer a fresh-exclusive child.
+            if (eventType === "message.updated") {
+                const messageInfo = properties.info;
+                if (messageInfo &&
+                    messageInfo.role === "user" &&
+                    typeof messageInfo.sessionID === "string") {
+                    observeChildPrompt(messageInfo.sessionID, typeof messageInfo.id === "string" ? messageInfo.id : undefined);
+                }
+                return;
+            }
             const info = properties.info;
             const eventSessionId = properties.sessionID ?? info?.id;
             if (!eventSessionId)
@@ -614,6 +1269,13 @@ export const WorkflowPlugin = async ({ client, directory }) => {
                 return;
             }
             if (eventType === "session.deleted") {
+                for (const [key, binding] of delegatedLaunchBindings) {
+                    if (binding.sessionId === eventSessionId) {
+                        delegatedLaunchBindings.delete(key);
+                    }
+                }
+                childPromptMessageIds.delete(eventSessionId);
+                resumedChildSessions.delete(eventSessionId);
                 stores.delete(eventSessionId);
                 await deleteWorkflowSessionDir(eventSessionId);
                 await client.app.log({