fix: let read accept optional: false as a required read (#189494)
Root cause: `src/agents/sessions/tools/tool-schemas.ts:95` publishes `read.optional` as literal `true`, and the OpenClaw read wrapper (`src/agents/agent-tools.read.ts:712`, `createOpenClawReadTool`, which owns how `optional` is interpreted) prepares no arguments, so agent-core validates the model's `optional: false` unchanged and `packages/llm-core/src/validation.ts:416` rejects the call with `optional: must be equal to constant` before the read runs.
Fixes #189440.
Thanks @Pkieffaber-dotcom for the report with session counts and the exact received arguments, @wr-web for this PR, and @moonbow0407 for #192113, which fixed the same bug. @wr-web's commits are kept as they are; the fix commit on top replaces the schema change.
## What Problem This Solves
Some models send `"optional": false` on `read` to mean "this file is required". OpenClaw rejected that call with `optional: must be equal to constant` before reading anything, so the model had to spend another turn retrying without the flag. The reporter saw it on 13 of 38 cron runs with `openai/gpt-5.4-mini`.
## User Impact
`read` with `optional: false` now reads the file on the first try. A missing file with `optional: false` is still an error, and `optional: true` on a missing file still returns the structured "Optional file not found" result.
## Why This Change Was Made
- `createOpenClawReadTool` now sets `prepareArguments` to `prepareReadToolParams` (in `agent-tools.params.ts`), which drops `optional: false` before validation, so it means the same as leaving the flag out. It is typed `unknown -> unknown` like the cron and computer preparers; no type assertions. Agent-core runs it before argument validation.
- The canonical daily-memory path check moves next to it in `agent-tools.params.ts` unchanged, so both rules about `optional` live together and `agent-tools.read.ts` does not grow past its line cap.
- The input schema stays `optional: true` only. The tool definition the model sees is byte-identical to `main`, so prompt caches are not invalidated. @wr-web's first commit widened the schema to `boolean`; that changed the published definition, so it is reverted here.
- Accepted edge: a canonical daily-memory journal path (`memory/YYYY-MM-DD.md`) is already read as optional when the flag is absent. With `optional: false` on a missing journal the model now gets the same "Optional file not found" result as with no flag, not an error.
- Merged current `main` (`src/agents/code-mode.test.ts` was deleted on `main`, so this PR's change to it is gone).
Line deltas against the merge base: production +21/-4 (`agent-tools.params.ts` +17, `agent-tools.read.ts` +4/-4), tests +25/-1 (one regression in `agent-tools.schema.test.ts`).
## Evidence
Real Gateway from source (`ocx src`: `gateway run`, then `openclaw agent` through the Gateway), isolated profile and state, and a scripted OpenAI-compatible model with a fixture key. In each turn the model calls `read` once; the result is the tool output the model got back in the next request.
| `read` call from the model | main `96189709bc50` | this branch `ada2a82357f1` |
|---|---|---|
| existing `SKILL.md`, `optional: false` (reporter's argument shape) | `Validation failed for tool "read": - optional: must be equal to constant` | the file content |
| missing file, `optional: true` | `Optional file not found: missing.md.` | same |
| missing file, `optional: false` | validation error | `File not found: .../missing.md.` (required read fails) |
| `read.optional` schema sent to the model | `{"type":"boolean","const":true,...}` | same |
Observed proof lines: https://github.com/openclaw/openclaw/pull/189494#issuecomment-6998463471 (reruns on later heads below it)
Tests: `agent-tools.schema.test.ts` "runs read optional: false through the agent loop as a required read" runs the wrapped read tool through `runAgentLoop`: an existing file reads, a missing one fails as required. It fails on `main` with `optional: must be equal to constant` and passes here. `agent-tools.prefix-stability.test.ts`, `agent-tools.workspace-outside.test.ts` (daily-memory rule) and `sessions/tools/read.test.ts` pass.
Not covered: no run against `openai/gpt-5.4-mini` on OpenRouter; why that model started sending the flag after 2026.10.7 is not investigated.
Merge danger: two-way door. The change only rewrites one tool argument before validation and writes no state, so a revert fully undoes it. Blast radius: `read` calls that send `optional: false`, which failed before and now run as required reads.
Co-authored-by: Ayaan Zaidi <hi@obviy.us>
Current
·
C2
·2026-11
fix: let read accept optional: false as a required read (#189494)
Find Your Interest
Current
·
C2
·2026-11





