# AGENTS.md - Machine Instructions for g3

**Purpose**: Machine-specific instructions for AI agents working with this codebase.  
**For code locations**: See Workspace Memory (loaded automatically)  
**For project overview**: See [README.md](README.md)

## Critical Invariants

### MUST Hold

1. **Tool calls must be valid JSON** - The streaming parser expects well-formed tool calls
2. **Context window limits must be respected** - Exceeding limits causes API errors
3. **Provider trait implementations must be Send + Sync** - Required for async runtime
4. **Session IDs must be unique** - Used for log file paths and TODO scoping
5. **File paths in tools support tilde expansion** - `~` expands to home directory
6. **Streaming is preferred** - Non-streaming requests block UI
7. **Tool results are size-limited** - Large outputs are truncated or thinned automatically
8. **String slicing must be UTF-8 safe** - Use `chars().take(n)` or `char_indices()`, never byte slicing like `&s[..n]` on user-facing strings

### MUST NOT Do

1. **Never block the async runtime** - Use `tokio::spawn` for CPU-intensive work
2. **Never store secrets in logs** - API keys are redacted in error logs
3. **Never modify files outside working directory without explicit permission**
4. **Never assume tool results fit in context** - Large results are thinned automatically
5. **Never use byte-index string slicing on text with potential multi-byte characters** - Causes panics on emoji, CJK, box-drawing chars

## Adding Features

- **New tool**: Add definition in `tool_definitions.rs`, implement in `tools/`, add dispatch case
- **New provider**: Implement `LLMProvider` trait in `g3-providers`
- **New CLI mode**: Add to CLI args, implement handler in `g3-cli`
- **New config option**: Add to `g3-config` structs

## Dangerous Code Paths

These areas have subtle bugs if modified incorrectly:

| Area | Risk |
|------|------|
| **Context window management** | Incorrect token estimates cause context overflow |
| **Streaming parser** | Partial JSON across chunks causes parsing failures |
| **Tool dispatch** | Missing dispatch cases cause silent failures |
| **Retry logic** | Aggressive retries hit rate limits harder |
| **Parser sanitization** | Inline JSON can trigger false tool call detection |

## Do's and Don'ts

### Do
- ✅ Run `cargo check` after modifications
- ✅ Run `cargo test` before committing
- ✅ Update tool definitions when adding tools
- ✅ Add tests for new functionality
- ✅ Keep functions under 80 lines

### Don't
- ❌ Add blocking code in async contexts
- ❌ Store sensitive data in plain text
- ❌ Ignore error handling
- ❌ Create deeply nested conditionals (>6 levels)
- ❌ Add external dependencies for simple tasks

## Common Incorrect Assumptions

1. **"All providers support tool calling"** - Embedded models use JSON fallback
2. **"Context window is unlimited"** - Each provider has limits (4k-200k tokens)
3. **"Tool results are always small"** - File reads can return megabytes
4. **"Sessions persist across runs"** - Sessions are ephemeral by default
5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility)