Open Questions
Areas where the excavation is incomplete or where implementation decisions require judgment.
Updated: January 2026 from v0.0.1769212917 deep excavation
RESOLVED Questions
1. Compaction Algorithm Details
Status: Resolved - documented in implementation/06-context-window.md
Key findings:
- Threshold: 100,000 tokens
- Trigger: Total tokens (input + cache_creation + cache_read + output) exceeds threshold
- Prompt: 5-section summary format (Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve)
- Result: All messages replaced with single user message containing the summary
2. Course Correction Thresholds
Status: Resolved - documented in enhancements/12-course-correction.md
Key findings:
- Trigger: 5+ tool calls AND at least one file edit (edit_file or create_file)
- Prevents re-correction: Skips if last user message was already a course correction
- Model: Gemini 3 Pro Preview
- Temperature: 0.1 (very low for consistency)
3. Skills System Internals
Status: Resolved - documented in enhancements/16-skills.md
Key findings:
- 9 discovery locations in priority order (workspace first, built-in last)
- 5 built-in skills: building-skills, bookkeeper, painter, code-review, migrating-to-skills
- Progressive disclosure: ~100 tokens at startup, <5k when loaded
- File watching with 200ms debounce
4. Permission Rules
Status: Resolved - documented in enhancements/15-permissions.md
Key findings:
- MCP tools (
mcp__*) - auto-allow - Toolbox tools (
tb__*) - auto-allow - Read-only commands (ls, cat, grep, git status) - auto-allow
- Build/test commands (npm test, pytest, cargo build) - auto-allow
- Destructive commands (rm -rf, git push) - require ask
- Default for Bash: ask
PARTIALLY RESOLVED Questions
5. Exact Token Counting
What we know:
- Bytes per token ratio: 3.5
- Max file size cap: 32,768 bytes (32KB)
- File token estimation:
ceil(min(fileSize, 32768) / 3.5) - Character fallback: 4 chars per token
Still unknown:
- Exact tokenizer used for each provider
- How cache tokens are counted separately
- Model-specific adjustments
Documented in: implementation/06-context-window.md
6. MCP Server Lifecycle
What we know:
- Reconnection uses exponential backoff with elapsed time tracking
- gRPC settings available:
initial_reconnect_backoff_ms,max_reconnect_backoff_ms
Still unknown:
- Exact backoff algorithm parameters
- Health check frequency
- Tool schema caching strategy
Documented in: implementation/04-tool-system.md (basic MCP integration)
7. Thread Persistence Format
Status: Mostly resolved - documented in implementation/11-threads.md
What we know:
- Thread ID format:
T-{uuid}(e.g.,T-a38f981d-52da-47b1-818c-fbaa9ab56e0c) - Complete Thread schema:
v,id,created,messages,relationships,env, etc. - Persistence: Dirty tracking, 100ms debounced flush, max 3 threads per batch
- Relationships: fork, handoff, mention (bidirectional)
- Version-based optimistic concurrency
- Exclusive write access pattern
Still unknown:
- Server-side sync protocol details
- Conflict resolution strategy for concurrent edits
REMAINING Open Questions
8. DTW (Durable Thread Worker) Architecture
Experimental feature for durable execution. Has executor/observer modes but full state machine unclear.
9. Credit System Implementation
Credits tracked for usage, free mode has limits. Calculation formula and policies unknown.
10. Walkthrough Implementation
New feature using walkthrough-planner subagent. Exact diagram generation and interaction flow unclear.
Key Constants Summary
| Constant | Value | Purpose |
|---|---|---|
| Bytes per token | 3.5 | File token estimation |
| Max file size (estimation) | 32,768 bytes | Per-file cap for budgeting |
| Max file size (Read tool) | 65,536 bytes | Hard limit for Read tool |
| Handoff token budget | 25,000 | Handoff file tokens (v0.0.1769212917) |
| Max handoff files | 10 | Files in handoff (v0.0.1769212917) |
| Compaction threshold | 100,000 | Tokens before compaction |
| Course correction trigger | 5 | Min tool calls |
| Skill watch debounce | 200 ms | File change debounce |
Note: Handoff constants changed between versions (earlier versions used 50,000/20). The spec uses values from v0.0.1769212917.
Updated January 2026 from v0.0.1769212917 deep excavation