- Tool calls return strings, not structured objects; treat any result starting with `error:` as failure. `think` and `todo` return JSON-encoded strings on success, so parse only those tool outputs.
- Keep stdout clean for the final answer and send diagnostics/logs to stderr. Do not print progress chatter to stdout.
- Read-before-write is enforced for existing files (`write_file`, `edit_file`, `delete_file`) unless disabled with `--no-read-guard`. `/clear` resets this guard state, but context compaction does not.
- Filesystem access is root-based: `base_dir` plus optional `--add-dir` (read/write) and `--add-dir-ro` (read-only) roots. Absolute paths/globs are allowed only when they resolve under authorized roots; even in `--yolo`, filesystem root is blocked.
- `run_command` behavior depends on mode: sandboxed mode expects argument arrays, while `--yolo` also accepts shell strings. For large command output, read the generated `.swival/cmd_output_*.txt` file with `read_file`.
- Config precedence is strict: CLI > project `swival.toml` > global config > defaults. Config path values resolve relative to the config file location, not the current working directory.
- Instruction loading order matters: user-level `AGENTS.md` is prepended before project-level `AGENTS.md`, with a shared size budget. `--system-prompt` and `--no-instructions` bypass normal instruction-file loading.
- Repeating the same tool error triggers automatic guardrail prompts (`IMPORTANT`/`STOP`) and can change loop behavior. If a tool keeps failing, adjust arguments or approach immediately instead of retrying unchanged.
- Reviewer integration is protocol-based: exit 0 accepts, 1 retries with reviewer stdout as feedback, and 2 accepts-as-is on reviewer failure. Review retries are capped and reflected in report stats/timeline.
- The source code of the Zig standard library is in `/opt/zig/lib/std` for reference when needed.