---
id: TASK-16
title: Add guarded agent tools
status: Done
assignee: []
created_date: '2026-06-23 11:55'
updated_date: '2026-06-23 19:12'
labels: []
dependencies: []
priority: high
ordinal: 16000
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Build AI agent tools for category health, category suggestions, guarded category write plans, and current-month spending preview.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Read-only agent tools cover category health, category suggestions, and current-month expense preview
- [x] #2 Write-capable agent tools create pending action plans without directly changing data
- [x] #3 Pending action plans can be listed, applied, and dismissed from the chat UI
- [x] #4 Applying action plans revalidates ownership, status, expiry, and operation limits
- [x] #5 Convex and UI tests cover the new tool and confirmation behavior
<!-- AC:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Implemented guarded agent tool package. Verification: npx vitest run passed (14 files, 79 tests); npm run build passed. npm run lint still fails on pre-existing unrelated files (bank/config.ts, TanAwaitDialog, fast-refresh/export warnings, SettingsPage effect), with no remaining lint error from the new action-plan module.

Post-review hardening: added tests and fixes for empty category names, duplicate category renames, stale transaction category plans, and expired plans. Re-verified: convex/savingsChat.test.ts 33 passed; full npx vitest run 81 passed; npm run build passed; npx convex codegen passed.
<!-- SECTION:NOTES:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented guarded AI agent tools with current-month expense preview, category health/suggestion tools, pending action plans, UI apply/dismiss controls, and post-review validation hardening. Verified with full Vitest suite, build, and Convex codegen; lint remains blocked by pre-existing unrelated project issues.
<!-- SECTION:FINAL_SUMMARY:END -->