fix(tools): report bad tool arguments as a sentence, not a JSON dump

[claude]

The defect

A ZodError's message is its pretty-printed issues array. ToolRegistry.execute let one escape from tool.parse(rawArgs) (tool-registry.ts:139), and the agent loop splices whatever it catches into Error: ${msg} as the tool result (run-agent-loop.ts:949). So a model that gets one field wrong prints this into the chat:

Error: [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": [ "todos", 0, "content" ],
    "message": "Invalid input: expected string, received undefined"
  }
]

Both audiences are worse off. The user reads a wall of JSON with the real problem buried in it. The model reads a payload to parse rather than an instruction it can act on, so its retry is a guess.

The change

Restate argument-validation failures at the registry — the one place that knows the arguments, rather than the tool's own execution, were at fault:

update_todos: the arguments did not match the tool's schema. todos[0].content — expected string, received undefined. Correct them and call the tool again.

• paths render as todos[0].content, matching the shape of the call the model just made, so the field is findable without translating a JSON pointer
• zod's Invalid input: prefix is dropped, since the surrounding sentence already says it
• at most five fields are listed, then and N more — past a handful the model needs to re-read the schema, not a longer list
• errors thrown from inside a tool are untouched; describeToolArgError returns null for anything that isn't a ZodError

This helps every tool, not just update_todos — the same escape existed for all of them.

Scope

The issue also asks for tolerance of near-miss todo shapes. I have not done that, deliberately: the screenshot captures the error but not the arguments, so I would be guessing at what qwen actually sent (title for content? a bare string?). Inventing aliases on a guess is how you get a schema nobody can reason about.

A readable message plausibly closes most of the gap on its own, since it tells the model exactly which field to fix. If it recurs, the captured payload is what's needed to design tolerance properly — worth reopening with one attached.

Testing

• tool-arg-error.test.ts — the reported missing-content plan, the dropped prefix, the five-field cap, a wholly wrong argument object, and execution errors passing through untouched
• Two tests in tool-registry.test.ts covering the path end to end, including that the tool does not run when validation fails
• Verified the registry test discriminates: reverting the guard fails it and leaves the other 19 passing
• Full unit suite 8653 pass / 0 fail / 3 skipped; typecheck, lint and oxfmt clean

Fixes #2442

---

🤖 Generated with Claude Code

https://claude.ai/code/session_012AZp6uiHQb3WbsHWyQqG76

---

Generated by Claude Code

[github-actions]

🖥️ PR preview

• Marketing site
• Browser demo
  Interactive, with a mocked backend — jump to a scenario:
• Builds a cupcake site
• Agent-proposed edits open the Changes panel
• Markdown list indentation
• Responsive composer footer
• Subagent display visual reference
• Subagent stays ungrouped beside reading tools
• Semantic search subagent markdown
• Light-theme approval with a bright accent
• Light-theme syntax, fills, and selection
• Grouped outside-sandbox command approval
• Remote desktop discovered-port list with one selected
• Settings scroll + sticky footer geometry
• Per-model reasoning / temperature / top-p
• Thread switch hydration notice
• Thread switch hydration failure
• Chat layout styling
  _{Static demo of the renderer against a mock API — the browser pane, terminal, and all main-process IPC are stubbed, so it never proves main-process behaviour. Rebuilt whenever a push changes the demo bundle; these links go live once the queued deploy lands, shortly after this comment. Removed when the PR closes.}