Safety and drift
Safety and drift
Section titled “Safety and drift”Agents Pack prefers a clear refusal over a speculative merge. These rules protect your work during init, sync, install, update, rollback, and eject.
Core safety rules
Section titled “Core safety rules”- Preview is honest.
--dry-runuses the real planner without writing provider files, installation state, transaction state, or the pack cache. - Unexpected edits stop the operation. Agents Pack does not silently merge or overwrite drifted generated content.
- Shared files stay shared. Codex instructions use a marked block inside
AGENTS.md; text outside that block remains user-owned. - Writes are transactional. A failed operation restores the previous filesystem state.
- Only one mutation runs at a time. Operation locks prevent concurrent commands from writing over one another.
- Interrupted work is recoverable. Rerunning a mutating command recovers unfinished transaction state before replanning.
- Paths are contained. Pack sources and generated paths cannot escape their allowed repository or home roots.
- Symlinks are not adopted as managed outputs.
- User-owned canonical source survives official update, rollback, and ejection.
What “drift” means
Section titled “What “drift” means”Managed outputs are reported by agents-pack status as:
| State | Meaning |
|---|---|
| clean | Matches what Agents Pack last wrote |
| missing | Expected managed content is gone |
| modified | Content differs from the recorded managed output |
| malformed | Structure or markers are invalid |
If a file is modified, missing, or malformed, mutating commands stop so Agents Pack does not guess whether an unexpected edit is safe to discard. There is no automatic “discard my edits” or three-way prose merge command.
Typical recovery
Section titled “Typical recovery”- Run
agents-pack status. - Inspect the reported file or managed block.
- If you customized an official skill or subagent in place: restore the generated file, fork it, then edit the canonical user-owned copy.
- If it is user-owned: edit
.agents-pack/user/or~/.agents-pack/user/, restore the generated copy, thensync. - Rerun
status, then retry the command.
Status is always read-only
Section titled “Status is always read-only”agents-pack statusStatus reports scope, pack ID and version, official or local source, pin state, selected agents, official and user-owned component names, every managed output’s health, and warnings such as unsynchronized user-owned source.
If a previous mutation was interrupted, status reports that recovery is required but does not modify anything. Rerun the interrupted mutating command to recover safely.
Confirmation and dry runs
Section titled “Confirmation and dry runs”Interactive confirmation requires y or yes — pressing Enter alone does not apply a plan. Non-interactive shells need --yes (or --dry-run when you only want the plan).