tunacode-cli 0.1.37__tar.gz

tunacode_cli-0.1.37/.claude/JOURNAL.md

@@ -0,0 +1,359 @@
+# Claude Journal
+
+## 2026-01-07: Renderer Unification
+
+Unifying the 8 tool renderers in `src/tunacode/ui/renderers/tools/` to eliminate duplication via a shared base class and registry pattern.
+
+### Completed:
+- Created `base.py` with `BaseToolRenderer[T]` ABC and `ToolRendererProtocol`
+- Extracted shared helpers: `truncate_line`, `truncate_content`, `pad_lines`
+- Added registry pattern: `@tool_renderer`, `get_renderer`, `list_renderers`
+- Migrated `list_dir.py` to use `BaseToolRenderer` (199 -> 149 lines)
+- Created documentation at `docs/ui/tool_renderers.md`
+
+### Architecture Decisions:
+- Module-level singleton renderer instances (not created per-call)
+- Render functions remain the public API (backward compatible)
+- `@tool_renderer` decorator for self-registration
+- Helpers are standalone functions, not methods
+
+---
+
+## 2026-01-07: Local Mode Context Optimization
+
+### Problem:
+- System prompt + tool schemas used ~3.5k tokens before any conversation
+- Each file read could use 2000 lines (~20k tokens)
+- With 10k context, only ~6.5k left for conversation
+- LLM APIs are stateless - system prompt sent every turn
+
+### Solution:
+
+**1. Minimal System Prompt**
+- `LOCAL_TEMPLATE` in `templates.py` - only 3 sections: AGENT_ROLE, TOOL_USE, USER_INSTRUCTIONS
+- `local_mode: true` setting triggers minimal template
+
+**2. Minimal Tool Schemas**
+- Reduced from 11 tools to 6 (bash, read_file, update_file, write_file, glob, list_dir)
+- 1-word descriptions ("Shell", "Read", "Edit", etc.) - saves ~1k tokens
+
+**3. Aggressive Pruning**
+- LOCAL_PRUNE_PROTECT_TOKENS: 2,000 (vs 40,000)
+- LOCAL_PRUNE_MINIMUM_THRESHOLD: 500 (vs 20,000)
+
+**4. Tool Output Limits**
+- LOCAL_DEFAULT_READ_LIMIT: 200 lines (vs 2,000)
+- LOCAL_MAX_LINE_LENGTH: 500 chars (vs 2,000)
+- LOCAL_MAX_COMMAND_OUTPUT: 1,500 chars (vs 5,000)
+
+**5. Response Limit**
+- local_max_tokens: 1000 - caps model output per turn
+
+### Token Budget (Local Mode):
+| Component | Tokens |
+|-----------|--------|
+| System prompt | ~1,100 |
+| Guide file | ~500 |
+| 6 tools (minimal) | ~575 |
+| **Total base** | **~2,200** |
+
+With 10k context: ~7.8k available for conversation.
+
+### Key Insight:
+LLM APIs are stateless. Every request sends: system prompt + tool schemas + full conversation history. Model has no memory - re-reads everything each turn.
+
+### Key Files:
+- `src/tunacode/core/limits.py` - Centralized limit configuration
+- `src/tunacode/core/prompting/templates.py` - LOCAL_TEMPLATE
+- `src/tunacode/core/prompting/local_prompt.md` - Condensed prompt
+- `src/tunacode/core/compaction.py` - Dynamic prune thresholds
+- `src/tunacode/constants.py` - Local mode limit constants
+
+---
+
+## 2026-01-06: Local Model Support
+
+### Task: Add local model support to tunacode
+
+### Completed:
+- Created condensed system prompt at `src/tunacode/prompts/local_model_prompt.txt` (~500 bytes vs 34KB full prompt)
+- Added `local_model: true/false` setting in config defaults
+- Modified `load_system_prompt()` to use condensed prompt when `local_model=true`
+- Added cache invalidation for `local_model` setting in `_compute_agent_version()`
+- Skip AGENTS.md loading for local models to save tokens
+- Created `fallback_executor.py` for models that output tool calls in text (e.g., `<tool_call>` tags)
+- Updated `node_processor.py` to detect and execute fallback tool calls
+- Passed `agent_ctx` through the call chain for result injection
+- Tested with multiple local models via LM Studio/vLLM
+
+### Notes:
+- Qwen2.5-Coder-14B supports native OpenAI tool calling format
+- Smaller models (0.6B-1.7B) output `<tool_call>` tags in content - fallback parser handles this
+- llama.cpp uses KV cache efficiently (LCP similarity) so repeated prompt not re-computed
+
+---
+
+## 2026-01-08: Config Restoration & Local Mode Docs
+
+### Task: Restore pre-local-mode config and document local mode setup
+
+### Completed:
+
+**1. Config Backup Discovery**
+Found three config variants in `~/.config/`:
+- `tunacode.json` - was set to local mode (grok-code-fast-1, 10k context)
+- `tunacode.json.bak` - MiniMax-M2.1, 200k context, no local mode
+- `@tunacode.json` - Gemini 3 Pro via OpenRouter
+
+**2. Restored Config**
+- Restored `~/.config/tunacode.json` from `.bak` (MiniMax config)
+- Settings: `minimax:MiniMax-M2.1`, 200k context, `guide_file: AGENTS.md`
+
+**3. Created Local Mode Example**
+- Created `docs/configuration/tunacode.local.json.example`
+- Documents all local mode settings:
+  - `local_mode: true`
+  - `local_max_tokens: 1000`
+  - `context_window_size: 10000`
+  - `OPENAI_BASE_URL: http://127.0.0.1:8080/v1`
+  - `guide_file: CLAUDE_LOCAL.md`
+
+### Key Files:
+- `~/.config/tunacode.json` - user config (restored to MiniMax)
+- `docs/configuration/tunacode.json.example` - standard example
+- `docs/configuration/tunacode.local.json.example` - NEW: local mode example
+
+### Notes:
+- Local mode uses condensed prompts and minimal tool schemas for small context windows
+- The `.bak` file preserved the pre-experimentation state - good backup hygiene!
+- User was testing local models, now back to cloud (MiniMax)
+
+---
+
+## 2026-01-08: Syntax Highlighting for Tool Renderers (Branch: ui-model-work)
+
+### The Mission:
+Make tool outputs pretty! All those ugly plain text viewports were a crime against NeXTSTEP aesthetics. Time to add syntax highlighting everywhere.
+
+### Completed (Commit 9db8e92):
+
+**1. Created `syntax_utils.py` - The Shared Foundation**
+- `EXTENSION_LEXERS` - 60+ file extension → lexer mappings
+- `get_lexer(filepath)` - Get pygments lexer from file path
+- `syntax_or_text(content, filepath)` - Render highlighted or plain
+- `detect_code_lexer(content)` - Heuristic code detection (shebangs, JSON, Python/JS patterns)
+- `SYNTAX_THEME = "monokai"` - Consistent theme everywhere
+
+**2. Created `write_file.py` - New Renderer!**
+- Was missing entirely - now shows syntax-highlighted preview of written content
+- Green "NEW" badge in header, file stats
+
+**3. Updated 8 Existing Renderers:**
+
+| Renderer | What Changed |
+|----------|-------------|
+| `read_file` | Syntax highlighting by file extension, built-in line numbers from Syntax component |
+| `grep` | Cyan file paths, yellow `reverse` highlighted matches, styled line numbers with `│` |
+| `glob` | Files colored by type: Python=bright_blue, JS=yellow, JSON=green, etc. Dir path dim, filename bold |
+| `list_dir` | Tree chars dim, directories bold cyan, files colored by lexer type |
+| `bash` | Smart detection: `git diff`→diff lexer, JSON commands→json lexer, labeled stdout/stderr |
+| `web_fetch` | URL-based detection (raw.githubusercontent.com, .json, /api/), content heuristics |
+| `research` | New "Code" section with syntax-highlighted examples from `code_examples` field |
+| `update_file` | Already had Syntax("diff") - unchanged, the OG |
+
+**4. Updated `__init__.py`:**
+- Added `write_file` renderer to exports
+- Added syntax utility functions to `__all__`
+- Better docstring explaining the 4-zone pattern
+
+### Key Design Decisions:
+- `syntax_or_text()` returns `RenderableType` - graceful fallback to `Text()` for unknown extensions
+- File-type coloring consistent across `glob`, `list_dir`, `grep` (same color = same type)
+- Bash output detection is conservative - only highlights when confident
+- Research viewport prioritizes findings over code (code is supplementary)
+
+### Files Modified:
+```
+src/tunacode/ui/renderers/tools/
+├── __init__.py        (exports + docstring)
+├── syntax_utils.py    (NEW - shared utilities)
+├── write_file.py      (NEW - renderer)
+├── read_file.py       (syntax highlighting)
+├── grep.py            (styled matches)
+├── glob.py            (colored paths)
+├── list_dir.py        (styled tree)
+├── bash.py            (smart detection)
+├── web_fetch.py       (URL/content detection)
+└── research.py        (code examples)
+```
+
+### What's Left on This Branch:
+- Other UI model work (the branch name suggests more to do)
+- Unstaged: `.claude/JOURNAL.md`, `CLAUDE.md`, research docs, config example
+
+### Commands:
+```bash
+uv run ruff check src/tunacode/ui/renderers/tools/  # All checks pass
+uv run python -c "from tunacode.ui.renderers.tools import list_renderers; print(list_renderers())"
+# ['bash', 'glob', 'grep', 'list_dir', 'read_file', 'research_codebase', 'update_file', 'web_fetch', 'write_file']
+```
+
+### Fun Fact:
+We went from 0 syntax-highlighted viewports to 8 in one session. The `update_file` renderer was the lonely pioneer - now it has friends!
+
+---
+
+## 2026-01-08: The Great Panel Width Debugging Adventure (Branch: master)
+
+### The Problem:
+Tool panels were narrower than agent panels. User showed screenshot - `read_file` panel was ~50 chars wide while `agent` panel was full width. Classic NeXTSTEP violation!
+
+### The Red Herring (What We Thought):
+Initially believed the issue was `width=TOOL_PANEL_WIDTH` (50 chars) on `Panel()` calls. Spent time:
+- Removing `width=TOOL_PANEL_WIDTH` from 7 Panel() calls in `panels.py`
+- Removing it from `search.py`, `update_file.py`, `app.py`
+- Cleaning up unused imports
+
+But panels were STILL narrow after restart. User called me out: "stop being lazy, dig deeper"
+
+### The Actual Root Cause (The AHA Moment):
+
+**Textual's `RichLog.write()` has its OWN `expand` parameter that defaults to `False`!**
+
+From `.venv/lib/python3.13/site-packages/textual/widgets/_rich_log.py`:
+```python
+def write(
+    self,
+    content: RenderableType | object,
+    width: int | None = None,
+    expand: bool = False,  # <-- THIS IS THE VILLAIN
+    shrink: bool = True,
+    ...
+)
+```
+
+When `expand=False` (default), RichLog measures the content's minimum width and renders at that width, **completely ignoring** the Panel's own `expand=True` property!
+
+The Panel's expand tells Rich "expand to console width", but RichLog overrides the console width to be just the measured content width. Two different expand flags, two different systems!
+
+### The Real Fix:
+Pass `expand=True` to `rich_log.write()`:
+
+```python
+# Before
+self.rich_log.write(panel)
+
+# After
+self.rich_log.write(panel, expand=True)
+```
+
+### Files Modified:
+| File | Change |
+|------|--------|
+| `src/tunacode/ui/app.py` | 3 panel writes → `expand=True` (lines 325, 377, 558) |
+| `src/tunacode/ui/plan_approval.py` | 1 panel write → `expand=True` (line 132) |
+| `src/tunacode/ui/renderers/panels.py` | Removed `width=TOOL_PANEL_WIDTH` (harmless cleanup) |
+| `src/tunacode/ui/renderers/search.py` | Removed unused import |
+| `src/tunacode/ui/renderers/tools/update_file.py` | Removed unused import |
+
+### The Lesson:
+When Rich Panel has `expand=True` but isn't expanding in Textual:
+1. The Panel's expand is **not** the issue
+2. Check how the panel is being **written** to the widget
+3. RichLog.write() has its own expand parameter!
+
+### Status:
+- Changes made, ruff passes
+- NOT COMMITTED YET - user needs to test
+- Previous width removal changes are technically unnecessary but harmless
+
+### Commands:
+```bash
+git diff --stat  # See all changes
+uv run ruff check src/tunacode/ui/  # Verify
+# Restart tunacode and make NEW request to test
+```
+
+### Philosophical Note:
+This bug was a perfect example of "the abstraction leaked". Panel.expand and RichLog.write(expand=) look like they should be the same thing, but they operate at different levels. Panel tells Rich what to do. RichLog tells Rich what size canvas to give it. The canvas size wins.
+
+---
+
+## 2026-01-14: Glob Tool Dead Code Cleanup (Branch: glob-improvements)
+
+### The Mission:
+Clean up glob tool based on research doc findings. Remove dead code, fix deprecations.
+
+### The Discovery: Semantically Dead Code
+
+Static analysis (Vulture) reported "no dead code" in glob.py. But manual review found:
+
+```python
+# Line 29: Global declared
+_gitignore_patterns: set[str] | None = None
+
+# Line 73-74: Function called
+if use_gitignore:
+    await _load_gitignore_patterns(root_path)
+
+# Lines 155-174: Function populates global
+async def _load_gitignore_patterns(root: Path) -> None:
+    global _gitignore_patterns
+    # ... reads .gitignore files, populates set
+```
+
+**The Problem:** `_gitignore_patterns` was NEVER READ. All 7 references were writes. The actual filtering used `DEFAULT_EXCLUDE_DIRS`. The `use_gitignore` parameter was a lie.
+
+### Why Vulture Missed It
+
+Vulture checks: "Is this symbol referenced?"
+It does NOT check: "Is the result consumed?"
+
+The function WAS called. The variable WAS assigned. But the data went nowhere.
+
+### Completed:
+
+**Commit 61384fe - Dead Code Removal:**
+- Removed `_gitignore_patterns` global
+- Removed `_load_gitignore_patterns()` function (21 lines)
+- Removed `use_gitignore` parameter from signature
+- Replaced 2x `asyncio.get_event_loop().run_in_executor()` with `asyncio.to_thread()`
+- Created QA card: `.claude/qa/semantically-dead-code.md`
+- Added lesson to CLAUDE.md Continuous Learning
+
+**Commit 745a56b - Asyncio Deprecation Fixes:**
+Fixed all remaining `get_event_loop()` calls in codebase:
+
+| File | Calls | Fix |
+|------|-------|-----|
+| `grep.py` | 2 | `get_running_loop().run_in_executor()` (custom executor) |
+| `startup.py` | 2 | `asyncio.to_thread()` |
+| `app.py` | 2 | `asyncio.to_thread()` |
+| `lsp/client.py` | 3 | `get_running_loop()` for create_future/time |
+
+### Key Insight: asyncio.to_thread() vs get_running_loop()
+
+- `asyncio.to_thread(func)` - For default executor (None), simpler API
+- `asyncio.get_running_loop().run_in_executor(exec, func)` - For custom executors
+
+### Prevention Rule
+
+When adding `load_X()` function:
+1. Grep for READS of X, not just references
+2. If a parameter "controls behavior", trace data flow to prove it changes output
+3. Question unused returns - if nothing reads it, why compute it?
+
+### Status:
+- Branch: `glob-improvements`
+- Tests: 304 passed
+- Ruff: clean
+- Zero `get_event_loop()` calls remain in src/
+- Ready to push
+
+### Next:
+Push branch, optionally create PR
+
+### References:
+- Research: `memory-bank/research/2026-01-14_12-27-29_glob-tool-bottlenecks.md`
+- QA Card: `.claude/qa/semantically-dead-code.md`
+- Skill used: `.claude/skills/dead-code-detector/` (Vulture - catches syntactic, not semantic)

