1 files changed, 64 insertions, 0 deletions

diff --git a/constrain/README.txt b/constrain/README.txt
new file mode 100644
index 0000000..01657a8
--- /dev/null
+++ b/constrain/README.txt
@@ -0,0 +1,64 @@
+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)
+codex-config.toml              optional: centralize VR_LOG for codex
+AGENTS.md                      how-to-navigate-with-vr guidance for the repo
+
+── one-time setup ──────────────────────────────────────────────────────────
+put vr on PATH:  go build -o ~/.local/bin/vr .   (repo root, not vrsite/)
+
+── running a constrained CLAUDE investigation ──────────────────────────────
+No repo mutation needed; from the target repo dir:
+
+  VR_LOG=/abs/path/trace.jsonl \
+  claude -p --settings /Users/goblin/00-projects/0x4200.cafe/vr-agent-logger/constrain/claude-headless-settings.json \
+         --allowedTools 'Bash(vr)' 'Bash(vr:*)' \
+         < prompt.txt > report.md
+
+  - --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)
+  VR_LOG=/abs/path/trace.jsonl \
+  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 .git/ writes,
+    which kills jj's working-copy snapshot and with it `vr read`.
+  - 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_LOG must point at a FILE path whose parent exists. If the path is a
+    directory (or becomes one), agents improvise their own log files and you
+    will be merging jsonl afterwards. Ask me how I know.
+  - Multiple agents may share one log: note ids are per-session, appends are
+    line-atomic. Same file = one merged timeline for free.
+  - In the prompt, tell the agent to leave pinned notes
+    (vr note -f FILE:START-END -t kind "...") — that is the payload.
+  - Render the trace afterwards:
+      vrsite/vrsite -log trace.jsonl -repo <repo> -out site -title "..."
+
+── 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).