Constrain agents to read files only through vr — enforcement comes from
harness config; AGENTS.md is navigation guidance only, never the constraint.

── files here ──────────────────────────────────────────────────────────────
claude-settings.json           project install: <repo>/.claude/settings.json
                               (hook path uses $CLAUDE_PROJECT_DIR)
claude-headless-settings.json  no-install variant for `claude -p --settings`
                               (hook path is absolute into this dir)
vr-only-guard.sh               PreToolUse hook: blocks cat/rg/sed/... and
                               jj/git content reads; its error message points
                               the agent at `vr -doc`, so agents converge
                               even with zero instructions
vr-only.rules                  codex execpolicy rules (allow vr, forbid readers)
AGENTS.md                      how-to-navigate-with-vr guidance for the repo

── one-time setup ──────────────────────────────────────────────────────────
put both on PATH:  go build -o ~/.local/bin/vr .          (repo root)
                   cd vrsite && go build -o ~/.local/bin/vrsite .
                   (vr is what agents call; vrsite is how you read the trace)

── running a constrained CLAUDE investigation ──────────────────────────────
From the target jj repo dir:

  claude -p --settings <vr-repo>/constrain/claude-headless-settings.json \
         --allowedTools 'Bash(vr)' 'Bash(vr:*)' \
         < prompt.txt > report.md

  (<vr-repo> is wherever this repo lives; the settings file's hook path is
   absolute into this directory, so it must be spelled out in full)

  - --allowedTools on the CLI is required headless: allow rules inside
    settings are IGNORED until the workspace is trusted (deny rules and the
    hook always apply). Interactive use instead: install claude-settings.json
    + hook into the repo's .claude/, open once, accept the trust dialog.
  - put the prompt on stdin; a positional prompt after --allowedTools gets
    eaten by the flag's list parsing.

── running a constrained CODEX investigation ───────────────────────────────
  cp vr-only.rules ~/.codex/rules/          # activate (GLOBAL: constrains
                                            # every codex session while there)
  codex exec -s danger-full-access "$(cat prompt.txt)" > report.md
  rm ~/.codex/rules/vr-only.rules           # deactivate when done

  - danger-full-access is required: workspace-write blocks jj metadata writes,
    including the sidecar rewrite and `vr read`'s working-copy snapshot.
  - enforcement is pre-exec by codex's execpolicy engine, even through
    `zsh -lc` wrappers; validate rules with:
      codex execpolicy check --rules vr-only.rules -- cat foo.txt

── shared trace + rendering ────────────────────────────────────────────────
  - vr creates one anonymous sidecar change directly under jj's root() on the
    first append. The repo-local alias vr_log names it; git.private-commits
    protects it from accidental pushes. No path or environment setup exists.
  - Multiple agents in the repo share that sidecar. Rewrites are serialized,
    note ids are assigned under the same lock, and the project @ is untouched.
  - The sidecar has no bookmark and is local-only. It does not survive a fresh
    clone; include the jj repository in backups when the trace matters.
  - In the prompt, tell the agent to leave pinned notes
    (vr note -f FILE:START-END -t kind "...") — that is the payload.
  - Read traces afterwards from one process. Bare `vrsite` scans below ~ at
    startup and when Refresh is pressed, then offers every repo with a sidecar:
      vrsite
    Its explicit buttons can start an empty private sidecar in a discovered jj
    repo or initialize colocated jj in a discovered Git repo. The project index
    is only in memory; those two requested metadata changes are the only writes.
  - To bypass the dashboard and serve one repository directly:
      vrsite -repo <repo> -title "..."
    or take a static copy to hand around (one change, no server features):
      vrsite -repo <repo> -out site -title "..."
    `vrsite -h` explains both, and what a log needs to be worth reading.

── known holes (accepted) ──────────────────────────────────────────────────
Scripting runtimes (python/node/perl) can still open files — uncomment their
rules in vr-only.rules / extend the hook to close, at the cost of breaking
legitimate scripts. Neither harness constrains its own non-shell internals
beyond what the deny rules cover. Codex's rules file is global-only; there is
no per-project rules mechanism (probed, none exists as of codex 0.145).