Glossary - CC Safety Net

This glossary defines terms used in the CC Safety Net documentation. Each entry gives a short definition and links to the page that defines the full behavior.

Core concepts

Term	Definition
PreToolUse hook	A hook that runs before a tool executes. CC Safety Net uses `PreToolUse` or the equivalent event for each agent to inspect shell commands before execution. See How it works.
Fail-closed	When the guard cannot reach a trustworthy verdict, that one tool call is denied rather than allowed. Causes include an unexpected analysis error, malformed or oversized hook input, an empty command, a parser limit, or an unparseable command under strict mode. Invalid configuration is not fail-closed; it degrades instead. See Design principles and Security model.
Decision	The guard’s allow-or-deny outcome for a single tool call. When audit logging records a command decision, it writes one audit record with the rule id, effective safety level, and degraded-runtime fallback state. See Audit log.
Segment	A single command split from a compound command by shell operators (`&&`, `\|\|`, `\|`, `;`, newline). The engine analyzes segments in sequence and carries relevant state, such as the effective working directory, between them. If one segment is blocked, the full command is denied. See Analysis engine.
Analysis engine	The platform-agnostic core that parses a command string and decides whether to block it. Every agent integration feeds the same engine. See Analysis engine.
Integration model	How CC Safety Net executes inside a coding agent: as a standard-input hook subprocess, an agent-loaded plugin, an in-process extension, or an event plugin. The integration model changes how the agent invokes CC Safety Net. All integrations use the same analysis engine. See Integration architecture.

Configuration

Term	Definition
Policy	The settings document `policy.json`, which defaults to `~/.cc-safety-net/policy.json`. It holds the safety preset, capability overrides, worktree mode, destructive-command protection, secret protection, and audit retention. Custom rules do not live there. See Policy.
Project policy	The optional `.cc-safety-net/policy.json` in the project root. It is a sparse file. It sets only the fields it lists, and every field it omits keeps the user policy’s value. It has no `audit` section; audit settings are user scope only. Writing it is denied like the user policy file. See Policy.
Effective policy	The user policy with the project policy layered on top. The project value wins for `safety.level`, `workflow.worktree_mode`, and each `enabled` flag it sets; per-rule overrides merge by rule id; `allow_paths` and `deny_paths` are the union of both scopes. Each field the project relaxes is reported as a weakening line. See Policy.
Policy snapshot	The effective runtime policy composed on every tool call from the user and project policy files, each scope’s `rule.json`, and each configured source’s rulebook file. Loading it performs no writes, no network requests, and no caching. It resolves to exactly one of two states, `ready` or `degraded`. See Configuration recovery.
Preset	The `safety.level` value that supplies inherited capability defaults: `standard`, `strict`, or `paranoid`. When overrides produce a combination that matches no preset, the reported effective level is `custom`. See Modes.
Capability	One individually settable protection behavior inherited from the preset: `fail_closed`, `paranoid_rm`, or `paranoid_interpreters`. `safety.overrides` in the policy file sets a capability up or down; the legacy environment flags can only raise it. See Modes.
Degraded	The policy snapshot state entered when a configuration source is rejected: the unverifiable source is dropped or falls back to protective defaults, ordinary work continues, and the state is reported on every diagnostic surface. The other state is `ready`. See Configuration recovery.

Shell command forms

Term	Definition
Shell wrapper	A shell command that wraps another command, such as `bash -c 'git reset --hard'`. CC Safety Net recursively analyzes wrapped commands up to 10 levels deep. See Blocked commands.
Interpreter one-liner	A command like `python -c 'import os; os.system("rm -rf /")'` that executes code inline. Detected and analyzed for dangerous patterns by default. See Blocked commands.
Dynamic substitution	A command value or structure that depends on runtime expansion, such as `$(...)`, `<(...)`, or `$VAR`. CC Safety Net handles dynamic substitution according to the command type and safety level. Some forms are allowed in standard and blocked when fail-closed behavior is active. See Analysis engine.

Recursive removal and paths

Term	Definition
CWD self-target	An `rm -rf` target that resolves to the current working directory itself, for example `rm -rf .`. Blocked at every safety level. See Blocked commands.
Effective cwd	The working directory tracked across `cd` and `pushd` commands within a compound command. Used for `rm -rf` target classification and worktree detection. See Analysis engine.
Within-cwd target	A recursive forced removal target that resolves inside the current working directory. Allowed by default and blocked under paranoid `rm` mode. See Allowed commands.

Modes

Term	Definition
Strict mode	The `strict` preset, which turns on the `fail_closed` capability so commands that cannot be safely analyzed are denied. Set `safety.level` in the policy file, or raise it with `CC_SAFETY_NET_STRICT=1`. See Modes.
Paranoid mode	The `paranoid` preset, which adds the `paranoid_rm` and `paranoid_interpreters` capabilities on top of strict. Set `safety.level` in the policy file, or raise individual capabilities with `CC_SAFETY_NET_PARANOID`, `CC_SAFETY_NET_PARANOID_RM`, and `CC_SAFETY_NET_PARANOID_INTERPRETERS`. See Modes.
Worktree relaxation	When worktree mode is on through `workflow.worktree_mode` in the policy file or `CC_SAFETY_NET_WORKTREE=1`, selected local Git discard commands are allowed inside confirmed linked Git worktrees. When CC Safety Net cannot verify the worktree, it does not apply the relaxation. See Modes.

Rules

Term	Definition
Rulebook	A JSON file holding custom blocking rules, metadata, and optional fixtures. It is configured as a source in `rule.json` and lives at `rules/<name>/rulebook.json` under that scope’s `.cc-safety-net` directory. The runtime reads it on every tool call, so a saved edit applies to the next command. Its `name` must match the source that lists it. Rulebook names are claimed globally across the user and project scopes. See Custom rules.
Transparent wrapper	A command declared in `rule.json` under `transparent_wrappers` that analysis looks through to reach the protected command it executes. Wrappers live in `rule.json` rather than in a rulebook, so a dropped rulebook keeps them but an unreadable `rule.json` loses that scope’s wrappers. See Custom rules.
Vendored rulebook	The copy of a remote rulebook that `rule add` and `rule update` write into the consumer’s own `rules/<name>/rulebook.json` after validating it. It is an ordinary file in the repository, so a person can read it and a diff shows what an update changed. Only `rule add` and `rule update` reach the network; the runtime reads the file. See Custom rules.

Looking for the formal schemas for rulebooks, rules, and fixtures? See the Custom rules reference. See Policy for the policy.json schema and Explain trace for the JSON returned by explain --json.

Last modified on August 31, 2026

⌘I