Explain JSON trace reference

explain --json returns the decision for a command plus a trace of each analysis step, as one JSON object. Scripts read the decision from the top-level fields and walk the trace for detail. For flags and exit codes, see explain.

npx cc-safety-net explain --json "git checkout -- file.txt"

A trace is not automatically safe to share. Read Before you share a trace first.

ExplainResult

Field	Type	Presence	Description
`result`	`"blocked" \| "allowed"`	always	The final outcome for the command
`reason`	`string`	blocked only	The block reason
`segment`	`string`	blocked only	The specific segment that triggered the decision
`ruleId`	`string`	blocked only	The id of the rule or fixed denial that produced the block
`trace`	`ExplainTrace`	always	The trace container with top-level and per-segment steps
`customRule`	`object`	when a custom or rulebook rule matched	`id`, plus optional `rulebook` (`name`, `version`), `source`, and `override` (`{ type: "reason", reason }`)
`configSource`	`string \| null`	always	The config file CC Safety Net loaded the effective config from
`configValid`	`boolean`	always	Whether the loaded config validated cleanly
`effectiveLevel`	`"standard" \| "strict" \| "paranoid" \| "custom"`	always	The level in force, after environment flags and overrides
`selectedPreset`	`"standard" \| "strict" \| "paranoid"`	always	The preset named in the policy, defaulting to `standard`
`safetyPresetScope`	`"user" \| "project" \| "default"`	only when a project policy file was read	Which scope supplied `selectedPreset`
`effectiveCapabilities`	`object`	always	Per-capability state. See below
`destructiveCommandRuleOverrides`	`Record<string, "on" \| "off">`	always, may be `{}`	Per-rule overrides stored in the policy
`ruleActivation`	`object`	conditional. See below	How the relevant rule got its on/off state

`effectiveCapabilities`

effectiveCapabilities is a record keyed by fail_closed, paranoid_rm, and paranoid_interpreters. Each value contains:

Field	Type	Description
`enabled`	`boolean`	Whether the capability is on
`source`	`"preset" \| "capability_override" \| "environment"`	What decided the final state
`sources`	`array`	Every input that contributed, in precedence order

See Modes for what each capability changes.

`ruleActivation`

ruleActivation is present only when a capability gates the relevant rule. The relevant rule is the matched rule, or a rule that would match if its level or capability were on.

Field	Type	Description
`id`	`string`	The rule id
`enabled`	`boolean`	Whether the rule is active right now
`inheritedEnabled`	`boolean`	Whether the rule would be active from inheritance alone
`changesInherited`	`boolean`	Whether the effective state differs from the inherited one
`source`	`string`	What decided it: `catastrophic`, `master_disabled`, `rule_override`, `preset`, `capability_override`, `environment`, or `built_in_default`
`activationCapability`	`string`	Optional. The capability that gates the rule
`override`	`"on" \| "off"`	Optional. The stored per-rule override, when there is one

Human-readable output shows it as one line: .

`ExplainTrace`

Field	Type	Description
`steps`	`TraceStep[]`	Top-level steps. Most traces start with the global `parse` step. A trace from a protection short circuit omits it.
`segments`	`object[]`	Per-segment entries, each with an `index` and its own `steps` array

Recording a trace never changes the decision. CC Safety Net caps very long traces. It shortens long text values and drops steps past the limit.

`TraceStep` variants

Use type to select the variant before you read its other fields.

