# Track Specification: Enhanced Context Control & Cache Awareness (enhanced_context_control_20260307)

## Overview
Give developers granular control over how files are included in the AI context and provide visibility into the active Gemini cache state. This involves moving away from a simple list of files to a structured format with per-file flags (`auto_aggregate`, `force_full`), revamping the UI to display this state, and updating the context builders and API clients to respect and expose these details.

## Core Requirements

### 1. `project.toml` Schema Update
- Migrate the `tracked_files` list to a more structured format (or preserve list for compatibility but support dictionaries/objects per file).
- Support per-file flags:
  - `auto_aggregate` (bool, default true): Whether to automatically include this file in context aggregation.
  - `force_full` (bool, default false): Whether to send the full file content, overriding skeleton extraction.

### 2. Files & Media Panel Refactoring
- Replace the existing simple list/checkboxes in the GUI (`src/gui_2.py`) with a structured table.
- Columns should include: File Name, Auto-Aggregate (checkbox), Force Full (checkbox), and a 'Cached' indicator (e.g., a green dot).
- The GUI must reflect real-time updates from the background threads using the established event queue (`_process_pending_gui_tasks`).

### 3. 'Context' Role for Manual Injections
- Implement a 'Context' role that allows manual file injections into discussions.
- Context amnesia needs to respect these manual inclusions or properly categorize them.

### 4. `aggregate.py` Updates
- `build_file_items()` and tier-specific context builders must respect the `auto_aggregate` and `force_full` flags.
- If `auto_aggregate` is false, the file is omitted unless manually injected.
- If `force_full` is true, bypass skeleton extraction (like `ASTParser.get_skeleton()`) and include the full file content.

### 5. `ai_client.py` Cache Tracking
- Add state tracking for the active Gemini cache (e.g., tracking which file hashes/paths are currently embedded in the `CachedContent`).
- Expose this state back to the UI (via `AsyncEventQueue` and `mma_state_update` or a dedicated `"refresh_api_metrics"` action) so the GUI can render the 'Cached' indicator dots.
- Ensure thread safety (`_send_lock` and appropriate variable locks) when updating and reading cache state.

## Architectural Constraints
- Follow the 1-space indentation rule for Python.
- Obey the decoupling of GUI (main thread) and asyncio background workers. All UI state mutations must occur via `_process_pending_gui_tasks`.
- No new third-party dependencies unless strictly necessary.

## Key Integration Points
- `src/project_manager.py`: TOML serialization/deserialization for tracked files.
- `src/gui_2.py`: The "Files & Media" panel and `_process_pending_gui_tasks`.
- `src/aggregate.py`: Context building logic.
- `src/ai_client.py`: Gemini API cache tracking.