[03-Developer] #260 in-app tool calling (Gemma 4 multi-turn)

ADR-0005 in-process tool runtime — 6 tools (catalog 2 + tracker 2 +
habit 2), ToolDispatcher with JSON-schema validation + modal ConfirmGate
for destructive ops, multi-turn LlmChatSession abstraction wired to
flutter_gemma 0.16.5 (ToolChoice.auto), ChatSessionController with
MAX_TURNS=4 safety + 8-turn history hint, ChatScreen entry behind AI
opt-in. R3/R7/R8 enforced inside handlers. 41 new tests (envelope,
catalog/tracker/habit tools, dispatcher, controller loop) — 151 total
passing.

Refs #260

app/lib/ai/tools/tool_definition.dart

@@ -0,0 +1,54 @@
+import '../../data/catalog/catalog_repository.dart';
+import '../../data/db/daos/habit_dao.dart';
+import '../../data/db/daos/tracker_dao.dart';
+import '../../domain/models/frame_pattern.dart';
+import 'tool_envelope.dart';
+
+/// Shared dependencies for every tool handler.
+///
+/// Frame patterns are passed in pre-loaded (memo'd at provider level) so the
+/// R7 avoidance check doesn't reparse seed JSON on every tool call.
+class ToolDeps {
+  final HabitDao habitDao;
+  final TrackerDao trackerDao;
+  final CatalogRepository catalog;
+  final List<FramePatternModel> framePatterns;
+  final String userId;
+
+  const ToolDeps({
+    required this.habitDao,
+    required this.trackerDao,
+    required this.catalog,
+    required this.framePatterns,
+    required this.userId,
+  });
+}
+
+typedef ToolHandler =
+    Future<ToolResult> Function(Map<String, dynamic> args, ToolDeps deps);
+
+/// Single tool the model can call.
+///
+/// `parametersSchema` follows the draft-07 JSON Schema shape that
+/// flutter_gemma 0.16.5's `Tool.parameters` expects — see ADR-0005 (Dart is
+/// the schema source-of-truth).
+class ToolDefinition {
+  final String name;
+  final String description;
+  final Map<String, dynamic> parametersSchema;
+  final bool isDestructive;
+  final ToolHandler handler;
+
+  /// Optional summariser used by `ConfirmGate` to render destructive args in
+  /// a sentence rather than raw JSON. Read-only tools leave this null.
+  final String Function(Map<String, dynamic> args)? summarize;
+
+  const ToolDefinition({
+    required this.name,
+    required this.description,
+    required this.parametersSchema,
+    required this.handler,
+    this.isDestructive = false,
+    this.summarize,
+  });
+}