cc-safety-net

<!-- Keep the body below in sync with src/integrations/templates/cc-safety-net.ts. -->

# CC Safety Net

CC Safety Net hooks into coding agent CLIs (Claude Code, Codex, Cursor, Gemini CLI, and others)
and blocks destructive commands and secret access before they run. The `cc-safety-net` CLI
inspects and controls that protection. Run it as `npx -y cc-safety-net`.

## Learn the current CLI

The installed CLI is the authority for command syntax. Do not guess flags.

```bash
npx -y cc-safety-net --help
npx -y cc-safety-net help <command>
```

Run `npx -y cc-safety-net rule doc` and treat that output as the complete source of truth for
rulebook schema, paths, GitHub sources, matching behavior, and validation.

These commands are read-only and safe to run for discovery: `--help`, `--version`, `status`,
`doctor`, `logs` (without `--prune-legacy`), `explain`, `rule list`, `rule verify`, `rule doc`,
`policy check`, `help`. Every other command mutates configuration or installed integrations; run
those only as part of a workflow below.

## Core model

- Built-in guards always apply. Custom rules only add restrictions; nothing in rule config can
  bypass built-in CC Safety Net protections.
- Config files (`rule.json`) list rulebook sources. Rule definitions live in `rulebook.json`,
  not directly in `rule.json`.
- Three scopes: user (all projects), project (current project only), and shareable GitHub
  rulebooks at `.cc-safety-net/rules/<rulebook-name>/rulebook.json` in a repository.
- Rulebooks are live files. The runtime reads each `rulebook.json` on every tool call, so a saved
  edit applies to the next command with no sync step.
- `policy.json` sets the safety level, per-feature toggles, per-rule overrides, and path lists. It
  has two scopes: the project file `.cc-safety-net/policy.json`, committed and shared with the
  team, layered on the user file that applies to every project.
- The session safety level is `standard`, `strict`, or `paranoid`, set per session with the
  `CC_SAFETY_NET_LEVEL` environment variable.

## Choose the workflow

- The user asks why a command was blocked, or shows a `BLOCKED by CC Safety Net` message:
  explain a decision.
- The user thinks a block was wrong: triage a false positive.
- The user wants to add, edit, disable, or migrate blocking rules: configure rules.
- The user wants to change the safety level, toggle a protection, or adjust path lists: configure
  the policy.
- The user wants CC Safety Net installed into or removed from an agent CLI: manage integrations.
- A rule does not fire, or the user asks whether protection is working: diagnose.
- The user asks how or why the analyzer behaves a certain way, beyond what `explain` and
  `rule doc` show: answer from the source.

## Explain a decision

1. Get the exact blocked command. If the user does not have it, find it with
   `npx -y cc-safety-net logs` (narrow with `--project .`, `--agent <name>`, or `--since <days>`).
2. Pass the exact command to `npx -y cc-safety-net explain` as one literal argument. Prefer an
   argv-capable tool; when invoking through a shell, shell-escape the whole command as one
   argument. Never interpolate raw command text into double quotes: `$()`, backticks, and
   variables would expand before `explain` receives it. Add `--cwd <path>` when the decision
   depends on the working directory. Once received, `explain` analyzes the string and never
   executes it.
3. Read the trace: how the command was split, which rule matched, and the RESULT status and
   reason. `explain` exits 0 for both allowed and blocked verdicts; read the verdict from the
   output, not the exit status.
4. Report the reason in plain language. For a genuine hazard, suggest the safer alternative the
   reason names, such as `git stash` before `git reset --hard`.

## Triage a false positive

1. List recent suspect denials with `npx -y cc-safety-net logs --suspect --since 7`, or fetch
   one entry with `npx -y cc-safety-net logs --id <id>`.
2. Reproduce the decision with `explain` and read which rule fired.
3. If a custom rule fired, fix that rulebook: disable or reword it with an override, or edit the
   rule (see configure rules), then re-run `explain` to confirm the new verdict.
4. If a built-in rule fired, no rule edit can relax it. Check the reason for a documented escape
   hatch, such as `CC_SAFETY_NET_WORKTREE=1` for local git discards in linked worktrees, or
   `rule wrapper add` when a trusted transparent wrapper hid the real command from the analyzer.
   Pass the wrapper name as a separate argv value, or shell-escape it as one argument. If the
   user explicitly wants that built-in rule off, read its id from the `ruleId` field of
   `explain --json` and propose a per-rule policy override (see configure the policy). Otherwise
   explain the risk the rule guards against and suggest reporting the case at
   https://github.com/kenryu42/cc-safety-net/issues.

## Configure rules

Use information already provided in the user's prompt. Ask only when the scope, action, rule
intent, merge behavior, or target command is unclear.

1. Determine the requested scope from the prompt when possible:
   - User: applies to all projects.
   - Project: applies only to the current project.
   - GitHub: edits or creates a shareable rulebook structure in the current repository.
2. Determine whether to add a rule, edit a rule, disable a rule, override a reason, trust a
   transparent wrapper, migrate legacy rules, or explain custom rules from the prompt when
   possible.
3. Inspect existing configs before modifying installed local rules:
   - Run `npx -y cc-safety-net rule verify`
   - Run `npx -y cc-safety-net rule list`
4. Inspect relevant project files only when the user asks for rule suggestions or the requested
   rule depends on project context. Look at manifests, scripts, task runners, CI, infrastructure,
   database, migration, and deployment files that explain risky commands.
5. Convert the request into valid CC Safety N