@osovv/vv-opencode 1.5.0 → 1.6.0

package/dist/lib/agent-tool-contract.js

@@ -0,0 +1,407 @@
+// FILE: src/lib/agent-tool-contract.ts
+// VERSION: 1.1.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Provide reusable cross-plugin agent-tool contract primitives: registered raw argument maps, strict full-object runtime schemas with output inference, bounded diagnostics, fail-closed definition/pre-execute/direct-execute guards, SDK-compatible result-envelope helpers, and loaded contract identity.
+//   SCOPE: Generic owned-tool contract descriptors and host-boundary adapters only. No catalog aggregation, no workflow/plugin runtime imports, no permission or state-eligibility decisions. Uses the pinned SDK tool.schema Zod instance; zod imports are type-only. Result-envelope validation is producer/test-only and never wraps post-side-effect execution.
+//   DEPENDS: [@opencode-ai/plugin, zod (types), src/lib/package.ts]
+//   LINKS: [M-AGENT-TOOL-CONTRACT]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   AGENT_TOOL_CONTRACT_REVISION - Public tool-contract revision string for loaded identity.
+//   PACKAGE_NAME - Re-exported canonical package name from package.ts.
+//   PACKAGE_VERSION - Re-exported cached package version from package.ts.
+//   resolveToolContractReferencePath - Package-relative path to the tool-contracts reference document.
+//   MAX_CONTRACT_ISSUES - Maximum structural issues retained per diagnostic.
+//   MAX_ISSUE_PATH_CHARS - Maximum rendered issue path length.
+//   MAX_ISSUE_MESSAGE_CHARS - Maximum rendered issue message length.
+//   MAX_ISSUE_VALUE_CHARS - Maximum safe scalar preview length.
+//   ContractIssueCode - Stable machine-readable structural issue codes.
+//   ContractIssue - Bounded, tokenized structural issue with safe value/type summary.
+//   escapePathSegment - Escape one issue path segment for safe tokenized rendering.
+//   formatIssuePath - Render a Zod path tuple as a bounded, control-safe token path.
+//   summarizeReceivedValue - Safe bounded scalar/container value summary.
+//   toContractIssues - Convert a ZodError into bounded tokenized contract issues (preserves union branch paths).
+//   formatContractIssues - Render issues as a bounded single-line explanation.
+//   ContractInputError - Pre-execution structural rejection with code, category, and issues.
+//   ContractHostCompatibilityError - Fail-closed host-context rejection for unsupported definition publication.
+//   OperationExample - Named accept/reject operation example metadata for a contract.
+//   OwnedToolResult - Object branch of the pinned SDK ToolResult (assignable through tool execute).
+//   OwnedToolAttachment - Pinned SDK ToolAttachment shape.
+//   ownedToolResult - Build an SDK-compatible structured tool result envelope.
+//   ownedToolAttachmentSchema - Strict attachment envelope schema for producer/test validation.
+//   ownedToolResultSchema - Strict result envelope schema; metadata/document content remain opaque.
+//   validateOwnedToolResult - Producer/test-only result envelope validation (no post-side-effect wrapper).
+//   strictObject - Build a closed object schema on the SDK tool.schema instance.
+//   contractInputJsonSchema - Input-mode JSON Schema projection for a contract schema.
+//   OwnedToolArgs - Schema-inferred argument type for an owned-tool registered map.
+//   OwnedToolContract - Registered raw map plus strict runtime schema and typed parse helpers.
+//   defineOwnedToolContract - Define a closed owned-tool contract from a raw argument map.
+//   parseOwnedToolArgs - Direct-execute parse returning schema-inferred output (defaults applied).
+//   ToolDefinitionHookOutput - Narrow structural view of the SDK tool.definition hook output.
+//   createToolDefinitionAdapter - Owned-only fail-closed tool.definition adapter publishing strict jsonSchema while preserving parameters identity.
+//   createPreExecuteGuard - Owned-only tool.execute.before structural guard that never mutates raw args.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [C-AGENT-TOOL-CONTRACTS - Correction cycle: fail-closed definition publication, Zod output inference end-to-end, SDK-compatible result envelope + producer validation schema, escaped diagnostic paths, and preserved nested union issue paths.]
+// END_CHANGE_SUMMARY
+import { tool } from "@opencode-ai/plugin";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./package.js";
+export { PACKAGE_NAME, PACKAGE_VERSION };
+// START_BLOCK_CONTRACT_IDENTITY
+/** Public tool-contract revision; independent of persistence and workflow contract versions. */
+export const AGENT_TOOL_CONTRACT_REVISION = "1";
+const TOOL_CONTRACT_REFERENCE_PACKAGE_PATH = "templates/skills/vv-execute/references/tool-contracts.md";
+/**
+ * Resolve the package-relative path to the shipped tool-contracts reference document.
+ * Uses the loaded module location, not global installs or user config.
+ */
+export function resolveToolContractReferencePath() {
+    const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+    return join(packageRoot, TOOL_CONTRACT_REFERENCE_PACKAGE_PATH);
+}
+// END_BLOCK_CONTRACT_IDENTITY
+// START_BLOCK_ISSUES
+/** Maximum number of structural issues retained in one diagnostic. */
+export const MAX_CONTRACT_ISSUES = 8;
+/** Maximum rendered path length in characters. */
+export const MAX_ISSUE_PATH_CHARS = 120;
+/** Maximum rendered message length in characters. */
+export const MAX_ISSUE_MESSAGE_CHARS = 200;
+/** Maximum safe scalar preview length in characters. */
+export const MAX_ISSUE_VALUE_CHARS = 48;
+function truncateChars(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+/**
+ * Escape one path segment so user-controlled keys cannot inject control characters
+ * or forge ambiguous dotted/bracketed paths.
+ */
+export function escapePathSegment(segment) {
+    let escaped = "";
+    for (const character of segment) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f) {
+            escaped += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else if (character === "\\" || character === "." || character === "[" || character === "]") {
+            escaped += `\\${character}`;
+        }
+        else {
+            escaped += character;
+        }
+    }
+    return escaped;
+}
+/** Render a Zod path tuple as a bounded dotted/bracketed token path with escaped segments. */
+export function formatIssuePath(path) {
+    let rendered = "";
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            rendered += `[${segment}]`;
+        }
+        else {
+            const token = escapePathSegment(typeof segment === "symbol" ? segment.toString() : segment);
+            rendered = rendered ? `${rendered}.${token}` : token;
+        }
+        if (rendered.length >= MAX_ISSUE_PATH_CHARS) {
+            return truncateChars(rendered, MAX_ISSUE_PATH_CHARS);
+        }
+    }
+    return rendered || "(root)";
+}
+/**
+ * Build a safe, bounded received-value summary.
+ * Scalars get a short preview; containers get a type name only — never a payload echo.
+ */
+export function summarizeReceivedValue(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "string") {
+        return truncateChars(JSON.stringify(value), MAX_ISSUE_VALUE_CHARS);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return truncateChars(String(value), MAX_ISSUE_VALUE_CHARS);
+    }
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "object")
+        return "object";
+    return truncateChars(String(value), MAX_ISSUE_VALUE_CHARS);
+}
+function issueCodeOf(code) {
+    switch (code) {
+        case "unrecognized_keys":
+        case "invalid_value":
+        case "invalid_type":
+        case "invalid_format":
+        case "too_small":
+        case "too_big":
+        case "missing_value":
+        case "invalid_union":
+        case "custom":
+            return code;
+        default:
+            return "custom";
+    }
+}
+function pushConcreteIssue(issues, raw, basePath) {
+    if (issues.length >= MAX_CONTRACT_ISSUES)
+        return;
+    const code = issueCodeOf(raw.code);
+    if (raw.code === "unrecognized_keys" && Array.isArray(raw.keys)) {
+        for (const key of raw.keys) {
+            if (issues.length >= MAX_CONTRACT_ISSUES)
+                break;
+            issues.push({
+                code: "unrecognized_keys",
+                path: formatIssuePath([...basePath, String(key)]),
+                message: truncateChars(`unrecognized key ${JSON.stringify(truncateChars(String(key), MAX_ISSUE_VALUE_CHARS))}`, MAX_ISSUE_MESSAGE_CHARS),
+                expected: "a known property of this request object",
+            });
+        }
+        return;
+    }
+    const expected = Array.isArray(raw.values) && raw.values.length > 0
+        ? truncateChars(raw.values.map((value) => summarizeReceivedValue(value)).join(" | "), MAX_ISSUE_MESSAGE_CHARS)
+        : raw.code === "invalid_type" && raw.expected !== undefined
+            ? truncateChars(String(raw.expected), MAX_ISSUE_MESSAGE_CHARS)
+            : undefined;
+    const received = raw.code === "invalid_type" && raw.received !== undefined
+        ? truncateChars(String(raw.received), MAX_ISSUE_VALUE_CHARS)
+        : undefined;
+    issues.push({
+        code,
+        path: formatIssuePath(basePath),
+        message: truncateChars(raw.message ?? "invalid value", MAX_ISSUE_MESSAGE_CHARS),
+        ...(expected !== undefined ? { expected } : {}),
+        ...(received !== undefined ? { received } : {}),
+    });
+}
+function pushIssueTree(issues, rawList, prefix) {
+    for (const raw of rawList) {
+        if (issues.length >= MAX_CONTRACT_ISSUES)
+            return;
+        const basePath = [...prefix, ...(raw.path ?? [])];
+        if (raw.code === "invalid_union" && Array.isArray(raw.errors) && raw.errors.length > 0) {
+            // Preserve nested union/discriminator branch paths (e.g. source.reference, source.kind).
+            for (const branch of raw.errors) {
+                pushIssueTree(issues, branch, basePath);
+                if (issues.length >= MAX_CONTRACT_ISSUES)
+                    return;
+            }
+            continue;
+        }
+        pushConcreteIssue(issues, raw, basePath);
+    }
+}
+/**
+ * Convert a ZodError into bounded tokenized contract issues.
+ * Unknown keys become precise leaf paths; union branch paths are preserved;
+ * values are summarized, not echoed wholesale.
+ */
+export function toContractIssues(error) {
+    const issues = [];
+    pushIssueTree(issues, error.issues, []);
+    return issues;
+}
+/** Render issues as one bounded single-line explanation suitable for host tool errors. */
+export function formatContractIssues(issues) {
+    if (issues.length === 0)
+        return "INVALID_INPUT: structural validation failed";
+    const parts = issues.map((issue) => {
+        const path = issue.path || "(root)";
+        const expected = issue.expected ? `; expected ${issue.expected}` : "";
+        const received = issue.received ? `; received ${issue.received}` : "";
+        return truncateChars(`${path}: ${issue.message}${expected}${received}`, MAX_ISSUE_MESSAGE_CHARS);
+    });
+    return truncateChars(`INVALID_INPUT: ${parts.join(" | ")}`, MAX_ISSUE_MESSAGE_CHARS * (MAX_CONTRACT_ISSUES + 1));
+}
+/** Pre-execution structural rejection for owned tools. Not a permission or state decision. */
+export class ContractInputError extends Error {
+    code = "INVALID_INPUT";
+    category = "input";
+    toolId;
+    issues;
+    constructor(toolId, issues) {
+        super(formatContractIssues(issues));
+        this.name = "ContractInputError";
+        this.toolId = toolId;
+        this.issues = issues;
+    }
+}
+/**
+ * Fail-closed host-context rejection when an owned tool cannot publish its contract
+ * through the host tool.definition seam. Never mutates the hook output before throwing.
+ */
+export class ContractHostCompatibilityError extends Error {
+    code = "HOST_CONTRACT_UNSUPPORTED";
+    category = "host_context";
+    toolId;
+    reason;
+    constructor(toolId, reason) {
+        super(truncateChars(`HOST_CONTRACT_UNSUPPORTED: tool=${escapePathSegment(toolId)}; ${reason}`, MAX_ISSUE_MESSAGE_CHARS));
+        this.name = "ContractHostCompatibilityError";
+        this.toolId = toolId;
+        this.reason = truncateChars(reason, MAX_ISSUE_MESSAGE_CHARS);
+    }
+}
+/**
+ * Build a structured tool result envelope compatible with the pinned SDK ToolResult.
+ * Empty output and empty metadata remain valid for consumers that need them.
+ */
+export function ownedToolResult(output, init) {
+    return {
+        ...(init?.title !== undefined ? { title: init.title } : {}),
+        output,
+        ...(init?.metadata !== undefined ? { metadata: init.metadata } : {}),
+        ...(init?.attachments !== undefined ? { attachments: init.attachments } : {}),
+    };
+}
+/** Closed object schema on the SDK tool.schema instance (rejects unknown keys). */
+export function strictObject(shape) {
+    return tool.schema.strictObject(shape);
+}
+/** Attachment envelope schema for producer/test validation of owned tool results. */
+export const ownedToolAttachmentSchema = strictObject({
+    type: tool.schema.literal("file"),
+    mime: tool.schema.string(),
+    url: tool.schema.string(),
+    filename: tool.schema.string().optional(),
+});
+/**
+ * Strict result-envelope schema for producer/test checks.
+ * `metadata` and nested document/binary content are declared opaque extension regions
+ * (record/unknown or declared opaque fields), not re-validated payload shapes.
+ * This is never applied as a throw-after-side-effect execute wrapper.
+ */
+export const ownedToolResultSchema = strictObject({
+    title: tool.schema.string().optional(),
+    output: tool.schema.string(),
+    metadata: tool.schema.record(tool.schema.string(), tool.schema.unknown()).optional(),
+    attachments: tool.schema.array(ownedToolAttachmentSchema).optional(),
+});
+/**
+ * Producer/test-only validation of a structured result envelope.
+ * Returns typed output on success; structural issues on failure.
+ * Do not call this after irreversible side effects as a gate that invites replay.
+ */
+export function validateOwnedToolResult(value) {
+    const result = ownedToolResultSchema.safeParse(value);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, issues: toContractIssues(result.error) };
+}
+/**
+ * Project a contract schema to its input-mode JSON Schema.
+ * Consistent with the host registry projection (io: "input", $defs → definitions).
+ */
+export function contractInputJsonSchema(schema) {
+    const projected = tool.schema.toJSONSchema(schema, { io: "input" });
+    if (typeof projected !== "object" || projected === null || Array.isArray(projected)) {
+        throw new Error("contract schema produced a non-object JSON Schema");
+    }
+    const record = projected;
+    const { $defs, ...rest } = record;
+    if (typeof $defs === "object" && $defs !== null && !Array.isArray($defs)) {
+        return { ...rest, definitions: $defs };
+    }
+    return rest;
+}
+/**
+ * Define an owned-tool contract from the same raw argument map used for SDK registration.
+ * The runtime schema is a strict full-object validator over that map; nested closedness
+ * comes from composing nested shapes with strictObject. Unknown keys are never coerced or filtered.
+ */
+export function defineOwnedToolContract(init) {
+    const runtimeSchema = strictObject(init.registeredArgs);
+    const inputJsonSchema = contractInputJsonSchema(runtimeSchema);
+    const examples = init.examples ?? [];
+    return {
+        toolId: init.toolId,
+        description: init.description,
+        registeredArgs: init.registeredArgs,
+        runtimeSchema,
+        inputJsonSchema,
+        examples,
+        safeParse(raw) {
+            const result = runtimeSchema.safeParse(raw);
+            if (result.success) {
+                return { success: true, data: result.data };
+            }
+            return { success: false, issues: toContractIssues(result.error) };
+        },
+        parse(raw) {
+            const result = runtimeSchema.safeParse(raw);
+            if (result.success)
+                return result.data;
+            throw new ContractInputError(init.toolId, toContractIssues(result.error));
+        },
+    };
+}
+/**
+ * Direct-execute validation: parse raw (host-forwarded) args through the contract schema,
+ * applying schema defaults/canonicalization for execute to consume.
+ * Returns the schema-inferred output type (defaults and enum literals preserved).
+ */
+export function parseOwnedToolArgs(contract, rawArgs) {
+    return contract.parse(rawArgs);
+}
+function isDefinitionHookOutput(value) {
+    return (typeof value === "object" && value !== null && "parameters" in value && "description" in value);
+}
+function hasJsonSchemaMember(value) {
+    return "jsonSchema" in value;
+}
+/**
+ * Owned-only tool.definition adapter (fail-closed).
+ * Publishes the strict input-mode jsonSchema through the host's observable jsonSchema member
+ * while preserving parameters identity (the host decoder is never replaced).
+ * For owned tool IDs, an unsupported host shape (malformed output or missing jsonSchema member)
+ * throws ContractHostCompatibilityError without mutating the output.
+ * Unowned tool IDs are left untouched.
+ */
+export function createToolDefinitionAdapter(contracts) {
+    const byId = new Map(contracts.map((contract) => [contract.toolId, contract]));
+    return async function toolDefinitionAdapter(input, output) {
+        const contract = byId.get(input.toolID);
+        if (!contract)
+            return;
+        if (!isDefinitionHookOutput(output)) {
+            throw new ContractHostCompatibilityError(contract.toolId, "malformed tool.definition output: missing required description/parameters members");
+        }
+        if (!hasJsonSchemaMember(output)) {
+            throw new ContractHostCompatibilityError(contract.toolId, "unsupported host tool.definition shape: missing jsonSchema member required for strict publication");
+        }
+        output.jsonSchema = contract.inputJsonSchema;
+    };
+}
+/**
+ * Owned-only pre-execute structural guard for tool.execute.before.
+ * Inspects raw args and throws ContractInputError on structural failure.
+ * Never mutates output.args and never confers state/permission eligibility.
+ */
+export function createPreExecuteGuard(contracts) {
+    const byId = new Map(contracts.map((contract) => [contract.toolId, contract]));
+    return async function preExecuteGuard(input, output) {
+        const contract = byId.get(input.tool);
+        if (!contract)
+            return;
+        const result = contract.runtimeSchema.safeParse(output.args);
+        if (!result.success) {
+            throw new ContractInputError(contract.toolId, toContractIssues(result.error));
+        }
+    };
+}
+// END_BLOCK_HOST_ADAPTERS
+//# sourceMappingURL=agent-tool-contract.js.map

