Skip to content

Guardrails

Agents run with their backend’s own permissions in Itervox’s worktrees and in the tmux sessions you start with New session. Without limits, an agent can git push --force, push to main, merge its own pull request or run a deploy. Itervox’s guardrails (on by default, guardrails:) refuse those operations, or hold them for a human:

The agent tries to…What happens
push its issue branch (a fast-forward)allowed
push to main, master, develop, the base branch or any other branchrefused
push a tagrefused
force-push or delete its issue branchrefused, unless guardrails.allow_force_push
git push --no-verify (or an abbreviation git accepts, such as --no-verif), git -c core.hooksPath=…, or a config include (git -c include.path=…)refused (it would skip the guardrail hook), except a core.hooksPath override on a read-only git command
git -c core.hooksPath=/dev/null ls-files … and the other read-only git commandsallowed; the override is dropped, so git still sees the guardrail hooks
gh pr merge, glab mr merge, a merge through gh api / glab apirefused
git merge while the default branch is checked outrefused
a command in guardrails.approval_commands (vercel --prod, kubectl apply, …)waits for a human; runs once on approve
push a change to CI workflows or CI config (guardrails.lanes.human)waits for a human; pushes once on approve; never auto-merged
push a change to a guardrails.lanes.second_opinion fileallowed; merge_pr then needs a reviewer on another backend
anything elseruns unchanged

Every refusal tells the agent what to do instead — push with git push origin HEAD:refs/heads/<issue branch>, merge the base into the issue branch rather than rebasing, leave merging to Itervox’s merge policy or a human.

The issue branch is the branch Itervox checked out for the issue (the worktree’s itervox/<issue> branch, the issue’s tracked branch, or the branch of its open pull request). An agent that creates a branch of its own for the issue may push it once it has it checked out: the first push of a new branch that is not protected is accepted, and that branch then takes the run’s pushes (Itervox also tracks it as the issue’s branch after the turn). A second new branch in the same run is refused.

For a tmux session started with New session, the issue branch is the branch checked out in the session’s folder when it starts; on main (or another protected branch) there is none, and the agent may only push a new branch it creates.

Read-only git commands may override the hooks path

Section titled “Read-only git commands may override the hooks path”

Some agents disable hooks for their own read-only git calls — Claude Code runs git -c core.hooksPath=/dev/null … ls-files --error-unmatch -- …. A git command that runs no hook cannot skip one, so the shim lets a core.hooksPath override (-c core.hooksPath=… or --config-env core.hooksPath=…) through when the git command is exactly one of these builtins:

blame, cat-file, check-attr, check-ignore, check-ref-format, cherry, count-objects, diff-files, diff-index, diff-tree, for-each-ref, grep, log, ls-files, ls-tree, merge-base, name-rev, rev-list, rev-parse, shortlog, show, show-branch, show-ref, var, version

Each reads the repository without writing the index or a ref, so git runs no hook for it. The read-only forms of two more builtins are allowed the same way: git remote, git remote -v and git remote get-url …, and a git config that only reads (--get, --get-all, --get-regexp, --list, the get and list subcommands, or one key and no value, as in git config user.name); a config or remote write is refused. An alias cannot stand in for one: git ignores an alias that has a builtin’s name. The shim drops the override before it runs git, so git, and any program it starts (a pager, an external diff), still sees the guardrail hooks.

status, diff and describe are allowed too, although they can run the post-index-change hook when they refresh the index: because the override is dropped, that hook runs as configured, so nothing is skipped. Claude Code runs git status --short this way on every turn.

Everything else with a hooks-path override stays refused as hook_bypass:

  • any other git command, including commit, push, merge, rebase, am, checkout, switch, pull and fetch, and a config or remote command that writes;
  • a -c alias.…, -c include.path=… or -c includeIf.….path=… on the same command line;
  • a global option the shim does not recognise exactly (git does not accept abbreviations either), and --exec-path, --help, --super-prefix or --list-cmds.

When an agent runs a command that matches guardrails.approval_commands, the command blocks and the issue shows an input request — on the dashboard, in the Sessions panel, in the Mac app and as a tracker comment:

Agent wants to run: vercel --prod

