Understanding the Tool Contract Schema in DeepSeek Reasonix for Regression Review

The tool contract schema in Reasonix is a compile-time specification that defines every built-in tool's interface, validation rules, and safety constraints, enforcing mandatory regression reviews through the review_report tool before high-risk mutations can be committed.

The tool contract schema in DeepSeek Reasonix provides a machine-readable interface definition for all built-in tools available to the model. This schema ensures that every tool call adheres to strict validation rules and safety constraints, particularly when handling destructive operations that require regression review. By codifying tool capabilities in docs/TOOL_CONTRACT.md and enforcing validation through internal/evidence/review_report.go, Reasonix creates an auditable execution pipeline that prevents unreviewed changes from reaching completion.

What Is the Tool Contract Schema?

The tool contract schema describes every built-in tool available to the model at compile-time. According to the DeepSeek-Reasonix source code, each tool entry in the contract specifies four critical fields:

• Tool name: The identifier used in tool calls (e.g., bash, read_file, review_report).
• Read-only flag: A boolean indicating whether the tool only reads data (true) or mutates the workspace (false).
• Description: A human-readable purpose string explaining the tool's function.
• Canonical JSON schema: The exact JSON Schema generated by tool.BuiltinContractEntries that validates the arguments a tool may receive.

The complete schema snapshot is documented in docs/TOOL_CONTRACT.md, which serves as the human-readable reference for all registered tools. The test TestBuiltinToolContractDocumentation in internal/tool/registry_canon_test.go guarantees that every registered tool has a documented entry and a matching canonical schema, ensuring the documentation remains synchronized with the implementation.

How the Contract Enables Regression Review

When Reasonix encounters high-risk changes that mutate the workspace, the tool contract schema enforces a structured review flow through the review_report tool. This write-only, evidence-backed tool must be called after any destructive mutation, and its arguments must strictly conform to the contract schema.

Validation in review_report.go

The ParseReviewReport function in internal/evidence/review_report.go performs rigorous validation of the review_report tool call:

func ParseReviewReport(raw json.RawMessage) (ReviewReport, error) {
    var r ReviewReport
    if err := json.Unmarshal(raw, &r); err != nil {
        return ReviewReport{}, fmt.Errorf("invalid review_report JSON: %w", err)
    }
    if r.Kind != "review" && r.Kind != "security" {
        return ReviewReport{}, fmt.Errorf("review_report.kind must be review or security")
    }
    if r.Verdict != "pass" && r.Verdict != "warn" && r.Verdict != "block" {
        return ReviewReport{}, fmt.Errorf("review_report.verdict must be pass, warn, or block")
    }
    if len(r.ReviewedPaths) == 0 {
        return ReviewReport{}, fmt.Errorf("review_report.reviewed_paths must be non-empty")
    }
    // Host-side check that each path has read evidence...
    return r, nil
}

The schema requires four specific fields:

• kind: Must be either "review" or "security".
• verdict: Must be "pass", "warn", or "block".
• reviewed_paths: A non-empty list of file paths that correspond to files the host has observed being read.
• findings: An array of observation objects documenting the review results.

Evidence-Backed Verification

The review_report tool rejects calls that list paths without corresponding read evidence in the host ledger. This prevents the model from claiming to have reviewed files it never accessed. After successful validation, the host ledger records a Receipt (see ReviewReportReceipt in the same file), creating an immutable audit trail.

Delivery Hardening and Safety Gating

The delivery hardening logic enforces that a valid review_report must precede task completion. As implemented in internal/agent/delivery_hardening_test.go, the executor verifies the presence of a review_report receipt before marking a turn complete.

If the review is missing or malformed, the executor emits a nudging message (e.g., "Call review_report now…") and refuses to finish the task until a valid report is submitted. This guard prevents regressions from slipping through unnoticed by ensuring destructive actions are always accompanied by verifiable review steps.

Regression Testing and Schema Stability

Reasonix maintains regression guard tests that assert the schema's stability and the correct enforcement of review mechanisms. The test file internal/tool/builtin/completestep_test.go ensures that complete_step and related review mechanisms remain consistent across versions, preventing accidental relaxation of safety constraints.

These tests validate that:

• The tool contract schema remains stable and backward-compatible.
• The review_report tool cannot be bypassed for mutation operations.
• Ledger receipts correctly capture review evidence for future audits.

Summary

• The tool contract schema defines every built-in tool's interface at compile-time, including validation rules and read-only status.
• docs/TOOL_CONTRACT.md documents the canonical schema, while TestBuiltinToolContractDocumentation ensures synchronization between code and documentation.
• The review_report tool enforces mandatory regression reviews with strict validation in internal/evidence/review_report.go.
• Delivery hardening requires a valid review receipt before task completion, preventing unreviewed mutations.
• Regression tests in internal/tool/builtin/completestep_test.go and internal/agent/delivery_hardening_test.go verify that safety constraints remain enforced.

Frequently Asked Questions

What fields are required in the Reasonix tool contract schema?

The tool contract schema requires four fields for every built-in tool: the tool name (identifier used in calls), a read-only flag (indicating if the tool mutates state), a description (human-readable purpose), and a canonical JSON schema (generated by tool.BuiltinContractEntries for argument validation).

How does the review_report tool prevent unreviewed regressions?

The review_report tool prevents unreviewed regressions by requiring a structured report with kind, verdict, reviewed_paths, and findings fields. The ParseReviewReport function in internal/evidence/review_report.go validates that reviewed paths have corresponding read evidence in the host ledger, and the delivery hardening logic refuses to complete the task until a valid receipt is recorded.

Where is the tool contract schema documented and tested?

The schema is documented in docs/TOOL_CONTRACT.md and tested in internal/tool/registry_canon_test.go via TestBuiltinToolContractDocumentation, which verifies that every registered tool has a matching schema entry. Regression tests in internal/agent/delivery_hardening_test.go and internal/tool/builtin/completestep_test.go ensure the schema's stability and enforcement.

What happens if a review_report call is malformed or missing?

If the review_report call is malformed, ParseReviewReport returns an error specifying which validation failed (invalid kind, verdict, or empty reviewed_paths). If the call is missing entirely, the delivery hardening logic emits a nudging message demanding the review and blocks task completion until a valid report is submitted and recorded in the ledger.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}