tunacode_cli-0.1.37/.claude/debug_history/2026-01-12_missing-cached-tokens.md

@@ -0,0 +1,45 @@
+---
+title: Missing cached_tokens in RequestUsage crashes usage tracking
+link: missing-cached-tokens-request-usage
+type: delta
+path: src/tunacode/core/agents/agent_components/orchestrator/usage_tracker.py
+depth: 0
+seams: [D] data
+ontological_relations:
+  - relates_to: [[agent-orchestrator]]
+  - affects: [[usage-tracking]]
+  - fixes: [[requestusage-missing-cached-tokens]]
+tags:
+  - usage
+  - crash
+  - tracking
+created_at: 2026-01-12T22:19:08Z
+updated_at: 2026-01-12T22:19:08Z
+uuid: 00080ff4-9b7e-418b-b7dc-ca671160aee7
+---
+
+## Summary
+
+The new usage tracker accessed `cached_tokens` directly on provider usage objects, which caused an AttributeError for providers that omit that field. We now normalize usage objects at the boundary and default missing fields to 0, matching the old behavior.
+
+## Context
+
+This surfaced after the node processor refactor when the usage tracking logic moved into `usage_tracker.py` and lost the defensive `getattr` fallback. We missed it because the refactor did not include a regression test for usage objects without cached token data.
+
+## Root Cause
+
+Provider usage payloads are not uniform: some only include request/response tokens. The new code assumed the presence of `cached_tokens`, violating the implicit contract that missing fields should be treated as zero. Prevention: normalize usage objects at the type boundary and add a test for missing cached tokens.
+
+## Changes
+
+- Added a normalization helper for usage objects with defaults for missing fields.
+- Updated usage tracking to use the normalized shape.
+- Added a regression test covering missing `cached_tokens`.
+
+## Behavioral Impact
+
+Usage tracking no longer crashes when a provider omits cached token data; costs and totals still accumulate correctly with cached tokens treated as zero.
+
+## Related Cards
+
+None