Reply approve (or yes, ok, allow) to run it once; any other reply rejects it, and the agent is told your reply as the reason (so no, deploy to staging first is useful). Dismissing the request rejects it too. The run keeps going while it waits — nothing is paused or resumed.

Answer an approval

Needs attention row for DEMO-4: Agent wants to run vercel --prod, opened for reply, with the text no, deploy to staging first in the reply box Needs attention row for DEMO-4: Agent wants to run vercel --prod, opened for reply, with the text no, deploy to staging first in the reply box
The request waits in Needs attention. Reply approve to run the command once, or anything else to refuse it with a reason.
The issue's Now panel: the build passed, the last tool call is Bash vercel --prod, and Waiting for approval: Agent wants to run vercel --prod The issue's Now panel: the build passed, the last tool call is Bash vercel --prod, and Waiting for approval: Agent wants to run vercel --prod
The issue's Now panel shows the command the run is waiting on.
  • An agent cannot answer its own request: itervox action provide-input is ignored for it, and the guarded agent’s environment has no ITERVOX_API_TOKEN.
  • If the agent’s tool times out while waiting, the request stays open. When the agent runs the exact same command again it joins that request, and an approval given in the meantime runs it then — still once.
  • When the run ends, an open request is dropped and the command is refused.
  • The agent prints nothing while it waits. That silence does not count against agent.read_timeout_ms or agent.stall_timeout_ms, so take the time you need; there is no reason to raise them for approvals. Both start again from your answer. agent.turn_timeout_ms (one hour by default) still bounds the wait: when it runs out, the run ends and the request is dropped. This applies to held pipeline pushes too (below).
  • Tmux sessions have no approval channel: matching commands are refused there, and the agent is told to ask you to run them.

Patterns are glob tokens: the first matches the program name, the rest must each match an argument, in order, with other arguments allowed between them. kubectl apply matches kubectl -n prod apply -f k8s/; helm upgrade *-prod matches helm upgrade api-prod ./chart. Setting approval_commands replaces the default list.

A deploy command is often safe against one environment and not another: terraform apply in the dev workspace is routine, in prod it should wait for a human. An approval_commands entry may be an object with a when_env map; the command is held only when every named environment variable’s value matches its glob in the environment the command runs with:

guardrails:
approval_commands:
- "vercel --prod" # plain: always held, as before
- match: "terraform apply"
when_env: {TF_WORKSPACE: "prod*"} # held for prod, prod-eu, …
- match: "kubectl apply"
when_env: {KUBECONFIG: "*prod*"}
- match: "helm upgrade"
when_env: {DEPLOY_ENV: "!dev*"} # held unless DEPLOY_ENV is dev…
  • match has the plain-entry syntax. The globs use * (anything) and ? (one character); a leading ! negates. An unset variable is the empty string, so prod* lets a command with the variable unset through, while !dev* holds it — write the negated form when an unset variable should fail closed.
  • The shim checks the environment the program is really started with, at exec time: TF_WORKSPACE=prod terraform apply, an export earlier in the session and a value computed by the shell all count.
  • The condition reads environment variables only. A target chosen by a flag or a file is not an environment variable: kubectl --context prod apply is matched by the pattern itself (match: "kubectl --context prod* apply"), and kubectl’s current context in ~/.kube/config is not seen at all. Pick the variable your tool really reads (TF_WORKSPACE, KUBECONFIG, AWS_PROFILE, CLOUDSDK_CORE_PROJECT, …).
  • A plain string entry still matches in every environment; if a plain kubectl apply is in the list, scoping another kubectl apply entry changes nothing. Remember that a list replaces the defaults, which hold kubectl apply and terraform apply unconditionally.
  • An entry that cannot be applied as written (no match, an unknown key, a when_env that is not a map of variable names to strings) is a startup error, never silently dropped.

See Lanes for the full guide, and the pipeline-guard demo to watch a held pipeline push on your machine.

Where a push goes is one question; what it changes is another. An agent fixing a red build could add continue-on-error: true to .github/workflows/ci.yml on its own issue branch, and the push would be a perfectly ordinary fast-forward. Lanes draw the line:

An agent may change what CI checks, never how CI checks.

