feat(tools): render optional description or intent in tool approval cards

[Shreyasnalle]

Description

Adds an optional description parameter to the schemas of mutation tools (execute_bash, string_replace, write_file, diff_edit, and file_op) thus rendering it directly above the command or file path in the tool confirmation preview cards.

This improves transparency during the tool approval phase by allowing models to communicate their code work intend before the user approves execution which reduces the need to cancel commands to ask for an explanation over the changes made in the code by the agent.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Changeset

• Added a changeset (pnpm changeset) describing this change for the changelog

Testing

Automated Tests

• New features include passing tests in .spec.ts/tsx files (execute-bash.spec.tsx, string-replace.spec.tsx, write-file.spec.tsx)
• All existing tests pass (pnpm test:ava runs with 100% passes)
• Tests cover both success and error scenarios
• pnpm run test:types passes (0 errors)
• pnpm run test:lint passes (0 errors)

Manual Testing

• Tested with Ollama
• Tested with OpenRouter
• Tested with OpenAI-compatible API
• Verified preview renders Description: when passed as tool arguments
• Verified preview renders cleanly without blank rows when description is omitted

Checklist

• Code follows project style guidelines (Biome)
• Self-review completed
• Documentation and system prompts updated (tool-rules.md)
• No breaking changes (backwards-compatible optional field)
• Changeset included (.changeset/tool-approval-description.md)

[github-actions]

nc-review: comments — 1 important, 1 nit

@Shreyasnalle — a few things worth a look, none blocking.

Adds an optional description parameter to the execute_bash, string_replace, and write_file tool schemas and renders it in the approval card so the model can communicate intent before execution. The code is correct, backwards-compatible, and the new tests genuinely exercise the rendered output. The remaining concern is scope completeness: diff_edit and file_op are also file-mutating tools that use the same approval pathway, and the new system-prompt rule explicitly limits the recommendation to the three covered tools.

🟠 important · scope · source/app/prompts/sections/tool-rules.md

The new prompt rule explicitly lists only execute_bash, string_replace, and write_file:

When calling tools that modify files or execute commands (`execute_bash`, `string_replace`, `write_file`), provide a concise `description` parameter ...

But source/tools/file-ops/diff-edit.tsx (diff_edit) and source/tools/file-ops/file-op.tsx (file_op — delete/move/copy/mkdir) are also file-mutating tools that go through createFileToolApproval and produce a confirmation preview. A model following the rule will add description to those three and silently omit it for the others, so the user-visible inconsistency is reinforced by the prompt itself rather than by the tool capabilities.

Either generalize the rule (e.g. "when calling any tool that triggers a confirmation preview, provide a concise description") or add the description field to the remaining mutation tools so the rule's enumeration stays accurate. Worth a maintainer call before merging so the prompt and the schemas agree.

⚪ nit · tests · source/tools/execute-bash.spec.tsx

The three new tests only cover the presence path — formatter called with a description argument asserts /Description:/ appears. None of the existing formatter tests, nor any new test, asserts that the Description: block is absent when description is omitted. The conditional render is small and the existing renders without result test happens to cover it indirectly, but a one-line negative assertion (e.g. t.notRegex(output!, /Description:/) against an args object with no description) would pin the optional behaviour and prevent a future regression where someone drops the && guard and always renders an empty block.

---

_{🔴 blocking · 🟠 a reviewer would ask for a change · ⚪ optional}

_{Automated code review — correctness, security, design, tests, plus duplicates and scope. A human still decides; this is not a substitute for review and is not exhaustive. The required status checks separately cover lint, formatting, types, unused dependencies, the test suite and the build. This bot never merges. Maintainers can rerun with /re-review.}

[Shreyasnalle]

Addressed the review comments, added description parameter schema and preview support to diff_edit and file_op, aligned tool-rules.md and added negative test assertions across all tool formatters.

[akramcodez]

Great work, thanks for the PR @Shreyasnalle

[Shreyasnalle]

My pleasure, thankyou