tunacode_cli-0.1.37/.claude/debug_history/list-dir-tool-execution-error.md

@@ -0,0 +1,55 @@
+---
+title: list_dir halts agent on bad paths
+link: list-dir-tool-execution-error
+type: delta
+path: src/tunacode/tools/list_dir.py
+depth: 0
+seams: [M] module
+ontological_relations:
+  - relates_to: [[tools]]
+  - affects: [[tool-executor]]
+  - fixes: [[agent-halt-on-tool-error]]
+tags:
+  - tools
+  - error-handling
+  - list_dir
+  - ModelRetry
+created_at: 2026-01-07T22:54:00-08:00
+updated_at: 2026-01-07T23:15:00-08:00
+uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+---
+
+## Summary
+
+`list_dir` raised `FileNotFoundError` on non-existent directories, which `@base_tool` wrapped as `ToolExecutionError`. Since `ToolExecutionError` is in `NON_RETRYABLE_ERRORS`, the agent halted instead of letting the LLM self-correct with a valid path.
+
+## Context
+
+Surfaced when agent called `list_dir("/home/tuna/tunacode/apps")` - a directory that doesn't exist. Agent crashed with `ToolExecutionError` instead of retrying.
+
+## Root Cause
+
+Error propagation chain:
+1. `list_dir` raises `FileNotFoundError`
+2. `@base_tool` decorator wraps it as `ToolExecutionError`
+3. `tool_executor.py` has `ToolExecutionError` in `NON_RETRYABLE_ERRORS`
+4. Non-retryable errors propagate immediately, halting the agent
+
+First attempted fix: switch to `@file_tool` decorator. Failed because `@file_tool` expects required `filepath` positional arg, but `list_dir` has optional `directory="."`.
+
+## Changes
+
+- Import `ModelRetry` from `pydantic_ai.exceptions`
+- Replace `raise FileNotFoundError(...)` with `raise ModelRetry(...)`
+- Replace `raise NotADirectoryError(...)` with `raise ModelRetry(...)`
+- Keep `@base_tool` decorator (not `@file_tool`)
+
+## Behavioral Impact
+
+- Agent no longer halts on bad directory paths
+- LLM receives retry signal with error message, can self-correct
+- No change to valid path behavior
+
+## Related Cards
+
+- [[glob-grep-error-strings]] - similar smell: return error strings instead of raising