The pre-push hook lists the files each push changes and puts every one in a lane, the highest that matches:

LaneFilesWhat happens
humanguardrails.lanes.human (default below)The push waits for a human approval, like an approval command; merge_pr never merges the issue’s pull request
second_opinionguardrails.lanes.second_opinion (default: none)The push goes through; merge_pr refuses until a reviewer on a different backend than the writer’s has approved, after the last such push
autoeverything elseUnchanged

The default human lane is deliberately short — files that decide how a change is checked rather than what it does:

.github/** .gitlab-ci.yml .circleci/**
.itervox/** !.itervox/handoff/** WORKFLOW.md
CODEOWNERS .github/CODEOWNERS
jest.config.* vitest.config.* pytest.ini .coveragerc codecov.yml
.golangci.yml Makefile

.itervox/handoff/ is excluded because every run commits its handoff there. pyproject.toml, package.json and go.mod are not in it: their test and coverage sections cannot be told apart from dependencies by path. Add what your project uses (setup.cfg, tox.ini, noxfile.py, turbo.json, a scripts/ci/** directory, …). Setting human replaces the default list, so copy it to keep it; human: [] turns the lane off.

Patterns are gitignore-style, over paths relative to the repository root:

  • ** matches any number of directories, * and ? stay inside one, […] is a class;
  • a pattern without a / matches that name at any depth (Makefile matches services/api/Makefile); one with a / (or a leading /) is anchored at the root;
  • a pattern that matches a directory matches everything under it;
  • !pattern excludes what an earlier pattern of the same lane matched;
  • matching is case-sensitive, like git paths.

Which files count. For a branch the remote already has, the files that differ between the remote tip and the pushed commit — and that also differ from the base branch, so merging the base in (as the guardrails tell agents to do) does not count as changing what the base changed. For a new branch, the files that differ from its merge base with the issue’s base branch: the pull request’s base (the blocker’s branch for a stacked PR, workspace.base_branch otherwise), then agent.base_branch, origin/HEAD, origin/main and main, first found wins. Renames count as a deletion and an addition, so moving a workflow away is caught too. When the changed files cannot be listed, the push is held for a human.

A held push shows as an input request labelled Pipeline change, on the dashboard, in the Mac app, on your phone and as a tracker comment, with the files it changes (up to ten, then “and N more”):

Pipeline change: the agent wants to push changes to .github/workflows/ci.yml (git push origin refs/heads/itervox/eng-1)

It works exactly like an approval command: reply approve to let that push through once (new commits ask again); any other reply, or dismissing it, refuses the push, and the agent is told your reply. The agent cannot answer its own request. Tmux sessions have no approval channel: the push is refused and the agent is told to ask you.

Approve a held push from your phone (through the hub)

The hub on a phone: Needs you, one card for DEMO-1 in web-app labelled Pipeline change, changes .github/workflows/ci.yml (+1), with an Answer button The hub on a phone: Needs you, one card for DEMO-1 in web-app labelled Pipeline change, changes .github/workflows/ci.yml (+1), with an Answer button
The hub's phone page lists the held push with its first file.
The DEMO-1 page on a phone: Waiting for your approval, the pipeline change with .github/workflows/ci.yml and Makefile, Approve and Reject buttons, and the run's Now panel below The DEMO-1 page on a phone: Waiting for your approval, the pipeline change with .github/workflows/ci.yml and Makefile, Approve and Reject buttons, and the run's Now panel below
Answer opens the issue: the files the push changes sit right above Approve and Reject.

See Your phone to set the phone up.

Merge policy. Pushes that the hook lets through in the human or second_opinion lane are recorded for the issue (kept across restarts in .itervox/push_lanes.json, dropped when the issue is done). merge_pr checks that record before anything else: an issue whose pushes changed human-lane files is refused with lane_human — even after you approved the push, merging it stays with a human. A second-opinion issue is refused with lane_second_opinion until a reviewer whose backend (claude, codex, …) is not one the writing runs used has recorded an approving verdict after the last second-opinion push.

guardrails:
lanes:
human: [".github/**", ".gitlab-ci.yml", ".circleci/**", ".itervox/**", "!.itervox/handoff/**",
"WORKFLOW.md", "CODEOWNERS", ".github/CODEOWNERS", "jest.config.*", "vitest.config.*",
"pytest.ini", ".coveragerc", "codecov.yml", ".golangci.yml", "Makefile",
"tox.ini"] # your own
second_opinion: ["internal/auth/**", "migrations/**"]

Check the lanes with itervox doctor. Its Lanes section prints the human and second-opinion globs in effect ((default) when human is not set, off for an empty list) and warns when the human lane is off. It also warns when a profile’s verify check is defined by a file the agent could change on its own. make test runs whatever the Makefile says, so a Makefile outside the human lane lets the agent change how the check checks:

Lanes
human: .github/**, WORKFLOW.md
second_opinion: off
WARNING: implementer: verify check test runs `make test`, defined by Makefile, which the agent can change without a human; add it to guardrails.lanes.human
implementer: require_evidence lint is agent-reported, not daemon-run (add a verify check of the same name to have the daemon run it)

The files doctor looks for: Makefile for make, package.json for npm, pnpm and yarn, pytest.ini, pyproject.toml, setup.cfg, tox.ini and conftest.py for pytest, tox.ini for tox, justfile for just, and a script run by relative path (./scripts/test.sh, bash scripts/ci.sh). A cd dir && before the command is followed. go test is not on the list: what it runs is the code under test. The last line lists require_evidence names that no verify check runs, so the agent’s own evidence file is the only proof (ci is the pull request’s CI checks and is never listed). None of this changes doctor’s exit code, and itervox config show ends with the same section.

Every refused or approved operation is logged (guardrails: refused …, guardrails: approved …; the command is redacted, never a URL with credentials), written to the issue’s log, and every refusal is recorded in Recent failures (kind guardrail) and counted in itervox_guardrail_blocks_total{kind} — branch, force_push, delete, tag, hook_bypass, self_merge, approval_rejected, approval_unavailable, lane_human (a pipeline push refused with no one to approve it, or left unanswered), lane_rejected (a pipeline push a human rejected or dismissed) and patch_out (an agent of a push: daemon profile tried to push or to open or change a pull request; see Patches only). An approved pipeline push and a refused merge_pr are logged and written to the issue’s log.

Each guarded run gets a private directory with:

  • shims — small scripts named git, gh, glab and the programs of approval_commands, put first on the agent’s PATH. A shim runs the itervox binary, which inspects the arguments and either refuses, asks for an approval, or replaces itself with the real program (found on PATH past the shims), passing the same arguments, input, environment and exit status;
  • git hooks — core.hooksPath points at the directory through GIT_CONFIG_PARAMETERS. Its pre-push checks every ref the push updates; every hook then chains to your repository’s own hooks directory (its core.hooksPath or .git/hooks), so your hooks still run.

Shims and hooks reach the daemon only through token-gated endpoints (/api/v1/agent-actions/{issue}/guardrail/…) with a per-run token: one records a refusal, one raises and reads an approval request, and one records the lane a let-through push reached (a push whose lane cannot be recorded is refused). Nothing on the daemon runs a command for an agent. Itervox’s own git commands are not affected.

  • End to end. The shim and hook tests run real git against a bare remote, with the test binary standing in for itervox, through the same shims and hooks a run gets, including commands quoted and spaced the ways a shell accepts.
  • Fuzzing. Go fuzz targets cover the command classifier (FuzzDecide, FuzzMatchApproval), the lane matcher (FuzzLanes) and the signed-check records (FuzzRecordVerify, FuzzRecordByteFlip). They check that the classifier is deterministic, that adding arguments never relaxes a refusal, that spellings git treats as the same (CORE.HOOKSPATH, -cKEY=VALUE, --config-env, --no-verif) and gh/glab flags placed between the words stay refused, and that the glob and lane matchers agree with independent reference implementations. They also check that path spellings (./, //, a trailing /, \) never change a lane, and that no byte string verifies as a record the key did not sign. The seeds run with every go test; make fuzz runs each target for FUZZTIME (30s by default).
  • Cost per call. scripts/guardrails-shim-latency.sh times git rev-parse HEAD and git status --short through the shim and directly. On a shared 4-CPU Linux test machine under load, the shim added about 8–9 ms at p50 and 10–15 ms at p95 per git call (git alone: about 2 ms). Most of that is starting sh and the itervox binary; the decision itself is microseconds. Expect different numbers on your machine.

See Signed checks for the full guide.

The writer is never the judge. An agent saying “done” is a claim, and with require_evidence the agent that wrote the fix also writes the proof. With a profile’s verify list, the daemon runs each check itself, on the tree the agent left, and signs what it saw: done is a claim, a signed run on the same tree is proof.

agent:
profiles:
implementer:
require_evidence: [test]
verify:
- name: test
run: make test

After the agent’s last turn, before the run counts as succeeded (and before the handoff, the pull request push or the completion move), the worker runs each command in the worktree. A non-zero exit, a timeout or a check that changes the tree holds the run input required with the check’s name and exit code, exactly like missing evidence; every check exiting 0 lets the run succeed.

What is recorded. One JSON line per check in .itervox/attestations/<identifier>/<run timestamp>_<profile>.jsonl next to WORKFLOW.md, followed by a seal line with the tree after the last check:

FieldMeaning
command, argv, pipefailThe configured command (redacted) and how it ran: bash -lc with set -o pipefail, so make test | tail records make’s status, not tail’s.
exit_code, timed_out, errorThe process’s real exit status; -1 when it was killed or could not start.
started_at, duration_msWhen it ran and for how long.
output_sha256, output_tailSHA-256 of the complete combined stdout and stderr; its last 4 KiB, redacted like log lines.
tree_hash, tree_excludes, headThe git tree of the working tree when the check started — tracked files plus untracked files git does not ignore, committed or not, without .itervox/handoff/ and .itervox/evidence/ — and the HEAD commit.
key_id, sigThe signing key’s id and an ed25519 signature over every other field.

The tree hash is computed with a private copy of the index (GIT_INDEX_FILE in a temporary directory, git add -A, git write-tree), so your index, staged changes and git status are untouched.

Verifying. A record is verified when its signature is valid for the daemon’s key and its tree is the run’s final tree (the seal’s). The dashboard API reports this per record (GET /api/v1/issues/{identifier}/attestations), and the dashboard shows it in the issue panel’s Signed checks section: each run’s checks with their exit code, duration, short tree hash and whether the record and the run’s seal verify; anyone with the public key can check a file offline, and --tree proves the records are for the code in front of them:

Terminal window
itervox attest verify .itervox/attestations/ENG-1/2026-11-14T10-00-00.000Z_implementer.jsonl --tree ../worktree

A record copied from an earlier tree fails --tree; an edited exit code or output hash fails the signature.

The key. The daemon (and itervox run) creates an ed25519 key pair the first time it starts with a profile that has verify: .itervox/attest.key (mode 0600, gitignored) and .itervox/attest.pub (share it to let others verify). The private key is on the process isolation deny list, and under isolation: process the checks themselves run in the agent’s sandbox, so neither the agent nor the code it wrote can read the key to forge a record.

What it does not prove. A signature says this daemon ran this command on this tree and saw this exit code; it does not say the command tests the right thing. Keep verify commands in WORKFLOW.md, not in files the agent edits: make test runs the Makefile on the agent’s branch, so keep it in the human lane (it is by default); itervox doctor warns about a check whose definition is not. Without isolation: process an agent runs as your user and could read the key; the signature then proves only that the record was not edited afterwards.

The shims and the pre-push hook guard the agents Itervox starts. For an agent session you run yourself — Claude Code or Codex in your own terminal — itervox hook applies the same policy, read from the project’s WORKFLOW.md, as a PreToolUse hook. No daemon has to run.

Terminal window
itervox hook install claude # .claude/settings.json (this project)
itervox hook install claude --user # ~/.claude/settings.json (every project)
itervox hook install codex # .codex/hooks.json
itervox hook install claude --print # show the snippet, write nothing
itervox hook install claude --user --absolute # run this binary by its path

The entry runs itervox from PATH. If that is missing, or is another itervox (one older than 0.3.3 has no itervox hook), the hook fails, and Claude Code and Codex treat a failing hook as non-blocking, so the guardrail silently does not apply. install warns when the itervox on PATH is not the binary you ran it with, and itervox doctor warns for every installed hook in that situation. --absolute writes this binary’s path instead (the PATH path when that is the same binary, so a Homebrew upgrade keeps it working); prefer it for --user, and keep the bare itervox in a project file you commit, where each developer’s path differs.

install merges one hooks.PreToolUse entry into the settings file and keeps everything else (other hooks, permissions, key order); running it again changes nothing, and an older itervox entry is replaced, not duplicated. The project entry for Claude Code is:

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
"hooks": [
{
"type": "command",
"command": "itervox hook claude-pretooluse --workflow \"$CLAUDE_PROJECT_DIR\"/WORKFLOW.md"
}
]
}
]
}
}

For each tool call the hook answers:

The agent’s tool callHook answer
a Bash command the guardrails refuse (gh pr merge, git push --no-verify, git -c core.hooksPath=… other than on a read-only git command, git merge on the default branch, a push to a protected branch, a tag push, a force push or remote branch deletion unless allow_force_push)deny, with the refusal’s reason
a Bash command in approval_commands (an environment-scoped entry only when the session’s environment, or the command’s own VAR=value prefix, matches)ask: you confirm it in the agent’s permission prompt
an edit (Edit, Write, MultiEdit, NotebookEdit) of a guardrails.lanes.human fileask: “pipeline file: an agent may change what CI checks, not how”
anything elseno answer: the agent’s own permission rules decide

Every command of a line is checked — after &&, ; or |, inside $(…), backticks, bash -c '…' and eval, behind sudo, env, timeout and xargs, and by its program name when called by path. A program the shell only knows at run time ($TOOL apply) asks, and so does a scoped rule whose variable is set from a substitution (TF_WORKSPACE=$(cat ws) terraform apply).

Fail-safe. If the hook cannot apply the policy — the named WORKFLOW.md is missing or does not parse, a guardrails: entry is invalid, the hook input is not PreToolUse JSON — it answers ask with the reason, never a silent allow. Without --workflow (the --user install) the hook uses the nearest WORKFLOW.md at or above the session’s directory; finding none means the project does not use Itervox, and the hook stays out of the way (--require-workflow asks instead). guardrails.enabled: false turns it off.

Codex. Codex runs PreToolUse hooks from .codex/hooks.json (the same hooks.PreToolUse shape) for its shell tool and for apply_patch, whose patch’s file headers the hook reads as the edited paths. Codex does not support an ask answer (it treats one as a hook failure and lets the call run), so codex-pretooluse turns every ask into a deny whose reason says a human has to run or approve the command. Codex asks you to review a new or changed hook before it runs it: open /hooks in Codex and trust it.

  • Runs on SSH worker hosts are not guarded in this version; a warning is logged at startup and for each such run.
  • Sessions you start by hand are never touched by the shims and hooks; the PreToolUse hook is an opt-in convenience layer for them.
  • The shim reads the command line, not git’s configuration: a git alias for push (git config alias.p push, then git p --no-verify) is not recognised as a push.
  • Lanes see only pushes that go through the hook. The same bypasses apply (git by absolute path, --no-verify through another git, a push through the GitHub or GitLab API, an agent with its own token), and a pull request edited on the web is never classified. merge_pr refuses on the issue’s recorded pushes; it does not re-read the pull request’s file list, so a change that reached the branch another way is not caught there. Protect CI files with branch protection and CODEOWNERS review on the remote; lanes keep honest agents honest, they are not a substitute.
  • Lanes are path patterns. A test-runner setting inside a file that is not in the human lane (package.json’s jest key, pyproject.toml’s [tool.pytest], a conftest.py that skips tests, a test marked skip) is not seen. Code review still matters.
  • An agent CLI running in its own sandbox that blocks network access (for example Codex with permission_mode: sandbox) cannot reach the daemon: refusals still apply but are not reported, and approval commands are refused once the shim gives up waiting.
  • An agent with tracker write access through its own credentials could post a tracker reply to its own approval request; for strict approvals, answer on the dashboard and keep agents’ tracker credentials read-only.