@osovv/vv-opencode 1.4.5 → 1.6.0

package/dist/plugins/workflow/index.js

@@ -1,42 +1,46 @@
 // FILE: src/plugins/workflow/index.ts
-// VERSION: 0.7.0
+// VERSION: 0.9.1
 // START_MODULE_CONTRACT
-//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance, including delegated control tools with bounded recovery, host-call-bound attempts, terminal report-rejection settlement, and checkpoint reviewer linkage.
-//   SCOPE: work_item_open/list/close registration, delegated-only work_item_decide and work_checkpoint registration with root-session authorization and an SDK-backed read-only authorization-message lookup for user-authorized recovery, 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 bounded same-session continuation with explicit hard-stop suppression, callID-bound delegated attempt results, terminal settlement of protocol-invalid reports as report_rejected attempts through staged persistence, checkpoint reviewer bookkeeping, round aggregation with bounded excerpts, implementation round limits, durably committed recovery with synchronous persist and rollback so launch permissions appear only after a durable write, 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
+//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance, including profile-independent control tools with bounded recovery, host-call-bound attempts, terminal report-rejection settlement, checkpoint reviewer linkage, and strict owned-tool contract publication/validation.
+//   SCOPE: work_item_open/list/close registration, profile-independent work_item_decide and work_checkpoint registration with root-session authorization and an SDK-backed read-only authorization-message lookup for user-authorized recovery, owned tool.definition publication of strict input JSON Schemas plus early validateWorkflowToolInput guards in tool.execute.before (without touching task-launch hooks), pre-dispatch structural validation of mutation tools, tracked launch validation with delegated barriers, overlapping-write gates, and authoritative native sealed-run rejection, live host-call bindings that convert supported foreground vv-implementer task launches into failed delegated attempts on confirmed host-terminal errors, result normalization and bounded same-session continuation with explicit hard-stop suppression, callID-bound delegated attempt results, terminal settlement of protocol-invalid reports as report_rejected attempts through staged persistence, checkpoint reviewer bookkeeping, round aggregation with bounded excerpts, implementation round limits, checked persistence, and profile-selected chat.message guidance. Tool argument schemas come from schemas.ts; branch-aware validation from input-validation.ts; the authorization guard and message lookups from authorization.ts; staged transactions and committed recovery from recovery.ts.
+//   DEPENDS: [@opencode-ai/plugin, src/lib/agent-tool-contract.ts, src/lib/config-layers.ts, src/lib/orchestration.ts, src/lib/plugin-toggle-config.ts, src/plugins/workflow/authorization.ts, src/plugins/workflow/checkpoint-io.ts, src/plugins/workflow/checkpoints.ts, src/plugins/workflow/delegated.ts, src/plugins/workflow/input-validation.ts, src/plugins/workflow/persistence.ts, src/plugins/workflow/protocol.ts, src/plugins/workflow/recovery.ts, src/plugins/workflow/repair.ts, src/plugins/workflow/results.ts, src/plugins/workflow/schemas.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-AGENT-TOOL-CONTRACT, V-M-PLUGIN-WORKFLOW
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   WorkflowPlugin - Registers workflow work-item tools, delegated control tools under the delegated profile, tracked task protocol enforcement with callID-bound delegated attempts, bounded recovery with durable persist-and-rollback commits, terminal report-rejection settlement, checkpoint linkage, live host-call failure bindings, and primary-session workflow guidance injection.
+//   WorkflowPlugin - Registers workflow work-item tools, profile-independent control tools whose execution remains root-session gated, owned tool.definition/execute.before contract hooks, tracked task protocol enforcement with callID-bound delegated attempts, bounded recovery with durable persist-and-rollback commits, terminal report-rejection settlement, checkpoint linkage, live host-call failure bindings, and primary-session workflow guidance injection.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-WORKFLOW-BOUNDED-RECOVERY-R1 - Added decision/checkpoint recover wiring with an SDK-backed authorization lookup and durable persist-then-rollback commits, settled terminal protocol-invalid delegated reports as report_rejected attempts, and calibrated the delegated instruction for bounded recovery and native plan registration.]
+//   LAST_CHANGE: [C-AGENT-TOOL-CONTRACTS T-007 - Appended one shared tracked result-protocol instruction, generated from protocol.ts status vocabularies, to the review-only/selective/delegated guidance so common launch/result rules and the on-demand reference path are available without the native execution skill; the profile-specific ownership text and the tracked system instruction are otherwise unchanged. Prior T-004: removed the redundant registration spread and made the native launch hook reject an authoritatively sealed plan run.]
 // END_CHANGE_SUMMARY
 import { tool } from "@opencode-ai/plugin";
 import { attemptTrackedResultRepair, detectExplicitHardStopStatus, isTrackedResultRepairEligible, unwrapResumableTaskResult, } from "./repair.js";
