# Tool Contract Schema in Reasonix: Complete Guide to Regression Compliance

> Understand the Reasonix Tool Contract schema for argument validation and safety gating. Ensure regression compliance with mandatory review report calls and strict validation.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-11

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/evidence/review_report.go) validates:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/evidence/review_report.go) performs strict argument validation:

```go
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:

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

```

The **delivery hardening** logic in [`internal/agent/delivery_hardening_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/registry_canon_test.go) | Schema-to-documentation alignment for all tools |
| [`internal/agent/delivery_hardening_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/delivery_hardening_test.go) | Enforcement of `review_report` before task completion |
| [`internal/tool/builtin/completestep_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md) | Human-readable schema reference and snapshot |
| [`internal/evidence/review_report.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/evidence/review_report.go) | `review_report` implementation, `ParseReviewReport` validation, and ledger recording |
| [`internal/tool/registry_canon_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/registry_canon_test.go) | Contract-to-documentation consistency tests |
| [`internal/agent/delivery_hardening_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/delivery_hardening_test.go) | Turn-completion gatekeeping tests |
| [`internal/tool/builtin/completestep_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/registry_canon_test.go)
- **Regression compliance** requires a valid `review_report` call validated by `ParseReviewReport` in [`internal/evidence/review_report.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md) and passing `TestBuiltinToolContractDocumentation` in [`internal/tool/registry_canon_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.