## TL;DR

The agent parses a schema that changed. Pin the gitleaks version in the agent's environment, add a schema-normalization layer, and detect the schema version at runtime.

## Error

```text
agent failed when gitleaks changed its report schema
```

## Steps

1. Diff the old and new report schemas to list what moved. Expected: the breaking changes enumerated.
2. Pin the gitleaks version the agent installs. Expected: reproducible reports.
3. Add a normalization step that maps known schema versions to the agent's internal model. Expected: the agent tolerates both.
4. Detect the schema version at runtime and reject unknown ones loudly. Expected: future changes fail fast with a clear message.
5. Test the agent against both schema versions. Expected: proven compatibility.

## When to use

- Agent breakage after scanner upgrades.
- Building version-tolerant integrations.

## When not to use

- Config errors (different problem).
- You control the scanner version fully (just pin it).

## Tool compatibility

- Gitleaks report formats; agent parsers.

## Variant phrasings

### gitleaks schema change broke parser

Normalize.

### report format changed

Pin and adapt.

## Why it happens

Scanners improve their reports; agents that parse exact field paths break on any move.

## Edge cases

- Pinning forever misses security fixes; schedule upgrade windows.
- Normalization should be tested against real reports, not just docs.
- Unknown-schema failures should page, not silently drop findings.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3CkN2TAxIwYRgQnbOsmJIA