-import { parseResultBlock, parseWorkItemHeader, TRACKED_SUBAGENT_NAMES, } from "./protocol.js";
-import { applyTrackedResult, createRecordLookupKey, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, createWorkItemStoreView, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
+import { describeStatusVocabulary, parseResultBlock, parseWorkItemHeader, TRACKED_SUBAGENT_NAMES, } from "./protocol.js";
+import { applyTrackedResult, createRecordLookupKey, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
 import { applyDelegatedLaunchFailure, applyDelegatedReportRejection, applyDelegatedResult, beginDelegatedLaunch, revertInFlightDelegatedLaunches, summarizeDelegatedProgress, } 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 { workCheckpointArgs, workItemCloseArgs, workItemDecideArgs, workItemListArgs, workItemOpenArgs, } from "./schemas.js";
+import { isWorkflowToolId, validateWorkflowToolInput, workflowToolContracts, } from "./input-validation.js";
+import { ContractInputError, createToolDefinitionAdapter } from "../../lib/agent-tool-contract.js";
+import { serializeWorkflowResult, workflowInputFailure } from "./results.js";
+import { deriveDelegatedGuidance } from "./inspection.js";
+import { assertWorkflowToolAccess, createWorkflowAuthorization, shouldInjectForAgent, } from "./authorization.js";
+import { createRecoverySupport } from "./recovery.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, hydrateWorkflowStateChecked, snapshotWorkflowStateChecked, } from "./persistence.js";
 import { loadApprovedDelegatedPlan } from "./checkpoint-io.js";
-import { isTaskLaunchableInStore } from "./execution.js";
-import { runWorkflowTransaction, WorkflowTransactionQueue } from "./transactions.js";
-const z = tool.schema;
+import { isTaskLaunchableInStore, latestAttemptView } from "./execution.js";
 const TRACKED_SUBAGENT_SET = new Set(TRACKED_SUBAGENT_NAMES);
 const WORK_ITEM_MISSING_MARKER = "__VVOC" + "_SECRET_BEARER_TOKEN_a6f582092f05__";
 const INVALID_NEXT_AGENT_MARKER = "__VVOC" + "_SECRET_BEARER_TOKEN_513fa2de603d__";
-const WORKFLOW_CONTROLLER_AGENT = "vv-controller";
 const REVIEW_ONLY_WORKFLOW_SYSTEM_INSTRUCTION = `
 <workflow_protocol>
 Tracked review-only mechanics are available when independent evaluation is explicitly requested or
@@ -103,17 +107,29 @@ packets, while keeping planning artifacts, acceptance decisions, and verificatio
 session.
 </workflow_protocol>
 `.trim();
+// Common result-protocol guidance appended to the non-tracked profile
+// instructions. It states shared launch/result rules only: it does not select a
+// source or lifecycle, and it adds no delegation or review obligation. Status
+// vocabularies come from protocol.ts so the text cannot drift from the parser.
+const TRACKED_RESULT_PROTOCOL_INSTRUCTION = `
+<tracked_result_protocol>
+A tracked subagent result begins on its first line with the protocol top block — no preface, prose, or code fence — followed by a blank line and the body. Use the exact VVOC_WORK_ITEM_ID returned by work_item_open for that assignment; never reuse a sample id from another task.
+- vv-implementer: VVOC_STATUS ${describeStatusVocabulary("vv-implementer")}, with a required VVOC_ROUTE.
+- vv-spec-reviewer / vv-code-reviewer: VVOC_STATUS ${describeStatusVocabulary("vv-spec-reviewer")}; a reviewer result carries no route.
+A result whose first field names a different work item is a work-item mismatch, not a malformed header, and is never relabeled to the expected id. Inspect work_item_list before retrying to recover the current identity, state, attempt, and remaining budget. Common tool calls follow the published input schemas, and work_item_list reports the loaded contract revision and the on-demand reference path at contract.referencePath.
+</tracked_result_protocol>
+`.trim();
 /** Returns the exact workflow instruction compatible with one resolved policy. */
 function getWorkflowSystemInstruction(policy) {
     switch (policy.workflowGuidance) {
         case "review-only":
-            return REVIEW_ONLY_WORKFLOW_SYSTEM_INSTRUCTION;
+            return `${REVIEW_ONLY_WORKFLOW_SYSTEM_INSTRUCTION}\n\n${TRACKED_RESULT_PROTOCOL_INSTRUCTION}`;
         case "selective":
-            return SELECTIVE_WORKFLOW_SYSTEM_INSTRUCTION;
+            return `${SELECTIVE_WORKFLOW_SYSTEM_INSTRUCTION}\n\n${TRACKED_RESULT_PROTOCOL_INSTRUCTION}`;
         case "tracked":
             return workflowSystemInstructionTemplate.trim();
         case "delegated":
-            return DELEGATED_WORKFLOW_SYSTEM_INSTRUCTION;
+            return `${DELEGATED_WORKFLOW_SYSTEM_INSTRUCTION}\n\n${TRACKED_RESULT_PROTOCOL_INSTRUCTION}`;
     }
 }
 function isTrackedSubagent(value) {
@@ -180,19 +196,6 @@ function delegatedHostFailurePrefix(childSessionId) {
     return `Subagent failed (task_id: ${childSessionId}): `;
 }
 // END_BLOCK_DELEGATED_FAILURE_BINDING_TYPES
-function canUseWorkflowTools(agentName) {
-    return agentName === WORKFLOW_CONTROLLER_AGENT;
-}
-function assertWorkflowToolAccess(agentName, toolName) {
-    if (canUseWorkflowTools(agentName)) {
-        return;
-    }
-    const resolvedAgent = agentName?.trim() || "unknown-agent";
-    throw new Error(`WORKFLOW_TOOL_DENIED: ${toolName} is only available to ${WORKFLOW_CONTROLLER_AGENT} sessions. Current agent: ${resolvedAgent}.`);
-}
-function shouldInjectForAgent(agentName) {
-    return canUseWorkflowTools(agentName);
-}
 function appendSystemInstruction(existingSystem, instruction) {
     if (!existingSystem?.trim()) {
         return instruction;
@@ -202,8 +205,11 @@ function appendSystemInstruction(existingSystem, instruction) {
     }
     return `${existingSystem.trim()}\n\n${instruction}`;
 }
-function stringifyToolOutput(value) {
-    return JSON.stringify(value, null, 2);
+// Serialize every public workflow result through the shared results contract so
+// failures gain a stable category and post-side-effect reporting failures stay
+// bounded and truthful instead of throwing raw after a committed mutation.
+function stringifyToolOutput(value, outcome) {
+    return serializeWorkflowResult(value, outcome !== undefined ? { outcome } : undefined);
 }
 function createRoundLimitMessage(record, attemptedRound) {
     return [
@@ -625,221 +631,21 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
     }
     // 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}.`);
-        }
-    }
+    // New control mutations require the primary vv-controller session; the
+    // guard, its root-session identity check, and the SDK-backed message
+    // lookups live in authorization.js over this explicit plugin context.
+    const { assertPrimaryControllerMutation, lookupRecoveryUserMessage, lookupAuthorityMessage } = createWorkflowAuthorization({
+        client,
+        directory,
+        worktree,
+        trustedWorkspaceRoot,
+        invalidHydrationSessions,
+    });
     // END_BLOCK_DELEGATED_AUTHORIZATION
     // START_BLOCK_RECOVERY_SUPPORT
-    // Read-only SDK message lookup for user-authorized recovery. Only identity
-    // and timing metadata (role, sessionID, id, time.created) are retained;
-    // message bodies never enter validation, persistence, or logs. Transport
-    // failures throw so the domain reports AUTHORIZATION_LOOKUP_FAILED instead
-    // of conflating an unreachable lookup with a nonexistent message.
-    const lookupRecoveryUserMessage = async (sessionId, messageId) => {
-        const response = await client.session.message({
-            path: { id: sessionId, messageID: messageId },
-            query: { directory },
-        });
-        if (response.error || !response.data) {
-            const errorName = response.error?.name;
-            if (errorName && errorName !== "NotFound") {
-                throw new Error(`session message lookup failed: ${errorName}`);
-            }
-            return undefined;
-        }
-        const info = response.data.info;
-        return {
-            role: info.role,
-            sessionID: info.sessionID,
-            id: info.id,
-            timeCreatedMs: typeof info.time?.created === "number" && Number.isFinite(info.time.created)
-                ? info.time.created
-                : undefined,
-        };
-    };
-    // Advance-authority provenance uses the same pinned SDK message response.
-    // Only verified identity/timing/eligibility metadata leaves this lookup; raw
-    // user text is never persisted or logged.
-    const lookupAuthorityMessage = async (input) => {
-        const response = await client.session.message({
-            path: { id: input.sessionId, messageID: input.messageId },
-            query: { directory },
-        });
-        if (response.error || !response.data) {
-            const errorName = response.error?.name;
-            if (errorName && errorName !== "NotFound") {
-                throw new Error(`authority message lookup failed: ${errorName}`);
-            }
-            return undefined;
-        }
-        const info = response.data.info;
-        const parts = Array.isArray(response.data.parts) ? response.data.parts : [];
-        const textParts = parts
-            .map((part) => part)
-            .filter((part) => part.type === "text" && typeof part.text === "string")
-            .map((part) => part.text);
-        return {
-            messageId: info.id ?? input.messageId,
-            sessionId: info.sessionID ?? input.sessionId,
-            role: info.role === "user" ? "user" : "assistant",
-            createdMs: typeof info.time?.created === "number" && Number.isFinite(info.time.created)
-                ? info.time.created
-                : 0,
-            ignored: info.ignored === true,
-            syntheticOnly: false,
-            textParts,
-        };
-    };
-    // Per-session serialization for generic mutating tool calls. The staged
-    // snapshot persists before the committed state is published, so a failed
-    // write never exposes new obligations, authority, or launch permissions.
-    const workflowTransactions = new WorkflowTransactionQueue();
-    async function commitGenericToolResult(sessionId, run) {
-        const liveStore = stores.get(sessionId);
-        if (!liveStore) {
-            return {
-                ok: false,
-                errorCode: "SESSION_MISMATCH",
-                message: `no live workflow store for session ${sessionId}`,
-            };
-        }
-        if (invalidHydrationSessions.has(sessionId)) {
-            return {
-                ok: false,
-                errorCode: "INVALID_STATE",
-                message: `persisted workflow state for session ${sessionId} is invalid`,
-            };
-        }
-        const outcome = await runWorkflowTransaction({
-            queue: workflowTransactions,
-            sessionId,
-            getData: () => liveStore.getStoreData(),
-            operation: async (staged) => {
-                const result = await run(createWorkItemStoreView(staged));
-                if (result.ok !== true) {
-                    // Validation failed: persist nothing and publish nothing.
-                    return { result, skipPersist: true };
-                }
-                return { result };
-            },
-        });
-        if (!outcome.ok) {
-            void client.app
-                .log({
-                body: {
-                    service: "workflow",
-                    level: "error",
-                    message: "[workflow][generic][BLOCK_GENERIC_COMMIT] persistence failed",
-                    extra: { sessionID: sessionId, error: outcome.error.slice(0, 300) },
-                },
-            })
-                .catch(() => undefined);
-            return {
-                ok: false,
-                errorCode: "PERSISTENCE_FAILED",
-                message: `generic workflow mutation could not be persisted: ${outcome.error}`,
-            };
-        }
-        return outcome.result;
-    }
-    /**
-     * Execute one recovery mutation durably on the live store: the domain
-     * reducer applies to the live entry (re-prechecking after any authorization
-     * await), and the whole live store is then persisted synchronously. If the
-     * write fails, the captured prior entry is restored so no unpersisted launch
-     * permission is ever exposed — there is no await between mutation, persist,
-     * and rollback, so no concurrent actor can observe the intermediate state,
-     * and no stale whole-store snapshot can regress concurrent transitions.
-     */
-    async function executeCommittedRecovery(sessionId, runRecovery, captureRestore, wasApplied) {
-        const liveStore = stores.get(sessionId);
-        if (!liveStore || invalidHydrationSessions.has(sessionId)) {
-            throw new Error(`CONTROL_DENIED: persisted workflow state for session ${sessionId} is invalid; resolve or remove it before new control mutations.`);
-        }
-        const restore = captureRestore();
-        const result = await runRecovery(liveStore);
-        if (!wasApplied(result)) {
-            return result;
-        }
-        const persisted = snapshotWorkflowStateChecked(sessionId, liveStore.getStoreData());
-        if (!persisted.ok) {
-            restore();
-            void client.app
-                .log({
-                body: {
-                    service: "workflow",
-                    level: "error",
-                    message: "[workflow][recovery][BLOCK_RECOVERY_COMMIT] recovery persistence failed",
-                    extra: { sessionID: sessionId, error: persisted.error.slice(0, 300) },
-                },
-            })
-                .catch(() => undefined);
-            throw new Error(`PERSISTENCE_FAILED: recovery applied in memory but could not be persisted and was rolled back: ${persisted.error}`);
-        }
-        return result;
-    }
-    /** Capture and restore one work-item record entry for recovery rollback. */
-    function captureRecordRestore(sessionId, workItemId) {
-        const liveStore = stores.get(sessionId);
-        if (!liveStore)
-            return () => undefined;
-        const liveData = liveStore.getStoreData();
-        const lookupKey = createRecordLookupKey(sessionId, workItemId);
-        const prior = liveData.records.get(lookupKey);
-        return () => {
-            if (prior) {
-                liveData.records.set(lookupKey, prior);
-            }
-        };
-    }
-    /** Capture and restore one checkpoint entry for recovery rollback. */
-    function captureCheckpointRestore(sessionId, runId, checkpointId) {
-        const liveStore = stores.get(sessionId);
-        if (!liveStore)
-            return () => undefined;
-        const run = liveStore.getStoreData().planRuns.get(runId);
-        if (!run)
-            return () => undefined;
-        const priorCheckpoint = run.checkpoints.get(checkpointId);
-        return () => {
-            if (priorCheckpoint) {
-                run.checkpoints.set(checkpointId, priorCheckpoint);
-            }
-        };
-    }
+    // Staged generic transactions and durably committed recovery with rollback
+    // live in recovery.js over this explicit persistence seam.
+    const { commitGenericToolResult, executeCommittedRecovery, captureRecordRestore, captureCheckpointRestore, } = createRecoverySupport({ client, stores, invalidHydrationSessions });
     // END_BLOCK_RECOVERY_SUPPORT
     // START_BLOCK_CHECKPOINT_LINKAGE
     /** Find the in-flight checkpoint generation whose linked review item matches. */
@@ -870,66 +676,46 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
         lookupUserMessage: lookupRecoveryUserMessage,
         lookupAuthorityMessage,
     });
+    // START_BLOCK_TOOL_CONTRACT_HOOKS
+    // Owned-only contract publication and early structural/branch validation.
+    // The tool.definition adapter publishes the strict input JSON Schema through
+    // the host's observable jsonSchema member (T-001-proven seam) without
+    // replacing the host decoder; the execute.before guard rejects invalid
+    // raw arguments with bounded tokenized paths before any handler runs and
+    // never touches the task-launch hooks below.
+    const toolDefinitionAdapter = createToolDefinitionAdapter([...workflowToolContracts]);
+    // END_BLOCK_TOOL_CONTRACT_HOOKS
     return {
         tool: {
             work_item_open: tool({
                 description: workItemOpenTool.description,
-                args: {
-                    items: z.array(z.object({
-                        key: z.string(),
-                        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(),
-                        taskId: z.string().optional(),
-                        goal: z.string().optional(),
-                        acceptanceCriteria: z.array(z.string()).optional(),
-                        verification: z.array(z.string()).optional(),
-                        dependsOn: z.array(z.string()).optional(),
-                        blockedBy: z.array(z.string()).optional(),
-                    })),
-                    execution: z
-                        .object({
-                        executionKey: z.string(),
-                        source: z.record(z.string(), z.unknown()),
-                        goal: z.string(),
-                        boundary: z.object({
-                            files: z.array(z.string()),
-                            directories: z.array(z.string()),
-                        }),
-                        checkpoints: z.array(z.record(z.string(), z.unknown())).optional(),
-                    })
-                        .optional(),
-                    runId: z.string().optional(),
-                    amendmentId: z.string().optional(),
-                    rationale: z.string().optional(),
-                },
+                args: workItemOpenArgs,
                 async execute(args, context) {
                     assertWorkflowToolAccess(context.agent, "work_item_open");
-                    const isGeneric = args.execution !== undefined || args.runId !== undefined;
+                    const validation = validateWorkflowToolInput("work_item_open", args);
+                    if (!validation.ok) {
+                        return stringifyToolOutput(workflowInputFailure("work_item_open", context.sessionID, validation.issues));
+                    }
+                    const isGeneric = validation.data.execution !== undefined || validation.data.runId !== undefined;
                     if (isGeneric) {
                         // Hydrate/validate the session store before the transaction boundary
                         // reads it, matching every other tool entry point.
                         getOrCreateStore(context.sessionID);
-                        const result = await commitGenericToolResult(context.sessionID, (view) => workItemOpenTool.execute(args, {
+                        const result = await commitGenericToolResult(context.sessionID, "work_item_open", (view) => workItemOpenTool.execute(args, {
                             sessionId: context.sessionID,
                             workspaceRoot: trustedWorkspaceRoot,
                         }, view));
-                        return stringifyToolOutput(result);
+                        return stringifyToolOutput(result, result.ok === true ? "committed" : "not_applied");
                     }
                     const sessionStore = getOrCreateStore(context.sessionID);
                     const opened = workItemOpenTool.execute(args, { sessionId: context.sessionID }, sessionStore);
-                    snapshotSession(context.sessionID);
-                    return stringifyToolOutput(opened);
+                    const openedPersisted = snapshotSession(context.sessionID);
+                    return stringifyToolOutput(opened, opened.ok === false ? "not_applied" : openedPersisted.ok ? "committed" : "unknown");
                 },
             }),
             work_item_list: tool({
                 description: workItemListTool.description,
-                args: {
-                    includeClosed: z.boolean().optional(),
-                },
+                args: workItemListArgs,
                 async execute(args, context) {
                     assertWorkflowToolAccess(context.agent, "work_item_list");
                     const sessionStore = getOrCreateStore(context.sessionID);
@@ -938,166 +724,133 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
             }),
             work_item_close: tool({
                 description: workItemCloseTool.description,
-                args: {
-                    workItemId: z.string(),
-                },
+                args: workItemCloseArgs,
                 async execute(args, context) {
                     assertWorkflowToolAccess(context.agent, "work_item_close");
                     const sessionStore = getOrCreateStore(context.sessionID);
                     const closed = workItemCloseTool.execute(args, { sessionId: context.sessionID }, sessionStore);
-                    snapshotSession(context.sessionID);
-                    return stringifyToolOutput(closed);
+                    const closedPersisted = snapshotSession(context.sessionID);
+                    return stringifyToolOutput(closed, closed.ok === false ? "not_applied" : closedPersisted.ok ? "committed" : "unknown");
                 },
             }),
             // Control tools are registered independent of the startup profile; they
             // remain root-session, agent, workspace, and invalid-hydration gated at
             // execution time.
-            ...{
-                work_item_decide: tool({
-                    description: workItemDecideTool.description,
-                    args: {
-                        workItemId: z.string(),
-                        attempt: z.number().int().min(1),
-                        decision: z.enum(["accept", "request_changes", "rework", "recover"]),
-                        rationale: z.string().optional(),
-                        evidence: z.array(z.string()).optional(),
-                        concernsDisposition: z.string().optional(),
-                        runId: z.string().optional(),
-                        checkpointId: z.string().optional(),
-                        diagnosis: z.string().optional(),
-                        changedCondition: z.string().optional(),
-                        verification: z.array(z.string()).optional(),
-                        recoveryId: z.string().optional(),
-                        userMessageId: z.string().optional(),
-                        authorityId: 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");
-                        // Recovery is the only decision family that must persist
-                        // before it exposes new launch permissions. Authority-bearing
-                        // recovery stages the work-item recovery and the reserve debit in
-                        // one serialized transaction so they commit or fail together.
-                        if (args.decision === "recover") {
-                            if (args.authorityId !== undefined) {
-                                const staged = await commitGenericToolResult(context.sessionID, (view) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, view));
-                                return stringifyToolOutput(staged);
-                            }
-                            const workItemId = String(args.workItemId ?? "");
-                            const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, liveStore), () => captureRecordRestore(context.sessionID, workItemId), (result) => result.ok === true);
-                            return stringifyToolOutput(recovered);
-                        }
-                        const decided = await 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",
-                            "recover",
-                            "review",
-                            "bind",
-                            "complete",
-                            "amend",
-                            "authorize",
-                            "record_approval",
-                            "revoke_authority",
-                        ]),
-                        planPath: z.string().optional(),
-                        runId: z.string().optional(),
-                        checkpointId: z.string().optional(),
-                        complete: z.boolean().optional(),
-                        diagnosis: z.string().optional(),
-                        changedCondition: z.string().optional(),
-                        verification: z.array(z.string()).optional(),
-                        recoveryId: z.string().optional(),
-                        userMessageId: z.string().optional(),
-                        checkpoints: z.array(z.record(z.string(), z.unknown())).optional(),
-                        tasks: z.array(z.record(z.string(), z.unknown())).optional(),
-                        amendmentId: z.string().optional(),
-                        rationale: z.string().optional(),
-                        startFingerprint: z.string().optional(),
-                        reviewer: z.string().optional(),
-                        authorityId: z.string().optional(),
-                        messageId: z.string().optional(),
-                        approvalId: z.string().optional(),
-                        stage: z.string().optional(),
-                        stages: z.array(z.string()).optional(),
-                        decisionScope: z.string().optional(),
-                        fileBoundary: z.array(z.string()).optional(),
-                        reservedStops: z.array(z.string()).optional(),
-                        artifactPath: z.string().optional(),
-                        artifactSha256: z.string().optional(),
-                        revocationId: 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_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}` };
-                            },
-                        };
-                        // Generic (non-native) executions route through the atomic
-                        // transaction boundary: staged persist, then publish.
-                        const runIdArg = String(args.runId ?? "");
-                        const liveExecution = runIdArg
-                            ? sessionStore.getStoreData().executions.get(runIdArg)
-                            : undefined;
-                        const authorityAction = args.action === "authorize" ||
-                            args.action === "record_approval" ||
-                            args.action === "revoke_authority";
-                        const genericAction = args.action !== "register" &&
-                            liveExecution !== undefined &&
-                            (liveExecution.source.kind !== "native-package" || authorityAction);
-                        const nativeAuthorityRecover = args.action === "recover" &&
-                            args.authorityId !== undefined &&
-                            liveExecution !== undefined;
-                        const genericRegister = args.action === "register" && !args.planPath;
-                        if (genericAction || genericRegister || nativeAuthorityRecover) {
-                            const result = await commitGenericToolResult(context.sessionID, (view) => workCheckpointTool.execute(args, toolContext, view));
-                            return stringifyToolOutput(result);
+            work_item_decide: tool({
+                description: workItemDecideTool.description,
+                args: workItemDecideArgs,
+                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 validation = validateWorkflowToolInput("work_item_decide", args);
+                    if (!validation.ok) {
+                        return stringifyToolOutput(workflowInputFailure("work_item_decide", context.sessionID, validation.issues));
+                    }
+                    // Recovery is the only decision family that must persist
+                    // before it exposes new launch permissions. Authority-bearing
+                    // recovery stages the work-item recovery and the reserve debit in
+                    // one serialized transaction so they commit or fail together.
+                    // Routing uses the same validated/normalized values the handler consumes.
+                    const parsedDecide = validation.data;
+                    if (parsedDecide.decision === "recover") {
+                        if (parsedDecide.authorityId !== undefined) {
+                            const staged = await commitGenericToolResult(context.sessionID, "work_item_decide", (view) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, view));
+                            return stringifyToolOutput(staged, staged.ok === true ? "committed" : "not_applied");
                         }
-                        // Checkpoint recovery commits durably on the live store and
-                        // rolls the checkpoint entry back on write failure, so a
-                        // granted generation is never exposed before its state is
-                        // durably recorded.
-                        if (args.action === "recover") {
-                            const runId = String(args.runId ?? "");
-                            const checkpointId = String(args.checkpointId ?? "");
-                            const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workCheckpointTool.execute(args, toolContext, liveStore), () => captureCheckpointRestore(context.sessionID, runId, checkpointId), (result) => result.ok === true);
-                            return stringifyToolOutput(recovered);
+                        const workItemId = parsedDecide.workItemId.trim();
+                        const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, liveStore), () => captureRecordRestore(context.sessionID, workItemId), (result) => result.ok === true);
+                        // executeCommittedRecovery returns a success only after a durable
+                        // write, and throws (rollback) if the write fails.
+                        return stringifyToolOutput(recovered, recovered.ok === true ? "committed" : "not_applied");
+                    }
+                    const decided = await 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}`);
                         }
-                        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(decided, decided.ok === true ? "committed" : "not_applied");
+                },
+            }),
+            work_checkpoint: tool({
+                description: workCheckpointTool.description,
+                args: workCheckpointArgs,
+                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 validation = validateWorkflowToolInput("work_checkpoint", args);
+                    if (!validation.ok) {
+                        return stringifyToolOutput(workflowInputFailure("work_checkpoint", context.sessionID, validation.issues));
+                    }
+                    const parsedArgs = validation.data;
+                    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}` };
+                        },
+                    };
+                    // Generic (non-native) executions route through the atomic
+                    // transaction boundary: staged persist, then publish. Routing uses
+                    // the same trimmed runId the handler looks up, not a raw caller
+                    // field that could select a different persistence path.
+                    const runIdArg = parsedArgs.runId?.trim() ?? "";
+                    const liveExecution = runIdArg
+                        ? sessionStore.getStoreData().executions.get(runIdArg)
+                        : undefined;
+                    const authorityAction = parsedArgs.action === "authorize" ||
+                        parsedArgs.action === "record_approval" ||
+                        parsedArgs.action === "revoke_authority";
+                    const genericAction = parsedArgs.action !== "register" &&
+                        liveExecution !== undefined &&
+                        (liveExecution.source.kind !== "native-package" || authorityAction);
+                    const nativeAuthorityRecover = parsedArgs.action === "recover" &&
+                        parsedArgs.authorityId !== undefined &&
+                        liveExecution !== undefined;
+                    const genericRegister = parsedArgs.action === "register" && parsedArgs.planPath === undefined;
+                    if (genericAction || genericRegister || nativeAuthorityRecover) {
+                        const result = await commitGenericToolResult(context.sessionID, "work_checkpoint", (view) => workCheckpointTool.execute(args, toolContext, view));
+                        return stringifyToolOutput(result, result.ok === true ? "committed" : "not_applied");
+                    }
+                    // Checkpoint recovery commits durably on the live store and
+                    // rolls the checkpoint entry back on write failure, so a
+                    // granted generation is never exposed before its state is
+                    // durably recorded.
+                    if (parsedArgs.action === "recover") {
+                        const runId = parsedArgs.runId ?? "";
+                        const checkpointId = parsedArgs.checkpointId ?? "";
+                        const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workCheckpointTool.execute(args, toolContext, liveStore), () => captureCheckpointRestore(context.sessionID, runId, checkpointId), (result) => result.ok === true);
+                        return stringifyToolOutput(recovered, recovered.ok === true ? "committed" : "not_applied");
+                    }
+                    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);
-                    },
-                }),
-            },
+                    }
+                    return stringifyToolOutput(result, result.ok === true ? "committed" : "not_applied");
+                },
+            }),
         },
+        "tool.definition": toolDefinitionAdapter,
         "tool.execute.before": async (input, output) => {
+            // Owned workflow tools get strict structural plus branch validation on
+            // the raw forwarded arguments before their handlers run. This runs before
+            // the non-task early return and never mutates output.args.
+            if (isWorkflowToolId(input.tool)) {
+                const validation = validateWorkflowToolInput(input.tool, output.args);
+                if (!validation.ok) {
+                    throw new ContractInputError(input.tool, validation.issues);
+                }
+                return;
+            }
             if (input.tool !== "task") {
                 return;
             }
@@ -1248,6 +1001,9 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                 const planRunId = workItem.delegated?.planRunId;
                 if (planRunId) {
                     const run = data.planRuns.get(planRunId);
+                    if (run?.status === "sealed") {
+                        throw new Error(`LAUNCH_REJECTED_SEALED: run ${planRunId} is sealed and cannot launch ${workItem.workItemId}.`);
+                    }
                     const binding = run
                         ? [...run.tasks.values()].find((task) => task.workItemId === workItem.workItemId)
                         : undefined;
@@ -1489,12 +1245,18 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                     ? [
                         `Report rejected: attempt ${settledAttempt} of ${header.value} settled as report_rejected with bounded diagnostics retained.`,
                         (() => {
-                            const settledRecord = getWorkItem(getOrCreateStore(input.sessionID), input.sessionID, header.value);
-                            const progress = settledRecord
-                                ? summarizeDelegatedProgress(settledRecord)
+                            const store = getOrCreateStore(input.sessionID);
+                            const settledRecord = getWorkItem(store, input.sessionID, header.value);
+                            const guidance = settledRecord
+                                ? deriveDelegatedGuidance({
+                                    record: settledRecord,
+                                    progress: summarizeDelegatedProgress(settledRecord),
+                                    latest: latestAttemptView(settledRecord),
+                                    context: { data: store.getStoreData(), sessionId: input.sessionID },
+                                })
                                 : undefined;
-                            return `Next action: ${progress?.nextAction ?? "inspect work_item_list"}${progress?.nextAction === "recover" ||
-                                progress?.nextAction === "recover_with_user_authorization"
+                            return `Next action: ${guidance?.nextAction ?? "inspect work_item_list"}${guidance?.nextAction === "recover" ||
+                                guidance?.nextAction === "recover_with_user_authorization"
                                 ? ' through work_item_decide decision "recover"'
                                 : ""}.`;
                         })(),