tunacode_cli-0.1.37/.claude/delta/2026-01-17-dangling-tool-calls.md

@@ -0,0 +1,171 @@
+---
+title: Dangling Tool Calls on User Abort
+link: dangling-tool-calls-abort
+type: delta
+path: src/tunacode/core/agents/main.py
+depth: 0
+seams: [M, S]
+ontological_relations:
+  - relates_to: [[conversation-turns]]
+  - affects: [[message-history]]
+  - fixes: [[api-error-on-next-request]]
+tags:
+  - bug
+  - abort-handling
+  - message-invariants
+  - tool-calls
+created_at: 2026-01-17T06:00:00Z
+updated_at: 2026-01-17T06:00:00Z
+uuid: d7c8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f
+---
+
+# Dangling Tool Calls on User Abort
+
+## Summary
+
+When a user aborted mid-tool-call (Ctrl+C or tool denial), the conversation history was left with a `ModelResponse` containing tool calls but no corresponding `ToolReturn` messages. The next API request failed because the provider expected tool returns for pending calls.
+
+## Context
+
+- File: `src/tunacode/core/agents/main.py`
+- PR: #246
+- Surfaces: On any abort during tool execution, next request fails
+
+## Root Cause
+
+**Missing invariant enforcement on exception path.**
+
+The message flow has an implicit invariant:
+
+```
+INVARIANT: Every ModelResponse with tool_calls MUST be followed by
+           matching ToolReturn(s) before the next ModelRequest
+```
+
+The happy path naturally maintains this - tool executes, result recorded. But `UserAbortError` breaks out of the loop BEFORE recording tool returns, violating the invariant.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Happy Path:                                                 │
+│   ModelResponse(tool_calls=[A, B])                          │
+│   → execute tools                                           │
+│   → ToolReturn(A), ToolReturn(B)                            │
+│   → ModelRequest (next turn)  ✓                             │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Abort Path (BEFORE fix):                                    │
+│   ModelResponse(tool_calls=[A, B])                          │
+│   → execute tool A                                          │
+│   → UserAbortError raised                                   │
+│   → messages still has ModelResponse with [A, B]            │
+│   → NO ToolReturn recorded                                  │
+│   → ModelRequest (next turn)  ✗ API ERROR                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Changes
+
+Added `_remove_dangling_tool_calls()` in the `except UserAbortError` handler:
+
+```python
+except UserAbortError:
+    cleanup_applied = _remove_dangling_tool_calls(
+        self.state_manager.session.messages,
+        self.state_manager.session.tool_call_args_by_id,
+    )
+    if cleanup_applied:
+        self.state_manager.session.update_token_count()
+    raise
+```
+
+The function walks backward through messages, removing any trailing `ModelResponse` that has unanswered tool calls, and clears cached args.
+
+## Behavioral Impact
+
+- User aborts mid-tool → dangling messages cleaned up
+- Next request works normally
+- Token count recalculated after cleanup
+
+## Prevention: What We Should Have Done
+
+### 1. Document Message Invariants
+
+The conversation turns doc now exists, but we missed documenting this invariant:
+
+```markdown
+## Message Invariants
+
+1. **Tool Call Pairing**: Every `ModelResponse` with tool_calls MUST
+   be followed by matching `ToolReturn(s)` before any new `ModelRequest`.
+
+2. **Exception Safety**: Any exception path that exits the agent loop
+   must restore message history to a valid state.
+```
+
+Add this to `docs/codebase-map/architecture/conversation-turns.md`.
+
+### 2. Add Exception Path Tests
+
+No test existed for abort scenarios:
+
+```python
+async def test_abort_mid_tool_call_cleans_up_messages():
+    """Verify abort during tool execution doesn't corrupt message history."""
+    # Arrange: Start a request that will trigger a tool call
+    # Act: Raise UserAbortError during tool execution
+    # Assert: messages ends with a valid state (no dangling tool calls)
+    # Assert: Next request succeeds
+```
+
+### 3. State Machine Should Track Message Validity
+
+The `ResponseState` tracks iteration progress but not message-level invariants. Consider:
+
+```python
+def validate_message_invariants(messages: list[Any]) -> bool:
+    """Return False if messages violate tool-call pairing invariant."""
+    # Walk through messages
+    # Track pending tool calls
+    # Verify each is answered before next ModelRequest
+```
+
+This could be called:
+- After each agent iteration (debug mode)
+- Before persisting session
+- On session load
+
+### 4. Design Pattern: Exception-Safe State Updates
+
+The broader lesson: **state mutations during a loop must be exception-safe**.
+
+Options:
+1. **Rollback on exception** (what we did) - detect and fix invalid state
+2. **Transactional updates** - only commit state after successful completion
+3. **Copy-on-write** - work on a copy, swap on success
+
+For message history, option 2 would be:
+```python
+# Don't append to session.messages during the loop
+# Collect in a local buffer
+# Merge to session.messages only on successful completion
+```
+
+This is partially what `agent_run.all_messages()` does - but the exception path didn't use it.
+
+## Related Cards
+
+- [[conversation-turns]] - Full turn flow documentation
+- [[message-history-persistence]] - How messages are persisted
+- [[response-state]] - State machine for agent progress
+
+## Lesson
+
+**Exception paths are first-class citizens.** When designing a stateful loop:
+
+1. List every exception that can exit the loop
+2. For each: what state is left behind?
+3. For each: is that state valid for the next operation?
+4. Add tests for exception scenarios
+
+The bug was obvious in hindsight - we just never traced what happens when `UserAbortError` interrupts the tool execution flow.