`type`	Key fields	When it appears
`parse`	`input`, `segments`	The initial shell split into token segments
`env-strip`	`input`, `envVars`, `output`	Environment assignments stripped from the front of the segment. `envVars` contains only the assigned names, with no values. The assignment tokens stay in `input` with their values redacted
`leading-tokens-stripped`	`input`, `removed`, `output`	Leading tokens such as `env` or `command`, removed before analysis
`shell-wrapper`	`wrapper`, `innerCommand`	The analyzer unwrapped a shell wrapper such as `bash -c`
`interpreter`	`interpreter`, `codeArg`, `paranoidBlocked`	The analyzer inspected an interpreter one-liner. `paranoidBlocked` marks an outright denial in paranoid mode
`busybox`	`subcommand`	The analyzer resolved a busybox-style dispatch to a subcommand
`transparent-wrapper`	`wrapper`, `output`	The analyzer looked through a registered transparent wrapper. See below
`recurse`	`reason`, `innerCommand`, `depth`	The analyzer started a recursive re-analysis
`script-file`	`path`, `bytes`	The analyzer read a shell script from disk. See below
`rule-check`	`rule`, `matched`, `reason?`	The analyzer evaluated a built-in rule
`worktree-relaxation`	`originalReason`, `gitCwd`	The analyzer relaxed a git discard command because the target is a linked worktree
`temp-root-relaxation`	`originalReason`, `gitCwd`	The analyzer relaxed a git rule because git runs in a disposable repository under a trusted temp root
`tmpdir-check`	`tmpdirValue`, `allowTmpdirVar`	`$TMPDIR` resolution and override detection
`fallback-scan`	`tokensScanned`, `embeddedCommandFound?`	Fallback dangerous-text scan over the remaining tokens
`custom-rules-check`	`rulesChecked`, `matched`, `reason?`	The analyzer evaluated custom rules
`cwd-change`	`segment`, `effectiveCwdNowUnknown`	The effective cwd became unknown, so later classification has no cwd anchor. `effectiveCwdNowUnknown` is always `true`, and a tracked `cd` records no step
`dangerous-text`	`token`, `matched`, `reason?`	The analyzer scanned a token against dangerous-text patterns
`strict-unparseable`	`rawCommand`, `reason`	Strict mode failed closed on an unparseable command
`segment-skipped`	`index`, `reason`	The analyzer skipped a segment because an earlier segment already blocked the command
`error`	`message`, `partial?`	The analyzer captured an analysis error. `partial` marks partial output

See Temp-root relaxation for when temp-root-relaxation applies.

`recurse` reasons

recurse.reason has one of eight values: shell-wrapper, interpreter, busybox, shell-eval, shell-trap, shell-stdin, shell-heredoc, or heredoc-file. heredoc-file means the command ran a script that an earlier heredoc in the same command wrote. See What the analyzer sees through.

`script-file` steps

A script-file step appears for a command such as sh deploy.sh or ./deploy.sh. path is the path as the command spelled it, and bytes is the file’s size. The commands inside the script produce no further steps, and no field carries the script’s text. See Scripts run from a file. A script that a heredoc in the same command wrote records a recurse step with the reason heredoc-file instead. That step carries the body.

`transparent-wrapper` steps

A transparent-wrapper step appears when analysis looks through a command registered with rule wrapper add. wrapper is the wrapper name, and output is the token list of the wrapped command. One step per candidate comes right before that command’s analysis.

Trace order

A typical trace starts with parse. Each segment then shows env-strip or leading-tokens-stripped, then the wrapper detection steps shell-wrapper, interpreter, busybox, and transparent-wrapper, then rule-check or custom-rules-check. Nested commands appear as recurse steps with a depth. Four protections block before the evaluator runs. Their trace holds a single synthetic rule-check step and no parse step, so a script that expects every trace to open with parse must handle them:

Protection	`ruleId`
Policy-file protection	`guard.policy-config`
`policy apply` protection	`guard.policy-apply`
Git-metadata protection	`guard.git-metadata`
Secret protection	The id of the matched secret rule

Redaction removes only recognized credential shapes, using the same pattern list as the audit log. File paths, hostnames, IP addresses, usernames, project or client names, and secrets in unrecognized formats stay in full. Reproduce the case with placeholder credentials and paths, then read the output end to end before you share it.

The parse step records the raw command string and every parsed token. These fields also carry raw text:

fallback-scan.tokensScanned, dangerous-text.token, strict-unparseable.rawCommand
shell-wrapper.innerCommand, interpreter.codeArg, recurse.innerCommand, transparent-wrapper.output
script-file.path, worktree-relaxation.gitCwd, temp-root-relaxation.gitCwd, cwd-change.segment

configSource is an absolute path, normally inside your home directory. You can include explain output in a vulnerability report. A credential format that redaction misses in text you supplied is an ordinary bug for a public GitHub issue, not a vulnerability.

Get started

Guides

Configuration

Troubleshooting

CLI commands

Rules and protection

Logs and traces

More reference

Concepts

Project

Explain JSON trace reference

ExplainResult

`effectiveCapabilities`

`ruleActivation`

`ExplainTrace`

`TraceStep` variants

`recurse` reasons

`script-file` steps

`transparent-wrapper` steps

Trace order

​ExplainResult

​effectiveCapabilities

​ruleActivation

​ExplainTrace

​TraceStep variants

​recurse reasons

​script-file steps

​transparent-wrapper steps

​Trace order

​Before you share a trace

ExplainResult

`effectiveCapabilities`

`ruleActivation`

`ExplainTrace`

`TraceStep` variants

`recurse` reasons

`script-file` steps

`transparent-wrapper` steps

Trace order

Before you share a trace