Troubleshoot Shield
Run shield status and shield doctor in the affected project. Follow any
reported recovery command, or find your symptom below.
| What you observe | Where to look |
|---|---|
| No apparent Shield checks in the agent | Integration loading |
| Old behavior after installing a new Shield | Reload the new version |
| A command proceeds despite a recorded Ask | Codex Ask handling |
| An unexpected Allow or Deny | Inspect the request and matching rule |
| A YAML edit has no effect | Review and activate the edit |
| An old proposal cannot be applied | Stale proposals |
| Status reports repair or cache failure | Policy files or compiled cache |
| Initialization fails while downloading | Baseline acquisition |
| A change cannot obtain confirmation | Terminal confirmation |
The agent does not seem to use Shield
Check whether the agent is registered with shield status. If it is missing,
run shield mcp setup --agent claude or shield mcp setup --agent codex in an interactive terminal,
review the changes, and confirm.
Restart the agent, trust the project, enable native hooks, and approve the MCP
connection. Codex also requires reviewing hook definitions through /hooks.
Use shield doctor to check for missing or changed owned files and binaries.
If doctor reports an interrupted confirmed setup, use shield mcp setup to
finish it. If an owned entry was edited, inspect the named configuration and
resolve the conflict; Shield preserves conflicting edits instead of replacing
them silently.
Hooks must be loaded to check requests. A host may continue execution if it skips, disables, kills, or times out a hook. See loading and coverage.
The agent still uses the previous Shield
Hooks start the installed shield for every request, but the MCP server is one
process that the agent starts with its session. After installing a new build:
- In each project, run
shield mcp setup --agent claudeorshield mcp setup --agent codexand confirm. Setup records the new executable’s digest; until thenshield statusreports that the registered binary changed. - Exit the agent session and start a new one, so the agent launches the new MCP
server. Reconnecting the MCP server from the agent (for example
/mcpin Claude Code) also restarts it. An open session keeps the old server process. - Run
shield doctor. If it reports the compiled cache as missing or incompatible, runshield cache prepare; the cache is rebuilt from the saved active policy without changing it.
Saved policy, proposals, history and approvals stay in .shield/ across
updates. Do not delete .shield/review/ to recover; only the compiled cache is
disposable.
The request was allowed or blocked unexpectedly
Inspect the recorded request:
shield history list
Use an entry ID from that list in place of ENTRY:
shield history show ENTRY
shield rule list --json
Check the command, working directory, matching rule, failed requirements, and active revision. Extra arguments or unknown options can stop a rule matching; failed requirements can select its Ask or Deny branch.
Check the host action too: Codex’s Allow fallback can let a policy Ask proceed.
If the message asks for a rewrite, submit the supported literal form it names. If it identifies an unsupported tool, a policy change cannot add that support. If policy returns Deny, ordinary approval cannot override it. Review a narrower request or an appropriate policy change instead. See policy decisions for precedence and Ask handling.
A command runs even though policy says Ask
Check the Ask fallback with shield status. New Codex setups let valid Ask
requests proceed, including unmatched requests and Strict-profile Asks.
History still records Ask, without individual operator approval.
To reject an operation, review a matching Deny rule. Ask or a missing match will not block it under the Allow fallback. See policy decisions and requirements with an unmet branch. The integration guide covers exceptions and saved fallbacks.
I edited a rule, but behavior did not change
Shield uses the reviewed active snapshot, not unreviewed file edits. Run:
shield policy review
Choose the manual action to review edited configuration or rules and confirm
the change. Use shield status to inspect the active revision afterwards.
Use shield pack add to acquire a new pack release rather than replacing its cached
artifact by hand.
For future custom-rule changes, shield rule add, shield rule edit ID, and
shield rule remove ID combine validation, review, and activation. See
project policy.
A proposal is stale
Another policy or setup change can make a proposal stale. Ask the agent to inspect current state and prepare a fresh proposal. Wait for each application result before preparing the next; do not reuse old approval arguments. See proposal review.
Policy files need repair
If shield status reports projection repair, run shield policy review and choose
repair. This recreates missing generated policy files from the committed
snapshot. Other manual edits are preserved for manual review.
A reported committed change with repair needed can already be active even if a projected file could not be written. Check status before retrying a mutation. For lock errors, preserve the private review state and inspect the diagnostic; Shield does not automatically steal an abandoned writer lock. See active policy and repair.
The compiled policy cache cannot load
Shield normally rebuilds missing, corrupt, or incompatible cache data from the saved active policy. To prepare it explicitly, run:
shield cache prepare
This does not activate manual edits or pending proposals. If preparation still
fails, follow the reported cause: invalid retained source or an inaccessible
cache directory prevents evaluation. shield status --json reports the chosen
cache root. See cache locations and overrides.
Initialization cannot download the baseline
Default initialization needs the pinned main registry. Check the reported
connection or verification error; failed acquisition leaves a new project
unenrolled. Retry shield init after resolving that cause.
If you intend to start without the baseline, use shield init --no-baseline.
This is a different policy choice, not a way to bypass artifact verification.
Unmatched requests return Ask. See first setup.
Terminal confirmation is unavailable
Run the command yourself in an interactive, cursor-capable terminal. Redirected input, JSON mode, and intercepted agent tool calls cannot provide CLI operator confirmation. Enlarge the terminal if a prompt cannot fit.
Agents can prepare changes with policy_propose and request your host’s
approval with policy_apply. If the host cannot complete that approval,
review pending proposals yourself with shield policy review.
See terminal controls.