tunacode_cli-0.1.37/.claude/delta/remove-global-cache-user-config.md

@@ -0,0 +1,54 @@
+---
+title: Remove global cache state from user_configuration
+link: delta/remove-global-cache-user-config
+type: delta
+path: src/tunacode/utils/config/user_configuration.py
+depth: 3
+seams: [M] module
+ontological_relations:
+  - relates_to: [[utils]]
+  - affects: [[user_configuration.py]]
+tags:
+  - utils
+  - config
+  - state-management
+  - cleanup
+created_at: 2026-01-12T00:00:00Z
+updated_at: 2026-01-12T00:00:00Z
+uuid: 3383a720-0203-4a5b-9c1c-7b2f8c4d5e6f
+---
+
+## Summary
+
+Removed global mutable cache state from the user configuration module. The previous implementation used module-level `_config_fingerprint` and `_config_cache` variables for a fast-path optimization that was likely premature for configuration file handling.
+
+## Context
+
+The original `load_config()` function stored parsed config and its SHA-1 fingerprint in module globals to avoid re-parsing unchanged files. This added complexity and hidden state that could cause cache staleness issues.
+
+## Root Cause
+
+The fast-path optimization was unnecessary overhead for configuration files that:
+- Are small (typically < 1KB)
+- Are read infrequently (once per session or on demand)
+- May change externally between calls
+
+The cost of hashing and comparing fingerprints likely exceeded the cost of simply parsing the JSON.
+
+## Changes
+
+- Removed `_config_fingerprint` and `_config_cache` module-level globals
+- Simplified `load_config()` to read and parse file directly
+- Changed `save_config()` return type from `bool` to `None` (always returned `True`)
+- Changed `set_default_model()` return type from `bool` to `None`
+- Removed dead `except ConfigurationError: raise` code in `set_default_model()`
+
+## Behavioral Impact
+
+- Config loading is now simpler and more predictable
+- No functional change in behavior - callers already handled `None` returns and exceptions
+- Slightly more straightforward debugging with no hidden cache state
+
+## Related Cards
+
+- [[utils]] - Parent system