Error envelope

Tool errors are a JSON envelope in the text result. isError is true. Do not scrape a free-text sentence when this object is present.

{
  "error": {
    "code": "NOT_ALLOWED",
    "message": "...",
    "path": "C:\\proj\\file.txt",
    "details": {},
    "suggestion": "call list_allowed_directories",
    "retryable": false,
    "recovery": "fix_arguments"
  }
}

OCC_MISMATCH also includes expected_hash, current_hash, and conflict.

`retryable`

retryable: true means use the envelope before another call. It does not authorize replaying the same mutation.

Filesystem codes set retryable true only for:

Code	`recovery`
`OCC_MISMATCH`	`read_and_rebase`
`HASH_REQUIRED`	`read_and_rebase`
`STALE_GIT`	`read_and_rebase`

Every other filesystem code has retryable: false.

recovery values used by the filesystem mapper:

`recovery`	Codes
`read_and_rebase`	`OCC_MISMATCH`, `HASH_REQUIRED`, `PATCH_FAILED`, `STALE_GIT`
`check_already_applied`	`ROLLBACK_PARTIAL`, `ROLLBACK_FAILED`, `ROLLBACK_COMPLETE`
`fix_arguments`	the rest

PATCH_FAILED is not retryable. Read the file and regenerate the hunk. Do not send the same patch again.

Codes

Code	When
`NOT_ALLOWED`	Path is outside the allowlist.
`NOT_FOUND`	Path is missing.
`ROOTS_EMPTY`	No sandbox roots.
`SECRET_DENIED`	Secret filename, and `--allow-secrets` is off.
`FILE_POLICY_DENIED`	File security policy blocked the call.
`READONLY`	Mutating tool while `--readonly`.
`VALIDATION`	Unknown or wrong parameter.
`REWRITE_BLOCKED`	Accidental full-file rewrite. Use `write_file` or `allow_rewrite`.
`OCC_MISMATCH`	`expected_hash` does not match.
`HASH_REQUIRED`	`--auto-occ=block` and no `expected_hash`.
`PATCH_FAILED`	Unified diff did not apply.
`BEGIN_PATCH`	Codex `*** Begin Patch`, not a unified diff.
`BUDGET_EXCEEDED`	`--mutation-budget` reached.
`STALE_GIT`	`expected_status_hash` does not match. No diff body.
`TOOL_UNAVAILABLE`	Tool is not available in this process.
`ROLLBACK_COMPLETE`	Journal rolled back.
`ROLLBACK_PARTIAL`	Journal rollback was partial.
`ROLLBACK_FAILED`	Journal rollback failed.
`GH_CLI_MISSING`	`gh` is not installed.
`GH_AUTH_REQUIRED`	`gh` is not authenticated.
`GH_FORBIDDEN`	GitHub denied the call.
`GH_NOT_FOUND`	GitHub repo or issue missing.
`GH_RATE_LIMIT`	GitHub or GitLab rate limit.
`GH_NETWORK`	GitHub network or transport failure.
`GH_AMBIGUOUS`	More than one GitHub repo matches.
`GH_REPO_UNRESOLVED`	Could not resolve owner/repo.
`GH_OUTPUT_LIMIT`	`gh` output was capped.
`GH_NOT_ISSUE`	The number is not an issue.
`GH_HOST_DENIED`	Host is outside `--git-remote-allow`.
`GH_FAILED`	Other `gh` failure.
`GL_AUTH_REQUIRED`	GitLab auth failed.
`GL_NOT_FOUND`	GitLab project or issue missing.
`GL_FORBIDDEN`	GitLab denied the call.
`GL_NETWORK`	GitLab network or HTTP failure.
`GL_AMBIGUOUS`	More than one GitLab remote matches.
`GL_REPO_UNRESOLVED`	Could not resolve the GitLab project.

Issue tools set retryable on the call, not only from the table above. GH_RATE_LIMIT and GH_NETWORK are retryable for reads only. GitLab network and 5xx reads can be retryable. A GitLab write that fails in transit may already have been applied. Check the issue. Do not retry it automatically.