Limitations
Where ivar's guard stops, and what ivar does not isolate or coordinate for you.
The write guard is a guardrail
Repos you haven't promoted are guarded: ivar keeps the agent's writes inside the feature and refuses commits on the default branch. It is a guardrail against agent mistakes, not a security boundary. (Kernel-enforced on Linux; see limitations below.)
The write guard is designed to catch unintended edits, wrong-directory file creation, or agents straying outside the promoted repositories of a feature. It does not protect against a determined process executing arbitrary local code as your user.
By platform and launcher
Write enforcement depends on the operating system and how the session was launched:
- On Linux (kernel ≥ 5.13 with Landlock): When launched via
ivar session startin a terminal (with a TTY), ivar applies an irreversible, kernel-enforcedLandlockwrite sandbox to the harness process before execution. Writes to unpromoted repositories or outside allowed session roots fail directly at the syscall layer withEACCES(Permission denied), including writes from Bash subprocesses. - On macOS, on kernels without Landlock, and under
ivar session connect: Kernel sandboxing is unavailable. Protection relies on filesystem permissions where only the worktree root loses its write bits (mode & !0o222), and files in subfolders stay writable. - Under
ivar session start --provider t3: T3 Code starts the agent, not ivar, so there is no kernel sandbox on any platform. The tool guard hook is the only enforcement, and a shell command can write outside the session's writable set.
Other worktrees of a promoted repo
On Linux, when a repository is promoted for a feature, Landlock grants write
access to the entire .ivar/repos/<repo>/ directory.
This allows ivar to create worktrees and handle Git operations smoothly, but it means that other feature worktrees and the default branch checkout of that same promoted repo remain writable at the kernel level.
The hook and the view dir
In sessions launched by ivar session start, the advisory tool guard hook
does not execute in the session's view directory. As a result, when an agent
attempts an unauthorized write under Landlock on Linux, it sees an EACCES
error from the kernel rather than an advisory diagnostic message naming
ivar feature promote.
Shared state outside git
A Git worktree gives each feature its own working tree and files, but it does not isolate shared external daemon state such as databases, caches, or background services.
Two features promoting the same repository share the same local database unless
configured otherwise. To isolate services per session, use session hooks
(.ivar/setups/<repo>.session.sh) which run on every ivar session start with
IVAR_SESSION_ID exported:
# docker compose: unique project name per session
export COMPOSE_PROJECT_NAME="${IVAR_SESSION_ID}"
docker compose up -d
# postgres: dedicated database per session
createdb "app_${IVAR_SESSION_ID}"
export DATABASE_URL="postgres:///app_${IVAR_SESSION_ID}"Ports
A session reserves port allocations in local state, preventing two ivar sessions from being assigned identical ports.
However, ivar does not proxy network traffic or force arbitrary background processes to bind to their assigned port. If a process ignores its environment configuration or crashes without releasing a socket, collisions can still occur.
Local state is disposable
Everything stored under .ivar/ (except versioned configuration in .ivar/skills/
and setups) is local derived state: bare clones, worktrees, socket reservations,
and SQLite indexes.
Deleting .ivar/ discards no committed history or pushed branches—it requires
only re-cloning repositories and recreating active sessions. Never store
uncommitted artifacts or credentials in .ivar/.
No atomic push across repos
When delivering across multiple repositories, local fast-forward merges into
the default branch are verified and coordinated locally. However, the subsequent
remote git push operations are executed independently against each remote.
There is no distributed transaction across distinct Git remotes. If a network failure occurs during push, ivar reports the failure and indicates which repositories were pushed and which remain ahead locally. Merges are not rolled back across remotes to compensate for push failures.
What protects the default branch
Protection for the default branch is multi-layered:
- Pre-commit hook:
ivar syncconfigures a worktree-local Gitpre-commithook on the default-branch worktree that rejects direct commits. (Bypassed only during programmatic squash delivery landings or with explicit--no-verify). - Worktree root write bits: Default branch worktrees have write permissions removed on the root directory to prevent accidental file creation or deletion at the repository root.
- Landlock write sandbox (on Linux): Restricts unpromoted repository trees
at the syscall level during
ivar session start. - Structured tool guard: The advisory hook inspects structured edit tool invocations when running in supported harnesses.
Hall memory
- Capture is local to the machine. Observations, handoffs and messages live in
.ivar/memory.dband never cross git; only the pages underdocs/memory/do. - Each provider records only the events its hooks expose. OpenCode records no session end and flags no failed tool; T3 Code records the end when you archive the thread.
- A session's spool is capped at 8 MiB, which bounds the disk one session can
fill while no drain runs. Past the cap, events are dropped and
ivar doctorreportsmemory.spool_dropped. session.*observations are deleted 30 days after the session's last one. Delivery, memory, handoff and message events are kept.- The memory tools never commit. A page they write stays uncommitted until you
commit it, and
ivar doctorreportsmemory.page_uncommitted. - The delivery review gate reads what the spool drain stored. A failed drain
warns
deliver.memory_drain_failed, and events still in the spool are not in the review.
See Hall memory.
Structured tool guard and device writes
The advisory tool guard inspects tool calls from supported harnesses:
- Multi-target validation: For edit tools submitting multiple file patches (such as hashline headers,
MV, or patch blocks in a single payload), every target path is validated. If any target belongs to an unpromoted repository or unauthorized directory, the entire invocation is blocked and the first offending target is named. - Device writes: Writes directed to device paths such as
xd://ast_editor mutatingxd://lspoperations (rename,rename_file, code actions) are unpacked and their target file paths checked before execution. - LSP rename residual: An allowed
xd://lsprename operation targeting a file inside a promoted repo may cause the language server daemon to edit references across unpromoted files. On Linux, Landlock restricts these secondary filesystem writes at the syscall level.