--- name: sapper-setup description: Opt-in the CURRENT project to the sapper engagement-graph working memory (offensive specialization of the fact graph). Creates the local .sapper/ graph, registers the SessionStart + UserPromptSubmit hooks in this project's .claude/settings.json (NOT global — other projects are untouched), and writes AGENTS.md teaching typed facts (host/service/cred/vuln/loot/flag), the flag ledger (sapper flag), and the arena bridge (sapper arena). After setup, every turn in this project auto-injects the current graph state and current date output so Claude always knows what's confirmed vs. tried and what time it is; sub-agents (sapper dispatch) can read/write the same graph. For multi-agent tmux work, list panes with sapper peers --discover and ask the user which panes/AI peers may communicate before authorizing any target. Use when the user says "enable sapper here", "在这个项目用 sapper", "setup the engagement graph", or when starting a pentest engagement / CTF challenge / multi-step debugging/research/audit campaign that should be tracked and resumable. For competitions, follow up with `sapper arena init` and set SAPPER_ARENA_TOKEN. This is the per-project initializer the install.sh skill exposes as a slash command. license: MIT --- # sapper-setup Per-project initializer for the **sapper engagement graph** working memory. This is the opt-in switch: until you run it in a project, sapper does nothing there. After you run it, that one project auto-reads and auto-maintains its graph on every turn. Zero servers — it just drops a local `.sapper/` and writes the two hook entries into **this project's** `.claude/settings.json`. For penetration engagements, pair it with `sapper arena init` (competition platform config) and record findings as typed facts (`-k host/service/cred/vuln/loot/flag`). ## What it does Run inside the target project directory. Exactly three things, all local: 1. **Creates the graph** at `./.sapper/` (unless one already exists): `project.json`, `facts/goal.json`, and the `intents/` `hints/` dirs. 2. **Registers hooks** in `./.claude/settings.json` — `SessionStart` and `UserPromptSubmit`, both pointing at `sapper-hook.py`. These inject the current graph state and `date` output into every turn so the model always knows the frontier and current local time. This is a **project-level** settings file; the user-level `~/.claude/settings.json` and every other project are completely untouched. 3. **(optional) Writes `AGENTS.md`** so dispatched sub-agents learn the fact-graph protocol (`sapper fact`, `sapper done`, etc.). No daemons, no ports, no database. `rm -rf .sapper .claude` undoes everything. ## How to run it From the shell (after `bash install.sh`): ```bash cd /path/to/your/project sapper setup --goal "reproduce the empty-token crash" --agents ``` Or, since this is a skill, the user can just type `/sapper-setup ` inside Claude Code and Claude will run the equivalent commands. ## Multi-agent tmux authorization flow If the user wants multiple AI agents to coordinate through tmux, do this after the normal setup: 1. Run `sapper peers --discover` and show the pane list to the user. 2. Ask which panes/agents are allowed to communicate and what names to use. 3. Only after explicit approval, run: ```bash sapper peers --add harley --target api-6:0.0 --sender "Codex/api2-4" ``` 4. Use `sapper send harley "message"` for communication. It appends to `.sapper/ai-channel.txt` and uses a reliable tmux paste-buffer submit flow. 5. After sending a question, use `sapper capture harley --lines 120` to read recent direct TUI replies from that authorized peer. Peers may answer without using `sapper send`, so the shared channel log is not always enough. Do **not** infer authorization from discovery output or from session names. Never send to or capture from a tmux target unless `sapper peers` shows it as authorized in this project's `.sapper/ai-peers.json`. ## After setup - The model is reminded each session + each turn to read/maintain the graph. - The hooks inject current local time from `date` each session + each turn. - Drive it with `sapper dispatch reason` (commander proposes next work), `sapper dispatch --skip-permissions` (executor does the work), `sapper dispatch verify --intent ` (verify a result), or `sapper auto --skip-permissions` (full loop to completion). - See state anytime: `sapper status`, `sapper graph`; run the read-only `sapper validate` audit before autonomous dispatch or committing `.sapper/`. ## Undo ```bash sapper teardown # removes sapper hooks + its AGENTS.md, keeps .sapper/ sapper teardown --purge # also deletes the graph data ``` `install.sh --uninstall` removes the `sapper` command and this skill globally, but never touches project-level `.sapper/` or `.claude/` — those are per-project and must be removed per-project with `teardown`. ## Autonomy guardrail (prompt injection) A dispatched executor (`sapper dispatch `, `sapper auto`) runs the whole graph — every fact/intent/hint text — interpolated into its prompt. So text recorded as a "fact" becomes instructions the next executor sees. The executor system prompt fences graph content as **untrusted data** and tells the agent to treat embedded "ignore your rules / run this command" text as an observation to record, not a command to obey. That is a textual defense, not a sandbox. Dangerous combination: a graph fed by **untrusted** content (a hostile `.sapper/*.json` in the repo, or facts transcribed from attacker-controlled code/output) **plus** `--skip-permissions` **plus** real shell/file access. In that case a graph field can attempt to drive the agent. **Do not run `sapper auto --skip-permissions` on a repo whose `.sapper/` is untrusted** — prefer the default (each tool use prompts you), and read the facts an autonomous run writes before acting on them. Treat `--skip-permissions` as opt-in per run. ## Where things live (IMPORTANT — nothing global) - `./.sapper/` — all graph data. Move/delete the project, the graph goes with it. - `./.claude/settings.json` — the two hook entries, project-scoped. - `./AGENTS.md` — sub-agent protocol (optional). - `~/.local/bin/sapper` — the CLI (one symlink). - `~/.claude/skills/sapper-setup` — this skill (one symlink). There is no `~/.sapper`, no global hook registration, no shared state between projects. Two opted-in projects have two independent graphs.