{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ErrorJson",
"description": "Serializable error envelope emitted as a single NDJSON line.",
"type": "object",
"properties": {
"best_candidate": {
"description": "Closest near-miss when a match cascade fails (v0.1.29 P0-2).",
"anyOf": [
{
"$ref": "#/$defs/BestCandidate"
},
{
"type": "null"
}
]
},
"code": {
"description": "Machine-readable error code string.",
"type": "string"
},
"error": {
"description": "Always true, marks this line as an error event.",
"type": "boolean"
},
"error_class": {
"description": "Error class: transient, conflict, `precondition_failed`, or permanent.",
"type": "string"
},
"exit": {
"description": "Suggested process exit code.",
"type": "integer",
"format": "uint8",
"maximum": 255,
"minimum": 0
},
"failed_pair_index": {
"description": "1-based index of the failed `--old`/`--new` pair (multi-pair edit, G117).",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"message": {
"description": "Human-readable error message.",
"type": "string"
},
"pair_results": {
"description": "Per-pair diagnostics up to and including the failed pair (multi-pair edit, G117).\nPairs after the failure were never attempted and are absent.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/PairResult"
}
},
"pairs_total": {
"description": "Total number of `--old`/`--new` pairs in the invocation (multi-pair edit, G117).",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"path": {
"description": "Filesystem path related to the error, if applicable.",
"type": [
"string",
"null"
]
},
"retryable": {
"description": "Whether a retry may resolve this error.",
"type": "boolean"
},
"suggestion": {
"description": "Optional actionable suggestion for the caller.",
"type": [
"string",
"null"
]
},
"workspace": {
"description": "Workspace root used for jail validation, if applicable.",
"type": [
"string",
"null"
]
}
},
"required": [
"error",
"code",
"exit",
"message",
"error_class",
"retryable"
],
"$defs": {
"BestCandidate": {
"description": "Closest near-miss when a fuzzy/exact match fails (v0.1.29 P0-2).\n\nAgents use this to correct `old` without re-reading the full file.",
"type": "object",
"properties": {
"column": {
"description": "1-based column of the candidate start.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"diff_preview": {
"description": "Optional short unified-diff style preview.",
"type": [
"string",
"null"
]
},
"line": {
"description": "1-based line of the candidate start in the file.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"similarity": {
"description": "Similarity score 0.0–1.0 of the best attempt.",
"type": [
"number",
"null"
],
"format": "double"
},
"strategy": {
"description": "Strategy that produced this candidate score.",
"type": [
"string",
"null"
]
},
"text": {
"description": "Snippet of the best matching region (truncated to 500 chars).",
"type": [
"string",
"null"
]
}
}
},
"PairResult": {
"description": "Outcome of matching a single `--old`/`--new` pair in multi-pair edit mode.\n\nEmitted in `pair_results` on both success and error envelopes so agents\ncan verify each pair objectively without re-running the edit (G117).\nIn the default all-or-nothing mode, pairs after the first failure are\nnever attempted and are absent from the array.",
"type": "object",
"properties": {
"index": {
"description": "1-based position of the pair in the `--old`/`--new` invocation order.",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"matched": {
"description": "Whether the pair matched and was applied to the content.",
"type": "boolean"
},
"similarity": {
"description": "Similarity score of the fuzzy match, 0.0-1.0 (block-anchor and context-aware only).",
"type": [
"number",
"null"
],
"format": "double"
},
"source": {
"description": "Source of the match/replacement content: `\"arg\"` or `\"file\"`.",
"type": [
"string",
"null"
]
},
"strategy": {
"description": "Matching strategy that succeeded (e.g. `exact`, `whitespace_normalized`).",
"type": [
"string",
"null"
]
}
},
"required": [
"index",
"matched"
]
}
}
}