@osovv/vv-opencode 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 1.7.0 (2026-09-25)
+
+### Summary
+
+Version 1.7.0 refines the correctness and evidence discipline carried by vvoc-managed agent prompts and the universal guidance injected into primary sessions. Agents now keep an evidence-supported conclusion settled until a concrete trigger reopens it — contradictory evidence, a specific counterexample, a changed requirement, or changed relevant inputs — rather than flipping on vague doubt or unsupported pressure, and they surface false premises and investigate the actual mechanism instead of silently substituting a different goal or adding an unnecessary dependency. Test results are treated as evidence against the request and established contracts rather than as the authoritative specification, so a failing test that contradicts the agreed contract is reported rather than triggering automatic rewrites of code or tests, and conflicting or mutually exclusive reviewer findings are routed back to the controller instead of quietly redefining requirements. This matters because it keeps agent work anchored to the task contract and observed evidence, reduces churn and unrequested changes, and makes disagreements and unmet checks visible to users. In addition, the release tooling now defaults release changelog summary generation to the deepseek/deepseek-flash model, restoring reliable release summaries after the previous default began returning server errors.
+
+* feat(prompts): refine evidence-based revision discipline ([4534b81](https://github.com/osovv/vv-opencode/commit/4534b81))
+* fix(release): default release summary model to deepseek/deepseek-flash ([995656e](https://github.com/osovv/vv-opencode/commit/995656e))
+
+## 1.6.0 (2026-09-24)
+
+### Summary
+
+Version 1.6.0 strengthens the public contract of all nine vvoc-owned agent tools so agents can call them reliably without reverse-engineering installed code. Every tool now publishes a closed input schema and rejects invalid or contradictory arguments before it mutates state, edits a file, or dispatches a provider request: unknown keys are refused instead of silently stripped, and a supplied value that conflicts with the chosen action or decision is diagnosed rather than ignored. Workflow failures now return machine-readable results with a stable error code and a category (input, state, authorization, host context, persistence, or internal) plus bounded, field-level issues, and outcomes stay truthful after side effects so a reporting failure is never misreported as a rejected call or an invitation to replay. `work_item_list` also gains read-only same-session inspection of work items and generic/native executions with the loaded package and contract identity, and a generated on-demand nine-tool reference ships with the vv-execute skill. Two new gates keep this honest: a read-only contracts check wired into `check` and `pack:check`, and an isolated live-host matrix exercised against the built package. Tool names, exports, schema v3, persistence v4, defaults, and authorization semantics are unchanged, so existing workflows keep working; the tightening only stops accepting calls whose constraints were previously dropped.
+
+* chore(grace): apply and archive C-AGENT-TOOL-CONTRACTS ([df24116](https://github.com/osovv/vv-opencode/commit/df24116))
+* feat(tools): enforce strict public contracts for all nine vvoc agent tools ([0831078](https://github.com/osovv/vv-opencode/commit/0831078))
+
 ## 1.5.0 (2026-09-22)
 
 ### Summary

package/README.md

@@ -169,7 +169,7 @@ grep '<COMPONENT-' .vvoc/specs/*/*.xml      # component map across spec and plan
 | **ModelRolesPlugin** | Semantic model roles (`vv-role:smart`, `vv-role:fast`, …) instead of hardcoded model IDs in agents, subagents, and commands — resolved per machine or project at startup. |
 | **GuardianPlugin** | Keeps long or AFK runs moving by auto-approving routine low-risk permission requests; anything risky stays in OpenCode's normal manual approval flow. |
 | **HashlineEditPlugin** | Routes each model to exactly one native edit tool (host `edit` for GLM/Qwen/Kimi, host `apply_patch` for GPT, `str_replace_editor` for DeepSeek, `hashline_edit` for unmatched models) and hides the other edit tools per session. |
-| **SystemContextInjectionPlugin** | Injects universal guidance — including correctness obligations for behavior changes — plus the work policy selected by the orchestration profile into vv-controller at startup, and registers skill discovery; subagents stay unpolluted. |
+| **SystemContextInjectionPlugin** | Injects universal guidance — including correctness obligations and evidence discipline for behavior changes — plus the work policy selected by the orchestration profile into vv-controller at startup, and registers skill discovery; subagents stay unpolluted. |
 | **SecretsRedactionPlugin** | Redacts tokens, keys, emails, and other sensitive values before messages reach the model, restoring them only where local execution needs the originals. |
 | **WebToolsPlugin** | Two provider-neutral tools — `web_search` and `web_fetch` — over Exa, Brave, Z.AI, native retrieval, or Spider, with permission checks and normalized output. |
 | **ToolHistoryCompactionPlugin** | Shrinks the context replayed to the model by compacting old tool outputs non-destructively, without touching on-disk history. |
@@ -192,7 +192,7 @@ All prompt files are scaffolded by `vvoc install` / `vvoc sync`:
 | `investigator` | Finds the root cause first when behavior is unclear or a failure needs diagnosis |
 | `guardian` | Supports GuardianPlugin by reviewing permission requests and auto-approving only routine low-risk ones |
 
-Managed prompts and the universal guidance injected into primary sessions carry explicit correctness obligations. For behavior changes, agents derive the material properties that must be preserved from the request and established contracts, separate write scope from impact and verification scope, investigate directly affected consumers, challenge a material assumption with a diagnostic counterexample, and choose verification at the level the risk arises. Controllers tie completion claims to observed evidence rather than status markers; reviewers distinguish no discovered defect from sufficient support for a material claim and can fail a change for a material verification gap. These obligations are prompt-level guidance only: `vvoc install` / `vvoc sync` deliver the current wording, changes take effect after an OpenCode restart like all vvoc config changes, and the bundled contract tests check instruction delivery and wording — they do not evaluate or guarantee how a real model behaves.
+Managed prompts and the universal guidance injected into primary sessions carry explicit correctness obligations. For behavior changes, agents derive the material properties that must be preserved from the request and established contracts, separate write scope from impact and verification scope, investigate directly affected consumers, challenge a material assumption with a diagnostic counterexample, and choose verification at the level the risk arises. Controllers tie completion claims to observed evidence rather than status markers; reviewers distinguish no discovered defect from sufficient support for a material claim and can fail a change for a material verification gap. Agents also keep evidence-supported conclusions settled until a concrete trigger — contradictory evidence, a specific counterexample, a changed requirement, or changed inputs — reopens them; they surface false premises instead of silently satisfying them, distinguish unsupported pressure from concrete evidence, and interpret test results as evidence against the request and contracts rather than as the specification. These obligations are prompt-level guidance only: `vvoc install` / `vvoc sync` deliver the current wording, changes take effect after an OpenCode restart like all vvoc config changes, and the bundled contract tests check instruction delivery and wording — they do not evaluate or guarantee how a real model behaves.
 
 ### Managed skills
 
@@ -461,7 +461,7 @@ For review-only reports, use `"mode": "review_only"`. In review-only mode, revie
 
 #### Delegated execution and review checkpoints
 
-Under the `delegated` profile the workflow plugin also registers two control tools — `work_item_decide` and `work_checkpoint` — for the primary vv-controller session only (child sessions, untrusted workspaces, and unverifiable session identity are denied).
+The workflow plugin registers two control tools — `work_item_decide` and `work_checkpoint` — for the primary vv-controller session independent of the startup profile. Registration is profile-independent; enforcement is not: child sessions, untrusted workspaces, and unverifiable session identity are denied by the root-controller guard.
 
 Delegated tasks are opened with `"mode": "delegated"`, an explicitly empty `requiredReviewers` array, and a declared `writeScope` of workspace-relative files. One worker (`vv-implementer`) is launched per task with a bounded packet; attempts are bound to the host call identity, so stale or duplicate callbacks fail without side effects. A `DONE` worker parks the item in `awaiting_acceptance` — it never closes the item and the worker never accepts its own result. The controller explicitly decides with `work_item_decide`:
 
@@ -482,14 +482,14 @@ When a tracked subagent returns a recognized task envelope whose inner result is
 
 Independent review happens at checkpoints declared in the plan. An approved delegated plan carries an `<execution><mode>delegated</mode>` section with `<review_checkpoints>` (`CHECKPOINT-R-NNN` identities, each with kind, wave barrier, covered tasks, reviewed scope files, reviewer set, acceptance criteria, and verification commands) and per-task `<write_scope>` lists. Registration accepts only this supported approved native plan package (the approved spec and plan pair under `.vvoc/specs/`); a provided plan or conversation-scoped execution stays on its own source and lifecycle rather than being converted into a native package. `work_checkpoint` handles these actions:
 
-- `register` — with `planPath`, loads an approved active plan plus its linked approved spec, fully lints them, and binds the run to their content hashes and the canonical workspace root. With a generic `runId` instead, it appends checkpoints to that execution. Re-registering identical inputs is idempotent; changed approved inputs are explicit plan drift, never a progress reset.
+- `register` — with `planPath`, loads an approved active plan plus its linked approved spec, fully lints them, and binds the run to their content hashes and the canonical workspace root. With a generic `runId` and its required `amendmentId` plus `rationale` instead, it appends a validated task batch (tasks and checkpoints) to that existing execution; it never starts a fresh run. Re-registering identical inputs is idempotent; changed approved inputs are explicit plan drift, never a progress reset.
 - `start` — after every covered task is accepted, captures a fingerprint over the checkpoint scope (native scope files and existence, or the generic accepted-attempt coverage) and opens exactly the declared reviewer set as an ordinary `review_only` item. Writes overlapping an in-flight checkpoint scope are refused.
 - `verify` — for native runs, derives `passed`, `failed`, `stale`, or `stopped` from the recorded reviewer results plus freshly recomputed fingerprints and approval hashes. A checkpoint passes only when every declared reviewer passes for the pinned snapshot; a closed review-only `FAIL` report is findings, not approval; edits during review make the generation stale. The final checkpoint seals the run only via `verify` with `complete: true` after every task is accepted, every earlier checkpoint passed, and the complete declared write scope is covered with fresh verification. Completion is refused while a declared reviewer is missing: a skipped reviewer is never fabricated into a pass.
-- `review` / `bind` — record one generic reviewer result (optionally binding a reviewer call identity) and settle the generation when every declared reviewer reported.
+- `review` / `bind` — `review` records one generic reviewer result; `bind` is the outcome-recording alias that settles the generation from the linked review item's recorded result when every declared reviewer reported. The callID launch binding itself is a host hook, not this tool action.
 - `complete` — complete a generic execution when every active task is accepted and every assigned checkpoint passed for the current revision, reporting `controller_accepted` or `independently_reviewed` honestly.
 - `amend` — append validated tasks or checkpoints to a generic execution without replaying accepted work.
 - `authorize` / `record_approval` / `revoke_authority` — record a bounded advance authority from an eligible root-user instruction, record a truthful controller-delegated stage approval, or revoke/narrow future authority credits.
-- `recover` — bounded recovery for a checkpoint generation that stopped (`NEEDS_CONTEXT`) or exhausted its ordinary generations. Recovery takes the same `diagnosis`, `changedCondition`, `verification`, `recoveryId`, and optional `userMessageId` fields as task recovery, with the same one-unit autonomous-then-authorized policy per checkpoint; a generic exhausted checkpoint recovers under a recorded advance authority referenced by `runId` and `authorityId`. Recovering a stopped generation settles it into history as a `stopped` entry — it does not convert the stop into a failure, so checkpoint rework stays locked until a real failed generation exists — and recovering an exhausted checkpoint grants exactly one further generation with a fresh snapshot at the next `start`. Recovery never satisfies prerequisites, erases a `FAIL`, or seals a run: only the required passing final review does.
+- `recover` — bounded recovery for a checkpoint generation that stopped (`NEEDS_CONTEXT`) or exhausted its ordinary generations. Common required fields are `diagnosis`, `changedCondition`, `verification`, and `recoveryId`. For a native-package checkpoint, recovery supports `userMessageId`: a stopped generation resumes, and an exhausted generation follows the one-unit autonomous-then-authorized policy (a fresh root-user message, or a recorded advance). For a generic checkpoint, `userMessageId` is rejected: a stopped generation is a cost-free bounded resume with no automatic budget reset, and only an *exhausted* generic checkpoint needs a recorded advance authority referenced by `runId` and `authorityId` — a stopped generic checkpoint does not require one. Recovering a stopped generation settles it into history as a `stopped` entry — it does not convert the stop into a failure, so checkpoint rework stays locked until a real failed generation exists — and recovering an exhausted checkpoint grants exactly one further generation with a fresh snapshot at the next `start`. Recovery never satisfies prerequisites, erases a `FAIL`, or seals a run: only the required passing final review does.
 
 Passed milestones stay historical: later planned edits are covered by later checkpoints or the final gate, not by an old approval. Hard stops (`BLOCKED`, `NEEDS_CONTEXT`) are never reset or bypassed by acceptance or checkpoint handling; only a separately recorded recovery decision resumes the affected work. Checkpoint state persists per session and survives restarts; a persisted `PASS` is not fresh evidence until `verify` recomputes current hashes.
 
@@ -499,6 +499,26 @@ Delegated and checkpoint state persists under `$XDG_DATA_HOME/vvoc/workflow/<ses
 
 Plans without an `<execution>` section keep their legacy meaning; executing them with different acceptance or review obligations requires an explicit agreed plan amendment, and archived plans are never rewritten. In a deterministic dispatch-count scenario, a twenty-task plan with two intermediate code-review checkpoints and one final spec+code checkpoint needs exactly four initial reviewer launches instead of forty — that is a property of the declared checkpoint policy, not a wall-clock or model-quality benchmark.
 
+#### Public tool contracts and strict input
+
+The nine vvoc-owned tools keep their existing names: `work_item_open`, `work_item_list`, `work_item_close`, `work_item_decide`, `work_checkpoint`, `hashline_edit`, `str_replace_editor`, `web_search`, and `web_fetch`. Every one now publishes a closed public input contract and rejects invalid or contradictory calls before it mutates state, edits a file, or dispatches a provider request.
+
+This is an intentional compatibility tightening: unknown keys in a vvoc-controlled request object are rejected before mutation instead of being stripped, and a supplied value that conflicts with the selected operation or action is diagnosed instead of being silently ignored. A misspelled authority stage or reserved stop, alone or mixed with valid entries, rejects the entire authority operation — it is never filtered down to the valid subset — and cannot create an authority, claim an authorization message, consume reserve, or grant a launch. Missing optional fields keep their documented defaults; only *invalid supplied* fields are refused. Tool names, package exports, canonical vvoc config schema v3, and persistence snapshot version 4 are unchanged, no config or persistence migration is introduced, and runtime plugin changes still take effect only after an OpenCode restart.
+
+The five workflow tools (`work_item_open`, `work_item_list`, `work_item_close`, `work_item_decide`, `work_checkpoint`) return workflow failures as machine-readable JSON carrying a stable `errorCode` plus a `category` — one of `input`, `state`, `authorization`, `host_context`, `persistence`, or `internal` — and bounded `issues` with tokenized argument paths, the violated expectation, and a safe value/type summary. The edit tools keep their existing human-readable `text`/`Error` result surface plus apply warnings rather than a JSON envelope, and the web tools keep their `ToolResult` text/metadata/attachment delivery. Web structural validation throws the bounded `ContractInputError`; provider failures keep the existing `WebProviderError` behavior (a provider-named code and message with no universal bounded-payload or JSON-shape promise). All nine share the same bounded field-level structural diagnostics, but the host is not promised to expose an output schema for any tool and edit/web output is not forced into JSON; the workflow JSON result shapes are a producer/test contract, not an assumed model-visible SDK feature. Owned structural and workflow diagnostics never echo a full payload and never parse free-form message prose to recover a lost field path; edit text and web document or binary content stay opaque. In particular:
+
+- Invalid `execution.source.kind` is reported as an input error, not as a missing workspace root; a failed generic lookup is not disguised as a missing native-only argument.
+- The generic execution descriptor accepts only `conversation-scoped` or a provided-plan variant carrying its bounded reference. The native-package path is not reachable through that descriptor: it loads only through the approved native `planPath` loader, with spec linkage, lint, and content-hash binding preserved.
+- Standalone `implementation`/`review_only` items require a non-empty unique reviewer set and reject delegated write scopes or native plan bindings. Standalone `delegated` items require an empty reviewer set, an exact-file `writeScope`, and paired optional native bindings. Generic tasks accept an explicit empty or non-empty reviewer set and default `taskId` from `key` and `goal` from `title`.
+
+Path contracts are explicit. `writeScope` entries are exact workspace-relative files and reject wildcards, absolute/home/drive paths, backslashes, traversal, empty segments, and a trailing separator; `boundary.directories` keeps its established one-trailing-separator directory-subtree normalization, so an exact file and a directory subtree are never conflated.
+
+`work_item_list` is read-only over the current session and additively exposes generic and native executions alongside the existing `items` and `planRuns`, with the latest attempt status, current generations, remaining allowances, assigned obligations, and bounded prerequisites. The same response carries the loaded contract identity (`packageName`, `packageVersion`, `toolContractRevision`, and `referencePath`) so an agent can discover the exact reference material shipped with the running release; `toolContractRevision` is the loaded `AGENT_TOOL_CONTRACT_REVISION`. Guidance is snapshotted from the same eligibility gates the mutations use: it is a statement about current state, not a future permission, and it never promises a launch will still be available after concurrent state changes. Inspecting state or describing a recovery path neither grants recovery nor consumes a unit.
+
+For a workflow mutation whose outcome is genuinely unknown — for example a post-side-effect reporting failure — the response never claims the change was untouched, never labels it a pre-execution input rejection, and never invites a blind replay; the truthful `committed`/`not_applied`/`rolled_back`/`unknown` outcome is preserved in the workflow result and the safe next step is to inspect with `work_item_list` before retrying. This workflow envelope is not forced onto the edit and web tools, which keep their own text/`Error` or `ToolResult` delivery.
+
+The full nine-tool contract lives in `templates/skills/vv-execute/references/tool-contracts.md`. It is generated from the pure catalog (`bun run contracts:generate`), shipped with the skill, and kept honest by a coverage gate; it is loaded on demand from the shipped file, not generated when you read it. It is deliberately on-demand documentation rather than a manual injected on every turn, so load the section you need. A declared `writeScope` is an edit boundary, not a universal filesystem sandbox, and nothing here claims that free-form evidence strings mechanically prove a claim or that stricter schemas reduce model errors.
+
 ### Edit format routing
 
 `HashlineEditPlugin` resolves an edit mode per session model and exposes exactly one native edit tool to that model — either a host-owned tool or one of the plugin profiles:
@@ -526,6 +546,8 @@ The default routing table sends `deepseek` to `str_replace_editor`, `kimi`, `qwe
 
 Routing changes require an OpenCode restart, like other runtime plugin settings.
 
+`hashline_edit` and `str_replace_editor` publish closed input contracts and reject conflicting or malformed fields before touching a file, without changing literal edit behavior: `replace` keeps its optional inclusive `end` (the `replace_range` alias still works), `lines` accepts a string, a string array, or `null` (an empty array or `null` deletes the range), `append`/`prepend` perform boundary insertion, `new_str` may be intentionally empty to delete, and `view_range` may end at `-1` to view to end of file. Supplying conflicting anchors, an unknown field, or a malformed range is a structural error that leaves file content, paths, freshness metadata, and the metadata sink unchanged, and the existing current-file and stale-anchor checks stay authoritative before any mutation.
+
 ### Tool history compaction
 
 `ToolHistoryCompactionPlugin` shrinks the context replayed to the model on every turn without touching on-disk storage. It rewrites only the in-memory message copy through the `experimental.chat.messages.transform` hook, and only the `output` of old completed tool parts — `input` and part structure (callID/type/order) are never changed, so provider tool_use/tool_result stitching stays intact.
@@ -663,6 +685,8 @@ The `web-tools` vvoc plugin toggle is enabled by default. Provider selection bel
 
 Supported search providers are `exa` (default), `brave`, and `zai`. Supported fetch providers are `native` (default, no credential required), `spider`, and `zai`. A `zai` section must set `region` to either `international` or `china`; the plugin never guesses or falls back to another region.
 
+Both tools validate a closed caller contract before any provider dispatch. `web_search` accepts `query`, an optional `count` (1–20), and an optional `freshness`; `web_fetch` accepts a URL, an optional `format`, and an optional `timeout` in seconds greater than 0 and at most 120 (fractional values such as `0.5` are allowed). Unknown keys, an invalid URL scheme or shape, or an out-of-range provided value are rejected before the permission prompt or any provider request, so no provider is dispatched and no network call is made. Provider credentials are resolved from configuration once at startup as described below; structural validation only prevents the permission prompt, provider dispatch, and network use, and does not re-resolve or override that startup resolution. Document text, binary/media content, and per-call provider or credential selection are never part of the caller contract. Defaults are applied at execution time even when OpenCode forwards raw, unparsed arguments, so the effective behavior is unchanged: an omitted `count` is 8, an omitted `format` is `markdown`, and an omitted `timeout` is 30 seconds (bounded at 120). Provider and credential configuration is still resolved once at startup from `vvoc.json`; changing it takes effect only after restarting OpenCode through the same `vvoc sync` and restart flow as before.
+
 Direct Z.AI endpoint routing:
 
 | Region | Search | Reader | Search engine |
@@ -706,12 +730,19 @@ The `context` vvoc plugin toggle defaults to enabled. Disable it with `vvoc plug
 ## Local development
 
 ```bash
-bun install             # Install dependencies
-bun run check           # Typecheck + lint + format check + GRACE markup check + test
-bun run fmt             # Auto-format source files
-bun run release:check   # Verify package/schema release consistency
+bun install                  # Install dependencies
+bun run check                # Typecheck + lint + format check + GRACE markup + tool-contract check + test
+bun run fmt                  # Auto-format source files
+bun run contracts:check      # Read-only nine-tool contract completeness gate
+bun run contracts:generate   # Regenerate the on-demand tool-contracts reference
+bun run contracts:host       # Isolated live-host contract gate (see below)
+bun run release:check        # Verify package/schema release consistency
 ```
 
+`bun run contracts:check` is a repository-only, read-only gate: it censuses owned tool registrations independently of the catalog, executes every catalog fixture through the real validators and result schemas, and fails on a fake tool, a missing fixture or result variant, an opaque known object, a changed default, or a stale generated reference. It is part of `bun run check` and requires no network or host process. Run `bun run contracts:generate` only as a deliberate, reviewed step when a contract change is intended — the generated file is checked for currency, so editing it by hand fails the gate.
+
+`bun run contracts:host` proves the same contract against the real host. It requires a locally installed `opencode` at the pinned live version (1.18.32 recorded by the current evidence), a current `bun run build` (it exercises the built `dist/` plugins), and the existing evidence target directory `.grace/changes/active/C-AGENT-TOOL-CONTRACTS/`. The runner only checks that this directory exists: it does not validate the GRACE approval state and it does not accept an arbitrary active bundle. It never creates or recreates the directory, never writes into an archive, and never finalizes lifecycle state — approval and lifecycle are owned by the GRACE controller. It creates disposable HOME/XDG/config/workspace directories, uses only local built plugin URLs, synthetic agents/messages/credentials, and loopback OpenAI-compatible and Anthropic-compatible responders, and it sends no real provider or paid request. `bun scripts/check-tool-contracts-host.ts --probe` runs the minimal host-seam feasibility test, while the default full run executes the nine-tool matrix and writes `compatibility-evidence.json` only on a full observed pass; a missing executable, an unsupported host version, or any failed scenario exits nonzero instead of recording a skipped success. The generated evidence is one of three distinct levels and never stands in for the separately executed SDK-floor/normalizer unit fixtures (the pinned 1.18.2 projection plus OpenAI/Anthropic/Google lowering fixtures) or for real remote-provider acceptance and model quality.
+
 Git hooks are managed via `lefthook`.
 
 Smoke-test the built CLI against an isolated config home:

package/dist/lib/agent-tool-catalog.d.ts

@@ -0,0 +1,144 @@
+import type { ZodRawShape, ZodType } from "zod";
+import { type ContractIssue, type OwnedToolContract } from "./agent-tool-contract.js";
+/** One checked positive/negative input fixture with independent coverage metadata. */
+export interface CatalogOperation {
+    readonly id: string;
+    readonly label: string;
+    readonly expect: "accept" | "reject";
+    readonly input: Record<string, unknown>;
+    /** Vocabulary field path to value this operation positively covers. */
+    readonly covers?: Readonly<Record<string, string>>;
+    /** Independent negative-scenario tags (e.g. unknown_key, missing_required). */
+    readonly tags?: readonly string[];
+    /** State/host prerequisites the fixture does not itself establish. */
+    readonly prerequisites?: readonly string[];
+}
+/** A model-facing closed vocabulary for one discriminated input field. */
+export interface CatalogVocabulary {
+    readonly field: string;
+    readonly values: readonly string[];
+}
+/** An execute-time default applied by a tool schema. */
+export interface CatalogDefault {
+    readonly field: string;
+    readonly value: unknown;
+    readonly note: string;
+}
+/** Declared meaning and rules for one path argument. */
+export interface CatalogPathKind {
+    readonly field: string;
+    readonly kind: "exact-file" | "directory-subtree" | "absolute-file" | "url";
+    readonly rules: string;
+}
+/** One checked result-family fixture for a tool. */
+export interface CatalogResultVariant {
+    readonly id: string;
+    readonly label: string;
+    readonly fixture: unknown;
+}
+/** Representative failure diagnostic path/expectation. */
+export interface CatalogErrorExample {
+    readonly path: string;
+    readonly expectation: string;
+}
+/** Structural validation outcome exposed for fixture checks. */
+export interface CatalogValidationResult {
+    readonly ok: boolean;
+    readonly data?: unknown;
+    readonly issues?: readonly ContractIssue[];
+}
+/** Aggregated catalog entry for one owned tool. */
+export interface AgentToolCatalogEntry {
+    readonly toolId: string;
+    readonly summary: string;
+    readonly contract: OwnedToolContract<ZodRawShape>;
+    readonly validate: (raw: unknown) => CatalogValidationResult;
+    readonly resultSchema: ZodType;
+    readonly vocabularies: readonly CatalogVocabulary[];
+    readonly operations: readonly CatalogOperation[];
+    readonly defaults: readonly CatalogDefault[];
+    readonly prerequisites: readonly string[];
+    readonly conditionals: readonly string[];
+    readonly pathKinds: readonly CatalogPathKind[];
+    readonly results: readonly CatalogResultVariant[];
+    readonly errors: readonly CatalogErrorExample[];
+    readonly normalization: readonly string[];
+}
+/** Package-relative path of the generated reference document. */
+export declare const CONTRACT_REFERENCE_PACKAGE_PATH = "templates/skills/vv-execute/references/tool-contracts.md";
+/**
+ * Recorded pre-change contract-size baseline with provenance.
+ * Measured once from the clean starting commit; future checks compare against the
+ * catalog-derived current measurement rather than reading mutable git history.
+ */
+export declare const CONTRACT_SIZE_BASELINE: {
+    readonly provenance: {
+        readonly commit: "f4319f8";
+        readonly sdk: "@opencode-ai/plugin@1.18.2";
+        readonly method: "source-extraction";
+        readonly detail: "UTF-8 byte sizes measured at the clean starting commit f4319f8 by extracting each owned tool's model-facing description string and projecting its pre-change registered argument map with the pinned SDK (io:\"input\"). This is a declaration/projection size, not a provider-exact token count and not a model-quality or model-effectiveness claim.";
+        readonly procedure: "Reproduce the baseline: `git show f4319f8:<tool-source> | extract the model-facing description`, then project each pre-change registered argument map with @opencode-ai/plugin@1.18.2 via tool.schema.toJSONSchema(schema, { io: \"input\" }) and sum Buffer.byteLength(value, \"utf8\"). \"After\" is the catalog-derived `measureCatalogContractSize()` value printed below as \"Current model-facing size\"; compare it to this baseline. Numbers reported are exact UTF-8 byte counts, never estimated token counts.";
+    };
+    readonly before: {
+        readonly descriptionBytes: 8796;
+        readonly inputSchemaBytes: 6815;
+    };
+};
+/** The nine owned tool catalog entries in stable registration order. */
+export declare const agentToolCatalog: readonly AgentToolCatalogEntry[];
+/** Sorted tool ids covered by the catalog. */
+export declare const AGENT_TOOL_CATALOG_TOOL_IDS: readonly string[];
+/** Sorted tool ids covered by the catalog. */
+export declare function catalogToolIds(): string[];
+/** Current description/input-schema UTF-8 byte measurement derived from the catalog. */
+export declare function measureCatalogContractSize(entries?: readonly AgentToolCatalogEntry[]): {
+    descriptionBytes: number;
+    inputSchemaBytes: number;
+    totalBytes: number;
+};
+/**
+ * Run every catalog fixture through the actual exporting validator, and every
+ * result-family fixture through the actual result schema. This is the shared
+ * fixture gate used by both the catalog test and scripts/check-tool-contracts.ts.
+ */
+export declare function validateAgentToolCatalog(): {
+    ok: boolean;
+    failures: string[];
+    checked: number;
+};
+/** One ancestor union option that a fixture must also satisfy for a nested branch. */
+export interface ResultBranchAncestor {
+    readonly valuePath: readonly string[];
+    readonly schema: unknown;
+}
+/** One union branch location reachable from a result schema, with its fixture value path. */
+export interface ResultBranchLocation {
+    readonly path: string;
+    readonly valuePath: readonly string[];
+    readonly schema: unknown;
+    readonly ancestors: readonly ResultBranchAncestor[];
+}
+export declare function collectResultBranches(schema: unknown): ResultBranchLocation[];
+/** Result-schema union branches a single catalog entry's fixtures do not cover. */
+export declare function resultBranchGaps(entry: AgentToolCatalogEntry): string[];
+/** Result-schema union branches not covered by any catalog result fixture. */
+export declare function resultCoverageGaps(entries?: readonly AgentToolCatalogEntry[]): string[];
+/**
+ * Find arbitrary (non-closed) object or unconstrained nodes in a published input schema.
+ * A node is opaque when it accepts an arbitrary value: an object that does not close
+ * `additionalProperties` to false (including a missing `additionalProperties`), an empty
+ * or keyword-free schema, a `true` schema, or an unresolvable `$ref`. Known object
+ * properties, unions (`anyOf`/`oneOf`/`allOf`), array items, and resolvable local refs
+ * are visited. Genuine opaque input regions are not permitted for public inputs; there is
+ * no whole-tool exemption.
+ */
+export declare function findOpaqueInputObjects(schema: unknown, basePath?: string, root?: unknown, visiting?: ReadonlySet<string>): string[];
+/**
+ * Render the deterministic, on-demand tool-contracts reference from the catalog.
+ * No timestamps, absolute paths, or environment values are embedded, so the
+ * output is byte-stable and can be checked for currency by `bun run contracts:check`.
+ * Each checked example's outcome is derived from running the actual validator, so
+ * mislabeled metadata cannot be published as a passing example. `entries` is
+ * injectable so self-tests can validate an isolated catalog without the global one.
+ */
+export declare function renderToolContractsReference(entries?: readonly AgentToolCatalogEntry[]): string;