feat: add guarded savings agent tools

backlog/tasks/task-16 - Add-guarded-agent-tools.md

@@ -0,0 +1,41 @@
+---
+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 -->