feat(token-tracking): introduce token note taxonomy (measured/userbased/workplan/heuristic)

Tier 1 (exact counts) now defaults to note="measured" instead of null,
signalling the counts were read from the Claude Code status bar.
Callers can pass note="userbased" when a human provided the numbers.

  measured  — agent read exact counts from the Claude Code status bar
  userbased — counts provided by a human
  workplan  — prorated from workplan total across task count
  heuristic — server fallback, 1000/500, no agent input

Added token_note field to TaskUpdate schema and exposed note param on
update_task_status and record_interactive_task MCP tools.
TOOLS.md documents the full taxonomy. 185 tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api/schemas/task.py

@@ -39,13 +39,15 @@ class TaskUpdate(BaseModel):
     intervention_note: str | None = None
     parent_task_id: uuid.UUID | None = None
     # Token passthrough — three tiers (highest precision wins):
-    # 1. tokens_in + tokens_out  → exact counts (best practice)
+    # 1. tokens_in + tokens_out  → exact counts; note defaults to "measured"
     # 2. workplan_tokens_in + workplan_tokens_out  → prorated across task count (note="workplan")
     # 3. neither provided, status=done  → heuristic 1000/500 (note="heuristic")
+    # token_note overrides the auto-assigned note for Tier 1 only (e.g. "userbased")
     tokens_in: int | None = None
     tokens_out: int | None = None
     workplan_tokens_in: int | None = None
     workplan_tokens_out: int | None = None
+    token_note: str | None = None
     model: str | None = None
     agent: str | None = None
     session_id: str | None = None