package/dist/lib/agent-tool-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool-contract.js","sourceRoot":"","sources":["../../src/lib/agent-tool-contract.ts"],"names":[],"mappings":"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"}

package/dist/lib/workflow-contract.d.ts

@@ -2,6 +2,12 @@ export declare const WORKFLOW_CONTRACT_VERSION = 1;
 export declare const WORKFLOW_ID_MAX_CHARS = 128;
 export declare const WORKFLOW_TEXT_MAX_CHARS = 2000;
 export declare const WORKFLOW_TEXT_MAX_ITEMS = 64;
+/** Canonical work-item intent values accepted by work_item_open. */
+export declare const WORK_ITEM_MODES: readonly ["implementation", "review_only", "delegated"];
+/** Canonical independent reviewer roles accepted across workflow inputs. */
+export declare const REVIEWER_ROLES: readonly ["spec", "code"];
+/** Canonical delegatable lifecycle stages for advance authority. */
+export declare const AUTHORITY_STAGES: readonly ["specification", "planning", "implementation", "verification"];
 /** Normalized workspace-relative path, or the reason a declared path is malformed. */
 export type DeclaredScopePathResult = {
     ok: true;
@@ -225,6 +231,12 @@ export interface WorkflowMessageClaim {
 export interface WorkflowContractProblem {
     code: string;
     message: string;
+    /**
+     * Tokenized field/index path of the offending value when it applies to one
+     * element (e.g. ["boundary", "files", 0]); absent when the problem applies to
+     * the whole value rather than a single indexed element.
+     */
+    path?: readonly (string | number)[];
 }
 export type WorkflowContractValidation<T> = {
     ok: true;

package/dist/lib/workflow-contract.js

@@ -1,10 +1,10 @@
 // FILE: src/lib/workflow-contract.ts
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Dependency-free common execution contract for native-package, provided-plan, and conversation-scoped workflow runs: declared-path normalization, bounded task/checkpoint/boundary contracts, explicit reviewer sets, exact-reference DAG validation, lineage/revision records, and authority/stage provenance shapes.
-//   SCOPE: Pure path normalization, bounded identity/text validation, explicit reviewer-set normalization, execution boundary containment, task and checkpoint contract validation, exact reference and acyclic dependency checks, native definition adaptation into common contracts, and structural source/lineage/authority record types. No filesystem access, native XML parsing, SDK transport, task dispatch, or persistence.
+//   PURPOSE: Dependency-free common execution contract for native-package, provided-plan, and conversation-scoped workflow runs: canonical work-item/reviewer/authority enums, declared-path normalization, bounded task/checkpoint/boundary contracts, explicit reviewer sets, exact-reference DAG validation, lineage/revision records, and authority/stage provenance shapes.
+//   SCOPE: Pure path normalization, bounded identity/text validation, canonical enum constants shared by tool schemas and domain owners, explicit reviewer-set normalization, execution boundary containment (with boundary-reporting containment failures), task and checkpoint contract validation, exact reference and acyclic dependency checks, native definition adaptation into common contracts, and structural source/lineage/authority record types. No filesystem access, native XML parsing, SDK transport, task dispatch, or persistence.
 //   DEPENDS: [] (deliberately dependency-free so the native adapter and the generic runtime share one contract without a cycle)
-//   LINKS: [M-WORKFLOW-CONTRACT, M-SPEC-LINT, M-WORKFLOW-EXECUTION, M-WORKFLOW-AUTHORITY]
+//   LINKS: [M-WORKFLOW-CONTRACT, M-SPEC-LINT, M-WORKFLOW-EXECUTION, M-WORKFLOW-AUTHORITY, M-WORKFLOW-STATE, M-WORKFLOW-TOOLING]
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
 // END_MODULE_CONTRACT
@@ -14,6 +14,9 @@
 //   WORKFLOW_ID_MAX_CHARS - Maximum accepted workflow identity length.
 //   WORKFLOW_TEXT_MAX_CHARS - Maximum accepted bounded contract text length.
 //   WORKFLOW_TEXT_MAX_ITEMS - Maximum accepted list length inside one contract field.
+//   WORK_ITEM_MODES - Canonical work-item intent values accepted by work_item_open.
+//   REVIEWER_ROLES - Canonical independent reviewer roles accepted across workflow inputs.
+//   AUTHORITY_STAGES - Canonical delegatable lifecycle stages for advance authority.
 //   WorkflowReviewer - Canonical independent reviewer role.
 //   WorkflowObligationOrigin - Where a registered obligation came from (source, user, controller).
 //   DelegatedReviewer - Canonical delegated checkpoint reviewer roles (spec, code).
@@ -43,7 +46,7 @@
 //   WorkflowStageApproval - Recorded stage approval bound to an approved artifact hash.
 //   WorkflowReserveDebit - One consumed unit of the shared advance-recovery reserve.
 //   WorkflowMessageClaim - Session-wide claim that one root-user message already funded a grant.
-//   WorkflowContractProblem - One deterministic contract validation problem.
+//   WorkflowContractProblem - One deterministic contract validation problem, with an optional indexed path.
 //   WorkflowContractValidation - Validation result carrying a value or deterministic problems.
 //   isBoundedWorkflowId - Whether a value is a bounded explicit workflow identity.
 //   isPathInExecutionBoundary - Whether a normalized path is contained in an execution boundary.
@@ -56,13 +59,24 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-WORKFLOW-PLAN-INDEPENDENCE - Initial dependency-free common contract extracted from the native spec linter so provided-plan and conversation-scoped execution share one validated contract.]
+//   LAST_CHANGE: [C-AGENT-TOOL-CONTRACTS T-002 - Added canonical work-item mode, reviewer role, and authority stage enum constants for schema/domain reuse, made OUT_OF_BOUNDARY containment failures report the offending scope together with the applicable declared boundary, and gave boundary problems precise indexed paths with bounded value previews.]
 // END_CHANGE_SUMMARY
 // START_BLOCK_CONTRACT_CONSTANTS
 export const WORKFLOW_CONTRACT_VERSION = 1;
 export const WORKFLOW_ID_MAX_CHARS = 128;
 export const WORKFLOW_TEXT_MAX_CHARS = 2000;
 export const WORKFLOW_TEXT_MAX_ITEMS = 64;
+/** Canonical work-item intent values accepted by work_item_open. */
+export const WORK_ITEM_MODES = ["implementation", "review_only", "delegated"];
+/** Canonical independent reviewer roles accepted across workflow inputs. */
+export const REVIEWER_ROLES = ["spec", "code"];
+/** Canonical delegatable lifecycle stages for advance authority. */
+export const AUTHORITY_STAGES = [
+    "specification",
+    "planning",
+    "implementation",
+    "verification",
+];
 /**
  * Text-level canonical normalization for declared scope file paths. The linter
  * and the runtime snapshot fingerprint share this representation so a plan that
@@ -201,32 +215,52 @@ export function normalizeReviewerSet(value) {
 }
 // END_BLOCK_REVIEWER_NORMALIZATION
 // START_BLOCK_BOUNDARY_VALIDATION
-function normalizeUniquePaths(raw, field, normalize, problems) {
+/** Bounded preview of one offending value; never echoes an unbounded payload. */
+const DIAGNOSTIC_PREVIEW_MAX_CHARS = 64;
+function previewValue(value) {
+    const json = JSON.stringify(value);
+    const text = json === undefined ? String(value) : json;
+    return text.length <= DIAGNOSTIC_PREVIEW_MAX_CHARS
+        ? text
+        : `${text.slice(0, DIAGNOSTIC_PREVIEW_MAX_CHARS - 1)}…`;
+}
+function normalizeUniquePaths(raw, field, normalize, problems, pathBase = []) {
     if (raw === undefined || raw === null)
         return [];
     if (!Array.isArray(raw)) {
-        problems.push({ code: "INVALID_LIST", message: `${field} must be an array` });
+        problems.push({
+            code: "INVALID_LIST",
+            message: `${field} must be an array`,
+            path: [...pathBase],
+        });
         return [];
     }
     const seen = new Set();
     const out = [];
-    for (const entry of raw) {
+    for (let index = 0; index < raw.length; index += 1) {
+        const entry = raw[index];
         if (typeof entry !== "string") {
-            problems.push({ code: "INVALID_PATH", message: `${field} entries must be strings` });
+            problems.push({
+                code: "INVALID_PATH",
+                message: `${field} entries must be strings`,
+                path: [...pathBase, index],
+            });
             return [];
         }
         const normalized = normalize(entry);
         if (!normalized.ok) {
             problems.push({
                 code: "INVALID_PATH",
-                message: `${field} path ${JSON.stringify(entry)} is malformed (${normalized.reason})`,
+                message: `${field} path ${previewValue(entry)} is malformed (${normalized.reason})`,
+                path: [...pathBase, index],
             });
             return [];
         }
         if (seen.has(normalized.path)) {
             problems.push({
                 code: "DUPLICATE_PATH",
-                message: `${field} path ${JSON.stringify(normalized.path)} is declared more than once`,
+                message: `${field} path ${previewValue(normalized.path)} is declared more than once`,
+                path: [...pathBase, index],
             });
             return [];
         }
@@ -241,19 +275,29 @@ export function validateExecutionBoundary(raw) {
     if (raw === null || typeof raw !== "object") {
         return {
             ok: false,
-            problems: [{ code: "INVALID_BOUNDARY", message: "execution boundary must be an object" }],
+            problems: [
+                {
+                    code: "INVALID_BOUNDARY",
+                    message: "execution boundary must be an object",
+                    path: ["boundary"],
+                },
+            ],
         };
     }
     const candidate = raw;
-    const files = normalizeUniquePaths(candidate.files, "boundary.files", normalizeDeclaredScopePath, problems);
-    const directories = normalizeUniquePaths(candidate.directories, "boundary.directories", normalizeDeclaredDirectoryPath, problems);
+    const files = normalizeUniquePaths(candidate.files, "boundary.files", normalizeDeclaredScopePath, problems, ["boundary", "files"]);
+    const directories = normalizeUniquePaths(candidate.directories, "boundary.directories", normalizeDeclaredDirectoryPath, problems, ["boundary", "directories"]);
     if (problems.length > 0)
         return { ok: false, problems };
     if (files.length === 0 && directories.length === 0) {
         return {
             ok: false,
             problems: [
-                { code: "EMPTY_BOUNDARY", message: "execution boundary declares no files or directories" },
+                {
+                    code: "EMPTY_BOUNDARY",
+                    message: "execution boundary declares no files or directories",
+                    path: ["boundary"],
+                },
             ],
         };
     }
@@ -265,6 +309,15 @@ export function isPathInExecutionBoundary(path, boundary) {
         return true;
     return boundary.directories.some((directory) => path.startsWith(`${directory}/`));
 }
+/** Bounded one-line summary of a declared boundary for containment diagnostics. */
+function describeExecutionBoundary(boundary) {
+    const summarize = (entries) => entries.length <= 8
+        ? entries.join(", ")
+        : `${entries.slice(0, 8).join(", ")}, …(+${entries.length - 8})`;
+    const files = boundary.files.length > 0 ? summarize(boundary.files) : "(none)";
+    const directories = boundary.directories.length > 0 ? summarize(boundary.directories) : "(none)";
+    return `files: ${files}; directories: ${directories}`;
+}
 // END_BLOCK_BOUNDARY_VALIDATION
 // START_BLOCK_TASK_VALIDATION
 function normalizeBoundaryFiles(raw, field, problems, options) {
@@ -515,7 +568,7 @@ export function validateWorkflowContractGraph(graph) {
             if (!isPathInExecutionBoundary(path, graph.boundary)) {
                 problems.push({
                     code: "OUT_OF_BOUNDARY",
-                    message: `task ${task.taskId} writeScope ${JSON.stringify(path)} is outside the execution boundary`,
+                    message: `task ${task.taskId} writeScope ${JSON.stringify(path)} is outside the execution boundary (declared ${describeExecutionBoundary(graph.boundary)})`,
                 });
             }
         }
@@ -537,7 +590,7 @@ export function validateWorkflowContractGraph(graph) {
             if (!isPathInExecutionBoundary(path, graph.boundary)) {
                 problems.push({
                     code: "OUT_OF_BOUNDARY",
-                    message: `checkpoint ${checkpoint.checkpointId} scope ${JSON.stringify(path)} is outside the execution boundary`,
+                    message: `checkpoint ${checkpoint.checkpointId} scope ${JSON.stringify(path)} is outside the execution boundary (declared ${describeExecutionBoundary(graph.boundary)})`,
                 });
             }
         }