- **Tool failures are data, not exceptions.** Return recoverable failures to the model as lowercase `error: ...` strings so the loop can continue.
- **CLI fatal errors use a separate contract.** User-facing failures are `Error: ...` on stderr with fixed exit codes: `1` for runtime/config errors and `2` for max-turn exhaustion.
- **Read-before-write is enforced by default.** Existing files must be read (or previously written in-session) before edit/overwrite/delete; this also applies to `write_file` rename destination when it already exists.
- **Sandboxing is based on resolved paths.** Access is limited to `base_dir` plus explicit extra roots (`--add-dir` for read-write, `--add-dir-ro` and skill paths for read-only), with symlink escapes blocked.
- **`--yolo` is broad but not absolute.** It relaxes sandbox and command restrictions, but filesystem root access is still blocked.
- **Tool availability is dynamic.** `run_command` exists only when command execution is enabled, and `use_skill` exists only when skills are discovered.
- **Config merging uses sentinel precedence.** Effective values are CLI > project `swival.toml` > global config > defaults via `_UNSET` resolution, so new flags must follow this wiring.
- **Core return shapes are stable APIs.** Keep contracts like `run_agent_loop -> (answer, exhausted)` and `handle_tool_call -> (tool_msg, metadata{name, arguments, elapsed, succeeded})` intact.
- **Large outputs must be context-safe.** Follow existing caps/truncation/continuation patterns and use `.swival/` spill files for pagination when needed.
- **`.swival/` is the runtime state boundary.** History, todo state, command spill files, and trash metadata live there and are relied on across modules and tests.
- **I/O split is strict for automation.** Final answer goes to stdout; diagnostics go to stderr (and are suppressible with `--quiet`).
- **Provider behavior is intentionally asymmetrical.** LM Studio may auto-discover/reload context, while HuggingFace/OpenRouter require explicit model and API-key resolution rules.