Tool Contract Schema in Reasonix: Complete Guide to Regression Compliance

The Tool Contract schema in Reasonix is a compile-time JSON-Schema definition for every built-in tool that enforces argument validation and safety gating, with regression compliance ensured through mandatory review_report calls that must pass strict validation in internal/evidence/review_report.go before any high-risk mutation can complete.

Reasonix implements a tool contract schema system that governs how the model interacts with its environment. Each tool carries a machine-readable contract describing its capabilities, safety properties, and expected arguments. This article explains the schema structure, its role in the execution pipeline, and the specific mechanisms that enforce regression compliance through the review_report tool.

What Is the Tool Contract Schema?

The tool contract schema is a compile-time artifact generated by tool.BuiltinContractEntries and documented in docs/TOOL_CONTRACT.md. Every registered tool exposes four canonical fields:

• Tool name — The identifier used in tool calls (e.g., bash, read_file, review_report)
• Read-only flag — true for read-only tools, false for mutating tools
• Description — A human-readable purpose string
• Canonical JSON schema — The exact JSON-Schema validating tool arguments

The test TestBuiltinToolContractDocumentation in internal/tool/registry_canon_test.go guarantees that every registered tool has a matching documented entry and canonical schema. This prevents schema drift between implementation and documentation.

How Regression Compliance Works

Reasonix enforces regression compliance through a structured review flow that triggers after any high-risk change. The system requires three validated components before allowing task completion.

1. Mandatory review_report Tool Call

The review_report tool is write-only and evidence-backed. After any mutation, the model must call this tool with arguments conforming to the contract schema. The implementation in internal/evidence/review_report.go validates:

review_report({
  "kind": "review",
  "verdict": "pass",
  "reviewed_paths": ["internal/agent/agent.go", "internal/evidence/review_report.go"],
  "findings": [
    {"summary": "No unexpected mutations", "kind": "info"}
  ]
})

Required fields:

• kind: Either "review" or "security"
• verdict: One of "pass", "warn", or "block"
• reviewed_paths: Non-empty array of files with read evidence
• findings: Structured observations about the reviewed changes

2. Validation in ParseReviewReport

The function ParseReviewReport in internal/evidence/review_report.go performs strict argument validation:

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("reviewed_paths must be non-empty")
    }
    // Host-side check: each path must have read evidence
    return r, nil
}

Critical safety check: The host rejects reviewed_paths entries without corresponding read evidence. This prevents the model from claiming to review files it never accessed.

3. Delivery Hardening and Ledger Recording

Upon successful validation, the host creates a ReviewReportReceipt recorded in the execution ledger:

ledger.Record(evidence.Receipt{
    ToolName: "review_report",
    Success:  true,
    Args:     json.RawMessage(reportJSON),
})

The delivery hardening logic in internal/agent/delivery_hardening_test.go verifies this receipt before marking a turn complete. Missing or malformed reviews trigger executor nudges ("Call review_report now...") and block task completion until compliance is achieved.

Regression Guard Tests

Reasonix maintains multiple test categories protecting the Tool Contract schema from regression:

Test File	Protection Scope
internal/tool/registry_canon_test.go	Schema-to-documentation alignment for all tools
internal/agent/delivery_hardening_test.go	Enforcement of review_report before task completion
internal/tool/builtin/completestep_test.go	Stability of complete_step and review mechanisms

These tests assert that the canonical schema remains stable and that safety gating cannot be bypassed through code changes.

Key Files and Their Roles

Path	Purpose
docs/TOOL_CONTRACT.md	Human-readable schema reference and snapshot
internal/evidence/review_report.go	review_report implementation, ParseReviewReport validation, and ledger recording
internal/tool/registry_canon_test.go	Contract-to-documentation consistency tests
internal/agent/delivery_hardening_test.go	Turn-completion gatekeeping tests
internal/tool/builtin/completestep_test.go	Regression guards for step completion flow

Tool Contract Schema Benefits

The schema provides three foundational guarantees:

• Argument validation — Every tool call is machine-validated against its canonical JSON-Schema
• Safety gating — Destructive actions require verifiable review steps with audit trails
• Regression testing — Automated test suite prevents schema or enforcement drift

Summary

• The Tool Contract schema is a compile-time JSON-Schema generated by tool.BuiltinContractEntries and tested in internal/tool/registry_canon_test.go
• Regression compliance requires a valid review_report call validated by ParseReviewReport in internal/evidence/review_report.go
• The host ledger records ReviewReportReceipt entries verified by delivery hardening logic before task completion
• Read evidence verification prevents the model from falsely claiming file reviews
• Multiple regression guard tests protect schema stability and enforcement integrity

Frequently Asked Questions

What happens if review_report is called with files that weren't read?

The ParseReviewReport function in internal/evidence/review_report.go performs a host-side check that rejects any path without corresponding read evidence in the ledger. This prevents incomplete or fabricated reviews from passing validation.

Can the Tool Contract schema change between versions?

Schema changes are possible but require updating docs/TOOL_CONTRACT.md and passing TestBuiltinToolContractDocumentation in internal/tool/registry_canon_test.go. The test suite ensures documented and implemented schemas remain synchronized.

How does delivery hardening interact with the review flow?

The delivery hardening logic in internal/agent/delivery_hardening_test.go inspects the ledger for a valid ReviewReportReceipt before allowing turn completion. If absent, the executor emits nudging messages and blocks indefinitely until compliance is achieved.

What distinguishes "review" from "security" in the kind field?

Both trigger the same validation pipeline, but "security" indicates a higher-sensitivity review typically required for authentication, authorization, or sandbox-escaping changes. The field is preserved in the ledger receipt for downstream audit filtering.

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